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.

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

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

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.

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

The specified variable symbols are reset to their unintialized state, in which the value of the variable is the variable name itself. It is not an error to DROP a variable that is already uninitialized. DROPping a stem symbol is equivalent to DROPping the values of all possible compound symbols derived from the stem. For example:

a = 123 /*Assign a value to a */
DROP a b /*DROP (remove) the values from A and B*/
SAY a b /*Results in A B.*/

The ECHO instruction is a synonym for the SAY instruction. It displays the expression result on the console. For example:

ECHO "you don't say"

The ELSE instruction provides the alternative conditional branch for an IF statement. It is valid only within the range of an IF instruction and must follow the conditional statement of the THEN branch. If the THEN branch isn't executed, the statement following the ELSE clause is performed.

ELSE clauses always bind to the nearest, preceding IF statement. It may be necessary to provide "dummy" ELSE clauses for the inner IF ranges of a compound IF statement to allow alternative branches for the outer IF statements. It is not sufficient to follow the ELSE with a semicolon or a null clause. Instead, the NOP (no-operation) instruction can be used. For example:

IF i > 2 THEN SAY `Really?'
ELSE SAY `I thought so'