Syntax of REXX Instructions

Some programming languages have rigid rules about how and where you enter characters on each line. For example, assembler statements must begin in a certain column. REXX, on the other hand, has simple syntax rules. You can use upper or lower or mixed case. REXX has no restrictions about the columns in which you can type.

An instruction can begin in any column on any line. The following are all valid instructions.

SAY 'You can type in any column'
                      SAY 'You can type in any column'
                                          SAY 'You can type in any column'

These instructions are sent to the terminal output device:

You can type in any column
You can type in any column
You can type in any column

The Format of REXX Instructions

The REXX language has free format. This means you can insert extra spaces between words. For example, the following all mean the same:

total=num1+num2
total =num1+num2
total = num1+num2
total = num1 + num2

You can also insert blank lines throughout a program without causing an error.

The Letter Case of REXX Instructions

You can enter a REXX instruction in lowercase, uppercase, or mixed case. For example, SAY, Say, and say all have the same meaning. The language processor translates alphabetic characters to uppercase, unless you enclose them in single or double quotation marks.

Using Quotation Marks in an Instruction

A series of characters within matching quotation marks is a literal string. The following examples contain literal strings.

SAY 'This is a REXX literal string.'  /* Using single quotation marks */

SAY "This is a REXX literal string."  /* Using double quotation marks */

Do not enclose a literal string with one each of the two different types of quotation marks. For example, the following is incorrect:

SAY 'This is a REXX literal string." /* Using mismatched quotation marks */

If you omit the quotation marks around a literal string in a SAY instruction, the language processor usually translates the statement to uppercase. For example,

SAY This is a REXX string.

results in:

THIS IS A REXX STRING.

(This assumes none of the words is the name of a variable that you have already assigned a value. In REXX, the default value of a variable is its own name in uppercase.)

If a string contains an apostrophe, you can enclose the literal string in double quotation marks.

SAY "This isn't difficult!"

You can also use two single quotation marks in place of the apostrophe, because a pair of single quotation marks is processed as one.

SAY 'This isn''t difficult!'

Either way, the outcome is the same.

This isn't difficult!

Ending an instruction

A line usually contains one instruction except when it contains a semicolon (;) or ends with a comma (,).

The end of the line or a semicolon indicates the end of an instruction. If you put one instruction on a line, the end of the line delineates the end of the instruction. If you put multiple instructions on one line, you must separate adjacent instructions with a semicolon.

SAY 'Hi!'; say 'Hi again!'; say 'Hi for the last time!'

This example would result in three lines.

Hi!
Hi again!
Hi for the last time!

Continuing an instruction

A comma is the continuation character. It indicates that the instruction continues to the next line. The comma, when used in this manner, also adds a space when the lines are concatenated. Here is how the comma continuation character works when a literal string is being continued on the next line.

SAY 'This is an extended',
    'REXX literal string.'

The comma at the end of the first line adds a space (between extended and REXX when the two lines are concatenated for output. A single line results:

This is an extended REXX literal string.

The following two instructions are identical and yield the same result:

SAY 'This is',
    'a string.'

SAY 'This is' 'a string.'

The space between the two separate strings is preserved:

This is a string.

Continuing a literal string without adding a space

If you need to continue an instruction to a second or more lines, but do not want REXX to add spaces in the line, use the concatenation operand (two single OR bars, ||).

SAY 'This is an extended literal string that is bro'||,
    'ken in an awkward place.'

This example results in one line no space in the word "broken".

This is an extended literal string that is broken in an awkward place.

Also note that the following two instructions are identical and yield the same result:

SAY 'This is' ||,
    'a string.'

SAY 'This is' || 'a string.'

These examples result in:

This isa string.

In both examples, the concatenation operator deletes spaces between the two strings.

The following example demonstrates the free format of REXX.

Figure 3. Example of Free Format
/************************* REXX *****************************/
SAY 'This is a REXX literal string.'
SAY               'This is a REXX literal string.'
  SAY 'This is a REXX literal string.'
SAY,
'This',
'is',
'a',
'REXX',
'literal',
'string.'

SAY'This is a REXX literal string.';SAY'This is a REXX literal string.'
SAY '     This is a REXX literal string.'

Running this example results in six lines of identical output, followed by one indented line.

This is a REXX literal string.
This is a REXX literal string.
This is a REXX literal string.
This is a REXX literal string.
This is a REXX literal string.
This is a REXX literal string.
     This is a REXX literal string.

Thus, you can begin an instruction anywhere on a line, you can insert blank lines, and you can insert extra spaces between words in an instruction. The language processor ignores blank lines, and it ignores spaces that are greater than one. This flexibility of format lets you insert blank lines and spaces to make a program easier to read.

Blanks and spaces are only significant during parsing, see section Parsing Data.

Types of REXX Clauses

REXX clauses can be: instructions, null clauses, and labels. Instructions can be keyword instructions, assignments, or commands. The following example shows a program with these types of clauses. A description of each type of clause follows the example.

/* QUOTA REXX program. Two car dealerships are competing to  */
/* sell the most cars in 30 days.  Who will win?             */

store_a=0; store_b=0
DO 30
   CALL sub
END
IF store_a>store_b THEN SAY "Store_a wins!"
 ELSE IF store_b>store_a THEN SAY "Store_b wins!"
  ELSE SAY "It's a tie!"
EXIT

sub:
store_a=store_a+RANDOM(0,20) /* RANDOM returns a random number in */
store_b=store_b+RANDOM(0,20) /* in specified range, here 0 to 20  */
RETURN

Keyword Instructions

A keyword instruction tells the language processor to do something. It begins with a REXX keyword that identifies what the language processor is to do. For example, DO can group instructions and execute them repetitively, and IF tests whether a condition is met. SAY writes to the current terminal output device.

IF, THEN and ELSE are three keywords that work together in one instruction. Each keyword forms a clause, which is a subset of an instruction. If the expression that follows the IF keyword is true, the instruction that follows the THEN keyword is processed. Otherwise, the instruction that follows the ELSE keyword is processed. (Note that a semicolon is needed before the ELSE if you are putting an ELSE clause on the same line with a THEN.) If you want to put more than one instruction after a THEN or ELSE, use a DO before the group of instructions and an END after them. More information about the IF instruction appears in section Using Conditional Instructions.

The EXIT keyword tells the language processor to end the program. Using EXIT in the preceding example is necessary because, otherwise, the language processor would execute the code in the subroutine after the label sub:. EXIT is not necessary in some programs (such as those without subroutines), but it is good programming practice to include it. More about EXIT appears in section EXIT Instruction.

Assignment

An assignment gives a value to a variable or changes the current value of a variable. A simple assignment instruction is:

number = 4

In the preceding program, a simple assignment instruction is: store_a=0. The left side of the assignment (before the equal sign) contains the name of the variable to receive a value from the right side (after the equal sign). The right side can be an actual value (such as 4) or an expression. An expression is something that needs to be evaluated, such as an arithmetic expression. The expression can contain numbers, variables, or both.

number = 4 + 4

number = number + 4

In the first example, the value of number is 8. If the second example directly followed the first in a program, the value of number would become 12. More about expressions is in section Using Expressions.

Label

A label, such as sub: is a symbolic name followed by a colon. A label can contain either single- or double-byte characters or a combination of single- and double-byte characters. (Double-byte characters are valid only if OPTIONS ETMODE is the first instruction in your program.) A label identifies a portion of the program and is commonly used in subroutines and functions, and with the SIGNAL instruction. (Note that you need to include a RETURN instruction at the end of a subroutine to transfer control back to the main program.) More about the use of labels appears in Writing Subroutines and Functions and section SIGNAL Instruction.

Null Clause

A null clause consists of only blanks or comments or both. The language processor ignores null clauses, but they make a program easier to read.

Comments
A comment begins with /* and ends with */. Comments can be on one or more lines or on part of a line. You can put information in a comment that might not be obvious to a person reading the REXX instructions. Comments at the beginning of a program can describe the overall purpose of the program and perhaps list special considerations. A comment next to an individual instruction can clarify its purpose.
Note:
REXX/CICS does not require that a REXX program begin with a comment. However, for portability reasons, you may want to start each REXX program with a comment that includes the word REXX.
Not every language processor requires this program identifier. However, to run the same exec on MVS TSO and CICS, you should include the /* REXX */ program identifier to satisfy TSO requirements.
Blank lines
Blank lines separate groups of instructions and aid readability. The more readable a program is, the easier it is to understand and maintain.

Commands

A command is a clause consisting of only an expression. Commands are sent to a previously defined environment for processing. (You should enclose in quotation marks any part of the expression not to be evaluated.) The example program did not include any commands. The following example includes a command in an ADDRESS instruction:

/* REXX program including a command */
ADDRESS REXXCICS 'DIR'

ADDRESS is a keyword instruction. When you specify an environment and a command on an ADDRESS instruction, a single command is sent to the environment you specify. In this case, the environment is REXXCICS. The command is the expression that follows the environment:

'DIR'

The DIR command lists the files in your current file system directory. For more details about changing the host command environment, see section Changing the Host Command Environment.

More information about issuing commands appears in Using Commands from a program.