Host command environment table

The host command environment table contains the names of environments for processing commands. The table contains the names you can specify on the ADDRESS instruction. In the parameter block, the SUBCOMTB field points to the host command environment table (see Table 1).

The table contains the environment names (for example, TSO, MVS™, LINK, and ATTACH) that are valid for execs that run in the language processor environment. The table also contains the names of the routines that the system invokes to handle "commands" for each host command environment.

You can add, delete, update, and query entries in the host command environment table using the IRXSUBCM routine. For more information, see Maintain entries in the host command environment table - IRXSUBCM.

When a REXX exec runs, the exec has at least one active host command environment that processes host commands. When the REXX exec begins processing, a default environment is available. The default is specified in the host command environment table. In the REXX exec, you can use the ADDRESS instruction to change the host command environment. When the language processor processes a command, the language processor first evaluates the expression and then passes the command to the host command environment for processing. A specific routine that is defined for that host command environment then handles the command processing. Commands to external environments describes how to issue commands to the host.

In the PARMBLOCK, the SUBCOMTB field points to the host command environment table. The table consists of two parts; the table header and the individual entries in the table. Table 1 shows the format of the host command environment table header. The first field in the header points to the first host command environment entry in the table. Each host command environment entry is defined by one row in the table. Each row contains the environment name, corresponding routine to handle the commands, and a user token. TSO/E provides a mapping macro IRXSUBCT for the host command environment table. The mapping macro is in SYS1.MACLIB.

Table 1. Format of the host command environment table header
Offset (decimal)	Number of bytes	Field name	Description
0	4	ADDRESS	Specifies the address of the first entry in the table. The address is a fullword binary number. Table 2 illustrates each row of entries in the table. Each row of entries in the table has an 8-byte field (NAME) that contains the name of the environment, a second 8-byte field (ROUTINE) that contains the name of the corresponding routine, followed by a 16-byte field (TOKEN) that is a user token.
4	4	TOTAL	Specifies the total number of entries in the table. This number is the total of the used and unused entries in the table and is a fullword binary number.
8	4	USED	Specifies the number of valid entries in the table. The number is a fullword binary number. All valid entries begin at the top of the table and are then followed by any unused entries. The unused entries must be on the bottom of the table.
12	4	LENGTH	Specifies the length of each entry in the table. This is a fullword binary number.
16	4	INITIAL	Specifies the name of the initial host command environment. This is the default environment for any REXX exec that is invoked and that is not invoked as either a function or a subroutine. The INITIAL field is used only if you call the exec processing routine IRXEXEC to run a REXX exec and you do not pass an initial host command environment on the call. Exec processing routines - IRXJCL and IRXEXEC describes the IRXEXEC routine and its parameters.
20	8	—	Reserved. The field is set to blanks.
28	8	—	The end of the table header must be indicated by X'FFFFFFFFFFFFFFFF'.

Table 2 shows three rows (three entries) in the host command environment table. The NAME, ROUTINE, and TOKEN fields are described in more detail after the table.

Table 2. Format of entries in host command environment table
Offset (decimal)	Number of bytes	Field name	Description
0	8	NAME	The name of the first environment (entry) in the table.
8	8	ROUTINE	The name of the routine that the system invokes to handle the processing of host commands in the environment specified at offset +0.
16	16	TOKEN	A user token that is passed to the routine (at offset +8) when the routine is invoked.
32	8	NAME	The name of the second environment (entry) in the table.
40	8	ROUTINE	The name of the routine that the system invokes to handle the processing of host commands in the environment specified at offset +32.
48	16	TOKEN	A user token that is passed to the routine (at offset +40) when the routine is invoked.
64	8	NAME	The name of the third environment (entry) in the table.
72	8	ROUTINE	The name of the routine that the system invokes to handle the processing of host commands in the environment specified at offset +64.
80	16	TOKEN	A user token that is passed to the routine (at offset +72) when the routine is invoked.

The following describes each entry (row) in the table.

NAME

An 8-byte field that specifies the name of the host command environment defined by this row in the table. The string is eight characters long, left justified, and is padded with blanks.

If the REXX exec uses the

ADDRESS name

instruction, and the value name in not in the table, no error is detected. However, when the language processor tries to locate the entry in the table to pass a command and no corresponding entry is found, the language processor returns with a return code of -3, which indicates an error condition.

ROUTINE

An 8-byte field that specifies the name of a routine for the entry in the NAME field in the same row in the table. This is the routine to which a string is passed for this environment. The field is eight characters long, left justified, and is padded with blanks.

If the language processor locates the entry in the table, but finds this field blank or cannot locate the routine specified, the language processor returns with a return code of -3. This is equivalent to the language processor not being able to locate the host command environment name in the table.

TOKEN

A 16-byte field that is stored in the table for the user's use (a user token). The value in the field is passed to the routine specified in the ROUTINE field when the system calls the routine to process a command. The field is for the user's own use. The language processor does not use or examine this token field.

When a REXX exec is running in the language processor environment and a host command environment must be located, the system searches the entire host command environment table from bottom to top. The first occurrence of the host command environment in the table is used. If the name of the host command environment that is being searched for matches the name specified in the table (in the NAME field), the system calls the corresponding routine specified in the ROUTINE field of the table.