Chapter 2. Keyword Instructions

A keyword instruction is one or more clauses, the first of which starts with a keyword that identifies the instruction. Some keyword instructions affect the flow of control, while others provide services to the programmer. Some keyword instructions, like DO, can include nested instructions.

In the syntax diagrams on the following pages, symbols (words) in capitals denote keywords or subkeywords. Other words, such as expression, denote a collection of tokens as defined previously. Note, however, that the keywords and subkeywords are not case-dependent. The symbols if, If, and iF all have the same effect. Note also that you can usually omit most of the clause delimiters (;) shown because the end of a line implies them.

A keyword instruction is recognized only if its keyword is the first token in a clause and if the second token does not start with an equal (=) character (implying an assignment) or a colon (implying a label). The keywords ELSE, END, OTHERWISE, THEN, and WHEN are treated in the same way. Note that any clause that starts with a keyword defined by Rexx cannot be a command. Therefore,

arg(fred) rest

is an ARG keyword instruction, not a command that starts with a call to the ARG built-in function. A syntax error results if the keywords are not in their correct positions in a DO, IF, or SELECT instruction. The keyword THEN is also recognized in the body of an IF or WHEN clause. In other contexts, keywords are not reserved and can be used as labels or as the names of variables (though this is generally not recommended).

Subkeywords are reserved within the clauses of individual instructions. For example, the symbols VALUE and WITH are subkeywords in the ADDRESS and PARSE instructions, respectively. For details, see the description of each instruction.

Whitespace characters (blanks or horizontal tabs) adjacent to keywords separate the keyword from the subsequent token. One or more whitespace characters following VALUE are required to separate the expression from the subkeyword in the example following:

 ADDRESS VALUE expression

However, no whitespace character is required after the VALUE subkeyword in the following example, although it would improve readability:

ADDRESS VALUE"ENVIR"||number

2.1. ADDRESS


>>-ADDRESS--+-----------------------------+--;-----------------><
            +-environment--+------------+-+
            |              +-expression-+ |
            +-+-------+--expression1------+
              +-VALUE-+

ADDRESS temporarily or permanently changes the destination of commands. Commands are strings sent to an external environment. You can send commands by specifying clauses consisting of only an expression or by using the ADDRESS instruction. (See Section 1.15, “Commands to External Environments”.)

To send a single command to a specified environment, code an environment, a literal string or a single symbol, which is taken to be a constant, followed by an expression. The environment name is the name of an external procedure or process that can process commands. The expression is evaluated to produce a character string value, and this string is routed to the environment to be processed as a command. After execution of the command, environment is set back to its original state, thus temporarily changing the destination for a single command. The special variable RC and the environment symbol .RS are set and errors and failures in commands processed in this way are trapped or traced.

Example 2.1. Instructions - ADDRESS (Windows)

ADDRESS CMD "DIR C:\CONFIG.SYS"

Example 2.2. Instructions - ADDRESS (Linux)

ADDRESS "bash" "ls /usr/lib"

If you specify only environment, a lasting change of destination occurs: all commands (see Section 1.15.2, “Commands”) that follow are routed to the specified command environment, until the next ADDRESS instruction is processed. The previously selected environment is saved.

Assume that the environment for a Windows text editor is registered by the name EDIT:

Example 2.3. Instructions - ADDRESS environments

address CMD
"DIR C:\AUTOEXEC.BAT"
if rc=0 then "COPY C:\AUTOEXEC.BAT C:\*.TMP"
address EDIT

Subsequent commands are passed to the editor until the next ADDRESS instruction.

Similarly, you can use the VALUE form to make a lasting change to the environment. Here expression1, which can be a variable name, is evaluated, and the resulting character string value forms the name of the environment. You can omit the subkeyword VALUE if expression1 does not begin with a literal string or symbol, that is, if it starts with a special character such as an operator character or parenthesis.

Example 2.4. Instructions - ADDRESS environments

ADDRESS ("ENVIR"||number)  /* Same as ADDRESS VALUE "ENVIR"||number */

With no arguments, commands are routed back to the environment that was selected before the previous change of the environment, and the current environment name is saved. After changing the environment, repeated execution of ADDRESS alone, therefore, switches the command destination between two environments. Using a null string for the environment name ("") is the same as using the default environment.

The two environment names are automatically saved across internal and external subroutine and function calls. See the CALL instruction (Section 2.3, “CALL”) for more details.

The address setting is the currently selected environment name. You can retrieve the current address setting by using the ADDRESS built-in function. (See Section 7.4.3, “ADDRESS”.) The Open Object Rexx: Programming Guide describes the creation of alternative subcommand environments.