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

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'

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:

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

Simple Loop Examples

/* Example of infinite loop. Loop terminates randomly */
DO FOREVER
   SAY "Digging..."
   IF ( random( 1, 6, time( 'S' ) ) = 6 ) THEN LEAVE
END
SAY "Gold! I'm rich!"

/* Print "Hello world!" three times */
DO 3
   SAY "Hello world!"
END

/* While loop example. The loop termination condition is evaluated before entering the loop. */
running = 1
score = 0
DO WHILE ( running )
   score = score + random( 1, 6, time( 'S' ) )
   SAY "Score:" score
   IF ( score > 21 ) THEN running = 0
END

/* Until loop example. The loop termination condition is evaluated at the end of each iteration. */
done = 0
score = 0
DO UNTIL ( done )
   score = score + random( 1, 6, time( 'S' ) )
   SAY "Score:" score
   IF ( score > 21 ) THEN done = 1
END

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

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

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.

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

Leave the named DO range:

DO hour = 0 TO 23
   DO minute = 0 TO 59
      SAY RIGHT( hour, 2, '0' ) || ':' || RIGHT( minute, 2, '0' )
      /* Leave both DO ranges immediately */
      IF ( hour = 2 ) & ( minute = 19 ) THEN LEAVE hour
   END
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 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.

The optional UPPER keyword may be used with any of the input sources and specifies that the input string is to be translated to upper case before being parsed. It must be the first token following PARSE.
The sources for the input strings are specified by the keyword symbols explained below. When multiple templates are supplied, each template receives a new input string, although for some source options the new string will be identical to the previous one. The input source string is copied before being parsed, so the original strings are never altered by the parsing process.

The ARG input option retrieves the argument strings supplied when the program was invoked. Command invocations normally have only a single argument string, but functions may have up to 15 argument strings.
The EXTERNAL input string is read from STDERR stream, (see Chapter 6) so as not to disturb any PUSHed or QUEUEd data. If multiple templates are supplied, each template will read a new string. This source option is the same as PULL.
The NUMERIC input option places the current numeric options in a string in the order DIGITS, FUZZ and FORM, separated by a single space.
The PULL input option reads a string from the input console. If multiple templates are supplied, each template will read a new string.
The SOURCE input option retrieves the "source" string for the program. This string is formatted as:

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

where:

{COMMAND | FUNCTION} indicates whether the program was invoked as a command or as a function.
{0 | 1} is a Boolean flag indicating whether a result string was requested by the caller.
CALLED is the name used to invoke this program.
RESOLVED is the final resolved name of the program.
EXT is the file extension to be used for searching (the default is "REXX").
HOST is the initial host address for commands.

The SOURCE option now returns the full path name of the ARexx program file. Formerly just a relative name was given, which was not sufficient to locate the program's source file.

The "VALUE expression WITH" input string is the result of the supplied expression. The WITH keyword is required to separate the expression from the template. The expression result may be parsed repeatedly by using multiple templates, but the expression is not re-evaluated.

The "VAR variable" input option uses the value of the specified variable as the input string. When multiple templates are provided, each template uses the current value of the variable. This value may change if the variable is included as an assignment target in any of the templates.

The VERSION input option of the current configuration of the ARexx interpreter is supplied in the form:

ARexx VERSION CPU MPU VIDEO FREQ

where:

VERSION is the release level of the interpreter, formatted as 1.14.
CPU indicates the processor currently running the program, and will be one of the values 68000, 68010, 68020, 68030 or 68040.
MPU will be either NONE, 68881, or 68882, depending on whether a math coprocessor is available.
VIDEO will indicate either NTSC or PAL.
FREQ gives the clock (line) frequency as either 60Hz or 50Hz.

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:

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:

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

AmigaOS Manual: ARexx Instructions

Contents