[AmigaOS / ApolloOS Command Reference\Execute]EXECUTE
Format: EXECUTE <script> [{<arguments>}] Template: FILE/A Purpose: To execute a script with optional argument substitution. Path: C:EXECUTE Specification: EXECUTE is used to run scripts of AmigaDOS commands. The lines in the script are executed just as if they had been entered at a Shell prompt. If the s protection bit of a file is set and the file is in the search path, you only need to enter the filename - the EXECUTE command is not needed. You can use parameter substitution in scripts by including special keywords in the script. When these keywords are used, you can pass variables to the script by including the variable in the EXECUTE command line. Before the script is executed, AmigaDOS checks the parameter names in the script against any arguments given on the command line. If any match, AmigaDOS substitutes the values you specified on the command line for the parameter name in the script. You can also specify default values for AmigaDOS to use if no variables are given. If you have not specifed a variable, and there is no default specified in the script, then the value of the parameter is empty (no substitution is made). The permissible keywords for parameter substitution are explained below. Each keyword must be prefaced with a dot character (.). The .KEY (or .K) keyword specifies both keyword names and positions in a script. It tells EXECUTE how many parameters to expect and how to interpret them. In other words, .KEY serves as a template for the parameter values you specify. Only one .KEY statement is allowed per script. If present, it should be the first line in the file. The arguments on the .KEY line can be given with the /A and /K directives, which work the same as in an AmigaDOS template. Arguments followed by /A are required; arguments followed by /K require the name of that argument as a keyword. For example, if a script starts with .KEY filename/A it indicates that a filename must be given on the EXECUTE command line after the name of the script. This filename will be substituted in subsequent lines of the script. For example, if the first line of a script is: .KEY filename/A, TO/K You must specify a filename variable. The TO variable is optional, but if specified the TO keyword must be used. For example: 1> EXECUTE Script Textfile TO NewFile Before execution, AmigaDOS scans the script for any items enclosed by BRA and KET characters (< and >). Such items may consist of a keyword or a keyword and a default value. Wherever EXECUTE finds a keyword enclosed in angle brackets, it tries to substitute a parameter. However, if you want to use a string in your script file that contains angle brackets, you will have to define substitute "bracket" characters with the .BRA and .KET commands. .BRA <ch> changes the opening bracket character to <ch>, while .KET <ch> changes the closing bracket character to <ch>. For example: .KEY filename ECHO "This line does NOT print <angle> brackets." .BRA { .KET } ECHO "This line DOES print <angle> brackets." ECHO "The specified filename is {filename}." Would result in the following output: 1> EXECUTE script TestFile This line does NOT print brackets. This line DOES print <angle> brackets. The specified filename is TestFile. The first ECHO statement causes AmigaDOS to look for a variable to substitute for the <angle> parameter. If no argument was given on the EXECUTE command line, the null string is substituted. The .BRA and .KET commands then tell the script to use braces to enclose parameters. So, when the second ECHO statement is executed, the angle brackets will be printed. The third ECHO statement illustrates that the braces now function as the bracket characters. When enclosing a keyword in bracket characters, you can also specify a default string to be used if a variable is not supplied on the command line. There are two ways to specify a default. The first way requires that you specify the default every time you reference a parameter. You must separate the two strings with a dollar sign ($). For example, in the following statement: ECHO "<word1$defword1> is the default for Word1." defword1 is the default value specified for word1. It will be printed if no other variable is given for word1. However, if you want to specify this default several times in your script, you would have to use <word1$defword1> each time. The .DOLLAR <ch> command allows you to change the default character from $ to <ch>. (You can also use .DOL <ch>.) For example: .DOL # ECHO "<word1#defword1> is the default for Word1." The second way to define a default uses the .DEF command. This allows you to specify a default for each specific keyword. For example: .DEF word1 "defword1" Assigns defword1 as the default for the word1 parameter throughout the script. The following statement: ECHO "<word1> is the default for Word1." Results in the same output as the previous ECHO statement: defword1 is the default for Word1. You can embed comments in a script by including them after a semicolon (;) or by entering a dot (.), followed by a space, then the comment..KEY
Argument template used to specify the format of arguments; may be abbreviated to .K.DOT <ch>
Change dot character from . to <ch>.BRA <ch>
Change opening "bracket" character from < to <ch>.KET <ch>
Change closing "bracket" character from > to <ch>.DOLLAR <ch>
Change default character from $ to <ch>; may be abbreviated to .DOL.DEF <keyword> <value>
Give default to parameter.<space>
Comment line.\
Blank comment line When you EXECUTE a command line, AmigaDOS looks at the first line of the script. If it starts with a dot command, AmigaDOS scans the script looking for parameter substitution and builds a temporary file in the T: directory. If the file does not start with a dot command, AmigaDOS assumes that no parameter substitution is necessary and starts executing the file immediately without copying it to T:. If you do not need parameter substitution, do not use dot commands as they require extra disk accesses and increase execution time. AmigaDOS provides a number of commands that are useful in scripts, such as IF, ELSE, SKIP, LAB, and QUIT. These commands, as well as the EXECUTE command, can be nested in a script. That is, a script can contain EXECUTE commands. To stop the execution of a script, press Ctrl+D. If you have nested script files, you can stop the set of EXECUTE commands by pressing Ctrl+C. Ctrl+D only stops the current script from executing. The current Shell number can be referenced by the characters <$$>. This is useful in creating unique temporary files, logical assignments, and PIPE names. Example 1: Assume the script List contains the following: .K filename RUN COPY <filename> TO PRT: + ECHO "Printing of <filename> done" The following command: 1> EXECUTE List Test/Prg Acts as though you had entered the following commands at the keyboard: 1> RUN COPY Test/Prg TO PRT: + 1> ECHO "Printing of Test/Prg done" Example 2: Another example, Display, uses more of the features described above: .Key name/A IF EXISTS <name> TYPE <name> NUMBER ; If file is in the given directory ; type it with line numbers. ELSE ECHO "<name> is not in this directory" ENDIF The command: 1> RUN EXECUTE Display Work/Prg2 Should display the Work/Prg2 file, with line numbers on the screen, if it exists on the current directory. If the file is not there, the screen displays an error message. Because of the /A, if a filename is not given on the command line after Display, an error will occur. See also: IF SKIP FAILAT LAB ECHO RUN QUIT