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 uppercase 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*/
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
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 is used to leave a function and return control to the point of the previous function 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:
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:
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
The SHELL instruction is a synonym for the ADDRESS instruction. For example:
SHELL edit /*Set host to `EDIT'*/
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:
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 of 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*/
|
|
