How to use CliRun by Mike Lawrence This doc file is for Version 1.4 of CLIRun. CliRun was written in TDI's Modula-2. Clirun allows you to run programs or batch files from the Workbench (icon environment) that can normally only be run from CLI. For this discussion, assume you want to run a program called: link which is in the root directory of your Workbench disk in the internal drive (df0:), needs a stack size of 6000 to run properly, and is normally run from CLI by typing: link where is the name of a disk file. To use Clirun to run 'link' follow these steps: 1. You must first make an icon for the program you want to run. It needs to be a project icon. What it looks like really doesn't matter. You can always change the way it looks later with iconed. Text files and picture files are usually project icons. To find a project icon, you can single click on icons on your disks, and select the 'info' item from the Workbench menu. (I'm assuming you have workbench loaded) Suppose you find a file called "ToFred" on your Workbench disk (which is in the internal drive at the momment) in a drawer named "text" that is a project. To make an icon for link you would type this from CLI: copy df0:text/tofred.info to df0:link.info (be sure not to leave off the .info parts) 2. Now if you close (if it's open) and re-open your Workbench disk, you should see an icon named link. 3. After moving the icon to a blank spot in the window, and Snapshot-ing it in place, single click on the link icon and select the 'info' item from the Workbench menu. Click in the box next to the word STACK and put 6000 in the box, and then press RETURN. ( If you don't know what to set the stack size to, start out with 4000.) Then Click in the DEFAULT TOOL box and put :clirun in the box, and press the RETURN key. Lastly, click on the SAVE gadget in the lower left of the screen. 4. Move the CliRun icon to your Workbench disk's window. 5. Now you should be able to run link by double clicking on the link icon. Clirun will open up a CLI-like window and ask you for the inputs for link. In this case we said link wanted a file name, so you would type a file name, and press RETURN. link should then run, and when finished, you will be asked to press RETURN to close the window that Clirun opens. TOOLTYPE KEYWORDS: If you want to get more sophisticated, you can take advantage of the ToolType KEYWORDS. This will let you do things like add custom prompts for your program or batch file. Use the Info item from the Workbench menu to edit the tooltypes for the icon for the program or batch file you're running. (More later on how to do this) I use the word "sequence" below to refer to the sequence of Tooltype entries used to tell CliRun how to (or not to) prompt the user. --------------------------------------------- KEYWORD: FILETYPE EXAMPLE: FILETYPE=CLIRUN FUNCTION: Indicates the start of the CliRun ToolType sequence EXAMPLE USAGE: FILETYPE=CLIRUN PROMPT=Enter file to edit You could use the tooltype sequence shown above for the ed editor program. Note: If the icon you are working with already has a FILETYPE= entry, you can just add |CLIRUN. Example: you've make a batchfile with Gizmoz memopad, which makes icons with a tooltype entry of FILETYPE=text|Memopad. You can just add |CLIRUN to change this to: FILETYPE=text|Memopad|CLIRUN and the CliRun program will recognize this. --------------------------------------------- KEYWORD: PROMPT EXAMPLE: PROMPT=Enter file to edit FUNCTION: Displays the text to the right of the = sign, and accepts keyboard input. A space plus the text that in typed in is added to the parameter (argument) text. Also prevents the default prompt from appearing. EXAMPLE USAGE: FILETYPE=CLIRUN PROMPT=Enter input file PROMPT=Enter output file If the above sequence was used on a program called makeedable, and the person running the program entered: origfile at the first prompt, and newfile at the second prompt, the resulting command string would be: makeedable origfile newfile --------------------------------------------- KEYWORD: NOPROMPT EXAMPLE: NOPROMPT=TRUE FUNCTION: Prevents the default prompt from appearing EXAMPLE USAGE: FILETYPE=CLIRUN MESSAGE=Please wait while the program loads NOPROMPT=TRUE This sequence would prevent the user from being prompted for anything. --------------------------------------------- KEYWORD: MESSAGE EXAMPLE: MESSAGE=Enter the file to view FUNCTION: Displays the text to the right of the = sign. Also prevents the default prompt from appearing. EXAMPLE USAGE: FILETYPE=CLIRUN MESSAGE=Makeedable strips binaries from files so they can be MESSAGE=edited with ed PROMPT=Enter input file PROMPT=Enter output file --------------------------------------------- KEYWORD: DEBUG EXAMPLE: DEBUG=TRUE FUNCTION: turns on display of text that helps you debug CliRun Tooltype "programs" Also prevents the default prompt from appearing. EXAMPLE USAGE: FILETYPE=CLIRUN DEBUG=TRUE PROMT=Enter file name DEBUG=FALSE MESSAGE=One momement please This would help you notice why line 3 isn't working (PROMPT is spelled wrong) --------------------------------------------- KEYWORD: ADD EXAMPLE: ADD=o FUNCTION: Adds a space plus the text to the right of the = sign to the argument string. Also prevents the default prompt from appearing. EXAMPLE USAGE: FILETYPE=CLIRUN PROMPT=Enter file to link ADD=o This can be used for TDI's linker to automatically add the o (optimize) option. For example, if you enter clirun at the prompt, the resulting command string will be: link clirun o --------------------------------------------- KEYWORD: BATCH EXAMPLE: BATCH=TRUE FUNCTION: Forces batch mode flag (overrides the .bat setting) Also prevents the default prompt from appearing. EXAMPLE USAGE: FILETYPE=CLIRUN BATCH=TRUE PROMPT=Enter file to install This would force this file to be treated as a batch file, regardless of whether its name ends in .bat or not. --------------------------------------------- KEYWORD: COMMAND EXAMPLE: COMMAND=execute install FUNCTION: Adds the AmigaDOS command on the right of the = sign to the list of commands to do after the Tooltypes are read and before the program or batch file is run. Also prevents the default prompt from appearing. (See DOS keyword for more information on when to use COMMAND and when to use DOS) EXAMPLE USAGE: FILETYPE=CLIRUN COMMAND=execute install PROMPT=Choose a file to display This could be used to execute a batch file before running a program. --------------------------------------------- KEYWORD: DOS EXAMPLE: DOS=dir FUNCTION: Executes the AmigaDOS command on the right of the = sign. Also prevents the default prompt from appearing. Note: this is not the same as the COMMAND keyword. This executes as the Tooltypes are being read. COMMAND waits until after the Tooltypes are read (and therefore all the input prompts have been done.) Note that COMMAND should always be used for commands that set things, like the AmigaDOS command "path". This is because if DOS is used, the setting will be "forgotten" when the program or batch file is executed. The DOS keyword is handy for displaying directories before an input PROMPT where a file is requested. (see example below) EXAMPLE USAGE: FILETYPE=CLIRUN MESSAGE=Here are the files available: DOS=dir #?.pic MESSAGE= PROMPT=Choose a file to display This could be used to show the choices available for a file prompt. --------------------------------------------- KEYWORD: ASSIGN EXAMPLE: ASSIGN=music FUNCTION: Adds an assign command to the list of commands to do after the Tooltypes are read and before the program or batch file is run. This assign command assigns the name on the right side of the = sign to the directory the program or batch file is in. Also prevents the default prompt from appearing. EXAMPLE USAGE: FILETYPE=CLIRUN ASSIGN=music PROMPT=Enter music file to play If the program here was in a directory named df0:x the resulting assign command would be assign music: df0:x This is useful for programs that look for files in a fixed device name (music in this example) --------------------------------------------- KEYWORD: EXAMPLE: FUNCTION: EXAMPLE USAGE: --------------------------------------------- How to use the Info Item to edit the Tooltypes: Returning to the link example, suppose you weren't happy with the default input prompt and wanted to take advantage of the ToolType KEYWORDS to customize the input prompt. (Note that I assume here that the Tooltype entries for the icon for link are blank initiallly) - Single click on the link program's icon, and select the Info item from the Workbench menu. - Click on the ADD gadget in the TOOL TYPES box. - Click in the box to the left of the ADD gadget and type: FILETYPE=CLIRUN and press RETURN - Click on ADD again, and type: PROMPT=Enter name of file to link and press RETURN - Click on the SAVE gadget. - You should now be able to double-click on the link icon and get the "Enter name of file to link" prompt instead of the default prompt. Info Gadgets for tooltype editing: The /\ and \/ gadgets move up and down through the list. The DEL gadget deletes the line shown in the box. The ADD gadget inserts a line after the one shown in the box. (Note that there seems therefore to be no way to insert a line before the first line) Limitations: - Up to 500 characters can be in the command sequence that both the COMMAND and ASSIGN KEYWORDS add to. The commands that CliRun itself always adds, like cd and stack also use up some of these 500 characters. - The first 20 lines of Tooltypes will be used by CliRun. Each line can be up to 127 characters long. - Up to 100 characters can be in the argument string that either the PROMPT and ADD KEYWORDS add to, or the default prompt sets. - Up to 20 programs or batch files can be selected at once. Notes: 1. If you get a message about the stack size being too small, try increasing the stack size (as described above). Because Clirun "inherits" the stack size of the icon you double-click on, and because clirun needs a stack size of at least 4000, you should set the stack size to at least 4000, or you can single-click on the icon you made, hold down the shift key, and then double-click on the Clirun icon (this prevents Clirun from inheriting the stack size of the program you're trying to run) 2. If the program fails, you may find yourself at a CLI style prompt. (like 1> or 2> , etc.) If this happens, just type endcli and press RETURN to continue. 3. When you just get the default prompt when you're running a program with CliRun: If you don't know what the inputs are for the program you are trying to run, just press RETURN when prompted for them. Most program tell you what the proper usage format is when they receive no inputs (and some require none). You can then run the program again after you've read the message telling how to use the program. Note also that some programs give instructions when you enter a ? as the input. (Just type: ? at the prompt). If, for example, you double-clicked on an icon you made, (called setlace) and just hit RETURN when asked for the inputs, and setlace said: usage: setlace you would know to type either on or off at the input prompt the next time you ran setlace. 4. Clirun can run multiple programs. Just single-click on the icons one at a time (hold down the shift key after the first one to avoid cancelling the other selections) and then double-click on the Clirun icon. The programs will then be run in the order selected. For example, you might want to run a compiler and then a linker. 5. For "Program mode", the following files are required in c: (usually the c directory on the Workbench disk): cd stack run endcli For "Batch File mode", these are required: cd failat stack run execute endcli plus whatever the batch file uses 6. Because of a bug in AmigaDos 1.2, if you run a program or batch file from a disk with a blank name (a zero length name) clirun will try to look for the program or batch file in the RAM disk, and so won't find it. 7. When you use CliRun to execute a batch file, the execute command that CliRun uses will need to write to a directory named T on the disk your batch file is on. If the directory doesn't exist, it will be created. Therefore if your disk is write protected you will get an error message. 8. Blank lines in the tools types will make CliRun think it has reached the end of the Tooltypes. 9. If you want to temporarily disable a line in the Tooltypes, just add an X to the start of the KEYWORD (like XPROMPT) , and CliRun will ignore the line. 10. If you are using the Tooltype KEYWORDS, watch out for programs that might overwrite the FILETYPE= setting. For example, you might have a batch file that works just fine, then edit it with Gizmoz Memopad, and then find it starts coming up with the default prompt, ignoring the Tooltype information. To add to the confusion, if you single click on the batch file's icon, and use the Info item to look at the Tooltype entries, everything looks ok! What has happened is Memopad has overwritten the FILETYPE= entry on the disk (or RAM disk), but you see what is in memory when you use the Info item from the Workbench Menu. (Unless you close and re-open the window the batch file's icon is in) The fix is to single click on the batch file's icon, select the Info item from the Workbench menu, and then click on the Info screen's SAVE gadget. This will fix the FILETYPE= entry so things should now work as before. 11. All the Tooltype keywords, plus TRUE, FALSE, and CLIRUN must be in uppercase to be recognized. Changes with Version 1.2: 1. If the name of the project ends with ".bat" (must be lower case), then CliRun will try to "execute" the file as a batch file, instead of run it as a program. The "failat" level is set to 100 before executing the batch file to keep the batch file from "crashing". (If will just ignore errors). Changes with Version 1.4: 1. Tools Type KEYWORDS added. 2. CliRun will now find a program that is in the RAM: disk. Known Bugs: 1. See Note 6. Please address questions, problems, and suggestions (especially for new Keywords) to: Mike Lawrence Tucson AZ: CCCC board: CC83 NAD board: Mike Lawrence National: CIS: 70030,160 PLINK: OLR536 BIX: mlawrence GEnie m.lawrence