REXX programs are recommended to start with a comment. REXX/CICS does not require this. However, for portability reasons, you are recommended to start each REXX program with a comment that begins on the first line and includes the word REXX. The example in Figure 48 illustrates this. The program starts with a comment and the characters "REXX" are in the first line (line 1).
/* REXX program */
...
...
...
EXIT
A REXX program is built from a series of clauses that are composed of:
Conceptually, each clause is scanned from left to right before processing, and the tokens composing it are identified. Instruction keywords are recognized at this stage, comments are removed, and multiple blanks (except within literal strings) are converted to single blanks. Blanks adjacent to operator characters and special characters (see page ***) are also removed.
Implementation maximum: The length of a clause cannot exceed 16K.
A character is a member of a defined set of elements that is used for the control or representation of data. You can usually enter a character with a single keystroke. The coded representation of a character is its representation in digital form. A character, the letter A, for example, differs from its coded representation or encoding. Various coded character sets (such as ASCII and EBCDIC) use different encodings for the letter A (decimal values 65 and 193, respectively). This book uses characters to convey meanings and not to imply a specific character code, except where otherwise stated. The exceptions are certain built-in functions that convert between characters and their representations. The functions C2D, C2X, D2C, X2C, and XRANGE have a dependence on the character set in use.
A code page specifies the encodings for each character in a set. You should be aware that:
For information about Double-Byte Character Set characters, see Appendix C. Double-Byte Character Set (DBCS) Support.
A comment is a sequence of characters (on one or more lines) delimited by /* and */. Within these delimiters any characters are allowed. Comments can contain other comments, as long as each begins and ends with the necessary delimiters. They are called nested comments. Comments can be anywhere and can be of any length. They have no effect on the program, but they do act as separators. (Two tokens with only a comment in between are not treated as a single token.)
/* This is an example of a valid REXX comment */
Take special care when commenting out lines of code containing /* or */ as part of a literal string. Consider the following program segment:
01 parse pull input
02 if substr(input,1,5) = '/*123'
03 then call process
04 dept = substr(input,32,5)
To comment out lines 2 and 3, the following change would be incorrect:
01 parse pull input
02 /* if substr(input,1,5) = '/*123'
03 then call process
04 */ dept = substr(input,32,5)
This is incorrect because the language processor would interpret the /* that is part of the literal string /*123 as the start of a nested comment. It would not process the rest of the program because it would be looking for a matching comment end (*/).
You can avoid this type of problem by using concatenation for literal strings containing /* or */; line 2 would be:
if substr(input,1,5) = '/' || '*123'
You could comment out lines 2 and 3 correctly as follows:
01 parse pull input
02 /* if substr(input,1,5) = '/' || '*123'
03 then call process
04 */ dept = substr(input,32,5)
For information about Double-Byte Character Set characters, see Appendix C. Double-Byte Character Set (DBCS) Support and the OPTIONS instruction on page OPTIONS.
A token is the unit of low-level syntax from which clauses are built. Programs written in REXX are composed of tokens. They are separated by blanks or comments or by the nature of the tokens themselves. The classes of tokens are:
A literal string with no characters (that is, a string of length 0) is called a null string.
These are valid strings:
'Fred'
"Don't Panic!"
'You shouldn''t' /* Same as "You shouldn't" */
'' /* The null string */
Note that a string followed immediately by a ( is considered to be the name of a function. If followed immediately by the symbol X or x, it is considered to be a hexadecimal string. If followed immediately by the symbol B or b, it is considered to be a binary string. Descriptions of these forms follow. Implementation maximum:A literal string can contain up to 250 characters. But note that the length of computed results is limited only by the amount of storage available. See the note on page *** for more information.
Hexadecimal strings let you include characters in a program even if you cannot directly enter the characters themselves. These are valid hexadecimal strings:
'ABCD'x
"1d ec f8"X
"1 d8"x
Implementation maximum: The packed length of a hexadecimal string (the string with blanks removed) cannot exceed 250 bytes.
A binary string is a literal string formed by packing the binary digits given. If the number of binary digits is not a multiple of eight, leading zeros are added on the left to make a multiple of eight before packing. Binary strings allow you to specify characters explicitly, bit by bit.
These are valid binary strings:
'11110000'b /* == 'f0'x */
"101 1101"b /* == '5d'x */
'1'b /* == '00000001'b and '01'x */
'10000 10101010'b /* == '0001 0000 1010 1010'b */
''b /* == '' */
Implementation maximum: The packed length of a hexadecimal string (the string with blanks removed) cannot exceed 250 bytes.
These are valid symbols:
Fred
Albert.Hall
WHERE?
<.H.E.L.L.O> /* This is DBCS */
For information about Double-Byte Character Set (DBCS) characters, see Appendix C. Double-Byte Character Set (DBCS) Support.
If a symbol does not begin with a digit or a period, you can use it as a variable and can assign it a value. If you have not assigned it a value, its value is the characters of the symbol itself, translated to uppercase (that is, lowercase a-z to uppercase A-Z). Symbols that begin with a number or a period are constant symbols and cannot be assigned a value.
One other form of symbol is allowed to support the representation of numbers in exponential format. The symbol starts with a digit (0-9) or a period, and it may end with the sequence E or e, followed immediately by an optional sign (- or +), followed immediately by one or more digits (which cannot be followed by any other symbol characters). The sign in this context is part of the symbol and is not an operator.
These are valid numbers in exponential notation:
17.3E-12
.03e+9
Implementation maximum: A symbol can consist of up to 250 characters. But note that its value, if it is a variable, is limited only by the amount of storage available. See the note on page *** for more information.
Numbers can have leading blanks (before and after the sign, if any) and can have trailing blanks. Blanks may not be embedded among the digits of a number or in the exponential part. Note that a symbol (see preceding) or a literal string may be a number. A number cannot be the name of a variable.
These are valid numbers:
12
'-17.9'
127.0650
73e+128
' + 7.9E5 '
'0E000'
You can specify numbers with or without quotation marks around them. Note that the sequence -17.9 (without quotation marks) in an expression is not simply a number. It is a minus operator (which may be prefix minus if no term is to the left of it) followed by a positive number. The result of the operation is a number.
A whole number is a number that has a zero (or no) decimal part and that the language processor would not usually express in exponential notation. That is, it has no more digits before the decimal point than the current setting of NUMERIC DIGITS (the default is 9).
Implementation maximum: The exponent of a number expressed in exponential notation can have up to nine digits.
345>=123
345 >=123
345 >= 123
345 > = 123
Some of these characters may not be available in all character sets, and, if this is the case, appropriate translations may be used. In particular, the vertical bar (|) or character is often shown as a split vertical bar.
Throughout the language, the not character, ¬, is synonymous with the backslash (\). You can use the two characters interchangeably according to availability and personal preference.
, ; : ) (
These characters constitute
the set of special characters. They all act as token delimiters, and
blanks adjacent to any of these are removed. There is an exception:
a blank adjacent to the outside of a parenthesis is deleted only if
it is also adjacent to another special character (unless the character
is a parenthesis and the blank is outside it, too). For example, the
language processor does not remove the blank in A (Z).
This is a concatenation that is not equivalent to A(Z),
a function call. The language processor does remove the blanks in (A) + (Z) because
this is equivalent to (A)+(Z).
The following example shows how a clause is composed of tokens.
'REPEAT' A + 3;
This is composed of six tokens--a literal string ('REPEAT'), a blank operator, a symbol (A, which may have a value), an operator (+), a second symbol (3, which is a number and a symbol), and the clause delimiter (;). The blanks between the A and the + and between the + and the 3 are removed. However, one of the blanks between the 'REPEAT' and the A remains as an operator. Thus, this clause is treated as though written:
'REPEAT' A+3;
The last element in a clause is the semicolon delimiter. The language processor implies the semicolon: at a line-end, after certain keywords, and after a colon if it follows a single symbol. This means that you need to include semicolons only when there is more than one clause on a line or to end an instruction whose last character is a comma.
A line-end usually marks the end of a clause and, thus, REXX implies a semicolon at most end of lines. However, there are the following exceptions:
REXX automatically implies semicolons after colons (when following a single symbol, a label) and after certain keywords when they are in the correct context. The keywords that have this effect are: ELSE, OTHERWISE, and THEN. These special cases reduce typographical errors significantly.
One way to continue a clause onto the next line is to use the comma, which is referred to as the continuation character. The comma is functionally replaced by a blank, and, thus, no semicolon is implied. One or more comments can follow the continuation character before the end of the line. The continuation character cannot be used in the middle of a string or it will be processed as part of the string itself. The same situation holds true for comments. Note that the comma remains in execution traces.
The following example shows how to use the continuation character to continue a clause.
say 'You can use a comma',
'to continue this clause.'
This displays:
You can use a comma to continue this clause.