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.
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 /*…*/
.
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 [[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 [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
The BREAK
instruction is used to exit from the range of a DO instruction or from within an INTERPRET
ed 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 {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 DROP
ped (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 [[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:
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.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.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.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.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.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.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.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.)/*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 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. DROP
ping a stem symbol is equivalent to DROP
ping 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 [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 [;] [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 [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 [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.
EXIT
information to be interpreted as a return code by the caller.For example:
EXIT /*No result needed*/ EXIT 10 /*An error return*/
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 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 INTERPRET
ed source, including DO
or SELECT
instructions. The BREAK
instruction can be used to terminate the processing of INTERPRET
ed 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 [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 [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
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 {DIGITS | FUZZ} expression NUMERIC FORM {SCIENTIFIC | ENGINEERING}
NUMERIC
instruction sets options relating to numeric precision and format. The numeric options are preserved when an internal function is called.DIGITS
expression option specifies the number of digits of precision for arithmetic calculations. The expression must evaluate to a positive whole number.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.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.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 [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 [;] [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 [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.
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
.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.EXTERNAL
input string is read from STDERR
stream, (see Chapter 6) so as not to disturb any PUSH
ed or QUEUE
d data. If multiple templates are supplied, each template will read a new string. This source option is the same as PULL
.NUMERIC
input option places the current numeric options in a string in the order DIGITS
, FUZZ
and FORM
, separated by a single space.PULL
input option reads a string from the input console. If multiple templates are supplied, each template will read a new string.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.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.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.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.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:
12 34 567890 1234567890
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 [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 [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, PUSH
ing the line into the stream and inserting a delimiter where required. For example:
DO i=1 to 5 PUSH 'echo "Line 'i'"' END
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 QUEUE
d lines always precede all interactively-entered lines and always follow any PUSH
ed (stacked) lines. For example:
DO i=1 to 5 QUEUE 'echo "Line 'i'"' END
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 [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
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 [symbol | string | [[VALUE] [expression]]
The SHELL
instruction is a synonym for the ADDRESS
instruction. For example:
SHELL edit /*Set host to 'EDIT'*/
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 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