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
Converted from AmigaGuide to HTML by Jaruzel