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

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

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

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

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

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

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

NUMERIC

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

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

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

This instruction is valid only within the range of a SELECT instruction and must follow all of the "WHEN ... THEN" statements. If non of the preceding WHEN clauses have 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 succeed. For example:

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

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 maybe used with an of the input sources and specifies that the input string is to be translated to uppercase 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:

12
34
567890
1234567890