Commands to External Environments

Issuing commands to the surrounding environment is an integral part of REXX.

Environment

The system under which REXX programs run is assumed to include at least one environment for processing commands. An environment is selected by default on entry to a REXX program. You can change the environment by using the ADDRESS instruction. You can find out the name of the current environment by using the ADDRESS built-in function. The underlying operating system defines environments external to the REXX program. The default environment for a REXX/CICS program is REXXCICS.

Commands

To send a command to the currently addressed environment, use a clause of the form:

expression;

The expression is evaluated, resulting in a character string (which may be the null string), which is then prepared as appropriate and submitted to the underlying system. Any part of the expression not to be evaluated should be enclosed in quotation marks.

The environment then processes the command, which may have side-effects. It eventually returns control to the language processor, after setting a return code. A return code is a string, typically a number, that returns some information about the command that has been processed. A return code usually indicates if a command was successful or not, but can also represent other information. The language processor places this return code in the REXX special variable RC. See section Special Variables.

In addition to setting a return code, the underlying system may also indicate to the language processor if an error or failure occurred. An error is a condition raised by a command for which a program that uses that command would usually be expected to be prepared. (For example, a locate command to an editing system might report requested string not found as an error.) A failure is a condition raised by a command for which a program that uses that command would not usually be expected to recover (for example, a command that is not executable or cannot be found).

Errors and failures in commands can affect REXX processing if a condition trap for ERROR or FAILURE is ON (see Conditions and Condition Traps). They may also cause the command to be traced if TRACE E or TRACE F is set. TRACE Normal is the same as TRACE F and is the default--see page Purpose.

Here is an example of submitting a command to the default REXX/CICS command environment. The sequence:

TSQ1 = 'TSQUEUE1'
"EXECIO * READ" TSQ1 "MYDATA."

results in the string EXECIO * READ TSQUEUE1 MYDATA. being submitted to REXX/CICS.

On return, the return code placed in RC has the value 0 if the CICS® temporary storage queue TSQUEUE1 was successfully read into MYDATA array. If TSQUEUE1 is empty the appropriate return code is placed in RC.

Note:
Remember that the expression is evaluated before it is passed to the environment. Enclose in quotation marks any part of the expression that is not to be evaluated.

Example:
"EXECIO * READ"         /* * does not mean "multiplied by"  */