AmigaOS Manual: ARexx Instructions

An instruction clause begins with the name of a particular instruction and tells ARexx to perform a certain action. This chapter provides an alphabetical list of the instructions available in ARexx.

Each instruction keyword may be followed by one or more subkeywords, expressions, or other instruction-specific information. Instruction keywords and subkeywords are recognized only in this specific context. This allows the same keywords to be used in a different context as variables or function names. An instruction keyword cannot be followed by a colon (:) or an equals (=) operator.

Syntax

The syntax for each instruction is shown to the right of the keyword heading. The conventions used in the syntax are shown in Table 4-1:

Table 4-1. Syntax Conventions

Convention	Definition
KEYWORD	All keywords and subkeywords are shown in uppercase letters
| (vertical bar)	Alternative selections are separated by a vertical bar
{ } (braces)	Required alternatives are enclosed by braces
[ ] (brackets)	Optional instruction parts are enclosed in brackets

Note
The syntax conventions do not apply to the specifications following the keyword heading. They only apply to the syntax shown to the right of the instruction keyword.

For example, the format for the CALL instruction is:

CALL {symbol | string} [expression] [,expression,...]

You must supply a symbol or a string as an argument. The vertical bar identifies the alternative selections, and the braces indicate that the use of an argument is required. The specification of an expression is optional, as indicated by the brackets.

Examples are given at the end of the instruction specification. Explanations or evaluations of the examples are shown as ARexx comments /*...*/.

Alphabetical Reference

This section provides an alphabetical list of ARexx's built-in instructions. The syntax of each instruction is shown to the right of the instruction keyword.

ADDRESS

ADDRESS [[symbol | string] | [VALUE][expressions]] ==

This instruction specifies a host address for commands issued by the interpreter. A host address is the name of an application's message port to which ARexx commands are sent. ARexx maintains two host addresses: a current and a previous value. Whenever a new host address is supplied, the previous address is lost and the current address becomes the previous one. These host addresses are part of a program's storage environment and are preserved across internal function calls. The current address can be retrieved with the built-in function ADDRESS().

The ADDRESS keyword alone interchanges the current and previous hosts. Repeated execution will toggle between the two host addresses.

ADDRESS {string | symbol]} specifies that the new host address is the string or symbol. The value of the string or symbol is the token itself. Message port names are case-sensitive. The appropriate syntax for a program command to a message port named MyPort is:

ADDRESS 'MyPort'

Omit the single quotes around MyPort and ARexx looks for the message port MYPORT and generates an error. The current host address becomes the previous address. An expression specified after a string or symbol is evaluated and the result is issued to the specified host. No changes are made to the current or previous address strings. This provides a convenient way to issue a single command to an external host without disturbing the current host addresses. The return code from the command is treated as it would be from a command clause.

If ADDRESS [VALUE] expression is specified. ARexx uses the result of the expression as the new host address, and the current address becomes the previous address. The VALUE keyword may be omitted if the first token of the expression is not a symbol or string. For example:

ADDRESS /*Swap current and previous address.*/
ADDRESS edit /*The new host address is EDIT.*/
ADDRESS edit 'top' /*Move to the top.*/
ADDRESS VALUE edit in /*Compute a new host address.*/