|
ADDRESS
ADDRESS environment [ command ]
---or---
ADDRESS [ VALUE ] expression
---or---
ADDRESS
address directs commands to the proper external environment(s) for execution.
An address instruction with both environment and command coded specifies to which external environment that command is sent. An address instruction with an environment but no command specifies the default external environment for subsequent commands. An address instruction with neither environment nor command coded toggles the target environment between the last two specified or used.
The value format defines the target environment by way of the resolved expression for subsequent commands. value and command cannot be coded in the same statement. The purpose of the value format is to provide for programmability in determining the target environment for subsequent commands.
The environments that may be specified for command execution are system-dependent. Use the address() function to find out what the current environment is.
Examples --
say address() /* displays the current command environment */
address system dir /* send the DIR command to the SYSTEM environment */
address command /* send all subsequent commands to the COMMAND environment */
'dir' /* as per the prior line of code, 'dir' is sent to the COMMAND environment */
The ANSI-1996 standard added a new format for the
ADDRESS instruction. It is not supported by z/OS and z/VM Rexx. Here is the template for this new format:
ADDRESS [ environment ] [ command ] [ redirection ]
---or---
ADDRESS [ [ VALUE ] expression [ redirection ] ]
redirection is: WITH INPUT input_redirection
and/or: WITH OUTPUT output_redirection
and/or: WITH ERROR output_rediection
input_redirection is: [ NORMAL | STREAM | STEM ] symbol
output_redirection is: [ APPEND | REPLACE ]
plus a destination: [ NORMAL | STREAM | STEM ] symbol
Optional extensions for the ANSI standard are fifo and lifo for the with input, with output and with error options.
Any, all or none of the three clauses with input, with output, and with error may be specified. They may be specified in any order. append or replace specify whether an output or error file will be appended to or over-written. replace is the default.
stream or stem specify whether an I/O stream or compound variable stem (an array) will provide the input or be written to as output or error. When using an array, element 0 should state the number of elements for input. Element 0 tells how many lines of output there are for output or error.
Example --
/* First, send an operating system SORT command to the SYSTEM environment.
Use file sortin.txt for input with output going to file sortout.txt. */
address SYSTEM sort WITH INPUT STREAM 'sortin.txt' , OUTPUT STREAM 'sortout.txt'
/* Now send the SORT command to the SYSTEM environment, but use arrays for input and output. Specify both arrays as compound variable stems (include the period after the array name). Before issuing the command, you must set Element 0 in the input array to the number of items in the input array. After the command, the number of elements
in the output array will be in Element 0 of that array. */
in_array.0 = 10 /* 10 items are in the input array called in_array. */
/* They are in array positions in_array.1 thru .10. */
address SYSTEM sort WITH INPUT STEM in_array. OUTPUT STEM sortout.
say 'Number of output elements:' sortout.0
ARG
ARG [ template ]
The arg instruction parses arguments in the template. It does so in the same manner as: parse upper arg [ template ]
[template] is a list of symbols separated by blanks and/or patterns.
arg automatically translates all input arguments to uppercase.
Example --
/* function invoked by: testsub('a',3,'c') */
arg string_1, number_1, string_2
/* string_1 contains 'A', number_1 contains '3', string_2 contains 'C' */
CALL
CALL name [ expression ] [, [ expression ] ] ...
---or---
CALL ON condition [ NAME trapname ]
---or---
CALL OFF condition
call either invokes a routine or enables an error condition. If on is specified, call enables the error condition and optionally specifies the name of the exception routine that will be invoked when it is raised. The condition must be one of error, failure, halt, and notready (z/OS does not support notready). Specifying off disables an error condition.
If neither on nor off is specified, call invokes an internal, built-in or external routine. Coding the routine name in quotes prevents searching for an internal routine. Zero, one, or more expression arguments may be passed to the routine.
If the routine returns a result, the special variable result is set to that value. Otherwise result is set to uninitialized.
Examples --
call on error /* enables ERROR trap with routine of ERROR: */
call on error name error_handler /* enables ERROR to ERROR_HANDLER: */
call off error /* dis-ables ERROR trap */
call my_routine parm_1 , parm_2 /* call routine my_routine with 2 parameters */
/* if a result was returned, display it... */
if result <> 'RESULT' then say 'The returned result was:' result
DO
DO [ repetitor ] [ condition ]
[ instruction_list ]
END [ symbol ]
repetitor is: symbol = expression_i [ TO expression_t ]
[ BY expression_b ] [ FOR expression_f ]
or: expression_r
or: FOREVER
condition is: WHILE expression_w
or: UNTIL expression_u
instruction_list is a sequence of one or more instructions.
The do-end instruction groups multiple instructions together and executes them 0, 1, or more times. to, by, and for are optional and can be coded in any order. by expression_b is an increment that defaults to 1. for expression_f sets a limit for loop iterations if not terminated by some other constraint. forever defines an endless loop that must be terminated or exited by some internal instruction. while is a top-driven structured loop, and until defines a bottom-driven unstructured loop. Loop control variables can be altered from within the loop and the leave, iterate, signal, return, and exit instructions may also modify loop behavior.
Examples --
if a = 2 then do /* a simple do-end pair to group multiple */
say 'a is 2' /* instructions into one for the IF instruction */
say 'Why?'
end
/* we assume all DO's below have a body and END. We just show the DO here. */
do 40 /* executes a loop 40 times */
do j = 1 to 40 /* executes a loop 40 times (BY 1 is implied) */
do while counter < 30 /* do-while with a condition specified */
do while (counter < 30 & flag = 'NO') /* multiple conditions specified */
do forever /* codes an endless loop... better have an
unstructured exit inside the loop ! */
DROP
DROP symbol [ symbol ... ]
drop "unassigns" one or more variables or stems by setting them to uninitialized.
Example --
a = 55
drop a
say a /* writes 'A' because this symbol is uninitialized */
EXIT
EXIT [ expression ]
exit unconditionally terminates a program and optionally returns the single value defined by expression to the caller.
Examples --
exit 1 /* unconditional termination, sends '1' to environment */
exit /* unconditional termination with no return code */
IF
IF expression [;] THEN [;] instruction [ ELSE [;] instruction ]
if conditionally executes a "branch" of instruction(s). The expression must evaluate to either 0 or 1. The else always matches to the nearest unmatched if. To execute more than one instruction after the then or else, use a do-end pair, such as: then do . . . end or else do . . . end. To code a branch with no instructions, use the nop instruction.
Examples --
if b = 1 then say 'B is 1' /* a simple IF instruction */
else say 'B is not 1'
if b = 1 then do /* THEN DO and ELSE DO are required */
say 'B is 1' /* to execute more than 1 instruction */
say 'TRUE branch taken' /* in a branch. */
end /* END terminates a logical branch. */
else do
say 'B is not 1'
say 'FALSE branch taken'
end
INTERPRET
INTERPRET expression
interpret executes instructions that may be built dynamically within the expression. The expression is evaluated, then executed. The expression must be syntactically complete; for example, a do must include a matched end. interpret is useful for creating self-modifying scripts. Set trace r or trace i if experiencing problems with interpret.
Example --
interpret say 'Hi there' /* interprets (executes) the SAY instruction */
ITERATE
ITERATE [ symbol ]
iterate alters the flow of control within a do loop by passing control directly back to the do instruction of that loop. This skips any subsequent instructions encoded south of the iterate instruction within that execution of the do loop.
Example --
do j = 1 by 1 to 3 /* This displays 1 and 3, but not 2. */
if j = 2 then iterate /* The ITERATE instruction skips displaying 2. */
say j
end
LEAVE
LEAVE [ symbol ]
leave alters the flow of control within a do loop by immediately passing control directly to the instruction following the end clause. This causes an unstructured exit from the do loop. Whereas iterate sets the loop to start on a new iteration, leave exits the loop.
Example --
do j = 1 by 1 to 3 /* This displays 1, then 'Hello.' The LEAVE */
if j = 2 then leave /* instruction exits the loop when j = 2. */
say j
end
say 'Hello'
NOP
NOP
nop means "no operation." It can be used within an if statement to code a branch with no action taken.
Example --
if flag = 'YES'
then nop /* no action taken when FLAG = 'YES' */
else say 'flag is NO'
NUMERIC
NUMERIC DIGITS [ expression ]
FORM [ SCIENTIFIC | ENGINEERING | [ VALUE ] expression ]
FUZZ [ expression ]
The numeric instruction controls various aspects of numeric calculation. digits set the number of significant digits; it defaults to 9. form sets the form in which exponential numbers are written; it defaults to scientific. fuzz controls how many digits will be ignored during comparisons; it defaults to 0.
Use the digits(), form() and fuzz() functions to find out the current values for these numeric settings.
Examples --
numeric digits 12 /* Set precision to 12 significant digits. */
say digits() /* This will now display: 12. */
numeric form engineering /* Display exponential numbers in engineering format. */
say form() /* This will now display: ENGINEERING. */
numeric fuzz 1 /* 1 digit will be ignored during comparisons. */
say fuzz() /* will now display: 1 */
Note that the example code above is run in sequence:
OPTIONS
OPTIONS expression
options passes commands to the interpreter. It can be used to alter the behavior of the Rexx interpreter or its defaults. The options allowable are strictly implementation-dependent. Interpreters ignore any options they do not recognize. This is good because it means implementation-dependent coding on this statement runs under other interpreters. But it also means that you must check to see whether the options you coded were implemented or ignored.
Example --
options 4.00 vm_compatible /* The two options '4.00' and 'vm_compatible' */
/* may each be set, or ignored, depending */
/* on whether the Rexx interpreter we are */
/* using recognizes them. */
PARSE
PARSE [ UPPER ] type [ template ]
where type is: [ ARG | LINEIN | PULL | SOURCE | VERSION ]
or: VALUE [ expression ] WITH
or: VAR symbol
parse assigns values to one or more variables from various data sources according to parsing rules and its template. If upper is specified, all input values are translated to uppercase.
[template] is a list of symbols separated by blanks and/or patterns.
ARG -- Parses input values to this routine
LINEIN -- Reads a line from the default input stream and parses it into variable(s)
PULL -- Reads a line from the stack, or it is empty, from the default input stream and parses this string into variable(s)
SOURCE -- Reads three words of system-dependent information:
system how_the_script_was_invoked filename_of_the_script
VERSION -- Reads five words of system-dependent information:
language level date month year
VALUE expression WITH -- Evaluates the expression and then parses it
VAR symbol -- Parses the string in symbol
z/OS and z/VM add two more TYPES: external and numeric. z/OS does not natively support linein, though it does support it if you have the Stream I/O package installed.
EXTERNAL -- Reads from terminal input buffer.
NUMERIC -- Returns current numeric controls.
Examples --
parse arg a, b /* internal routine reads its parameters */
parse linein /* reads a line from default input stream */
parse pull a /* reads A from the stack or input stream */
Examples: Let's parse a phone number into its three constituent parts --
phone = '212-855-1212' ; sep = '-' ;
parse value phone with area_code (sep) prefix (sep) number
parse value phone with area_code 4 5 prefix 8 9 number
parse value phone with area_code +3 +1 prefix +3 +1 number
parse value phone with 4 sep +1 . 1 area_code (sep) prefix (sep) numb
parse value phone with . (sep) prefix (sep) . → returns prefix
parse value phone with +8 number → returns number
parse value phone with =9 number → returns number
PROCEDURE
PROCEDURE [ EXPOSE variable_list ]
The procedure instruction makes all variables of the caller unavailable to this one. If it is not coded, all the caller's variables are available to this routine (they are global). If procedure is coded with the expose keyword, only the variables listed after the expose keyword are available to this routine. Exposed variables are accessible for both reading and updating by the routine.
Examples --
my_sub: procedure /* No caller variables are available to my_sub. */
my_sub: /* ALL caller variables are available to my_sub. */
my_sub: procedure expose a b /* a and b only are available to my_sub. */
PULL
PULL [ template ]
pull reads a line from the stack, or if none is available, reads a line from the default input stream.
pull parses the input according to the template and always translates all arguments to uppercase. pull is equivalent to:
parse upper pull [ template ]
[template] is a list of symbols separated by blanks and/or patterns.
Example --
pull input
/* reads one line from the stack, or reads */
/* input from the user if the stack is empty. */
/* waits for input to read if necessary. */
/* always translates to all uppercase letters */
PUSH
PUSH [ expression ]
Adds a line to the external data queue or stack, in the order last-in, first-out (LIFO). Use the queued() function to determine how many elements are on the stack at any time.
Example --
push line /* pushes LINE onto the stack LIFO */
QUEUE
QUEUE [ expression ]
Adds a line to the external data queue or stack, in the order first-in, first-out (FIFO). Use the queued() function to determine how many elements are on the stack at any time.
Example --
queue line /* places LINE onto the stack FIFO */
RETURN
RETURN [ expression ]
Returns control from a program or internal routine to its caller, optionally passing the single result of expression.
Examples --
return /* return with no result */
return 4 /* return with result of: 4 */
SAY
SAY [ expression ]
Writes a line to the default output stream, after evaluating expression. Using say is the same as coding:
call lineout , [expression]
Examples --
say 'Hi' /* displays: Hi */
say 'Hi' 'there' /* displays: Hi there */
SELECT
SELECT ; when_part [ when_part ... ] [ OTHERWISE [;] instruction_list ... ] ] END ;
when_part is: WHEN expression [;] THEN [;] instruction
instruction_list is a sequence of one or more instructions.
select implements the Case construct for determining the flow of control. Only the first when condition that evaluates to true( 1 ) executes. otherwise executes if none of the when conditions are true. If no otherwise is provided and none of the when conditions is true, a syntax error results. We recommend always coding an otherwise clause.
Example --
select
when input = 'yes' then do
say 'YES!'
say 'branch 1'
end
when input = 'no' then do
say 'NO!'
say 'branch 2'
end
otherwise
say 'user is crazy'
exit 99
end /* select */
SIGNAL
SIGNAL label_name
---or---
SIGNAL [ VALUE ] expression
---or---
SIGNAL ON condition [ NAME trapname ]
---or---
SIGNAL OFF condition
signal either causes an immediate unstructured transfer of control to the label at label_name, or enables or disables an error condition. If on is specified, signal enables the error condition and optionally specifies the name of the routine invoked when it is raised. The condition must be one of error, failure, halt, novalue, notready, or syntax. The ANSI-1996 standard adds the new condition lostdigits.
z/OS supports the conditions error, failure, halt, novalue, and syntax. z/VM supports error, failure, halt, notready, novalue, and syntax. Neither support lostdigits.
Specifying off disables an error condition.
If neither on nor off is specified, signal directly transfers control to the label of label_name, rather like the goto of other computer languages. Any active do, if, select, and interpret instructions are terminated. The value keyword allows transfer of control to a label whose name is determined at execution time.
Examples --
signal on error /* enables ERROR trap with routine of ERROR: */
signal on error name error_handler /* enables ERROR to ERROR_HANDLER: */
signal off error /* disables ERROR trap */
signal goto_place /* immediately goes to the label goto_place: */
TRACE
TRACE trace_setting | [ VALUE ] expression
trace_setting is any of these flags:
A -- All
C -- Commands
E -- Errors
F -- Failure
I -- Intermediates
L -- Labels
N -- Normal
O -- Off
R -- Results
? -- Toggles interactive tracing on or off; ? and ! can be followed by any single letter in this list.
! -- Inhibits host command execution (available on z/OS and z/VM, and certain other implementations only).
S -- Traces clauses but does not process them (z/OS and z/VM only)
A positive whole number -- If in interactive trace, skips the number of pauses specified
A negative whole number -- Inhibits tracing for the number of clauses specified
Sets the trace level for debugging. Multiple trace instructions may be placed within a script, altering the trace level at will. Setting it to a positive or negative whole number during interactive tracing skips or inhibits tracing for that number of pauses or clauses.
For z/OS and z/VM, the reference manuals also provide this alternative format for the trace instruction:
TRACE [string] | [symbol] | [ [value] expression]
Use the trace() function to retrieve the current setting for the trace level.
Examples --
say trace() /* displays the current trace setting */
trace a /* turn on TRACE ALL */
trace ?I /* toggle on (or off) interactive trace with setting of I */
(Note that the ANSI standard does allow for slightly differing implementations in regards to trace behavior, output content, and format of that output.)
UPPER (Mainframe only)
UPPER variable_list
Converts one or more variables to upper-case.
Example --
aa = 'hi' ; bb = 'there'
upper aa bb
say aa bb /* displays: HI THERE */
|
