Forms of the manipulative macroinstruction

The standard form of a manipulative macroinstruction expands at assembly time into (1) nonexecutable code that represents the parameters you specified on the macroinstruction and (2) executable code that causes the access method to be entered when the macroinstruction is executed. The nonexecutable code, called the parameter list, is assembled at the point in your application program where the macroinstruction appears.

Various alternative forms of the manipulative macroinstructions cause the assembler to:

Build the parameter list where the macroinstruction appears in your source code, but assemble no executable code (simple list form)
Assemble code that builds the parameter list at a location of your selection, but assemble no executable code that causes the access method to be entered (remote list form)
Assemble code that builds the parameter list at a location of your selection and assemble the code that causes the access method to be entered (generate form)
Assemble code that modifies a parameter list and cause the access method to be entered during program execution (execute form).

Table 1 summarizes the actions of these various forms. It also indicates the types of programs that would use each form and how the MF operand is used.

Table 1. Forms of manipulative macroinstructions
Form	During assembly	During execution	Useful for	Coded with
Standard	Parameter list built where macroinstruction appears in source code	Access method entered	Nonreentrant programs that are not sharing or modifying parameter lists	No MF operand
Simple List	Parameter list built where macroinstruction appears in source code	No executable code (execute form required)	Nonreentrant programs that are sharing or modifying parameter lists	MF=L
Remote List	Assemble code to build parameter list at a location you specify	Parameter list built, but access method not entered (execute form required)	Reentrant programs that are sharing or modifying parameter lists	MF=(L,address[,label])
Generate	Code assembled to: Build parameter list at a location you specify Enter the access method	Parameter list built and access method entered	Reentrant programs are not sharing or modifying parameter lists	MF=(G,address[,label])
Execute	Code assembled (where macroinstruction appears in the source code) to modify the parameter list whose address you supply	Parameter list modified and the access method entered	Programs using the list form	MF=(E,address)

As indicated in Table 1, the various alternative forms of the manipulative macroinstructions are designated with the MF operand.

The MF operand for the list form of any manipulative macroinstruction is coded as follows:

MF={L or (L,address[,label])}

L: Indicates that this is the list form of the macroinstruction. If you code just MF=L (simple list form), the parameter list is assembled in place. If you code MF=(L,address) (remote list form), the parameter list is built during program execution at the specified location.
address: Indicates the location where you want the parameter list to be built during program execution. This area must begin on a fullword boundary and, if your program is reentrant, must be in dynamically allocated storage. Because the assembler builds executable codes that in turn builds the parameter list, the macroinstruction must be in the executable portion of your program—that is, not treated as a program constant.
You can code this address in any of the forms of the address notation category (described in Summary of operand specifications).
label: This is a unique name that is used as a label for an assembled EQU instruction. During program assembly, the assembler equates this label to the length (in bytes) of the parameter list that is built during program execution. You can use this label to assure that you are obtaining enough dynamically allocated storage to hold the parameter list.
When coding label, follow the same rules that apply to any label for an assembler instruction.

List form example:

LA       10,PLISTLEN    OBTAIN LENGTH OF PARAMETER LIST
GETMAIN  R,LV=(10)      OBTAIN STORAGE FOR PARAMETER LIST
LR       5,1            SAVE STORAGE ADDRESS
TESTCB   RPL=RPL1,CONTROL=DATA,AM=VTAM,MF=(L,(5),PLISTLEN)

The MF operand for the generate form of any of the manipulative macroinstructions is coded as follows:

MF=(G,address[,label])

G: Indicates that this is the generate form of the macroinstruction.
address: Indicates the location where you want the parameter list to be built during program execution. Presumably, this is in dynamically allocated storage. In both manner of use and manner of coding, this address is identical to the address described in the preceding list form discussion.
label: Indicates the label to be used on an EQU instruction for the length of the parameter list. The function of the label operand and its rules for coding are identical to those described in the preceding list form discussion.

Generate form example:

LA       10,PLISTLEN     OBTAIN LENGTH OF PARAMETER LIST
GETMAIN  R,LV=(10)       OBTAIN STORAGE FOR PARAMETER LIST
LR       5,1             SAVE STORAGE ADDRESS
GENCB    BLK=RPL,AM=VTAM,MF=(G,(5),PLISTLEN)

The MF operand for the execute form of any of the manipulative macroinstructions is coded as follows:

MF=(E,address)

E

Indicates that this is the execute form of the macroinstruction.

address

Indicates the location of parameter list to be used by the access method.

The execute form allows you to modify the parameter list between the generation of that parameter list and the invocation of the access method routines that use the parameter list. Only the execute form provides a means for you to modify the parameter list after it has been built.

The optional operands you specify on the execute form of a particular macroinstruction are converted by the assembler into code that modifies a parameter list during execution. This code can only modify—and not expand—the parameter list. If the parameter list is actually a list form (as is typically the case), never refer to a control block field in an execute form that you did not specify in the list form. If you fail to observe this rule, and thereby attempt to expand the parameter list, the execute form is not processed successfully, and a return code of 8 is posted in register 15.

Execute form example:

EFORM    MODCB EXLST=EXLST1,LERAD=(3),AM=VTAM,                         C
               MF=(E,LFORM)
         ⋮
LFORM    MODCB EXLST=0,LERAD=0,MF=L,AM=VTAM