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.*/

ARG

ARG [template] [,template...]

ARG is a shorthand form for the PARSE UPPER ARG instruction. It retrieves one or more of the argument strings available to the program and assigns values to the variables in the template. The number of argument strings available depends on whether the program was invoked as a command or a function. Command invocations normally have only one argument string, but functions may have up to 15. The argument strings are not altered by the ARG instruction. ARG returns uppercase letters. For example:

ARG first,second /*Retrieve arguments*/

The structure and processing of templates is described briefly with the PARSE instruction.

BREAK

BREAK

The BREAK instruction is used to exit from the range of a DO instruction or from within an INTERPRETed string. It is valid only in these contexts. If used within a DO statement, BREAK exits from the innermost DO statement containing the BREAK. This contrasts with the similar LEAVE instruction, which exits only from an iterative (repeating) DO. For example:

DO /*Begin block*/
 IF i>3 THEN BREAK /*Finished?*/
 a = a + 1
 y.a = name
 END /*End block*/

CALL

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

The CALL instruction is used to invoke an internal or external function. The function name is specified by the symbol or string token. Any expressions that follow are evaluated and become the arguments to the called function. The value returned by the function is assigned to the special variable RESULT. It is not an error if a result string is not returned. In this case the variable RESULT is DROPped (becomes uninitialized).

The linkage to the function is established dynamically at the time of the call. ARexx follows a specific search order in attempting to locate the called function. For example:

CALL CENTER name, length+4, '+'

CENTER is the called function. The expressions will be evaluated and passed as arguments to CENTER.

DO

DO [[var=exp] | [exp] [TO exp] [BY exp]] [FOR exp] [FOREVER] [WHILE exp | UNTIL exp]

The DO instruction begins a group of instructions executed as a block. The range of the DO instruction includes all statements up to and including an eventual END instruction.

If not subkeywords follow the DO instruction, the block is executed once. Subkeywords can be used to iterate the block until a termination condition occurs. An interative DO instruction is sometimes called a loop since ARexx "loops back" to perform the instruction repeatedly. The various parts of the DO instruction are:

• An initializer expression of the form "variable=expression" defines the index variable of the loop. The expression is evaluated when the DO range is first activated and the result is assigned to the index variable. On subsequent iterations an expression of the form "variable = variable + increment" is evaluated, where the increment is the result of the BY expression. If specified, the initializer expression must precede any of the other subkeywords.

• The expression following a BY symbol defines the increment to be added to the index variable in each subsequent iteration. The expression must yield a numeric result, which may be positive or negative and need not be an integer. The default increment is 1.

• The result of the TO expression specifies the upper (or lower) limit for the index variable. At each iteration the index variable is compared to the TO result. If the increment (BY result) is positive and the variable is greater than the limit, the DO instruction terminates and control passes to the statement following the END instruction. The loop also terminates if the increment is negative and the index variable is less than the limit.

• The FOR expression must yield a positive whole number when evaluated and specifies the maximum number if iterations to be performed. The loop terminates when this limit is reached, irrespective of the value of the index variable.

• The initializer BY, TO and FOR expressions are evaluated only when the instruction is first activated, so the increment and limits are fixed through the execution. A limit is not required. For example, the instruction "DO i=1" will simply count away forever.

• The FOREVER keyword can be used if an iterative DO instruction is required but no index variable is necessary. The loop will be terminated by a LEAVE or BREAK instruction contained within the loop.

• The WHILE expression is evaluated at the beginning of each iteration and must result in a Boolean value. The iteration proceeds if the result is 1 (true); otherwise, the loop terminates.

• The UNTIL expression is evaluated at the end of each iteration and must result in a Boolean value. The instruction continues with the next iteration if the result is 0 (false), and terminates otherwise. (WHILE and UNTIL are mutually exclusive.)

Program 12. Iteration.rexx

/*Examples of DO*/
LIMIT = 20; number = 1
DO i=1 to LIMIT for 10 WHILE number < 20
   number = 1 * nuzmber
   SAY "Iteration" i "number=" number
   END
number = number/3.345; i = 0
DO number for LIMIT/5
   i = i + 1
   SAY "Iteration" i "number=" number
   END

The output is shown with comment lines for explanation. The comments would not appear on your screen.

Iteration 1 number = 1 /*1 * 1 = 1*/
Iteration 2 number = 2 /*2 * 1 = 2*/
Iteration 3 number = 6 /*3 * 2 = 6*/
Iteration 4 number = 24 /*4 * 6 = 24*/
Iteration 1 number = 7.17488789 /*24/3.345 = 7.17488789*/
Iteration 2 number = 7.17488789 /*number doesn't change*/
Iteration 3 number = 7.17488789 /*limit/5 = 20/5 = 4*/
Iteration 4 number = 7.17488789 /*operation repeats 4 times*/

Note
If a FOR limit is also present, the initial expression is still evaluated, but the result need not be a positive integer.