Club Amiga de Montreal - CAM/CAM_CD_1.iso/files/056.lha/Clirun.doc

Text File | 1986-11-20 | 15.2 KB | 454 lines

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 <filename>
where <filename> 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 <on/off>

   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