Home Page The Club Computers News Links Glossary EYAWTK
Before Amiga Background ICS OCS ECS AGA ??? PPC
U-Boot SLB Linux Amiga OS Dual Boot Motherboards Peripherals Other
Initialisation Installation OS4 Updates About OS4 File Systems Networking Printing Other
Introduction File System Workbench Preferences Commands Error Msgs Miscellaneous

AmigaOS 4.0 - About OS4 - Commands

EXECUTE Internal
Purpose: To execute a script with optional argument substitution.
Format: EXECUTE <script> [{<arguments>}]
Template: FILE/A/F
Path: C:EXECUTE
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 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 specified a variable, and there is no default specified in the script, then the value of the parameter is empty (no substitution is made).

The permissable 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 statment 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 the filename variable. The TO variable is optional, but if specified the TO keyword must be used. For example: 3.OS4:> 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 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}."
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 specify 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 enables 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 enables 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.

.K Argument template used to specify the format of arguments; same as .KEY
.KEY Argument template used to specify the format of arguments; same as .K
.DOT <ch> Change dot character from '.' to <ch>
.BRA <ch> Change opening "bracket" from '<' to <ch>
.KET <ch> Change closing "bracket" from '<' to <ch>
.DOL <ch> Change default character from '$' to <ch>; same as .DOLLAR
.DOLLAR <ch> Change default character from '$' to <ch>; same as .DOL
.DEF <keyword> <value> Give default for 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: 3.OS4:> EXECUTE LIST Test/Prg acts as though you had entered the following commands at the keyboard: 3.OS4:> RUN Copy Test/Prg TO PRT: +
3.OS4:> ECHO "Printing of Test/Prg done"

Example 2:

Another example, Display, uses more of the features described previously.

.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: 3.OS4:> RUN EXECUTE Display Work/Prg2 should display the Work/Prg2 file, with line numbers on the screen, if it exists in the current directory. If the file is not therem 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


Return to Commands Selection

Disclaimer: Amiga Auckland have prepared the above information for the use of its members based on our experiences and as such is subject to revision at any time. Amiga Auckland cannot guarantee any of the information and cannot be held accountable for any issues that may result from using it.


Copyright 2006 Amiga Auckland Inc. All rights reserved.
Revised: February 9, 2006.