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. For more information on the ICONX command, see Chapter 6.

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 of Chapter 4 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; under AmigaDOS Release 2 and beyond, 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 in Chapter 6 for information on LIST's LFORMAT option that the examples in Chapter 8 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 on page 5-7. To avoid conflict with the redirection arguments, <$$>'s angle brackets can be redefined using the .BRA and .KET commands. .BRA and .KET are described on page 5-8.

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 page 5-7 for 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. (Templates are described in Chapter 6.) 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.