AmigaOS Manual: AmigaDOS Using Scripts

Using Scripts

Script files are text files that contain lists of commands for repetitive or complicates tasks or for performing the same operation on multiple files. This chapter includes the following information about script files:

• Understanding scripts
• Scripting characters
• Script commands
• Condition flags
• Debugging script files
• Environment variables

Understanding Scripts

A script is a text file that contains a series of commands. Using scripts is a way to automate complex or repetitive tasks, especially those that you need to perform regularly. A script can perform virtually any operation normally done one command at a time, including working with programs and data files; performing calculations; and operating interactively, accepting and displaying information. Essentially a script is a small program that can be easily edited.

To create a script, follow these steps:

1. Open a text editor, such as ED, that saves files in ASCII format.
2. In the text editor, enter the script commands in the sequence in which they are to be performed.
3. Save the file. The S: directory is usually used for script files, but you can store a script anywhere.

You can then run the script in the Shell, entering the EXECUTE command followed by the full path to the script.

Note
You can avoid having to use the EXECUTE command and the full path by setting the script's s protection bit. Enter the command PROTECT <script> +s, substituting the path to the script. When the s bit is set, enter only the name of the script to execute it.

It is possible to run a script that has a Workbench project icon by using the ICONX command as the default tool. See ICONX for more information on the ICONX command.

Kinds of Scripts

There are several kinds of scripts that you can use on the Amiga, including scripts of AmigaDOS commands, scripts of ARexx commands, and scripts of ED commands. For details on writing ARexx scripts, see the ARexx User's Guide. See the ED section for information on ED command scripts.

When to Use ARexx

You can create both AmigaDOS and ARexx scripts on the Amiga. These scripts are not mutually exclusive; ARexx commands can appear in AmigaDOS scripts and vice versa. However, different tasks are appropriate to each.

Unlike ARexx, AmigaDOS is not a general purpose programming language. AmigaDOS is oriented toward basic file management and system configuration tasks. ARexx is meant to be used for accomplishing tasks more complex than simple branching and conditional execution.

Simple Scripts

A script can be as simple as a series of paths, telling the Amiga to run certain programs. A User-startup file is a good example of a simple script. You can add various configuration commands, such as an ADDBUFFERS statement, to such a script without worrying about affecting program flow or using error checking. For more information about the User-startup file, see Appendix D.

Automatic Scripts

You can automatically generate scripts using the LIST command. LIST has an LFORMAT option that allows you to modify its output to include any text you wish along with the usual LIST output. This text can be a command and command keywords, with the file name LISTed appearing as an argument to the command. If you list the contents of a directory this way, redirecting the output to a file, you have a ready-made script that applies a command to the contents of that directory.

When an operation on multiple files is too involved ot be done with a single pattern matching command, use an automatically generated script to execute the command for each of the files. For example, an operation that renames a series of files, giving the current file names the same extension, cannot be done with a single pattern-matching RENAME. See the LIST section for information on LIST's LFORMAT option and the AmigaDOS command examples for an illustration of this technique.

Special Script Characters

The semicolon, back apostrophe, dollar, double dollar, and question mark are special characters that are used primarily in scripts to add comments, execute commands from within strings, introduce environment variables, reference the current Shell number, and accept input redirection.

Semicolon (;)

Semicolons add comments to command lines. All characters to the right of a semicolon are ignored, allowing you to place descriptive comments on the same line with AmigaDOS commands. For example:

ASSIGN T: RAM: t ;set up T: directory for
                 ;scripts

Comments can continue onto additional lines if they are too long to fit on one line. New lines must begin with a semicolon and should be indented to the same level as the previous comment for clarity.

Back Apostrophe (`)

Back apostrophes are used to execute commands from within a string. If a string containing a command enclosed in back apostrophe is printed, the enclosed command is executed. For example:

1> ECHO "The date and time are: `date`"

prints "The date and time are: " followed by the output of the DATE command. When a command such as DIR that produces multiple lines of output is embedded in an ECHO statement, the output is not properly formatted; all of it appears on one line.

Note
Commands that refer to the current directory do not work correctly when invoked from within a string with the back apostrophe. Using the back apostrophe automatically sets up a temporary sub-shell for that command only. References to a current directory access the sub-shell's directory.

Dollar ($)

The dollar sign is used in two ways: as an operator that introduces an environment variable (which also works outside of a script) and in a bracketed statement to separate a variable value from a default value.

For example, with an environment variable:

1> ECHO "Current Kickstart version: $Kickstart"
Current Kickstart version: 40.70

As a default separator in a script:

COPY foo.library TO <LIBS:$userlibdir>

You can change the character that provides this function from the dollar sign to something else with the .DOLLAR scripting keyword.

Double Dollar (<$$>)

A bracketed double dollar sign (<$$>) substitutes the current process number. You can reference the current Shell number by the double dollar sign character string <$$> including brackets since it always returns the current process number as a string. When you create temporary files in a multitasking environment, it is essential for these files to have unique names so that processes do not interfere with each other. Adding the <$$> string to file names creates unique names for temporary files, logical assignments, and PIPEs. A .KEY statement is required in any script that uses <$$>. .KEY is described below. To avoid conflict with the redirection arguments, <$$>'s angle brackets can be redefined using the .BRA and .KET commands. .BRA and .KET are described below.

Question Mark (?)

The question mark, when used as a separate argument in a command, instructs the command to accept input redirection.

Script Commands

Any AmigaDOS command can be used in a script, however, there are some commands that are used only in scripts. You can do the following with script commands:

• Parameter substitution
• Enter arguments on the command line
• I/O redirection
• Specify default strings
• Enter comments
• Nest commands within scripts
• Create interactive scripts
• Create scripts that repeat commands

Script-Specific Commands

The following commands are typically used only with scripts:

Script Command	Meaning
ASK	Asks for user input.
ECHO	Prints a string.
ELSE	Allows an alternative in a conditional block.
ENDIF	Terminates an IF block.
ENDSKIP	Terminates a SKIP block.
EXECUTE	Executes a script with optional argument substitution.
FAILAT	Sets the failure condition of the script.
IF	Handles conditional operations.
LAB	Specifies a label; used with SKIP.
QUIT	Specifies a return code and exits a script.
REQUESTCHOICE	Allows AmigaDOS and ARexx scripts to use system requesters to ask the user for feedback.
REQUESTFILE	Allows AmigaDOS and ARexx scripts to use the system file requester.
SKIP	Skips the execution of the script ahead or backwards to the specified label.
WAIT	Waits for the specified time.

Dot Commands

Dot commands are keywords beginning with a period that are used only in scripts. Special dot command lines included in your script can specify places for parameter substitution. Enter these parameters as arguments to the EXECUTE command. The following table lists the dot commands.

Dot Command	Meaning
.KEY	Argument template used to specify the format of arguments; can be abbreviated to .K. Separate arguments for .KEY with commas. Do not use spaces. See Allowing Arguments more information on using .KEY.
.DOT <ch>	Change dot character from . to <ch>, where <ch> is the character that is substituted.
.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>; can be abbreviated to .DOL.
.DEF <keyword> <value>	Give default to parameter.
.<space>	Comment line. Be sure to include the space following the dot to avoid producing an error. Note that the preferred method for entering comments is with a semicolon (;).
.	Blank comment line. Be sure there is nothing else on the line with the dot to avoid producing an error.

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 the parameter substitutions described above 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: Because dot commands require extra disk accesses and increase execution time, do not use them if you do not need parameter substitution.

Allowing Arguments

The .KEY (or .K) keyword specifies both keyword names and positions in the command line. It teills EXECUTE the number of parameters and how to interpret them. Only one .KEY statement is allowed per script; if present, it should be the first line in the file. Any script containing <$$> must also contain a .KEY statement.

The arguments on the .KEY line can be given with the /A and /K directives, which work the same as in an AmigaDOS template. See Templates for all the options available. Arguments followed by /A are required; arguments followed by /K require the name of that argument as a keyword. Use commas to separate multiple arguments in the .KEY line, not spaces.

For example, if a script starts with .KEY filename/A it indicates that a file name must be given on the EXECUTE command line after the name of the script. This file name is substituted in subsequent lines of the script. For example, if you have a script called Newtext and the first line is:

.KEY filename/A,TO/K

you must specify a file name variable. The TO variable is optional, but, if specified, the TO keyword must be used. The following is an acceptable way to run Newtext:

1> EXECUTE Newtext Textfile TO NewFile

Substitution

Before execution, AmigaDOS scans the script for any items enclosed by .BRA and .KET characters (< and > by default). Such items can consist of a keyword or a keyword and a default value. EXECUTE tries to substitute a parameter when it finds a keyword enclosed in angle brackets. However, if you want to use a string in your script file that contains angle brackets or if your script uses angle brackets for redirection of input/output, you must 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, the following script called Demo uses these lines:

.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)."

1> EXECUTE Demo TestFile

which results in the following output:

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. Since no argument named "angle" is given on the EXECUTE command line, the null string is substituted. The .BRA and .KET commands tell the script to use braces instead of angle brackets to enclose parameters. When the second ECHO statement is executed, the angle brackets - with their special meaning removed - are printed as normal text. The third ECHO statement illustrates that he braces now function as the bracket characters.

Redefine <$$>'s angle brackets with .BRA and .KET to avoid redirection conflicts.

Defaults

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. Defaults can be specified in two ways: every time you reference a parameter or using the .DEF command.

If 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 is printed if no other variable is given for word1. However, if you want to specify this default several times in your script, you must use <word1$defword1> each time.

Defining a default using the .DEF command allows you to specify a default for each specific keyword. For example:

.DEF word1 "defword1"

assigns defword1 as the default for the word1 parameter through 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.

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."

Comments

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. Blank lines are accepted and ignored within scripts.

Note
We recommend that you use the semicolon method for entering comments to avoid errors caused by omitting the space following the dot.

Nesting Commands

AmigaDOS provides a number of commands that can be used in scripts, such as IF, ELSE, SKIP, LAB, and QUIT. These commands, as well as the EXECUTE command, can be nested in a script.

To stop the execution of the current script, press Ctrl+D. If you have nested script files, you can stop the set of EXECUTE commands by pressing Ctrl+C.

Example 1

Assume the script Printit contains the following:

.KEY filename
RUN COPY <filename> TO PRT: +
ECHO "Printing of <filename> done"

The following command:

1> EXECUTE Printit Test/Prg

responds as though you entered the following commands at the keyboard:

1> RUN COPY Test/Prg TO PRT: +
ECHO "Printing of Test/Prg done"

Note the use of the plus sign at the end of the first line. If you press Return after a plus sign, the RUN command also executes the command in the second line when the first command is finished.

Example 2

Another example, Show, 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> EXECUTE Show Work/Docfile

displays the Work/Docfile file, with line numbers on the screen, if Show exists in the current directory. If the file is not there, the screen displays an error message. The /A requires a file name be given on the command line after Show or an error occurs.

Interactive Script Files

You can create scripts that pause to request information from the user before continuing. The REQUESTCHOICE or REQUESTFILE commands for creating standard Amiga requesters let you use the familiar Workbench approach to get a user's response. This can accommodate variable conditions with a single script. For example, the following script copies six files from a hard drive to a floppy disk. When the six files are copied, the script asks for confirmation to continue the copy, allowing time to insert a new floppy disk into the disk drive if required.

COPY 2k.eps DF0:
COPY 2m.eps DF0:
COPY 2n.eps DF0:
COPY 2o.eps DF0:
COPY 2t.eps DF0:
COPY 2v.eps DF0:
ECHO "Chapter 2 files copied."
ASK "Continue Copy?"
IF WARN
   COPY 3a.eps DF0:
   COPY 3c.eps DF0:
   COPY 3g.eps DF0:
   COPY 3aa.eps DF0:
   COPY 3bb.eps DF0:
   COPY 3ff.eps DF0:
ENDIF

At the "Continue Copy?" prompt, press Y to copy the remaining files to a disk in DF0:. Press N or Return to terminate the copy process.

Repeating Commands

You can create scripts that repeat the same command, substituting a different file name in each command line. For example, to rename eight files in one operation you could create the following script:

RENAME section1 chap1.1
RENAME section2 chap1.2
RENAME section3 chap1.3
RENAME section4 chap1.4
RENAME section5 chap1.5
RENAME section6 chap1.6
RENAME section7 chap1.7
RENAME section8 chap1.8

This example assumes that the files are in the Shell's current directory. If not, you must specify the complete path to each file.

Scripts such as this can often be generated automatically by using the LFORMAT option of the LIST command.

Ending a Script

In general, scripts end when they have completed all the specified commands. Return codes report whether executed commands succeeded or failed. You can include a QUIT command in a script to end it, but unless there is a specific condition under which you wish the script to end, including QUIT is not necessary. You can stop a script by pressing Ctrl+D in the window in which it is running.

Condition Flags

Conditions flags indicate the condition upon which a particular command stops running. Then commands are executed, return codes report if they succeeded or failed. The standard return codes are:

0	The command succeeded.
5	Represents a caution, usually indicating that some type of error occurred. The error, however, was not serious enough to abort the command. If the command is part of a script, subsequent commands are executed. Several commands set the condition flag to WARN to specify a non-error command outcome.
10	Represents an error. A return code of 10 aborts a script, unless a higher limit has been set with the FAILAT command.
20	Represents a failure.

Other values may be returned by applications. In such cases, the previously listed values are considered lower limits of the specified condition as follows:

0-4	No Error
5-9	Warn
10-19	Error
20 or above	Failure

Some commands, such as ASK and SEARCH, use the WARN flag to signal certain conditions for testing in scripts.

For example, in the COPY script on page 5-12, the ASK command requests confirmation to continue the copy:

ASK "Continue Copy?"
IF WARN
   COPY 3a.eps DF0:

Pressing y sets the condition flag to 5 (WARN), executing the IF block. Pressing N or Return sets the condition flag to 0 (NO ERROR), aborting the script because the IF statement did not receive the specified return code.

Debugging Script Files

If a script command fails, you may see one of the following error messages:

Unknown command <command>

This occurs when you have entered a command that is unrecognizable.

<command> failed returncode 20

This occurs when a valid command's arguments are entered incorrectly. Enter WHY at the prompt after the error appears for more information about the error.

If an error appears, use your text editor (ED, MEmacs or a word processor that can save ASCII files) to correct the line containing that command.

Inserting the line SET ECHO ON within the script assists in locating errors. This causes all subsequent command lines to be ECHOed to the screen as they are executed. Error messages are printed after the system tries to execute the incorrect command. To disable SET ECHO, enter SET ECHO OFF or delete the SET ECHO ON line.

Using Environment Variables

Environment variables are used in scripts to hold status and string information. Variables can be substituted for strings that are long and tedious to enter. Changing the value of the variable is more convenient that re-editing the script when the value for the string changes.

Environment variables are maintained by AmigaDOS rather than individual applications. These variables can be accessed and used by different programs or scripts. When a variable name preceded by a dollar sign ($) is encountered in a script, the variable name is replaced by the value assigned to the variable. The line is then executed as if you had originally entered the value.

For example, AmigaDOS maintains the variables Workbench and Kickstart that track the current version numbers of your Workbench and Kickstart software. Running the following line prints the Workbench version number.

ECHO "Amiga Workbench Disk. Release Version $Workbench"

Some variables, such as the Workbench and Kickstart variables, have already been created. The Shell responds to the ECHO variable and maintains the PROCESS, RC, and RESULT2 local variables automatically. These are explained as follows:

ECHO	When the value of this variable is ON, commands are echoed to the screen when they are executed. When it is OFF (the default), commands are not echoed.
PROCESS	Holds the process (CLI) number.
RC	Holds the condition flag return code of the last command executed (0, 5, 10, or 20). This is often used in scripts.
RESULT2	Holds the secondary return code, or error number, that explains why a command failed.

For example, if you include the SET ECHO ON command at the beginning of a script, each line of the script is echoed to the screen as it is executed.

When an environment variable is given a numeric value, it can be used in calculations and expressions. For example, if you assign the value 9 to a variable called nine, $nine in EVAL expressions. For example:

1> SETENV nine 9
1> EVAL 5 * $nine
45

EVAL is an AmigaDOS command that evaluates integer and Boolean expressions. However, it does not work on environment variables that have a fractional numeric value; be sure to use whole numbers when using EVAL.

Creating Environment Variables

Environment variables can be created with the SET and SETENV commands.

SET

SET creates local variables, which are recognized only by the Shell in which they are created and any Shells created by that original Shell. For example, if you are creating an environment variable in your Shell window, then execute the NEWSHELL command through the Execute Command menu item, the new Shell does not recognize any of the variables created in your original Shell. However, if you open a second Shell by entering the NEWSHELL command in your original Shell, the new Shell recognizes any variables created in its parent Shell.

Using the GET command displays the value associated with a variable; using the UNSET command removes variables.

SETENV

SETENV creates global variables recognized by all Shells. Global variables are stored as small ASCII files in the ENV: directory. GETENV displays the value associated with global variables and UNSETENV removes global variables. Use global variables only when certain values must be available to other processes.

Some applications use environment variables. For example, the MORE program supports an Editor environment variable. You can use SETENV to specify MEmacs as your editor of choice:

1> SETENV Editor Extras:Tools/MEmacs

Be sure to specify the complete path to MEmacs.

If you use MORE to view the contents of the User-startup file, pressing Shift+E automatically transfers to a MEmacs screen with the User-startup loaded and ready for editing.