Structures

The structures are generated by macros that have various parameters to control the action of the macro.

Note: From time to time new versions of the IBM® MQ structures are introduced. The additional fields in a new version can cause a structure that previously was smaller than 256 bytes to become larger than 256 bytes. Because of this, write assembler instructions that are intended to copy an IBM MQ structure, or to set an IBM MQ structure to nulls, to work correctly with structures that might be larger than 256 bytes. Alternatively, use the DCLVER macro parameter or CMQVERA macro with the VERSION parameter to declare a specific version of the structure.

Specifying the name of the structure

To declare more than one instance of a structure, the macro prefixes the name of each field in the structure with a user-specifiable string and an underscore.

The string used is the label specified on the invocation of the macro. If no label is specified, the name of the structure is used to construct the prefix: 
* Declare two object descriptors
         CMQODA  ,        Prefix used="MQOD_" (the default)
MY_MQOD  CMQODA  ,        Prefix used="MY_MQOD_"

The structure declarations shown in this section use the default prefix.

Specifying the form of the structure

Structure declarations can be generated by the macro in one of two forms, controlled by the DSECT parameter:
DSECT=YES
An assembler DSECT instruction is used to start a new data section; the structure definition immediately follows the DSECT statement. The label on the macro invocation is used as the name of the data section; if no label is specified, the name of the structure is used.
DSECT=NO
Assembler DC instructions are used to define the structure at the current position in the routine. The fields are initialized with values, which can be specified by coding the relevant parameters on the macro invocation. Fields for which no values are specified on the macro invocation are initialized with default values.
The value specified must be uppercase. If the DSECT parameter is not specified, DSECT=NO is assumed.

Controlling the version of the structure

By default, the macros always declare the most recent version of each structure.

Although you can use the VERSION macro parameter to specify a value for the Version field in the structure, that parameter defines the initial value for the Version field, and does not control the version of the structure actually declared. To control the version of the structure that is declared, use the DCLVER parameter:
DCLVER=CURRENT
The version declared is the current (most recent) version.
DCLVER=SPECIFIED
The version declared is the version specified by the VERSION parameter. If you omit the VERSION parameter, the default is version 1.

If you specify the VERSION parameter, the value must be a self-defining numeric constant, or the named constant for the version required (for example, MQCNO_VERSION_3). If you specify some other value, the structure is declared as if DCLVER=CURRENT had been specified, even if the value of VERSION resolves to a valid value.

The value specified must be uppercase. If you omit the DCLVER parameter, the value used is taken from the MQDCLVER global macro variable. You can set this variable using the CMQVERA macro.

Declaring one structure embedded within another

To declare one structure as a component of another structure, use the NESTED parameter:
NESTED=YES
The structure declaration is nested within another.
NESTED=NO
The structure declaration is not nested within another.
The value specified must be uppercase. If you omit the NESTED parameter, NESTED=NO is assumed.

Specifying initial values for fields

Specify the value to be used to initialize a field in a structure by coding the name of that field (without the prefix) as a parameter on the macro invocation, accompanied by the value required.

For example, to declare a message-descriptor structure with the MsgType field initialized with MQMT_REQUEST, and the ReplyToQ field initialized with the string "MY_REPLY_TO_QUEUE", use the following: 
MY_MQMD  CMQMDA  MSGTYPE=MQMT_REQUEST,                                 X
               REPLYTOQ=MY_REPLY_TO_QUEUE

If you specify a named constant (equate) as a value on the macro invocation, use the CMQA macro to define the named constant. Do not enclose character string values in single quotation marks.

Controlling the listing

Control the appearance of the structure declaration in the assembler listing using the LIST parameter:
LIST=YES
The structure declaration appears in the assembler listing.
LIST=NO
The structure declaration does not appear in the assembler listing.
The value specified must be uppercase. If you omit the LIST parameter, LIST=NO is assumed.