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.

DROP

DROP variable [variable ...]

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

ECHO

ECHO [expression]

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"

ELSE

ELSE [;] [conditional statement]

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'

END

END [variable]

The END instruction terminates the range of a DO or SELECT instruction. If the optional variable symbol is supplied, it is compared to the index variable of the DO statement (which must be iterative). An error is generated if the symbols do not match. For example:

DO i=1 to 5 /*Index variable is i*/
   SAY i
   END i /*End "i" loop*/

EXIT

EXIT [expression]

The EXIT instruction terminates the execution of a program. It is valid anywhere within a program. The evaluated expression is passed back to the caller as the function or command result.

The processing of the EXIT result depends on whether a result string was requested by the calling program and whether the current invocation resulted from a command or function call.

• If a result string was requested, the expression result is copied to a block of allocated memory and a pointer to the block is returned as the secondary result of the call.

• If the caller did not request a result string and the program was invoked as a command, an attempt is made to convert the expression result to an integer. This value is then returned as the primary result, with 0 as the secondary result. This allows the EXIT information to be interpreted as a return code by the caller.

For example:

EXIT /*No result needed*/
EXIT 10 /*An error return*/

IF

IF expression [THEN] [;] [conditional statement]

The IF instruction is used in conjunction with THEN and ELSE instructions to conditionally execute a statement. The result of the expression must be a Boolean value. If the result is 1 (True), the statement following the THEN symbol is executed. Otherwise, control passes to the next statement. The THEN keyword need not immediately follow the IF expression, but may appear as a separate clause.

The instruction is analyzed as "IF expression; THEN; statement". The expression following the IF statement establishes the test condition that determines whether subsequent THEN or ELSE clauses will be performed. Any valid statement may follow the THEN symbol. In particular, a "DO ... END;" group allows a series of statements to be performed conditionally. For example:

IF result < 0 THEN exit /*All done?*/

INTERPRET

INTERPRET expression

The INTERPRET command treats the expression as though it were a source statement block. The expression is evaluated and the result is executed as one or more program statements. The statements are considered as a group, as if surrounded by a "DO ... END" combination. Any statements can be included in the INTERPRETed source, including DO or SELECT instructions. The BREAK instruction can be used to terminate the processing of INTERPRETed statements.

An INTERPRET instruction activates a control range when it is executed, which serves as a boundary for LEAVE and ITERATE instructions. These instructions can only be used with DO loops defined within the INTERPRET. While it is not an error to include label clauses within the interpreted string, only those labels defined in the original program are searched during a transfer of control.

The INTERPRET instruction can be used to construct programs dynamically and then execute them. Program fragments may be passed as arguments to functions, which then INTERPRET the fragments. For example:

inst = `SAY' /*An instruction*/
INTERPRET inst hello /*. . . "SAY HELLO"*/

ITERATE

ITERATE [variable]

The ITERATE instruction terminates the current iteration of a DO instruction and begins the next iteration. Effectively, control passes to the END statement and then (depending on the outcome of the UNTIL expression) back to the DO statement. The instruction normally acts on the innermost iterative DO range. An error results if the ITERATE instruction is not contained within an iterative DO instruction.

If several nested ranges exist, the optional variable symbol specifies which DO range is to be exited. The variable is taken as a literal and must match the index variable of a currently active DO instruction. An error results if a matching DO instruction is not found. For example:

DO i=1 to 5
   IF i = 3 THEN ITERATE i
   SAY i
   END

LEAVE

LEAVE [variable]

LEAVE forces an immediate exit from the iterative DO range containing the instruction. An error results if the LEAVE instruction is not contained within an iterative DO instruction. If several nested ranges exist, the optional variable symbol specifies which DO range is to be exited. The variable is taken as a literal and must match the index variable of a currently active DO instruction. An error results if a matching DO instruction is not found. For example:

DO i = 1 to limit
   IF i > 5 THEN LEAVE /*Maximum iterations*/
   END

NOP

NOP

The NOP (NO-oPeration) instruction is provided to control the binding of ELSE clauses in compound IF statements. For example:

IF i = j THEN           /*First (outer) IF*/
   IF j = k THEN a = 0  /*Inner IF*/
      ELSE NOP          /*Binds to inner IF*/
   ELSE a = a + 1       /*Binds to outer IF*/

NUMERIC

NUMERIC {DIGITS | FUZZ} expression NUMERIC FORM {SCIENTIFIC | ENGINEERING}

• The NUMERIC instruction sets options relating to numeric precision and format. The numeric options are preserved when an internal function is called.

• The DIGITS expression option specifies the number of digits of precision for arithmetic calculations. The expression must evaluate to a positive whole number.

• The FUZZ expression option specifies the number of digits to be ignored in numeric comparison operations. This must be a positive whole number, less than the current DIGITS setting.

• The FORM SCIENTIFIC option specifies that numbers that require exponential notation be expressed in scientific notation.

• The exponent is adjusted so that the mantissa for non-zero number is between 1 and 10. This is the default format.

• The FORM ENGINEERING option selects engineering format for numbers that require exponential notation. Engineering format normalizes a number so that its exponent is a multiple of three and the mantissa (if not 0) is between 1 and 1000.

NUMERIC DIGITS 12 /*12 digits of precision*/
NUMERIC FORM SCIENTIFIC /*Result in scientific notation*/

OPTIONS

OPTIONS [FAILAT expression]
OPTIONS [PROMPT expression]
OPTIONS [RESULTS]
OPTIONS [CACHE]

The OPTIONS instruction is used to set various internal defaults. The FAILAT expression sets the limit at or above which command return codes will be signaled as errors. It must evaluate to an integer value. The PROMPT expression provides a string to be used as the prompt with the PULL (or PARSE PULL) instruction. The RESULTS keyword indicates that the interpreter should request a result string when it issues command to an external host.

The internal options controlled by this instruction are preserved across function calls, so an OPTIONS instruction can be issued within an internal function without affecting the caller's environment. If no keyword is specified with the OPTIONS instruction, all controlled options revert to their default settings. The OPTIONS instruction also accepts a NO keyword to reset a selected option to its default value, making it more convenient to reset the RESULTS attribute for a single command without having to reset the FAILAT and PROMPT options.

OPTIONS also accepts a CACHE keyword that can be used to enable or disable an internal statement-caching scheme. The cache is normally enabled. For example:

OPTIONS FAILAT 10
OPTIONS PROMPT "Yes Boss?"
OPTIONS RESULTS