Rexx Programming/Introduction/syntax

Syntax

Looping

The loop control structure in Rexx begins with a DO and ends with an END but comes in several varieties. NetRexx uses the keyword LOOP instead of DO for looping, while ooRexx treats LOOP and DO as equivalent when looping.

Traditional forms:

 do expression [count]
 [instructions]
 end

 do until [condition]
 [instructions]
 end

 do while [condition]
 [instructions]
 end

With an index variable:

 do i = x [to y] [by z]
 [instructions]
 end

another variant:

 do i = x [by z ] [to y] [for k]
 [instructions]
 end

The step increment (z) may be omitted and defaults to 1. The upper limit (y) can also be omitted, which makes the loop continue forever. You can also loop forever without an index variable with this:

 do forever
 [instructions]
 end

A program can break out of the current loop with the leave instruction (which is the normal way to exit a "forever" loop), or can short-circuit it with the iterate instruction.

The do while and do until forms are equivalent to:

 do forever
 if [condition] then leave /*similar to WHILE*/
 [instructions]
 end

and:

 do forever
 [instructions]
 if [condition] then leave /*similar to UNTIL*/
 end

Conditionals

Testing conditions with IF:

 if [condition] then
 do
 [instructions]
 end
 else
 do
 [instructions]
 end

The ELSE clause is optional.

Or, to put it more concisely:

 if [condition] then do
 [instructions]
 end
 else do
 [instructions]
 end

For single instructions, DO and END can also be omitted:

 if [condition] then
 [instruction]
 else
 [instruction]

Or, in another concise version:

 if [condition] then [instruction]
 else [instruction]

Indentation is optional, but it helps improve the readability.

Testing for multiple conditions

SELECT is Rexx's CASE structure, like many other constructs derived from PL/I:

 select
 when [condition] then
 [instruction]
 when [condition] then
 do
 [instructions]
 end
 otherwise
 [instructions] or NOP
 end

NOP indicates no instruction is to be executed.

The OTHERWISE clause is optional. If omitted and no WHEN conditions are met, then the SYNTAX condition is raised.

Simple variables

Variables in Rexx are typeless, and initially are evaluated as their names, in upper case. Thus a variable's type can vary with its use in the program:

 say hello /* => HELLO */
 hello = 25
 say hello /* => 25 */
 hello = "say 5 + 3"
 say hello /* => say 5 + 3 */
 interpret hello /* => 8 */
 drop hello
 say hello /* => HELLO */

Compound variables

Unlike many other programming languages, classic Rexx has no direct support for arrays of variables addressed by a numerical index. Instead it provides compound variables. A compound variable consists of a stem followed by a tail. A . (dot) is used to join the stem to the tail. If the tails used are numeric, it is easy to produce the same effect as an array.

 do i = 1 to 10
 stem.i = 10 - i
 end

Afterwards the following variables with the following values exist: stem.1 = 9, stem.2 = 8, stem.3 = 7...

Unlike arrays, the index for a stem variable is not required to have an integer value. For example, the following code is valid:

 i = 'Monday'
 stem.i = 2

In Rexx it is also possible to set a default value for a stem.

 stem. = 'Unknown'
 stem.1 = 'USA'
 stem.44 = 'UK'
 stem.33 = 'France'

After these assignments the term stem.3 would produce 'Unknown'.

The whole stem can also be erased with the DROP statement.

 drop stem.

This also has the effect of removing any default value set previously.

By convention (and not as part of the language) the compound stem.0 is often used to keep track of how many items are in a stem, for example a procedure to add a word to a list might be coded like this:

 add_word: procedure expose dictionary.
 parse arg w
 n = dictionary.0 + 1
 dictionary.n = w
 dictionary.0 = n
 return

It is also possible to have multiple elements in the tail of a compound variable. For example:

 m = 'July'
 d = 15
 y = 2005
 day.y.m.d = 'Friday'

Multiple numerical tail elements can be used to provide the effect of a multi-dimensional array.

Features similar to Rexx compound variables are found in many other languages (including associative arrays in AWK, hashes in Perl and Hashtables in Java). Most of these languages provide an instruction to iterate over all the keys (or tails in Rexx terms) of such a construct, but this is lacking in classic Rexx. Instead it is necessary to keep auxiliary lists of tail values as appropriate. For example, in a program to count words the following procedure might be used to record each occurrence of a word.

 add_word: procedure expose count. word_list
 parse arg w .
 count.w = count.w + 1 /* assume count. has been set to 0 */
 if count.w = 1 then word_list = word_list w
 return

and then later:

 do i = 1 to words(word_list)
 w = word(word_list,i)
 say w count.w
 end

At the cost of some clarity it is possible to combine these techniques into a single stem:

 add_word: procedure expose dictionary.
 parse arg w .
 dictionary.w = dictionary.w + 1
 if dictionary.w = 1 /* assume dictionary. = 0 */
 then do
 n = dictionary.0+1
 dictionary.n = w
 dictionary.0 = n
 end
 return

and later:

 do i = 1 to dictionary.0
 w = dictionary.i
 say i w dictionary.w
 end

Rexx provides no safety net here, so if one of the words happens to be a whole number less than dictionary.0 this technique will fail mysteriously.

Recent implementations of Rexx, including IBM's Object REXX and the open source implementations like ooRexx include a new language construct to simplify iteration over the value of a stem, or over another collection object such as an array, table or list.

 do i over stem.
 say i '-->' stem.i
 end

Keyword instructions

PARSE

The PARSE instruction is particularly powerful; it combines some useful string-handling functions. Its syntax is:

 parse [upper] origin [template]

where origin specifies the source:

• arg (arguments, at top level tail of command line)
• linein (standard input, e.g. keyboard)
• pull (Rexx data queue or standard input)
• source (info on how program was executed)
• value (an expression) with: the keyword with is required to indicate where the expression ends
• var (a variable)
• version (version/release number)

and template can be:

• list of variables
• column number delimiters
• literal delimiters

upper is optional; if specified, data will be converted to upper case before parsing.

Examples:

Using a list of variables as template

 myVar = "John Smith"
 parse var myVar firstName lastName
 say "First name is:" firstName
 say "Last name is:" lastName

displays the following:

 First name is: John
 Last name is: Smith

Using a delimiter as template:

 myVar = "Smith, John"
 parse var myVar LastName "," FirstName
 say "First name is:" firstName
 say "Last name is:" lastName

also displays the following:

 First name is: John
 Last name is: Smith

Using column number delimiters:

 myVar = "(202) 123-1234"
 parse var MyVar 2 AreaCode 5 7 SubNumber
 say "Area code is:" AreaCode
 say "Subscriber number is:" SubNumber

displays the following:

 Area code is: 202
 Subscriber number is: 123-1234

A template can use a combination of variables, literal delimiters, and column number delimiters.

INTERPRET

The INTERPRET instruction evaluates its argument and treats its value as a Rexx statement. Sometimes INTERPRET is the clearest way to perform a task, but it is often used where clearer code is possible using, e.g., value().

The INTERPRET instruction is powerful and one of the major reasons why writing Rexx compilers is not trivial.

The other reasons being Rexx's (decimal) arbitrary precision arithmetic (including fuzzy comparisons), use of the PARSE statement with programmatic templates, stemmed arrays, and sparse arrays. -->

 /* a touch of [[w:Lisp (programming language)|LISP]] */
 X = 'square'
 interpret 'say' X || '(4) ; exit'
 SQUARE: return arg(1)**2

This displays 16 and exits. Because variable contents in Rexx are strings, including rational numbers with exponents and even entire programs, Rexx offers to interpret strings as evaluated expressions.

This feature could be used to pass functions as function parameters, such as passing SIN or COS to a procedure to calculate integrals.

Rexx offers only basic math functions like ABS, DIGITS, MAX, MIN, SIGN, RANDOM, and a complete set of hex plus binary conversions with bit operations. More complex functions like SIN had to be implemented from scratch or obtained from third party external libraries. Some external libraries, typically those implemented in traditional languages, did not support extended precision.

Later versions (non-classic) support CALL variable constructs. Together with the built-in function VALUE, CALL can be used in place of many cases of INTERPRET. This is a classic program:

 /* terminated by input "exit" or similar */
 do forever ; interpret linein() ; end

A slightly more sophisticated "Rexx calculator":

 X = 'input BYE to quit'
 do until X = 'BYE' ; interpret 'say' X ; pull X ; end

PULL is shorthand for parse upper pull. Likewise, ARG is shorthand for parse upper arg.

The power of the INTERPRET instruction had other uses. The Valour software package relied upon Rexx's interpretive ability to implement an object-oriented programming environment. Another use was found in an unreleased Westinghouse product called Time Machine that was able to fully recover following a fatal error.

NUMERIC

 say digits() fuzz() form() /* => 9 0 SCIENTIFIC */
 say 999999999+1 /* => 1.000000000E+9 */
 numeric digits 10 /* only limited by available memory */
 say 999999999+1 /* => 1000000000 */

 say 0.9999999999=1 /* => 0 (false) */
 numeric fuzz 3
 say 0.99999999=1 /* => 1 (true) */
 say 0.99999999==1 /* => 0 (false) */

 say 100*123456789 /* => 1.23456789E+10 */
 numeric form engineering
 say 100*123456789 /* => 12.34567890E+9 */

 numeric digits 50
 n=2
 r=1
 do forever /* Newton's method */
 rr=(n/r+r)/2
 if r=rr then leave
 r=rr
 end
 say "root" n '=' r /*root 2=1.414213562373095048801688724209698078569671875377*/

 numeric digits 50
 e=2.5
 f=0.5
 do n=3
 f=f/n
 ee=e+f
 if e=ee then leave
 e=ee
 end
 say "e=" e /*e=2.7182818284590452353602874713526624977572470936998*/

SIGNAL

The SIGNAL instruction is intended for abnormal changes in the flow of control (see the next section). However it like the GOTO statement found in other languages can be misused creating difficult-to-read code.

Error handling and exceptions

It is possible in Rexx to intercept and deal with errors and other exceptions, using the SIGNAL instruction. There are seven system conditions: ERROR, FAILURE, HALT, NOVALUE, NOTREADY, LOSTDIGITS and SYNTAX. Handling of each can be switched on and off in the source code as desired.

The following program will run until terminated by the user:

 signal on halt;
 do a = 1
 say a
 do 100000 /* a delay */
 end
 end
 halt:
 say "The program was stopped by the user"
 exit

Virtually all serious Rexx programs contain signal on novalue or a similar statement. This disables the "feature", where undefined variables get their own (upper case) name as value. The status of a variable can be checked with the built-in function SYMBOL returning VAR for defined variables.

Function VALUE can be used to get the value of variables without triggering a NOVALUE condition, but its main purpose is to read and set environment variables, similar to POSIX getenv and putenv.

Conditions

ERROR	Positive RC from a system command
FAILURE	Negative RC for a system command (e.g. command doesn't exist)
HALT	Abnormal termination
NOVALUE	An unset variable was referenced
NOTREADY	Input or output error (e.g. read attempts beyond end of file)
SYNTAX	Invalid program syntax, or some other error condition
LOSTDIGITS	Significant digits are lost (ANSI Rexx, not in TRL second edition)

When a condition is handled by SIGNAL ON, the SIGL and RC system variables can be analyzed to understand the situation. RC contains the Rexx error code and SIGL contains the line number where the error arose.

Beginning with Rexx version 4 conditions can get names, and there's also a CALL ON construct. That's handy if external functions do not necessarily exist:

 ChangeCodePage: procedure /* protect SIGNAL settings */
 signal on syntax name ChangeCodePage{{not a typo|.}}Trap
 return SysQueryProcessCodePage()
 ChangeCodePage.Trap: return 1004 /* windows-1252 on OS/2 */