home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 056.lha / Clirun.doc < prev    next >
Text File  |  1986-11-20  |  16KB  |  454 lines
  1. How to use CliRun by Mike Lawrence
  2.  
  3. This doc file is for Version 1.4 of CLIRun.
  4.  
  5. CliRun was written in TDI's Modula-2.
  6.  
  7. Clirun allows you to run programs or batch files from the Workbench
  8. (icon environment) that can normally only be run from
  9. CLI.
  10.  
  11. For this discussion, assume you want to run a program called:
  12.  
  13. link
  14.  
  15. which is in the root directory of your Workbench disk in the internal
  16. drive (df0:),  needs a stack size of 6000 to run properly, and is normally 
  17. run from CLI by typing:
  18. link <filename>
  19. where <filename> is the name of a disk file.
  20.  
  21.  
  22. To use Clirun to run 'link' follow these steps:
  23.  
  24. 1. You must first make an icon for the program you want to
  25.    run. It needs to be a project icon. What it looks like really
  26.    doesn't matter. You can always change the way it looks later
  27.    with iconed. Text files and picture files are usually
  28.    project icons. To find a project icon, you can single click
  29.    on icons on your disks, and select the 'info' item from
  30.    the Workbench menu. (I'm assuming you have workbench loaded)
  31.    Suppose you find a file called "ToFred" on your Workbench disk 
  32.    (which is in the internal drive at the momment)
  33.    in a drawer named "text" that is a project.
  34.    To make an icon for link you would type this from CLI:
  35.  
  36.    copy df0:text/tofred.info to df0:link.info
  37.  
  38.    (be sure not to leave off the .info parts)
  39.  
  40. 2. Now if you close (if it's open) and re-open your Workbench
  41.    disk, you should see an icon named link.
  42.  
  43. 3. After moving the icon to a blank spot in the window, and 
  44.    Snapshot-ing it in place, single click on the link icon and
  45.    select the 'info' item from the Workbench menu.
  46.    Click in the box next to the word STACK and put 6000
  47.    in the box, and then press RETURN.  ( If you don't know what
  48.    to set the stack size to, start out with 4000.)
  49.    Then Click in the DEFAULT TOOL box and put
  50.    :clirun 
  51.    in the box, and press the RETURN key. Lastly, click on
  52.    the SAVE gadget in the lower left of the screen.
  53.  
  54. 4. Move the CliRun icon to your Workbench disk's window.
  55.  
  56. 5. Now you should be able to run link by double clicking on the
  57.    link icon. Clirun will open up a CLI-like window and ask
  58.    you for the inputs for link.
  59.  
  60.    In this case we said link wanted a file name, so you would type
  61.    a file name, and press RETURN. link should then run, and
  62.    when finished, you will be asked to press RETURN to close the
  63.    window that Clirun opens.
  64.  
  65.  
  66. TOOLTYPE KEYWORDS:
  67.  
  68.   If you want to get more sophisticated, you can take advantage of
  69.   the ToolType KEYWORDS. This will let you do things like add custom
  70.   prompts for your program or batch file.
  71.  
  72.   Use the Info item from the Workbench menu to edit the tooltypes for the
  73.   icon for the program or batch file you're running. (More later on how
  74.   to do this)
  75.  
  76.   I use the word "sequence" below to refer to the sequence of Tooltype
  77.   entries used to tell CliRun how to (or not to) prompt the user.
  78.  
  79. ---------------------------------------------
  80. KEYWORD: FILETYPE
  81. EXAMPLE: FILETYPE=CLIRUN
  82. FUNCTION: Indicates the start of the CliRun ToolType sequence
  83. EXAMPLE USAGE:
  84.  
  85.         FILETYPE=CLIRUN
  86.         PROMPT=Enter file to edit
  87.         
  88.         You could use the tooltype sequence shown above for the ed editor
  89.         program.
  90.  
  91. Note: If the icon you are working with already has a FILETYPE= entry, you
  92.       can just add |CLIRUN. Example: you've make a batchfile with Gizmoz
  93.       memopad, which makes icons with a tooltype entry of
  94.       FILETYPE=text|Memopad. You can just add |CLIRUN to change this to:
  95.       FILETYPE=text|Memopad|CLIRUN and the CliRun program will recognize
  96.       this.
  97. ---------------------------------------------
  98. KEYWORD: PROMPT
  99. EXAMPLE: PROMPT=Enter file to edit
  100. FUNCTION: Displays the text to the right of the = sign, and accepts
  101.           keyboard input. A space plus the text that in typed in is added to
  102.           the parameter (argument) text.
  103.           Also prevents the default prompt from appearing.
  104.  
  105. EXAMPLE USAGE:
  106.         
  107.         FILETYPE=CLIRUN
  108.         PROMPT=Enter input file
  109.         PROMPT=Enter output file
  110.         
  111.         If the above sequence was used on a program called makeedable,
  112.         and the person running the program entered: origfile at the first
  113.         prompt, and newfile at the second prompt, the resulting
  114.         command string would be:
  115.  
  116.         makeedable origfile newfile
  117.  
  118. ---------------------------------------------
  119. KEYWORD: NOPROMPT
  120. EXAMPLE: NOPROMPT=TRUE
  121. FUNCTION: Prevents the default prompt from appearing
  122. EXAMPLE USAGE:
  123.  
  124.         FILETYPE=CLIRUN
  125.         MESSAGE=Please wait while the program loads
  126.         NOPROMPT=TRUE
  127.  
  128.      This sequence would prevent the user from being prompted for anything.
  129.  
  130. ---------------------------------------------
  131. KEYWORD: MESSAGE
  132. EXAMPLE: MESSAGE=Enter the file to view
  133. FUNCTION: Displays the text to the right of the = sign.
  134.           Also prevents the default prompt from appearing.
  135.  
  136. EXAMPLE USAGE:
  137.  
  138.         FILETYPE=CLIRUN
  139.         MESSAGE=Makeedable strips binaries from files so they can be
  140.         MESSAGE=edited with ed
  141.         PROMPT=Enter input file
  142.         PROMPT=Enter output file
  143.  
  144. ---------------------------------------------
  145. KEYWORD: DEBUG
  146. EXAMPLE: DEBUG=TRUE
  147. FUNCTION: turns on display of text that helps you debug CliRun Tooltype
  148.           "programs"
  149.           Also prevents the default prompt from appearing.
  150.  
  151. EXAMPLE USAGE: 
  152.  
  153.             FILETYPE=CLIRUN
  154.             DEBUG=TRUE
  155.             PROMT=Enter file name
  156.             DEBUG=FALSE
  157.             MESSAGE=One momement please
  158.  
  159.           This would help you notice why line 3 isn't working (PROMPT is
  160.           spelled wrong)
  161.  
  162. ---------------------------------------------
  163. KEYWORD: ADD
  164. EXAMPLE: ADD=o
  165. FUNCTION: Adds a space plus the text to the right of the = sign to the 
  166.           argument string.
  167.           Also prevents the default prompt from appearing.
  168.  
  169. EXAMPLE USAGE:
  170.  
  171.         FILETYPE=CLIRUN
  172.         PROMPT=Enter file to link
  173.         ADD=o
  174.         
  175.         This can be used for TDI's linker to automatically add the 
  176.         o (optimize) option. For example, if you enter clirun at the
  177.         prompt, the resulting command string will be:
  178.  
  179.         link clirun o
  180.  
  181. ---------------------------------------------
  182. KEYWORD: BATCH
  183. EXAMPLE: BATCH=TRUE
  184. FUNCTION: Forces batch mode flag (overrides the .bat setting)
  185.           Also prevents the default prompt from appearing.
  186.  
  187. EXAMPLE USAGE:
  188.  
  189.         FILETYPE=CLIRUN
  190.         BATCH=TRUE
  191.         PROMPT=Enter file to install
  192.  
  193.        This would force this file to be treated as a batch file, regardless
  194.        of whether its name ends in .bat or not.
  195.  
  196. ---------------------------------------------
  197. KEYWORD: COMMAND
  198. EXAMPLE: COMMAND=execute install
  199. FUNCTION: Adds the AmigaDOS command on the right of the = sign to the
  200.           list of commands to do after the Tooltypes are read and
  201.           before the program or batch file is run.
  202.           Also prevents the default prompt from appearing.
  203.           (See DOS keyword for more information on when to use COMMAND
  204.           and when to use DOS)
  205.  
  206. EXAMPLE USAGE:
  207.  
  208.         FILETYPE=CLIRUN
  209.         COMMAND=execute install
  210.         PROMPT=Choose a file to display
  211.  
  212.      This could be used to execute a batch file before running a program.
  213.  
  214. ---------------------------------------------
  215. KEYWORD: DOS
  216. EXAMPLE: DOS=dir
  217. FUNCTION: Executes the AmigaDOS command on the right of the = sign.
  218.           Also prevents the default prompt from appearing.
  219.           Note: this is not the same as the COMMAND keyword.
  220.           This executes as the Tooltypes are being read. COMMAND waits
  221.           until after the Tooltypes are read (and therefore all the input
  222.           prompts have been done.)
  223.           Note that COMMAND should always be used for commands that set
  224.           things, like the AmigaDOS command "path". This is because
  225.           if DOS is used, the setting will be "forgotten" when the
  226.           program or batch file is executed.
  227.           The DOS keyword is handy for displaying directories before
  228.           an input PROMPT where a file is requested. (see example below)
  229.  
  230. EXAMPLE USAGE:
  231.  
  232.         FILETYPE=CLIRUN
  233.         MESSAGE=Here are the files available:
  234.         DOS=dir #?.pic
  235.         MESSAGE=
  236.         PROMPT=Choose a file to display
  237.  
  238.      This could be used to show the choices available for a file prompt.
  239.  
  240.  
  241. ---------------------------------------------
  242.  
  243. KEYWORD: ASSIGN
  244. EXAMPLE: ASSIGN=music
  245. FUNCTION: Adds an assign command to the list of commands to
  246.           do after the Tooltypes are read and
  247.           before the program or batch file is run.
  248.           This assign command assigns the name on the right side
  249.           of the = sign to the directory the program or batch file is in.
  250.           Also prevents the default prompt from appearing.
  251.  
  252. EXAMPLE USAGE:
  253.  
  254.         FILETYPE=CLIRUN
  255.         ASSIGN=music
  256.         PROMPT=Enter music file to play
  257.  
  258.         If the program here was in a directory named df0:x the resulting
  259.         assign command would be
  260.         assign music: df0:x
  261.  
  262.         This is useful for programs that look for files in a fixed
  263.         device name (music in this example)
  264.  
  265. ---------------------------------------------
  266. KEYWORD: 
  267. EXAMPLE: 
  268. FUNCTION: 
  269. EXAMPLE USAGE:
  270. ---------------------------------------------
  271.  
  272. How to use the Info Item to edit the Tooltypes:
  273.  
  274. Returning to the link example, suppose you weren't happy with the
  275. default input prompt and wanted to take advantage of the ToolType
  276. KEYWORDS to customize the input prompt. (Note that I assume here
  277. that the Tooltype entries for the icon for link are blank initiallly)
  278.  
  279. - Single click on the link program's icon, and select the Info item
  280.   from the Workbench menu.
  281.  
  282. - Click on the ADD gadget in the TOOL TYPES box.
  283.  
  284. - Click in the box to the left of the ADD gadget and type: 
  285.     FILETYPE=CLIRUN
  286.   and press RETURN
  287.  
  288. - Click on ADD again, and type:
  289.     PROMPT=Enter name of file to link
  290.   and press RETURN
  291.  
  292. - Click on the SAVE gadget.
  293.  
  294. - You should now be able to double-click on the link icon and get
  295.   the "Enter name of file to link" prompt instead of the default prompt.
  296.  
  297. Info Gadgets for tooltype editing:
  298.  
  299. The /\ and \/ gadgets  move up and down through the list.
  300. The DEL gadget deletes the line shown in the box.
  301. The ADD gadget inserts a line after the one shown in the box.
  302.  (Note that there seems therefore to be no way to insert a line
  303.  before the first line)
  304.  
  305.  
  306. Limitations:
  307.  
  308. - Up to 500 characters can be in the command sequence that both the
  309.   COMMAND and ASSIGN  KEYWORDS add to. The commands
  310.   that CliRun itself always adds, like cd and stack also use up
  311.   some of these 500 characters.
  312.  
  313. - The first 20 lines of Tooltypes will be used by CliRun. Each line
  314.   can be up to 127 characters long.
  315.  
  316. - Up to 100 characters can be in the argument string that either
  317.   the PROMPT and ADD KEYWORDS add to, or the default prompt sets.
  318.  
  319. - Up to 20 programs or batch files can be selected at once.
  320.  
  321.  
  322. Notes: 
  323.  
  324. 1. If you get a message about the stack size being too small,
  325.    try increasing the stack size (as described above).
  326.    Because Clirun "inherits" the stack size of the icon
  327.    you double-click on, and because clirun needs a stack size
  328.    of at least 4000, you should set the stack size to at
  329.    least 4000, or you can single-click on the icon you made,
  330.    hold down the shift key, and then double-click on the Clirun
  331.    icon (this prevents Clirun from inheriting the stack size
  332.    of the program you're trying to run)
  333.  
  334. 2. If the program fails, you may find yourself at a CLI style
  335.    prompt. (like 1> or 2> , etc.)
  336.    If this happens, just type endcli and press RETURN to continue.
  337.  
  338. 3. When you just get the default prompt when you're running a program with
  339.    CliRun:
  340.    If you don't know what the inputs are for the program
  341.    you are trying to run, just press RETURN when prompted for them.
  342.    Most program tell you what the proper usage format is
  343.    when they receive no inputs (and some require none).
  344.    You can then run the program again after you've read the
  345.    message telling how to use the program.
  346.  
  347.    Note also that some programs give instructions when you enter
  348.    a ? as the input. (Just type:  ?  at the prompt).
  349.  
  350.    If, for example, you double-clicked on an icon you made, (called setlace)
  351.    and just hit RETURN when asked for the inputs,
  352.    and setlace said:
  353.  
  354.    usage: setlace <on/off>
  355.  
  356.    you would know to type either on or off
  357.    at the input prompt the next time you ran setlace.
  358.  
  359. 4. Clirun can run multiple programs. Just single-click on the icons one
  360.    at a time (hold down the shift key after the first one to avoid
  361.    cancelling the other selections) and then double-click on the
  362.    Clirun icon. The programs will then be run in the order selected.
  363.    For example, you might want to run a compiler and then a linker.
  364.  
  365. 5. For "Program mode", the following files are required in c:
  366.    (usually the c directory on the Workbench disk):
  367.  
  368.    cd
  369.    stack
  370.    run
  371.    endcli
  372.  
  373.    For "Batch File mode", these are required:
  374.  
  375.    cd
  376.    failat
  377.    stack
  378.    run
  379.    execute
  380.    endcli
  381.  
  382.    plus whatever the batch file uses
  383.  
  384. 6. Because of a bug in AmigaDos 1.2, if you run a program or batch
  385.    file from a disk with a blank name (a zero length name) clirun
  386.    will try to look for the program or batch file in the RAM disk,
  387.    and so won't find it.
  388.  
  389. 7. When you use CliRun to execute a batch file, the execute command that
  390.    CliRun uses will need to write to a directory named T on the disk
  391.    your batch file is on. If the directory doesn't exist, it will be
  392.    created. Therefore if your disk is write protected you will
  393.    get an error message.
  394.  
  395. 8. Blank lines in the tools types will make CliRun think it has reached
  396.    the end of the Tooltypes.
  397.  
  398. 9. If you want to temporarily disable a line in the Tooltypes, just add
  399.    an X to the start of the KEYWORD (like XPROMPT) , and CliRun will
  400.    ignore the line.
  401.  
  402. 10. If you are using the Tooltype KEYWORDS, watch out for programs that
  403.     might overwrite the FILETYPE= setting. For example, you might have
  404.     a batch file that works just fine, then edit it with Gizmoz Memopad,
  405.     and then find it starts coming up with the default prompt, ignoring
  406.     the Tooltype information. To add to the confusion, if you single click
  407.     on the batch file's icon, and use the Info item to look at the
  408.     Tooltype entries, everything looks ok!
  409.     What has happened is Memopad has overwritten the FILETYPE= entry
  410.     on the disk (or RAM disk), but you see what is in memory when you
  411.     use the Info item from the Workbench Menu. (Unless you close and
  412.     re-open the window the batch file's icon is in)
  413.     The fix is to single click on the batch file's icon, select the 
  414.     Info item from the Workbench menu,
  415.     and then click on the Info screen's SAVE gadget. This will fix
  416.     the FILETYPE= entry so things should now work as before.
  417.  
  418. 11. All the Tooltype keywords, plus TRUE, FALSE, and CLIRUN must be
  419.     in uppercase to be recognized.
  420.  
  421. Changes with Version 1.2:
  422.  
  423. 1. If the name of the project ends with ".bat" (must be lower case),
  424.    then CliRun will try to "execute" the file as a batch file, instead
  425.    of run it as a program. The "failat" level is set to 100 before
  426.    executing the batch file to keep the batch file from "crashing".
  427.    (If will just ignore errors).
  428.  
  429. Changes with Version 1.4:
  430.  
  431. 1. Tools Type KEYWORDS added.
  432.  
  433. 2. CliRun will now find a program that is in the RAM: disk.
  434.  
  435.  
  436. Known Bugs:
  437.  
  438. 1. See Note 6.
  439.  
  440. Please address questions, problems, and suggestions
  441. (especially for new Keywords) to:
  442.  
  443. Mike Lawrence
  444.  
  445. Tucson AZ:
  446. CCCC board: CC83
  447. NAD board: Mike Lawrence
  448.  
  449. National:
  450. CIS: 70030,160
  451. PLINK: OLR536
  452. BIX: mlawrence
  453. GEnie m.lawrence
  454.