Table of Contents

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 the table below:

Convention Definition
KEYWORD All keywords and subkeywords are shown in upper case 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

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'

If you omit the single quotes around MyPort, ARexx will look for the message port MYPORT and generate 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 upper case 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 no 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:

Program 12. Iteration.rexx

/*Examples of DO*/
LIMIT = 20; number = 1
DO i=1 to LIMIT for 10 WHILE number < 20
   number = i * number
   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*/

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.*/
mytable.1 = "Orange"
mytable.2 = "Apple"
mytable.3 = "Banana"
SAY mytable.1 mytable.2 mytable.3 /* Prints Orange Apple Banana */
DROP mytable. /* Drop all variables starting with a stem mytable */
SAY mytable.1 mytable.2 mytable.3 /* Prints MYTABLE.1 MYTABLE.2 MYTABLE.3 */

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.

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}
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 commands 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

OTHERWISE

OTHERWISE [;] [conditional statement]

This instruction is valid only within the range of a SELECT instruction and must follow all of the WHEN … THEN statements. If none of the preceding WHEN clauses has succeeded, the statement following the OTHERWISE instruction is executed. An OTHERWISE is not mandatory within a SELECT range. However, an error will result if the OTHERWISE clause is omitted and none of the WHEN instructions succeeds. For example:

SELECT
   WHEN i=1 THEN say 'one'
   WHEN i=2 THEN say 'two'
   OTHERWISE SAY 'other'
   END

PARSE

PARSE [UPPER] inputsource [template] [,template ...]

The PARSE instruction provides a mechanism to extract one or more substrings from a string and assign them to variables. The input string can come from a variety of sources, including argument strings, an expression, or from the console.

Parsing is controlled by a template, which may consist of symbols, strings, operators and parentheses. The template provides both the variables to be given values and the way to determine the value strings. During the parsing operation the input string is split into substrings that are assigned to the variable symbols in the template. The process continues until all of the variables in the template have been assigned a value. If the input string is "used up", any remaining variables are given null values.

When a variable in the template is followed immediately by another variable, the value string is determined by breaking the input string into words separated by blanks. Leading and trailing blanks are not permitted. Each word is assigned to a variable in the template. Normally the last variable receives the untokenized remainder of the input string, since it is not followed by a symbol. A placeholder symbol, a period (.), forces the variable with the period to terminate at the first space in the input stream. Placeholders behave like variables except that they are never assigned a value.

The template may be omitted if the instruction is intended only to create the input string. Templates are described in Chapter 7.

The goal of the parsing operation is to associate a current and next position with each variable symbol in the template. The substring between these positions is then assigned as the value to the variable.

The different options of the instruction are described below.

{COMMAND | FUNCTION} {0 | 1} CALLED RESOLVED EXT HOST

where:

ARexx VERSION CPU MPU VIDEO FREQ

where:

For example:

/*Numeric string is: "9 0 SCIENTIFIC"*/
PARSE NUMERIC DIGITS FUZZ FORM .
SAY Digits /*9*/
SAY fuzz /*0*/
SAY form /*SCIENTIFIC*/
myvar = 1234567890
PARSE VAR myvar 1 a 3 b +2 c 1 d
SAY a
SAY b
SAY c
SAY d

This is the output:

12
34
567890
1234567890

PROCEDURE

PROCEDURE [EXPOSE variable [variable...]]

The PROCEDURE instruction is used within an internal function to create a new symbol table. This protects the symbols defined in the caller's environment from being altered by the execution of the function. PROCEDURE is usually the first statement within the function, although it is valid anywhere within the function body. It is an error to execute two PROCEDURE statements within the same function.

The EXPOSE subkeyword provides a selective mechanism for accessing the caller's symbol table, and or passing global variables to a function. The variables following the EXPOSE keyword are taken to refer to symbols in the caller's table. Any subsequent changes made to these variables will be reflected in the caller's environment.

The variables in the EXPOSE list may include stem or compound symbols, in which case the ordering of the variables becomes significant. The EXPOSE list is processed from left to right and compound symbols are expanded based on the values in effect in the new generation. For example, suppose that the value of the symbol J in the previous generation is 123, and that J is uninitialized in the new generation. Then PROCEDURE EXPOSE J A.J will expose J and A.123, whereas PROCEDURE EXPOSE A.J J will expose A.J and J. Exposing a stem has the effect of exposing all possible compound symbols derived from that stem. That is, PROCEDURE EXPOSE A. exposes A.I, A.J, A.J.J, A.123, etc. For example:

fact: PROCEDURE /*A recursive function*/
   ARG i
   IF i = 1
   THEN RETURN 1
   ELSE RETURN i * fact (i-1)

PULL

PULL [template] [,template...]

Pull is the shorthand form of the PARSE UPPER PULL instruction. It reads a string from the input console, translates it to upper case and parses it using the template. Multiple strings can be read by supplying additional templates. The instruction will read from the console even if no template is given. (Templates are described in Chapter 7.) For example:

PULL first last . /*Read names*/ 

PUSH

PUSH [expression]

The PUSH instruction is used to prepare a stream of data to be read by a command shell or other program. It appends a newline to the result of the expression then stacks or "pushes" it into the STDIN stream. Stacked lines are placed in the stream in "last-in, first-out" order and are available to be read just as though they had been entered interactively. For example, after issuing the instructions:

PUSH line 1
PUSH line 2
PUSH line 3

the stream would be read in the order line 3, line 2, and line 1.

PUSH allows the STDIN stream to be used as a private scratch pad to prepare data for subsequent processing. For example, several files could be concatenated with delimiters between them by simply reading the input files, PUSHing the line into the stream and inserting a delimiter where required. For example:

DO i=1 to 5
   PUSH 'echo "Line 'i'"'
   END 

QUEUE

QUEUE [expression]

The QUEUE instruction is used to prepare a stream of data to be read by a command shell or other program. It is very similar to the PUSH instruction and differs only in that the data lines are placed in the STDIN stream in "first-in, first-out" order. In this case, the instructions:

QUEUE line 1
QUEUE line 2
QUEUE line 3

would be read in the order line 1, line 2, and line 3. The QUEUEd lines always precede all interactively-entered lines and always follow any PUSHed (stacked) lines. For example:

DO i=1 to 5
   QUEUE 'echo "Line 'i'"'
   END

RETURN

RETURN [expression]

RETURN is used to leave a function and return control to the point of the function's invocation. The evaluated expression is returned as the function result. If an expression is not supplied, an error may result in the caller's environment. Functions called from within an expression must return a result string and will generate an error if no result is available. Functions invoked by the CALL instruction need to return a result.

A RETURN issued from the base environment of a program is not an error and is equivalent to an EXIT instruction. Refer to the EXIT instruction for a description of how result strings are passed back to an external caller. For example:

RETURN 6*7 /*Returns 42*/ 

SAY

SAY [expression]

The result of the evaluated expressions is written to the output console, with a newline character appended. If the expression is omitted, a null string is sent to the console. For example:

SAY 'The answer is ' value 

SELECT

SELECT

SELECT begins a group of instructions containing one or more WHEN clauses and possibly a single OTHERWISE clause, each followed by a conditional statement. Only one of the conditional statements within the SELECT group will be executed. Each WHEN statement is executed in succession until one succeeds. If none succeeds, the OTHERWISE statement is executed. The SELECT range must be terminated by an END statement. For example:

SELECT
   WHEN i=1 THEN SAY 'one'
   WHEN i=2 THEN SAY 'two'
   OTHERWISE SAY 'other'
   END 

SHELL

SHELL [symbol | string | [[VALUE] [expression]]

The SHELL instruction is a synonym for the ADDRESS instruction. For example:

SHELL edit /*Set host to 'EDIT'*/ 

SIGNAL

SIGNAL {ON | OFF} condition SIGNAL [VALUE] expression

SIGNAL {ON | OFF} controls the state of the internal interrupt flags. Interrupts allow a program to detect and retain control when certain errors occur. In this form SIGNAL must be followed by one of the keywords ON or OFF and one of the condition keywords listed below. The interrupt flag specified by the condition symbol is then set to the indicated state. The valid signal conditions are:

Signal Description
BREAK_C A Ctrl+C break was detected.
BREAK_D A Ctrl+D break was detected.
BREAK_E A Ctrl+E break was detected.
BREAK_F A Ctrl+F break was detected.
ERROR A host command returned a non-zero code.
HALT An external HALT request was detected.
IOERR An error was detected by the I/O system.
NOVALUE An uninitialized variable was used.
SYNTAX A syntax or execution error was detected.

The condition keywords are interpreted as labels to which control will be transferred if the selected condition occurs. For example, if the ERROR interrupt is enabled and a command returns a non-zero code, ARexx will transfer control to the label ERROR:. The condition label must be defined in the program; otherwise, an immediate SYNTAX error results and the program exits.

In SIGNAL [VALUE] expression, the tokens following SIGNAL are evaluated as an expression. An immediate interrupt is generated that transfers control to the label specified by the expression result. The instruction thus acts as a "computed goto".

Whenever an interrupt occurs, all currently active control ranges (IF, DO, SELECT, INTERPRET, or interactive TRACE) are dismantled before the transfer of control. Thus, the transfer cannot be used to jump into the range of a DO loop or other control structure. Only the control structures in the current environment are affected by a SIGNAL condition, making it safe to SIGNAL from within an internal function without affecting the state of the caller's environment.

The special variable SIGL is set to the current line number whenever a transfer of control occurs. The program can inspect SIGL to determine which line was being executed before the transfer. If an ERROR or SYNTAX condition causes an interrupt, the special variable RC is set to the error code that triggered the interrupt. For the ERROR condition, this code is usually an error severity level. Refer to Appendix A for further details on error codes and severity levels. The SYNTAX condition will always indicate an ARexx error code. For example:

SIGNAL on error /*Enable interrupt*/
SIGNAL off syntax /*Disable SYNTAX*/
SIGNAL start /*Goto START*/ 

WHEN

WHEN expression [THEN [;] [conditional statement]]

The WHEN instruction is similar to the IF instruction, but is valid only within a SELECT range. Each WHEN expression is evaluated in turn and must result in a Boolean value. If the result is a 1, the conditional statement is executed and control passes to the END statement that terminates the SELECT. As with the IF instruction, the THEN need not be part of the same clause. For example:

SELECT
   WHEN i<j THEN SAY 'less'
   WHEN i=j THEN SAY 'equal'
   OTHERWISE SAY 'greater'
   END 

Index