Host commands and host command environments

You can issue host commands from a REXX program. When the language processor processes a clause that it does not recognize as a REXX instruction or an assignment instruction, the language processor considers the clause to be a host command and routes the command to the current host command environment. The host command environment processes the command and then returns control to the language processor.

For example, in REXX processing, a host command can be:
  • A TSO/E command processor, such as ALLOCATE, FREE, or EXEC
  • A TSO/E REXX command, such as NEWSTACK or QBUF
  • A program that you link to or attach
  • An MVS system or subsystem command that you invoke during an extended MCS console session
  • An ISPF command or service
  • An SAA CPI Communications call or APPC/MVS call
If a REXX exec contains 
FRED var1 var2
the language processor considers the clause to be a command and passes the clause to the current host command environment for processing. The host command environment processes the command, sets a return code in the REXX special variable RC, and returns control to the language processor. The return code set in RC is the return code from the host command you specified. For example, the value in RC may be the return code from a TSO/E command processor, an ISPF command or service, or a program you attached. The return code may also be a -3, which indicates that the host command environment could not locate the specified host command (TSO/E command, CLIST, exec, attached or linked routine, ISPF command or service, and so on). A return code of -3 is always returned if you issue a host command in an exec and the host command environment cannot locate the command. A return code of -3 is also returned if a TSO/E host command is in the AUTHCMD list of the IKJTSOxx parmlib member and the host command is found in a non-APF authorized library. This is different from what happens in a CLIST or line-mode TSO/E when a command from the AUTHCMD list is found in a non-APF authorized library. In those cases, the command is called and runs unauthorized. However, in a REXX exec if a command from the AUTHCMD list is found in a non-APF authorized library, it fails.

If you issue a host command from a REXX exec that is running in an authorized or isolated environment, a -3 return code might be returned.

If a system abend occurs during a host command, the REXX special variable RC is set to the negative of the decimal value of the abend code. If a user abend occurs during a host command, the REXX special variable RC is set to the decimal value of the abend code. If no abend occurs during a host command, the REXX special variable RC is set to the decimal value of the return code from the command.

Certain conditions may be raised depending on the value of the special variable RC:
  • If the RC value is negative, the FAILURE condition is raised.
  • If the RC value is positive, the ERROR condition is raised.
  • If the RC value is zero, neither the ERROR nor FAILURE conditions are raised.

See Conditions and condition traps for more information.

Tip: If you issue a host command in a REXX exec, you should enclose the entire command in double quotation marks. For example: 
"routine-name var1 var2"

TSO/E provides several host command environments that process different types of host commands. The following topics describe the different host command environments TSO/E provides for non-TSO/E address spaces and for the TSO/E address space (TSO/E and ISPF).