The LINKMVS and ATTCHMVS host command environments

For the LINKMVS and ATTCHMVS environments, you can pass multiple parameters to the program. Specify the name of the program followed by variable names for each of the parameters. Separate each variable name by one or more blanks. For example:

ADDRESS ATTCHMVS 'TESTPGMA var1 var2 var3'

For the parameters, specify variable names instead of the actual values. Enclose the name of the program and the variable names in either single or double quotation marks. By using the quotation marks, the language processor does not evaluate any variables. The language processor simply passes the expression to the host command environment for processing. The LINKMVS or ATTCHMVS environment itself evaluates the variables and performs variable substitution. If you do not use a variable for each parameter and enclose the expression in quotation marks, you may have problems with variable substitution and receive unexpected results.

After the LINKMVS or ATTCHMVS environment routine evaluates the value of each variable, it builds a parameter list pointing to the values. The routine then links to or attaches the program and passes the parameter list to the program.

Figure 1 shows how the LINKMVS or ATTCHMVS host command environment routine passes the parameters to the program. Register 0 points to the ENVBLOCK under which the REXX exec issuing the ADDRESS LINKMVS or ADDRESS ATTCHMVS is running. Register 1 contains the address of a parameter list, which consists of a list of addresses. Each address in the parameter list points to a parameter. The high-order bit of the last address in the parameter list is set to 1 to indicate the end of the parameter list.

Each parameter consists of a halfword length field followed by the parameter, which is the value of the variable you specified on the LINKMVS or ATTCHMVS instruction. The halfword length field contains the length of the parameter, which is the length of the value of the variable. The maximum value of the halfword length field is 32,767.

ikja3gc2 ikja3gc2 — Figure 1. Parameters for LINKMVS and ATTCHMVS environments

As an example, suppose you want to attach the RTNWORK program and you want to pass two parameters; an order number (43176) and a code (CDETT76). When you use the ADDRESS ATTCHMVS instruction, specify variable names for the two parameters; for example, ordernum for the order number, 43176, and codenum for the code, CDETT76. Before you use ADDRESS ATTCHMVS, assign the values to the variable names.

⋮
ordernum = 43176
codenum = "CDETT76"
⋮
ADDRESS ATTCHMVS "RTNWORK ordernum codenum"
⋮
EXIT

In the example, you assign to the variable ordernum the value 43176 and you assign to the variable codenum the value CDETT76. On the ADDRESS ATTCHMVS instruction, you use the variable names for the two parameters. The ATTCHMVS host command environment evaluates the variables and passes the values of the variables to the RTNWORK program. In the parameter list, the length field for the first parameter (variable ordernum) is 5, followed by the character string 43176. The length field for the second parameter (variable codenum) is 7, followed by the character string CDETT76.

On entry to the linked or attached program, the halfword length fields contain the actual length of the parameters. The linked or attached program can update the values of the parameters before it completes processing. The value that the program returns in the halfword length field determines the type of processing that LINKMVS or ATTCHMVS performs.

When the LINKMVS or ATTCHMVS environment routine regains control, it determines whether to update the values of the REXX variables before returning to the REXX exec. To determine whether to update the value of a variable for a specific parameter, the LINKMVS or ATTCHMVS environment checks the value in the halfword length field. Depending on the value in the length field, LINKMVS or ATTCHMVS updates the variable, does not update the variable, or sets the variable to the null string.

If the value in the length field is less than 0, the LINKMVS or ATTCHMVS environment does not update the variable for that parameter.
If the value in the length field is 0, the LINKMVS or ATTCHMVS environment sets the variable for that parameter to the null string.
If the value in the length field is greater than 0, the LINKMVS or ATTCHMVS environment updates the variable for that parameter with the value the program returned in the parameter list. If the length field is a positive number, LINKMVS or ATTCHMVS simply updates the variable using the length in the length field.
If the original length of the value is less than 500 bytes, TSO/E provides a storage area of 500 bytes regardless of the length of the value of the variable. For example, if the length of the value of the variable on entry to the program were 8 bytes, the halfword length field would contain the value 8. However, there are 500 bytes of storage available for the parameter itself. This allows the program to increase the length of the variable without having to obtain storage. If the invoked program changes the length of the variable, it must also update the length field.

If the original length of the value is 500 or more bytes, there is no additional space allotted. For example, suppose you specify a variable whose value has a length of 620 bytes. The invoked program can return a value with a maximum length of 620 bytes. TSO/E does not provide an additional buffer area. In this case, if you expect that the linked or attached program may want to return a larger value, pad the original value to the right with blanks.

As an example, suppose you link to a program called PGMCODES and pass a variable pcode that has the value PC7177. The LINKMVS environment evaluates the value of the variable pcode (PC7177) and builds a parameter list pointing to the value. The halfword length field contains the length of the value, which is 6, followed by the value itself. Suppose the PGMCODES program updates the PC7177 value to the value PC7177ADC3. When the PGMCODES program returns control to the LINKMVS environment, the program must update the length value in the halfword length field to 10 to indicate the actual length of the value it is returning to the exec.

You can use the LINKMVS or ATTCHMVS environments and not specify any parameters. For example:

ADDRESS ATTCHMVS 'workpgm'

If you do not specify any parameters, register 1 contains an address that points to a parameter list. The high-order bit is on in the first parameter address. The parameter address points to a parameter that has a length of 0.