[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