2.4. Instructions In this section, all instructions in standard REXX are described. Extensions are listed later in this chapter. First some notes on the terminology. What is called an instruction in this document is equivalent to a “unit” of clauses. That is, each instruction can consist of one or more clauses. For instance, the SAY instruction is always a single instruction, but the IF instruction is a multi-clause instruction. Consider the following script, where each clause has been boxed: if a=b then say ‘hello’ else say ‘bye’ Further, the THEN or ELSE parts of this instruction might consist of a DO/END pair, in which case the IF instruction might consists of an virtually unlimited number of clauses. Then, some notes on the syntax diagrams used in the following descriptions of the instructions. The rules applying to these diagrams can be listed as: · Anything written in courier font in the syntax diagrams indicates that it should occur as-is in the REXX program. Whenever something is written in italic font, it means that the term should be substituted for another value, expression, or terms. · Anything contained within matching pairs of square brackets ([...]) are optional, and may be left out. · Whenever a pair or curly braces is used, it contains two or more subclauses that are separated by the vertical bar (|). It means that the curly braces will be substituted for one of the subclauses it contains. · Whenever the ellipsis (...) is used, it indicates that the immediately following subclauses may be repeated zero or more times. The scope of the ellipsis is limited to the contents of a set of square brackets or curly braces, if it occurs there. · Whenever the vertical bar | is used in any of the syntax diagrams, it means that either the term to the left, or the term to the right can be used, but not both, and at least one of the must be used. This “operator” is associative (can be used in sequence), and it has lower priority than the square brackets (the scope of the vertical bar located within a pair of square brackets or curly braces is limited to the text within those square brackets or curly braces. · Whenever a semicolon (;) is used in the syntax diagram, it indicates that a clause separator must be present at the point. It may either be a semicolon character, or an end-of-line. · Whenever the syntax diagram is spread out over more lines, it means that any of the lines can be used, but that the individual lines are mutually exclusive. Consider the syntax: SAY = symbol string This is equivalent to the syntax: SAY [symbol | string ] Because in the first of these two syntaxes, the SAY part may be continued at either line. · Sometimes the syntax of an instruction is so complex that parts of the syntax has been extracted, and is shown below in its expanded state. The following is an example of how this looks: SAY something TO someone something : = HI HELLO BYE someone : = THE BOSS YOUR NEIGHBOR You can generally identify these situations by the fact that they comes a bit below the real syntax diagram, and that they contains a colon character after the name of the term to be expanded. In the syntax diagrams, some generic names have been used for the various parts, in order to indicate common attributes for the term. For instance, whenever a term in the syntax diagrams is called expr, it means that any valid REXX expression may occur instead of that term. The most common such names are: condition Indicates that the subclause can be any of the names of the conditions, e.g. SYNTAX, NOVALUE, HALT, etc. expr Indicates that the subclause can be any valid REXX expression, and will in general be evaluated as normal during execution. statement Indicates that extra clauses may be inserted into the instruction, and that exactly one of them must be a true statement. string Indicates that the subclause is a constant string, i.e. either enclosed by single quotes (’...’) or double quotes (”...”). symbol Indicates that the subclause is a single symbol. In general, whenever symbol is used as the name for a subclause, it means that the symbol will not automatically be expanded to the value of the symbol. But instead, some operation is performed on the name of the symbol. template Indicates that the subclause is a parsing template. The exact syntax of this is explain in a chapter on tracing, to be written later. In addition to this, variants may also exists. These variants will have an extra letter or number appended to the name of the subclause, and is used for differing between two or more subclauses having the same “type” in one syntax diagram. In the case of other names for the subclauses, these are explained in the description of the instruction.