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.