Instructions
Each REXX instruction is one ore more clauses, the first clause
is the one that identifies the instruction. Instructions end
with a semicolon or with a new line. One instruction may be
continued from one line to the next by using a comma at the end
of the line. Open strings or comments are not affected by line
ends.
The General Guidelines are:
name
refers to a variable, which can be assigned any value.
name is a symbol with the following exception: the
first character may not be a digit or a period. The
value of name is translated to uppercase before use, and
forms the initial value of the value of the variable.
Some valid names are:
Fred COST? next index A.j
name:
is a form of labels for CALL instructions, SIGNAL
instructions, and internal function calls. The colon
acts as a clause separator.
template
is a parsing template, described in a later section.
instr
is any one of the listed instructions.
The Instructions are:
expression
the value of expression is issued as a command, normally
to the command interpreter or to the specified environment
specified by the ADDRESS instruction. Look also the section
"Issuing Commands to Host System."
ie. 'DIR' '*.exe'
name = [expr];
is an assignment: the variable name is set to the value
of expr.
ie. fred = 'sunset'
a = 1 + 2 * 3
a = /* a contains '' */
ADDRESS [ [expr]];
redirect commands or a single command to a new
environment. ADDRESS VALUE expr may be used
for an evaluated environment name.
ie. address int2e 'dir' /* executes through int2e a dir cmd
address system /* all the following command will be
addressed to system */
env = 'dos'
address value env /* change address to dos */
ARG ;
parse argument string(s) given to program or in an
internal routine into variables according to template.
Arguments are translated into uppercase before the parsing.
Short for PARSE UPPER ARG.
ie. /* program is called with args "autoexec.bat auto.old"
arg src dest
/* src = "AUTOEXEC.BAT", dest="AUTO.OLD" */
/* a function is called MARMITA('Bill',3)
marmita:
arg firstarg, secondarg
/* firstarg = "BILL", secondarg = "3" */
CALL [symbol | string] [] [,]... ;
call an internal routine, an external routine or program,
or a built-in function. Depending on the type of
routine called, the variable RESULT contains the result
of the routine. RESULT is uninitialized if no result is
returned.
ie. call substr 'makedonia',2,3
/* now. variable result = 'ake' */
/* the same can be obtained with */
result = substr('makedonia',2,3)
In the following sections there is a description of
all the built-in rexx functions.
Internal functions are sequence of instructions inside the
same program starting at the label that matches the name in
the CALL instruction.
External routines are like internal but written in
a separate module that can be used as a library. In this
REXX external routines must be loaded with the built-in
function LOAD before the are used (see below).
As external routines can be used any DOS command or program
that uses standard input and output. (LOAD affects only REXX
routines)
/* external programs can be called as routines */
/* and the output of the program (to stdout) will */
/* be returned as the result string of the function */
call "dir" "*.exe","/w" /* or */
files = "dir"('*.exe',"/w")
current_directory = 'cd'()
DO [ [name=expri [TO exprt] [BY exprb]
[FOR exprf]] | [ FOREVER | exprr ]
[UNTIL expru | WHILE exprw] ;
[instr]... ;
END [symbol] ;
DO is used to group many instructions together and
optionally executes them repetively.
o Simple DO loop are used to execute a block of instructions
often used with IF-THEN statements.
Note. Simple DO loops are not affected with
ITERATE or LEAVE instructions (see below)
ie. If name = 'VIVI' then Do
i = i + 1
Say 'Hello Vivi'
End
o Simple repetitive loops.
ie. do 3 /* would display 3 'hello' */
say 'hello'
end
Note. DO expr, expr must evaluate to an integer number.
do forever /* infinite loop, display always */
say 'lupe forever' /* 'hello' */
end
o Loops with control variable. name is stepped from expri
to exprt in steps of exprb, for a maximum of exprf iterations.
do i = 1 to 10 by 3 /* would display the numbers */
say i /* 1, 4, 7, 10 */
end
Note. all the expressions are evaluated before the loop is
executed and may result to any kind of number, integer or real.
o Conditional loops
ie. a = 2 /* would display */
do while a < 5 /* 2 */
say a /* 4 */
a = a + 2
end
Note. exprw and expru are evaluated in each iteration and
must result to 0 or 1. WHILE expression is evaluated before
each iteration, where UNTIL expression is evaluated at the
end of each iteration.
You can combine them like:
a = 1 /* would display */
do for 3 while a < 5 /* 1 */
say a /* 2 */
a = a + 1 /* 3 */
end
DROP name [name]... ;
drop (reset) the named variables or group of variables
by freeing their memory. It returns them in their original
uninitialized state.
If an exposed variable is named, the variable itself
in the older generation will be dropped!
If a stem is specified all variables starting with that stem
will be dropped.
ie. j = 2
drop a x.1 y.j /* resets variables A X.1 and Y.2 */
drop z. /* resets all variables with names
starting with Z. */
EXIT [expr] ;
leave the program (with return data, expr). EXIT is
the same as RETURN except that all internal routines
are terminated.
ie. exit 12*3 /* will exit the program with rc=36 */
IF expr [;] THEN [;] instr ;
[ELSE [;] instr];
if expr evaluates to "1", execute the instruction
following the THEN. Otherwise, when expr evaluates to "0",
the instruction after ELSE is executed, if ELSE is present.
ie. if name="bill" then say "Hello billy."
else say "Hello stranger"
INTERPRET expr ;
expr is evaluated and then is processed, as it was a
part of the program.
ie. cmd = "say 'Hello'"
interpret cmd /* displayes "Hello" */
ITERATE [name] ;
start next iteration of the innermost repetitive loop
(or loop with control variable name).
ie. do i = 1 to 5 /* would display: 1 */
if i=3 then iterate /* 2 */
say i /* 4 */
end /* 5 */
LEAVE [name] ;
terminate innermost repetitive loop (or loop with control
variable name).
ie. do i = 1 to 5 /* would display: 1 */
if i=3 then leave /* 2 */
say i
end
LOWER name [name]...
translate the values of the specified individual
variables to lowercase.
ie. name = 'ViVi'
lower name /* now, name = 'vivi' */
NOP ;
dummy instruction, has no effect.
ie. if name='vivi' then nop; else say 'Hello vivi.'
NUMERIC DIGITS [expr] |
FORM [SCIENTIFIC | ENGINEERING] |
FUZZ [expr] ;
- dummy instruction, has no effect, just for compatibility
- with VM/CMS REXX.
PARSE [UPPER] + ARG | [template] ;
| AUTHOR |
| EXTERNAL |
| NUMERIC |
| PULL |
| SOURCE |
| VALUE [expr] WITH |
| VAR name |
+ VERSION +
Parse is used to assign data from various sources to
one or more variables according to the template
(see below for template patterns)
o ARG, parses the argument string(s) passed to the program,
subroutine, or function. UPPER first translates the
strings to uppercase. See also the ARG instruction.
+ o AUTHOR parse the author string.
o EXTERNAL, prompts for input and parses the input string
o NUMERIC, parse the current NUMERIC settings.
o PULL, read and parse the next string from rexx stack
if not empty otherwise prompts from input
See the PULL instruction.
o SOURCE, parse the program source description e.g.
"CMS COMMAND FRED EXEC A fred CMS".
o VALUE, parse the value of expr.
o VAR, parse the value of name.
o VERSION, parse the version string of the interpreter.
PROCEDURE [EXPOSE name [name]...] ;
start a new generation of variables within an internal
routine. Optionally named variables or groups of
variables from an earlier generation may be exposed.
If a stem is specified (variable ending in '.' dot, ie 'A.')
then every variable starting with this stem will be exposed
i = 1; j = 2
call myproc
exit
myproc: procedure expose i /* would display */
say i j /* 1 J */
return
PULL [template] ;
pops the next string from rexx internal stack. If stack
is empty then it prompts for input. Translates it
to uppercase and then parses it according to template.
Short for PARSE UPPER PULL.
push 'Bill Vlachoudis'
/* --- many instrs ---- */
pull name surname /* now: name='BILL', */
/* surname='VLACHOUDIS' */
PUSH [expr] ;
push expr onto head of the rexx queue (stack LIFO)
QUEUE [expr] ;
add expr to the tail of the rexx queue (stack FIFO)
RETURN [expr] ;
return control from a procedure to the point of its invocation.
if expr exits, then it is returned as the result of the
procedure.
num = 6
say num || '! = ' fact(num)
exit
fact: procedure /* calculate factorial with */
if arg(1) = 0 then return 1 /* recursion */
return fact(arg(1)-1) * arg(1) /* displayes: 6! = 720 */
SAY [expr];
evaluate expr and then writes the result to standard output
(normally user's console) followed by a newline.
SELECT ;
WHEN expr [;] THEN [;] instr;
[ WHEN expr [;] THEN [;] instr; ]
[ OTHERWISE [;] [instr]... ];
END ;
SELECT is used to conditionally process one of several alternatives.
Each WHEN expression is evaluated in sequence until
one results in "1". instr, immediately following it, is
executed and control leaves the block. If no
expr evaluated to "1", control passes to the
instructions following the OTHERWISE expression
that must then be present.
num = 10
select
when num > 0 then say num 'is positive'
when num < 0 then say num 'is negative'
otherwise say num 'is zero'
end
SIGNAL [name] |
[VALUE] expr |
+ ERROR + ;
| HALT |
| NOVALUE |
+ SYNTAX +
o NAME, jump to the label name specified. Any pending
instructions, DO ... END, IF, SELECT, and INTERPRET
are terminated.
o VALUE, may be used for an evaluated label name.
o ON|OFF, enable or disable exception traps. Condition
must be ERROR, HALT, NOVALUE, or SYNTAX. Control
passes to the label of the condition name if the event
occurs while ON
signal vivi
...
vivi:
say 'Hi!'
TRACE option;
Trace according to following option. Only first letter of
option is significant.
A (All) trace all clauses.
C (Commands) trace all commands.
E (Error) trace commands with non-zero return codes
after execution.
I (Intermediates) trace intermediate evaluation
results and name substitutions also.
L (Labels) trace only labels.
N (Negative or Normal) trace commands with negative
return codes after execution (default setting).
O (Off) no trace.
R (Results) trace all clauses and expressions.
S (Scan) display rest of program without any
execution (shows control nesting).
- ! turn command inhibition on or off, and trace
- according to next character.
? turn interactive debug (pause after trace) on or
off, and trace according to next character.
null restores the default tracing actions.
TRACE VALUE expr may be used for an evaluated
trace setting.
UPPER name [name]...
translate the values of the specified individual
variables to uppercase.
name = 'Vivi'
upper name /* now: name = 'VIVI' */