How the macroinstructions are described

Each macroinstruction description includes the following information:

Purpose of the macroinstruction
General comments about the use of the macroinstruction
The format or syntax of the macroinstruction and all parameters
A description of each parameter
Return and reason codes that can be returned for the macroinstruction

Syntax descriptions

The syntax for each macroinstruction uses the following format:


main diagram

>>-+------+--IVTCSM--| Required and optional operands |--------><
   '-name-'

The macroinstructions are coded in the same format as assembler instructions, using name, operation, and operand fields. See the IBM High Level Assembler Language Reference for MVS and VM for complete information about coding guidelines.

Operand descriptions

The name and description of each operand follows the syntax diagram. Each operand description begins with an explanation of the operand's function.

Parameter values that are shown in uppercase bold type must be coded as they appear in the syntax. For parameter values that are shown in lowercase italic type, specify a location that is to be the source of input data or the target of output data. The location must be defined in a manner that is consistent with the indicated data type. If you wish to pass the storage address in general purpose register (2)-(12), code a valid expression for the register within parentheses. Otherwise, code an expression that is valid as a storage operand on RS-type instructions.

Tip: If a register is specified for RETCODE or RSNCODE, the output is loaded straight into the register.

To reference the parameter list within your program, use the list form of the macro, MF=(L,...), to define the parameter list structure. The listaddr value you specify becomes the name by which you can reference the structure in your program. For example, the assembler instruction LA 1,listaddr puts the parameter list address in register 1. The name of the field associated with a parmlist operand opername is listaddr_Xopername. If macroinstruction-defined values are associated with opername, the constant for a particular value, valuenam, is listaddr_Xopername_valuenam.

Restriction: The PLISTVER operand is an exception to the rule. To reference its field, substitute opername with the keyword VERSION. Also, the macro does not define constants for any of the allowable PLISTVER values.

All of the executable macroinstructions pass return codes in registers, and most indicate status information in various control block fields when they are posted complete. For all macroinstructions that invoke CSM, the application can examine return codes in register 15 and reason codes in register 0. Descriptions of this status information can be found at the end of the macroinstruction description.