Host command environments for linking to and attaching programs

TSO/E provides the LINK, LINKMVS, and LINKPGM host command environments that let you link to unauthorized programs on the same task level.

TSO/E also provides the ATTACH, ATTCHMVS, and ATTCHPGM host command environments that let you attach unauthorized programs on a different task level.

When REXX attaches a program under any of these host command environments, the REXX exec task waits until the attached program completes. (That is, the attach is synchronous, not asynchronous.) Once the attached program returns, the REXX exec resumes at the point after the attach. The REXX exec can examine the REXX special variable RC for the results of the attach, as discussed below.

These link and attach environments are available to REXX execs that run in any address space.

To link to or attach a program, specify the name of the program followed by any parameters you want to pass to the program. For example: 
ADDRESS LINKMVS "program p1 p2 ... pn"

ADDRESS ATTCHPGM "program p1 p2 ... pn"
Enclose the name of the program and any parameters in either single or double quotation marks.
The host command environment routines for the environments use the following search order to locate the program:
  • Job pack area
  • ISPLLIB. If the user issued LIBDEF ISPLLIB ..., the system searches the new alternate library defined by LIBDEF followed by the ISPLLIB library.
  • Task library and all preceding task libraries
  • Step library. If there is no step library, the job library is searched, if one exists.
  • Link pack area (LPA)
  • Link library.
The differences between the environments are the format of the parameter list that the program receives, the capability of passing multiple parameters, variable substitution for the parameters, and the ability of the invoked program to update the parameters.
  • For the LINK and ATTACH environments, you can specify only a single character string that gets passed to the program. The LINK and ATTACH environments do not evaluate the character string and do not perform variable substitution. The environments simply pass the string to the invoked program. The program can use the character string it receives. However, the program cannot return an updated string to the exec.
  • For the LINKMVS, LINKPGM, ATTCHMVS, and ATTCHPGM environments, you can pass multiple parameters to the program. The environments evaluate the parameters you specify and perform variable substitution. That is, the environment determines the value of each variable. When the environment invokes the program, the environment passes the value of each variable to the program. The program can update the parameters it receives and return the updated values to the exec.
After you link to or attach the program, the host command environment sets a return code in the REXX special variable RC. For all of the link and attach environments, the return code may be:
  • A -3 if the host command environment could not locate the program you specified
  • The return code that the linked or attached program set in register 15
Additionally, for the LINKMVS, ATTCHMVS, LINKPGM, and ATTCHPGM environments, the return code set in RC may be -2, which indicates that processing of the variables was not successful. Variable processing may have been unsuccessful because the host command environment could not:
  • Perform variable substitution before linking to or attaching the program
  • Update the variables after the program completed

For LINKMVS and ATTCHMVS, you can also receive an RC value of -2 if the length of the value of the variable was larger than the length that could be specified in the signed halfword length field in the parameter list. The maximum value of the halfword length field is 32,767.

Note that the value that can be set in the RC special variable for the LINK, LINKMVS, and LINKPGM environments is a signed 31-bit number in the range -2,147,483,648 to +2,147,483,647. The value that can be set in RC for the ATTACH, ATTCHMVS, and ATTCHPGM environments is a signed 24-bit number in the range -8,388,608 to +8,388,607.

The following topics describe how to link to and attach programs using the different host command environments.