Field details for MQMD

The MQMD Message descriptor structure contains the control information that accompanies the application data when a message travels between the sending and receiving applications. The structure is an input/output parameter on the MQGET, MQPUT, and MQPUT1 calls.

StrucId (MQCHAR4)

This is the structure identifier of the message descriptor structure. It is always an input field. Its value is MQMD_STRUC_ID.

The value must be:

MQMD_STRUC_ID: Identifier for the message descriptor structure.
For the C programming language, the constant MQMD_STRUC_ID_ARRAY is also defined. This has the same value as MQMD_STRUC_ID, but is an array of characters instead of a string.

Version (MQLONG)

This is the structure version number, and must be one of the following:

MQMD_VERSION_1: Version-1 message descriptor structure.
This version is supported in all environments.
MQMD_VERSION_2: Version-2 message descriptor structure.
This version is supported in all IBM® MQ V6.0 and later environments, plus IBM MQ MQI clients connected to these systems.

Note: When a version-2 MQMD is used, the queue manager performs additional checks on any MQ header structures that might be present at the beginning of the application message data; for further details see the usage notes for the MQPUT call.

Fields that exist only in the more-recent version of the structure are identified as such in the descriptions of the fields. The following constant specifies the version number of the current version:

MQMD_CURRENT_VERSION: Current version of message descriptor structure.

This is always an input field. The initial value of this field is MQMD_VERSION_1.

Report (MQLONG)

A report message is a message about another message, used to inform an application about expected or unexpected events that relate to the original message. The Report field enables the application sending the original message to specify which report messages are required, whether the application message data is to be included in them, and also (for both reports and replies) how the message and correlation identifiers in the report or reply message are to be set. Any or all (or none) of the following types of report message can be requested:

Exception
Expiration
Confirm on arrival (COA)
Confirm on delivery (COD)
Positive action notification (PAN)
Negative action notification (NAN)

You can specify one or more of these options. To specify more than one option, either add the values together (do not add the same constant more than once), or combine the values using the bitwise OR operation (if the programming language supports bit operations).

The application that receives the report message can determine the reason that the report was generated by examining the Feedback field in the MQMD; see the Feedback field for more details.

The use of report options when putting a message to a topic can cause zero, one, or many report messages to be generated and sent to the application. This is because the publication message may be sent to zero, one, or many subscribing applications.

Exception options

Specify one of the options listed to request an exception report message.

MQRO_EXCEPTION

A message channel agent generates this type of report when a message is sent to another queue manager and the message cannot be delivered to the specified destination queue. For example, the destination queue or an intermediate transmission queue might be full, or the message might be too big for the queue.

Generation of the exception report message depends on the persistence of the original message, and the speed of the message channel (normal or fast) through which the original message travels:

For all persistent messages, and for nonpersistent messages traveling through normal message channels, the exception report is generated only if the action specified by the sending application for the error condition can be completed successfully. The sending application can specify one of the following actions to control the disposition of the original message when the error condition arises:
- MQRO_DEAD_LETTER_Q (this places the original message on the dead-letter queue).
- MQRO_DISCARD_MSG (this discards the original message).
If the action specified by the sending application cannot be completed successfully, the original message is left on the transmission queue, and no exception report message is generated.
For nonpersistent messages traveling through fast message channels, the original message is removed from the transmission queue and the exception report generated even if the specified action for the error condition cannot be completed successfully. For example, if MQRO_DEAD_LETTER_Q is specified, but the original message cannot be placed on the dead-letter queue because that queue is full, the exception report message is generated and the original message discarded.
For more information about normal and fast message channels, see Nonpersistent message speed (NPMSPEED).

An exception report is not generated if the application that put the original message can be notified synchronously of the problem by means of the reason code returned by the MQPUT or MQPUT1 call.

Applications can also send exception reports, to indicate that a message cannot be processed (for example, because it is a debit transaction that would cause the account to exceed its credit limit).

Message data from the original message is not included with the report message.

Do not specify more than one of MQRO_EXCEPTION, MQRO_EXCEPTION_WITH_DATA, and MQRO_EXCEPTION_WITH_FULL_DATA.

MQRO_EXCEPTION_WITH_DATA

This is the same as MQRO_EXCEPTION, except that the first 100 bytes of the application message data from the original message are included in the report message. If the original message contains one or more MQ header structures, they are included in the report message, in addition to the 100 bytes of application data.

Do not specify more than one of MQRO_EXCEPTION, MQRO_EXCEPTION_WITH_DATA, and MQRO_EXCEPTION_WITH_FULL_DATA.

MQRO_EXCEPTION_WITH_FULL_DATA

Exception reports with full data required.

This is the same as MQRO_EXCEPTION, except that all the application message data from the original message is included in the report message.

Do not specify more than one of MQRO_EXCEPTION, MQRO_EXCEPTION_WITH_DATA, and MQRO_EXCEPTION_WITH_FULL_DATA.

Expiration options

Specify one of the options listed to request an expiration report message.

MQRO_EXPIRATION

This type of report is generated by the queue manager if the message is discarded before delivery to an application because its expiry time has passed (see the Expiry field). If this option is not set, no report message is generated if a message is discarded for this reason (even if you specify one of the MQRO_EXCEPTION_* options).

Message data from the original message is not included with the report message.

Do not specify more than one of MQRO_EXPIRATION, MQRO_EXPIRATION_WITH_DATA, and MQRO_EXPIRATION_WITH_FULL_DATA.

MQRO_EXPIRATION_WITH_DATA

This is the same as MQRO_EXPIRATION, except that the first 100 bytes of the application message data from the original message are included in the report message. If the original message contains one or more MQ header structures, they are included in the report message, in addition to the 100 bytes of application data.

Do not specify more than one of MQRO_EXPIRATION, MQRO_EXPIRATION_WITH_DATA, and MQRO_EXPIRATION_WITH_FULL_DATA.

MQRO_EXPIRATION_WITH_FULL_DATA

This is the same as MQRO_EXPIRATION, except that all the application message data from the original message is included in the report message.

Do not specify more than one of MQRO_EXPIRATION, MQRO_EXPIRATION_WITH_DATA, and MQRO_EXPIRATION_WITH_FULL_DATA.

Confirm-on-arrival options

Specify one of the options listed to request a confirm-on-arrival report message.

MQRO_COA: This type of report is generated by the queue manager that owns the destination queue when the message is placed on the destination queue. Message data from the original message is not included with the report message.; If the message is put as part of a unit of work, and the destination queue is a local queue, the COA report message generated by the queue manager can be retrieved only if the unit of work is committed.; A COA report is not generated if the Format field in the message descriptor is MQFMT_XMIT_Q_HEADER or MQFMT_DEAD_LETTER_HEADER. This prevents a COA report being generated if the message is put on a transmission queue, or is undeliverable and put on a dead-letter queue.; In the case of an IMS bridge queue, the COA report is generated when the message reaches the IMS queue (acknowledgment received from IMS ) and not when the message is put in the MQ bridge queue. That means that if IMS is not active, no COA report is generated until IMS is started and a message is queued on the IMS queue.; The user that runs a program that puts a message with MQMD.Report=MQRO_COA must have +passid authority on the reply queue. If the user does not have +passid authority, the COA report message does not reach the reply queue. An attempt is made to put the report message on the dead letter queue.; Do not specify more than one of MQRO_COA, MQRO_COA_WITH_DATA, and MQRO_COA_WITH_FULL_DATA.
MQRO_COA_WITH_DATA: This is the same as MQRO_COA, except that the first 100 bytes of the application message data from the original message are included in the report message. If the original message contains one or more MQ header structures, they are included in the report message, in addition to the 100 bytes of application data.
Do not specify more than one of MQRO_COA, MQRO_COA_WITH_DATA, and MQRO_COA_WITH_FULL_DATA.
MQRO_COA_WITH_FULL_DATA: This is the same as MQRO_COA, except that all the application message data from the original message is included in the report message.
Do not specify more than one of MQRO_COA, MQRO_COA_WITH_DATA, and MQRO_COA_WITH_FULL_DATA.

Confirm-on-delivery options

Specify one of the options listed to request a confirm-on-delivery report message.

MQRO_COD

This type of report is generated by the queue manager when an application retrieves the message from the destination queue in a way that deletes the message from the queue. Message data from the original message is not included with the report message.

If the message is retrieved as part of a unit of work, the report message is generated within the same unit of work, so that the report is not available until the unit of work is committed. If the unit of work is backed out, the report is not sent.

A COD report is not always generated if a message is retrieved with the MQGMO_MARK_SKIP_BACKOUT option. If the primary unit of work is backed out but the secondary unit of work is committed, the message is removed from the queue, but a COD report is not generated.

A COD report is not generated if the Format field in the message descriptor is MQFMT_DEAD_LETTER_HEADER. This prevents a COD report being generated if the message is undeliverable and put on a dead-letter queue.

MQRO_COD is not valid if the destination queue is an XCF queue.

Do not specify more than one of MQRO_COD, MQRO_COD_WITH_DATA, and MQRO_COD_WITH_FULL_DATA.

MQRO_COD_WITH_DATA

This is the same as MQRO_COD, except that the first 100 bytes of the application message data from the original message are included in the report message. If the original message contains one or more MQ header structures, they are included in the report message, in addition to the 100 bytes of application data.

If MQGMO_ACCEPT_TRUNCATED_MSG is specified on the MQGET call for the original message, and the message retrieved is truncated, the amount of application message data placed in the report message depends on the environment:

On z/OS®, it is the minimum of:
- The length of the original message
- The length of the buffer used to retrieve the message
- 100 bytes.
In other environments, it is the minimum of:
- The length of the original message
- 100 bytes.

MQRO_COD_WITH_DATA is not valid if the destination queue is an XCF queue.

Do not specify more than one of MQRO_COD, MQRO_COD_WITH_DATA, and MQRO_COD_WITH_FULL_DATA.

MQRO_COD_WITH_FULL_DATA

This is the same as MQRO_COD, except that all the application message data from the original message is included in the report message.

MQRO_COD_WITH_FULL_DATA is not valid if the destination queue is an XCF queue.

Do not specify more than one of MQRO_COD, MQRO_COD_WITH_DATA, and MQRO_COD_WITH_FULL_DATA.

Action-notification options

Specify one or both of the options listed to request that the receiving application send a positive-action or negative-action report message.

MQRO_PAN: This type of report is generated by the application that retrieves the message and acts upon it. It indicates that the action requested in the message has been performed successfully. The application generating the report determines whether any data is to be included with the report.
Other than conveying this request to the application retrieving the message, the queue manager takes no action based on this option. The retrieving application must generate the report if appropriate.
MQRO_NAN: This type of report is generated by the application that retrieves the message and acts upon it. It indicates that the action requested in the message has not been performed successfully. The application generating the report determines whether any data is to be included with the report. For example, you might want to include some data indicating why the request could not be performed.
Other than conveying this request to the application retrieving the message, the queue manager takes no action based on this option. The retrieving application must generate the report if appropriate.

The application must determine which conditions correspond to a positive action and which correspond to a negative action. However, if the request has been only partially performed, generate a NAN report rather than a PAN report if requested. Every possible condition must correspond to either a positive action, or a negative action, but not both.

Message-identifier options

Specify one of the options listed to control how the MsgId of the report message (or of the reply message) is to be set.

MQRO_NEW_MSG_ID

This is the default action, and indicates that if a report or reply is generated as a result of this message, a new MsgId is generated for the report or reply message.

MQRO_PASS_MSG_ID

If a report or reply is generated as a result of this message, the MsgId of this message is copied to the MsgId of the report or reply message.

The MsgId of a publication message will be different for each subscriber that receives a copy of the publication and therefore the MsgId copied into the report or reply message will be different for each one.

If this option is not specified, MQRO_NEW_MSG_ID is assumed.

Correlation-identifier options

Specify one of the options listed to control how the CorrelId of the report message (or of the reply message) is to be set.

MQRO_COPY_MSG_ID_TO_CORREL_ID

This is the default action, and indicates that if a report or reply is generated as a result of this message, the MsgId of this message is copied to the CorrelId of the report or reply message.

The MsgId of a publication message will be different for each subscriber that receives a copy of the publication and therefore the MsgId copied into the CorrelId of the report or reply message will be different for each one.

MQRO_PASS_CORREL_ID

If a report or reply is generated as a result of this message, the CorrelId of this message is copied to the CorrelId of the report or reply message.

The CorrelId of a publication message will be specific to a subscriber unless it uses the MQSO_SET_CORREL_ID option and sets the SubCorrelId field in the MQSD to MQCI_NONE. Therefore it is possible that the CorrelId copied into the CorrelId of the report or reply message will be different for each one.

If this option is not specified, MQRO_COPY_MSG_ID_TO_CORREL_ID is assumed.

Servers replying to requests or generating report messages must check whether the MQRO_PASS_MSG_ID or MQRO_PASS_CORREL_ID options were set in the original message. If they were, the servers must take the action described for those options. If neither is set, the servers must take the corresponding default action.

Disposition options

Specify one of the options listed to control the disposition of the original message when it cannot be delivered to the destination queue. The application can set the disposition options independently of requesting exception reports.

MQRO_DEAD_LETTER_Q

This is the default action, and places the message on the dead-letter queue if the message cannot be delivered to the destination queue. This happens in the following situations:

When the application that put the original message cannot be notified synchronously of the problem by means of the reason code returned by the MQPUT or MQPUT1 call. An exception report message is generated, if one was requested by the sender.
When the application that put the original message was putting to a topic

MQRO_DISCARD_MSG

This discards the message if it cannot be delivered to the destination queue. This happens in the following situations:

When the application that put the original message cannot be notified synchronously of the problem by means of the reason code returned by the MQPUT or MQPUT1 call. An exception report message is generated, if one was requested by the sender.
When the application that put the original message was putting to a topic

If you want to return the original message to the sender, without the original message being placed on the dead-letter queue, the sender must specify MQRO_DISCARD_MSG with MQRO_EXCEPTION_WITH_FULL_DATA.

MQRO_PASS_DISCARD_AND_EXPIRY

If this option is set on a message, and a report or reply is generated because of it, the message descriptor of the report inherits:

MQRO_DISCARD_MSG if it was set.
The remaining expiry time of the message (if this is not an expiry report). If this is an expiry report the expiry time is set to 60 seconds.

Activity option

MQRO_ACTIVITY

Using this value allows the route of any message to be traced throughout a queue manager network. The report option can be specified on any current user message, instantly allowing you to begin calculating the route of the message through the network.

If the application generating the message cannot enable activity report generation, reporting can be enabled using an API crossing exit supplied by queue manager administrators.

Note:

The fewer the queue managers in the network that are able to generate activity reports, the less detailed the route.
The activity reports might be difficult to place in the correct order to determine the route taken.
The activity reports might not be able to find a route to their requested destination.
Messages with this report option set must be accepted by any queue manager, even if they do not understand the option. This allows the report option to be set on any user message, even if they are processed by a non-IBM WebSphere® MQ 6.0 or later queue manager.
If a process, either a queue manager or a user process, performs an activity on a message with this option set it can choose to generate and put an activity report.

Default option

Specify the following if no report options are required:

MQRO_NONE: Use this value to indicate that no other options have been specified. MQRO_NONE is defined to aid program documentation. It is not intended that this option be used with any other, but as its value is zero, such use cannot be detected.

General information

All report types required must be specifically requested by the application sending the original message. For example, if a COA report is requested but an exception report is not, a COA report is generated when the message is placed on the destination queue, but no exception report is generated if the destination queue is full when the message arrives there. If no Report options are set, no report messages are generated by the queue manager or message channel agent (MCA).
Some report options can be specified even though the local queue manager does not recognize them; this is useful when the option is to be processed by the destination queue manager. See Report options and message flags for more details.

If a report message is requested, the name of the queue to which to send the report must be specified in the ReplyToQ field. When a report message is received, the nature of the report can be determined by examining the Feedback field in the message descriptor.
If the queue manager or MCA that generates a report message cannot put the report message on the reply queue (for example, because the reply queue or transmission queue is full), the report message is placed instead on the dead-letter queue. If that also fails, or there is no dead-letter queue, the action taken depends on the type of the report message:
- If the report message is an exception report, the message that generated the exception report is left on its transmission queue; this ensures that the message is not lost.
- For all other report types, the report message is discarded and processing continues normally. This is done because either the original message has already been delivered safely (for COA or COD report messages), or is no longer of any interest (for an expiration report message).
Once a report message has been placed successfully on a queue (either the destination queue or an intermediate transmission queue), the message is no longer subject to special processing; it is treated just like any other message.
When the report is generated, the ReplyToQ queue is opened and the report message put using the authority of the UserIdentifier in the MQMD of the message causing the report, except in the following cases:
- Exception reports generated by a receiving MCA are put with whatever authority the MCA used when it tried to put the message causing the report.
- COA reports generated by the queue manager are put with whatever authority was used when the message causing the report was put on the queue manager generating the report. For example, if the message was put by a receiving MCA using the MCA's user identifier, the queue manager puts the COA report using the MCA's user identifier.
Applications generating reports must use the same authority as they use to generate a reply; this is usually the authority of the user identifier in the original message.
If the report has to travel to a remote destination, senders and receivers can decide whether to accept it, in the same way as they do for other messages.
If a report message with data is requested:
- The report message is always generated with the amount of data requested by the sender of the original message. If the report message is too big for the reply queue, the processing described above occurs; the report message is never truncated to fit on the reply queue.
- If the Format of the original message is MQFMT_XMIT_Q_HEADER, the data included in the report does not include the MQXQH. The report data starts with the first byte of the data beyond the MQXQH in the original message. This occurs whether or not the queue is a transmission queue.
If a COA, COD, or expiration report message is received at the reply queue, it is guaranteed that the original message arrived, was delivered, or expired, as appropriate. However, if one or more of these report messages is requested and is not received, the reverse cannot be assumed, because one of the following might have occurred:
1. The report message is held up because a link is down.
2. The report message is held up because a blocking condition exists at an intermediate transmission queue or at the reply queue (for example, the queue is full or inhibited for puts).
3. The report message is on a dead-letter queue.
4. When the queue manager was attempting to generate the report message, it could neither put it on the appropriate queue, nor on the dead-letter queue, so the report message could not be generated.
5. A failure of the queue manager occurred between the action being reported (arrival, delivery, or expiry), and generation of the corresponding report message. (This does not happen for COD report messages if the application retrieves the original message within a unit of work, as the COD report message is generated within the same unit of work.)
Exception report messages can be held up in the same way for reasons 1, 2, and 3 above. However, when an MCA cannot generate an exception report message (the report message cannot be put either on the reply queue or the dead-letter queue), the original message remains on the transmission queue at the sender, and the channel is closed. This occurs irrespective of whether the report message was to be generated at the sending or the receiving end of the channel.
If the original message is temporarily blocked (resulting in an exception report message being generated and the original message being put on a dead-letter queue), but the blockage clears and an application then reads the original message from the dead-letter queue and puts it again to its destination, the following might occur:
- Even though an exception report message has been generated, the original message eventually arrives successfully at its destination.
- More than one exception report message is generated in respect of a single original message, because the original message might encounter another blockage later.

Report messages when putting to a topic

Reports can be generated when putting a message to a topic. This message will be sent to all subscribers to the topic, which could be zero, one, or many. This should be taken into account when choosing to use report options as many report messages could be generated as a result.
When putting a message to a topic, there may be many destination queues that are to be given a copy of the message. If some of these destination queues have a problem, such as queue full, then the successful completion of the MQPUT depends on the setting of NPMSGDLV or PMSGDLV (depending on the persistence of the message). If the setting is such that message delivery to the destination queue must be successful (for example, it is a persistent message to a durable subscriber and PMSGDLV is set to ALL or ALLDUR), then success is defined as one of the following criteria being met:
- Successful put to the subscriber queue
- Use of MQRO_DEAD_LETTER_Q and a successful put to the Dead-letter queue if the subscriber queue cannot take the message
- Use of MQRO_DISCARD_MSG if the subscriber queue cannot take the message.

Report messages for message segments

Report messages can be requested for messages that have segmentation allowed (see the description of the MQMF_SEGMENTATION_ALLOWED flag). If the queue manager finds it necessary to segment the message, a report message can be generated for each of the segments that subsequently encounters the relevant condition. Applications must be prepared to receive multiple report messages for each type of report message requested. Use the GroupId field in the report message to correlate the multiple reports with the group identifier of the original message, and the Feedback field identify the type of each report message.
If MQGMO_LOGICAL_ORDER is used to retrieve report messages for segments, be aware that reports of different types might be returned by the successive MQGET calls. For example, if both COA and COD reports are requested for a message that is segmented by the queue manager, the MQGET calls for the report messages might return the COA and COD report messages interleaved in an unpredictable fashion. Avoid this by using the MQGMO_COMPLETE_MSG option (optionally with MQGMO_ACCEPT_TRUNCATED_MSG). MQGMO_COMPLETE_MSG causes the queue manager to reassemble report messages that have the same report type. For example, the first MQGET call might reassemble all the COA messages relating to the original message, and the second MQGET call might reassemble all the COD messages. Which is reassembled first depends on which type of report message occurs first on the queue.
Applications that themselves put segments can specify different report options for each segment. However, note the following points:
- If the segments are retrieved using the MQGMO_COMPLETE_MSG option, only the report options in the first segment are honored by the queue manager.
- If the segments are retrieved one by one, and most of them have one of the MQRO_COD_* options, but at least one segment does not, you cannot use the MQGMO_COMPLETE_MSG option to retrieve the report messages with a single MQGET call, or use the MQGMO_ALL_SEGMENTS_AVAILABLE option to detect when all the report messages have arrived.
In an MQ network, the queue managers can have different capabilities. If a report message for a segment is generated by a queue manager or MCA that does not support segmentation, the queue manager or MCA does not by default include the necessary segment information in the report message, and this might make it difficult to identify the original message that caused the report to be generated. Avoid this difficulty by requesting data with the report message, that is, by specifying the appropriate MQRO_*_WITH_DATA or MQRO_*_WITH_FULL_DATA options. However, be aware that if MQRO_*_WITH_DATA is specified, less than 100 bytes of application message data might be returned to the application that retrieves the report message, if the report message is generated by a queue manager or MCA that does not support segmentation.

Contents of the message descriptor for a report message

When the queue manager or message channel agent (MCA) generates a report message, it sets the fields in the message descriptor to the following values, and then puts the message in the normal way.

Table 1. Values used for MQMD fields when a report message is system-generated
Field in MQMD	Value used
`StrucId`	MQMD_STRUC_ID
`Version`	MQMD_VERSION_2
`Report`	MQRO_NONE
`MsgType`	MQMT_REPORT
`Expiry`	MQEI_UNLIMITED
`Feedback`	As appropriate for the nature of the report (MQFB_COA, MQFB_COD, MQFB_EXPIRATION, or an MQRC_* value)
`Encoding`	Copied from the original message descriptor
`CodedCharSetId`	Copied from the original message descriptor
`Format`	Copied from the original message descriptor
`Priority`	Copied from the original message descriptor
`Persistence`	Copied from the original message descriptor
`MsgId`	As specified by the report options in the original message descriptor
`CorrelId`	As specified by the report options in the original message descriptor
`BackoutCount`	0
`ReplyToQ`	Blanks
`ReplyToQMgr`	Name of queue manager
`UserIdentifier`	As set by the MQPMO_PASS_IDENTITY_CONTEXT option
`AccountingToken`	As set by the MQPMO_PASS_IDENTITY_CONTEXT option
`ApplIdentityData`	As set by the MQPMO_PASS_IDENTITY_CONTEXT option
`PutApplType`	MQAT_QMGR, or as appropriate for the message channel agent
`PutApplName`	First 28 bytes of the queue manager name or message channel agent name. For report messages generated by the IMS bridge, this field contains the XCF group name and XCF member name of the IMS system to which the message relates.
`PutDate`	Date when report message is sent
`PutTime`	Time when report message is sent
`ApplOriginData`	Blanks
`GroupId`	Copied from the original message descriptor
`MsgSeqNumber`	Copied from the original message descriptor
`Offset`	Copied from the original message descriptor
`MsgFlags`	Copied from the original message descriptor
`OriginalLength`	Copied from the original message descriptor if not MQOL_UNDEFINED, and set to the length of the original message data otherwise

An application generating a report is recommended to set similar values, except for the following:

The ReplyToQMgr field can be set to blanks (the queue manager changes this to the name of the local queue manager when the message is put).
Set the context fields using the option that would have been used for a reply, normally MQPMO_PASS_IDENTITY_CONTEXT.

Analyzing the report field

The Report field contains subfields; because of this, applications that need to check whether the sender of the message requested a particular report must use one of the techniques described in Analyzing the report field.

This is an output field for the MQGET call, and an input field for the MQPUT and MQPUT1 calls. The initial value of this field is MQRO_NONE.

MsgType (MQLONG)

This indicates the type of the message. Message types are grouped as follows:

MQMT_SYSTEM_FIRST: Lowest value for system-defined message types.
MQMT_SYSTEM_LAST: Highest value for system-defined message types.

The following values are currently defined within the system range:

MQMT_DATAGRAM: The message is one that does not require a reply.
MQMT_REQUEST: The message is one that requires a reply.
Specify the name of the queue to which to send the reply in the ReplyToQ field. The Report field indicates how to set the MsgId and CorrelId of the reply.
MQMT_REPLY: The message is the reply to an earlier request message (MQMT_REQUEST). The message must be sent to the queue indicated by the ReplyToQ field of the request message. Use the Report field of the request to control how to set the MsgId and CorrelId of the reply.
Note: The queue manager does not enforce the request-reply relationship; this is an application responsibility.
MQMT_REPORT: The message is reporting on some expected or unexpected occurrence, usually related to some other message (for example, a request message was received that contained data that was not valid). Send the message to the queue indicated by the ReplyToQ field of the message descriptor of the original message. Set the Feedback field s to indicate the nature of the report. Use the Report field of the original message to control how to set the MsgId and CorrelId of the report message.
Report messages generated by the queue manager or message channel agent are always sent to the ReplyToQ queue, with the Feedback and CorrelId fields set as described above.

Application-defined values can also be used. They must be within the following range:

MQMT_APPL_FIRST: Lowest value for application-defined message types.
MQMT_APPL_LAST: Highest value for application-defined message types.

For the MQPUT and MQPUT1 calls, the MsgType value must be within either the system-defined range or the application-defined range; if it is not, the call fails with reason code MQRC_MSG_TYPE_ERROR.

This is an output field for the MQGET call, and an input field for MQPUT and MQPUT1 calls. The initial value of this field is MQMT_DATAGRAM.

Expiry (MQLONG)

This is a period of time expressed in tenths of a second, set by the application that puts the message. The message becomes eligible to be discarded if it has not been removed from the destination queue before this period of time elapses.

For example, to set one minute for the expiry time, you need to set MQMD.Expiry to 600.

The value is decremented to reflect the time that the message spends on the destination queue, and also on any intermediate transmission queues if the put is to a remote queue. It can also be decremented by message channel agents to reflect transmission times, if these are significant. Likewise, an application forwarding this message to another queue might decrement the value if necessary, if it has retained the message for a significant time. However, the expiration time is treated as approximate, and the value need not be decremented to reflect small time intervals.

When the message is retrieved by an application using the MQGET call, the Expiry field represents the expiry time that still remains.

After a message's expiry time has elapsed, it becomes eligible to be discarded by the queue manager. The message is discarded when a browse or nonbrowse MQGET call occurs that would have returned the message had it not already expired. For example, a nonbrowse MQGET call with the MatchOptions field in MQGMO set to MQMO_NONE reading from a FIFO ordered queue discards all the expired messages up to the first unexpired message. With a priority ordered queue, the same call will discard expired messages of higher priority and messages of an equal priority that arrived on the queue before the first unexpired message.

A message that has expired is never returned to an application (either by a browse or a non-browse MQGET call), so the value in the Expiry field of the message descriptor after a successful MQGET call is either greater than zero, or the special value MQEI_UNLIMITED.

If a message is put on a remote queue, the message might expire (and be discarded) while it is on an intermediate transmission queue, before the message reaches the destination queue.

A report is generated when an expired message is discarded, if the message specified one of the MQRO_EXPIRATION_* report options. If none of these options is specified, no such report is generated; the message is assumed to be no longer relevant after this time period (perhaps because a later message has superseded it).

For a message put within syncpoint, the expiry interval begins at the time the message is put, not the time the syncpoint is committed. It is possible that the expiry interval can pass before the syncpoint is committed. In this case the message will be discarded at some time after the commit operation and the message will not be returned to an application in response to an MQGET operation.

Any other program that discards messages based on expiry time must also send an appropriate report message if one was requested.

Notes:

If a message is put with an Expiry time of zero or a number greater than 999 999 999, the MQPUT or MQPUT1 call fails with reason code MQRC_EXPIRY_ERROR; no report message is generated in this case.
To enable reason code 2013, MQRC_EXPIRY_ERROR, you must enable the environment variable AMQ_ENFORCE_MAX_EXPIRY_ERROR.
The following uses an example for Linux®:
```
$ export AMQ_ENFORCE_MAX_EXPIRY_ERROR=True
```
Note that the:
- Important thing is to export the variable
- Actual value is ignored, however, using True might be helpful when reviewing the setup.
Because a message with an expiry time that has elapsed might not be discarded until later, there might be messages on a queue that have passed their expiry time, and that are not therefore eligible for retrieval. These messages nevertheless count toward the number of messages on the queue for all purposes, including depth triggering.
If a subscriber/consumer (client) tries to get a message, and that message has expired, the client does not receive anything as the message was discarded as it was too old. In addition, the client will not receive any error message.
An expiration report is generated, if requested, when the message is discarded, not when it becomes eligible for discarding.
Discarding an expired message, and generating an expiration report if requested, are never part of the application's unit of work, even if the message was scheduled for discarding as a result of an MQGET call operating within a unit of work.
If a nearly-expired message is retrieved by an MQGET call within a unit of work, and the unit of work is subsequently backed out, the message might become eligible to be discarded before it can be retrieved again.
If a nearly-expired message is locked by an MQGET call with MQGMO_LOCK, the message might become eligible to be discarded before it can be retrieved by an MQGET call with MQGMO_MSG_UNDER_CURSOR; reason code MQRC_NO_MSG_UNDER_CURSOR is returned on this subsequent MQGET call if that happens.
When a request message with an expiry time greater than zero is retrieved, the application can take one of the following actions when it sends the reply message:
- Copy the remaining expiry time from the request message to the reply message.
- Set the expiry time in the reply message to an explicit value greater than zero.
- Set the expiry time in the reply message to MQEI_UNLIMITED.
The action to take depends on the design of the application. However, the default action for putting messages to a dead-letter (undelivered-message) queue must be to preserve the remaining expiry time of the message, and to continue to decrement it.
Trigger messages are always generated with MQEI_UNLIMITED.
A message (normally on a transmission queue) that has a Format name of MQFMT_XMIT_Q_HEADER has a second message descriptor within the MQXQH. It therefore has two Expiry fields associated with it. The following additional points should be noted in this case:
- When an application puts a message on a remote queue, the queue manager places the message initially on a local transmission queue, and prefixes the application message data with an MQXQH structure. The queue manager sets the values of the two Expiry fields to be the same as that specified by the application.
  If an application puts a message directly on a local transmission queue, the message data must already begin with an MQXQH structure, and the format name must be MQFMT_XMIT_Q_HEADER. In this case, the application need not set the values of these two Expiry fields to be the same. (The queue manager checks that the Expiry field within the MQXQH contains a valid value, and that the message data is long enough to include it). For an application that can write directly to the transmission queue, the application has to create a transmission queue header with the embedded message descriptor. However, if the expiry value in the message descriptor written to the transmission queue is inconsistent with the value in the embedded message descriptor, an expiry error rejection occurs.
- When a message with a Format name of MQFMT_XMIT_Q_HEADER is retrieved from a queue (whether this is a normal or a transmission queue), the queue manager decrements both these Expiry fields with the time spent waiting on the queue. No error is raised if the message data is not long enough to include the Expiry field in the MQXQH.
- The queue manager uses the Expiry field in the separate message descriptor (that is, not the one in the message descriptor embedded within the MQXQH structure) to test whether the message is eligible for discarding.
- If the initial values of the two Expiry fields are different, the Expiry time in the separate message descriptor when the message is retrieved might be greater than zero (so the message is not eligible for discarding), while the time according to the Expiry field in the MQXQH has elapsed. In this case the Expiry field in the MQXQH is set to zero.
The expiry time on a reply message returned from the IMS bridge is unlimited unless MQIIH_PASS_EXPIRATION is set in the Flags field of the MQIIH. See Flags for more information.

The following special value is recognized:

MQEI_UNLIMITED: The message has an unlimited expiration time.

This is an output field for the MQGET call, and an input field for the MQPUT and MQPUT1 calls. The initial value of this field is MQEI_UNLIMITED.

Expired messages on z/OS

On IBM MQ for z/OS, messages that have expired are discarded by the next appropriate MQGET call.

However, if no such call occurs, the expired message is not discarded, and, for some queues, a large number of expired messages can accumulate. To remedy this, set the queue manager to scan queues periodically and discard expired messages on one or more queues in one of the following ways:

Periodic scan

You can specify a period using the EXPRYINT (expiry interval) queue manager attribute. Each time the expiry interval is reached, the queue manager looks for candidate queues that are worth scanning to discard expired messages.

The queue manager maintains information about the expired messages on each queue, and knows whether a scan for expired messages is worthwhile. So, only a selection of queues is scanned at any time.

Shared queues are scanned by only one queue manager in a queue sharing group. Generally, it is the first queue manager to restart, or the first to have EXPRYINT set. If this queue manager terminates, another queue manager in the queue sharing group takes over the queue scanning. Set the expiry interval value for all queue managers within a queue sharing group to the same value.

Note that expiry processing takes place for every queue when a queue manager restarts, regardless of the EXPRYINT setting.

Explicit request

Issue the REFRESH QMGR TYPE(EXPIRY) command, specifying the queue or queues that you want scanned.

Feedback (MQLONG)

The Feedback field is used with a message of type MQMT_REPORT to indicate the nature of the report, and is only meaningful with that type of message.

The field can contain one of the MQFB_* values, or one of the MQRC_* values. Feedback codes are grouped as follows:

MQFB_NONE: No feedback provided.
MQFB_SYSTEM_FIRST: Lowest value for system-generated feedback.
MQFB_SYSTEM_LAST: Highest value for system-generated feedback.
The range of system-generated feedback codes MQFB_SYSTEM_FIRST through MQFB_SYSTEM_LAST includes the general feedback codes listed in this topic (MQFB_*), and also the reason codes (MQRC_*) that can occur when the message cannot be put on the destination queue.
MQFB_APPL_FIRST: Lowest value for application-generated feedback.
MQFB_APPL_LAST: Highest value for application-generated feedback.

Applications that generate report messages must not use feedback codes in the system range (other than MQFB_QUIT), unless they want to simulate report messages generated by the queue manager or message channel agent.

On the MQPUT or MQPUT1 calls, the value specified must either be MQFB_NONE, or be within the system range or application range. This is checked whatever the value of MsgType.

General feedback codes:

MQFB_COA: Confirmation of arrival on the destination queue (see MQRO_COA).
MQFB_COD: Confirmation of delivery to the receiving application (see MQRO_COD).
MQFB_EXPIRATION: Message was discarded because it had not been removed from the destination queue before its expiry time had elapsed.
MQFB_PAN: Positive action notification (see MQRO_PAN).
MQFB_NAN: Negative action notification (see MQRO_NAN).
MQFB_QUIT: End application.
This can be used by a workload scheduling program to control the number of instances of an application program that are running. Sending an MQMT_REPORT message with this feedback code to an instance of the application program indicates to that instance that it should stop processing. However, adherence to this convention is a matter for the application; it is not enforced by the queue manager.

Channel feedback codes

MQFB_CHANNEL_COMPLETED: A channel ended normally.
MQFB_CHANNEL_FAIL: A channel ended abnormally and goes into STOPPED state.
MQFB_CHANNEL_FAIL_RETRY: A channel ended abnormally and goes into RETRY state.

IMS-bridge feedback codes

These codes are used when an unexpected IMS-OTMA sense code is received. The sense code or, when the sense code is 0x1A the reason code associated with that sense code, is indicated in the Feedback.

For Feedback codes in range MQFB_IMS_FIRST (300) through MQFB_IMS_LAST (399), a sense code other than 0x1A was received. The sense code is given by the expression (Feedback - MQFB_IMS_FIRST+1)
For Feedback codes in range MQFB_IMS_NACK_1A_REASON_FIRST (600) through MQFB_IMS_NACK_1A_REASON_LAST (855), a sense code of 0x1A was received. The reason code associated with the sense code is given by the expression (Feedback - MQFB_IMS_NACK_1A_REASON_FIRST)

The meaning of the IMS-OTMA sense codes and corresponding reason codes are described in Open Transaction Manager Access Guide and Reference.

The following feedback codes can be generated by the IMS bridge:

MQFB_DATA_LENGTH_ZERO: A segment length was zero in the application data of the message.
MQFB_DATA_LENGTH_NEGATIVE: A segment length was negative in the application data of the message.
MQFB_DATA_LENGTH_TOO_BIG: A segment length was too large in the application data of the message.
MQFB_BUFFER_OVERFLOW: The value of one of the length fields would cause the data to overflow the message buffer.
MQFB_LENGTH_OFF_BY_ONE: The value of one of the length fields was 1 byte too short.
MQFB_IIH_ERROR: The Format field in MQMD specifies MQFMT_IMS, but the message does not begin with a valid MQIIH structure.
MQFB_NOT_AUTHORIZED_FOR_IMS: The user ID contained in the message descriptor MQMD, or the password contained in the Authenticator field in the MQIIH structure, failed the validation performed by the IMS bridge. As a result the message was not passed to IMS.
MQFB_IMS_ERROR: An unexpected error was returned by IMS. Consult the IBM MQ error log on the system on which the IMS bridge resides for more information about the error.
MQFB_IMS_FIRST: When the IMS-OTMA sense code is not 0x1A, IMS-generated feedback codes are in the range MQFB_IMS_FIRST (300) through MQFB_IMS_LAST (399). The IMS-OTMA sense code itself is Feedback minus MQFB_IMS_ERROR.
MQFB_IMS_LAST: Highest value for IMS-generated feedback when the sense code is not 0x1A.
MQFB_IMS_NACK_1A_REASON_FIRST: When the sense code is 0x1A, IMS-generated feedback codes are in the range MQFB_IMS_NACK_1A_REASON_FIRST (600) through MQFB_IMS_NACK_1A_REASON_LAST (855).
MQFB_IMS_NACK_1A_REASON_LAST: Highest value for IMS-generated feedback when the sense code is 0x1A

CICS®-bridge feedback codes

The following feedback codes can be generated by the CICS bridge:

MQFB_CICS_APPL_ABENDED

The application program specified in the message abnormally ended. This feedback code occurs only in the Reason field of the MQDLH structure.

MQFB_CICS_APPL_NOT_STARTED

The EXEC CICS LINK for the application program specified in the message failed. This feedback code occurs only in the Reason field of the MQDLH structure.

MQFB_CICS_BRIDGE_FAILURE

CICS bridge terminated abnormally without completing normal error processing.

MQFB_CICS_CCSID_ERROR

Character set identifier not valid.

MQFB_CICS_CIH_ERROR

CICS information header structure missing or not valid.

MQFB_CICS_COMMAREA_ERROR

Length of CICS COMMAREA not valid.

MQFB_CICS_CORREL_ID_ERROR

Correlation identifier not valid.

MQFB_CICS_DLQ_ERROR

The CICS bridge task was unable to copy a reply to this request to the dead-letter queue. The request was backed out.

MQFB_CICS_ENCODING_ERROR

Encoding not valid.

MQFB_CICS_INTERNAL_ERROR

CICS bridge encountered an unexpected error.

This feedback code occurs only in the Reason field of the MQDLH structure.

MQFB_CICS_NOT_AUTHORIZED

User identifier not authorized or password not valid.

This feedback code occurs only in the Reason field of the MQDLH structure.

MQFB_CICS_UOW_BACKED_OUT

The unit of work was backed out, for one of the following reasons:

A failure was detected while processing another request within the same unit of work.
A CICS abend occurred while the unit of work was in progress.

MQFB_CICS_UOW_ERROR

Unit-of-work control field UOWControl not valid.

Trace-route message feedback codes

MQFB_ACTIVITY: Used with the MQFMT_EMBEDDED_PCF format to allow the option of user data following activity reports.
MQFB_MAX_ACTIVITIES: Returned when the trace-route message is discarded because the number of activities the message has been involved in exceeds the maximum activities limit.
MQFB_NOT_FORWARDED: Returned when the trace-route message is discarded because it is about to be sent to a remote queue manager that does not support trace-route messages.
MQFB_NOT_DELIVERED: Returned when the trace-route message is discarded because it is about to be put on a local queue.
MQFB_UNSUPPORTED_FORWARDING: Returned when the trace-route message is discarded because a value in the forwarding parameter is unrecognized, and is in the rejected bit mask.
MQFB_UNSUPPORTED_DELIVERY: Returned when the trace-route message is discarded because a value in the delivery parameter is unrecognized, and is in the rejected bit mask.

IBM MQ reason codes

For exception report messages, Feedback contains an IBM MQ reason code. Among possible reason codes are:

MQRC_PUT_INHIBITED: (2051, X'803') Put calls inhibited for the queue.
MQRC_Q_FULL: (2053, X'805') Queue already contains maximum number of messages.
MQRC_NOT_AUTHORIZED: (2035, X'7F3') Not authorized for access.
MQRC_Q_SPACE_NOT_AVAILABLE: (2056, X'808') No space available on disk for queue.
MQRC_PERSISTENT_NOT_ALLOWED: (2048, X'800') Queue does not support persistent messages.
MQRC_MSG_TOO_BIG_FOR_Q_MGR: (2031, X'7EF') Message length greater than maximum for queue manager.
MQRC_MSG_TOO_BIG_FOR_Q: (2030, X'7EE') Message length greater than maximum for queue.

For a full list of reason codes, see:

For IBM MQ for z/OS, see API completion and reason codes.
For all other platforms, see API completion and reason codes.

This is an output field for the MQGET call, and an input field for MQPUT and MQPUT1 calls. The initial value of this field is MQFB_NONE.

Encoding (MQLONG)

This specifies the numeric encoding of numeric data in the message; it does not apply to numeric data in the MQMD structure itself. The numeric encoding defines the representation used for binary integers, packed-decimal integers, and floating-point numbers.

[z/OS] On z/OS, the binary integer portion of the Encoding field is also used to specify the integer encoding of character data in the message body when the corresponding character set identifier indicates that the representation of the character set is dependent on the encoding used for binary integers. This only affects certain multibyte character sets (for example UTF-16 character sets).

On the MQPUT or MQPUT1 call, the application must set this field to the value appropriate to the data. The queue manager does not check that the field is valid. The following special value is defined:

MQENC_NATIVE: The encoding is the default for the programming language and machine on which the application is running.
Note: The value of this constant depends on the programming language and environment. For this reason, applications must be compiled using the header, macro, COPY, or INCLUDE files appropriate to the environment in which the application will run.

Applications that put messages usually specify MQENC_NATIVE. Applications that retrieve messages must compare this field against the value MQENC_NATIVE; if the values differ, the application might need to convert numeric data in the message. Use the MQGMO_CONVERT option to request the queue manager to convert the message as part of the processing of the MQGET call. See Machine encodings for details of how the Encoding field is constructed.

If you specify the MQGMO_CONVERT option on the MQGET call, this field is an input/output field. The value specified by the application is the encoding to which to convert the message data if necessary. If conversion is successful or unnecessary, the value is unchanged. If conversion is unsuccessful, the value after the MQGET call represents the encoding of the unconverted message that is returned to the application.

In other cases, this is an output field for the MQGET call, and an input field for the MQPUT and MQPUT1 calls. The initial value of this field is MQENC_NATIVE.

CodedCharSetId (MQLONG)

This field specifies the character set identifier of character data within the message body.

Note: Character data in MQMD and the other MQ data structures that are parameters on calls must be in the character set of the queue manager. This is defined by the queue manager's CodedCharSetId attribute; see Attributes for the queue manager for details of this attribute.

If this field is set to MQCCSI_Q_MGR when calling MQGET with MQGMO_CONVERT in the options, the behavior is different between client and server applications. For server applications, the code page used for character conversion is the CodedCharSetId of the queue manager; for client applications, the code page used for character conversion is the current locale code page.

For client applications, MQCCSI_Q_MGR is filled in, based on the locale of the client rather than the one on the queue manager. The exception to that rule is when you put a message to an IMS bridge queue; what is returned, in the CodedCharSetId field of MQMD, is the CCSID of the queue manager.

You must not use the following special value:

MQCCSI_APPL: This results in an incorrect value in the CodedCharSetId field of the MQMD and causes a return code of MQRC_SOURCE_CCSID_ERROR (or MQRC_FORMAT_ERROR for z/OS ) when the message is received using the MQGET call with the MQGMO_CONVERT option.

You can use the following special values:

MQCCSI_Q_MGR

Character data in the message is in the queue manager's character set.

On the MQPUT and MQPUT1 calls, the queue manager changes this value in the MQMD that is sent with the message to the true character set identifier of the queue manager. As a result, the value MQCCSI_Q_MGR is never returned by the MQGET call.

MQCCSI_DEFAULT

The CodedCharSetId of the data in the String field is defined by the CodedCharSetId field in the header structure that precedes the MQCFH structure, or by the CodedCharSetId field in the MQMD if the MQCFH is at the start of the message.

MQCCSI_INHERIT

Character data in the message is in the same character set as this structure; this is the queue manager's character set. (For MQMD only, MQCCSI_INHERIT has the same meaning as MQCCSI_Q_MGR).

The queue manager changes this value in the MQMD that is sent with the message to the actual character set identifier of MQMD. Provided no error occurs, the value MQCCSI_INHERIT is not returned by the MQGET call.

Do not use MQCCSI_INHERIT if the value of the PutApplType field in MQMD is MQAT_BROKER.

MQCCSI_EMBEDDED

Character data in the message is in a character set with the identifier that is contained within the message data itself. There can be any number of character set identifiers embedded within the message data, applying to different parts of the data. This value must be used for PCF messages (with a format of MQFMT_ADMIN, MQFMT_EVENT, or MQFMT_PCF) that contain data in a mixture of character sets. Each MQCFST, MQCFSL, and MQCFSF structure contained within the PCF message must have an explicit character set identifier specified and not MQCCSI_DEFAULT.

If a message of format MQFMT_EMBEDDED_PCF is to contain data in a mixture of character sets, do not use MQCCSI_EMBEDDED. Instead set MQEPH_CCSID_EMBEDDED in the Flags field in the MQEPH structure. This is equivalent to setting MQCCSI_EMBEDDED in the preceding structure. Each MQCFST, MQCFSL, and MQCFSF structure contained within the PCF message must then have an explicit character set identifier specified and not MQCCSI_DEFAULT. For more information on the MQEPH structure, see MQEPH - Embedded PCF header.

Specify this value only on the MQPUT and MQPUT1 calls. If it is specified on the MQGET call, it prevents conversion of the message.

On the MQPUT and MQPUT1 calls, the queue manager changes the values MQCCSI_Q_MGR and MQCCSI_INHERIT in the MQMD that is sent with the message as described above, but does not change the MQMD specified on the MQPUT or MQPUT1 call. No other check is carried out on the value specified.

Applications that retrieve messages must compare this field against the value the application is expecting; if the values differ, the application might need to convert character data in the message.

[z/OS] On z/OS, the Encoding field of the MQMD is used to specify the integer encoding of character data in the message body, when the CodedCharSetId field of the MQMD indicates that the representation of the character set is dependent on the encoding used for binary integers.

[UNIX, Linux, Windows, IBM i] On Multiplatforms, the byte order of character data is assumed to be the same as the native integer encoding for the platform where the queue manager is running. This only affects certain multibyte character sets (for example UTF-16 character sets).

If you specify the MQGMO_CONVERT option on the MQGET call, this field is an input/output field. The value specified by the application is the coded character set identifier to which to convert the message data if necessary. If conversion is successful or unnecessary, the value is unchanged (except that the value MQCCSI_Q_MGR or MQCCSI_INHERIT is converted to the actual value). If conversion is unsuccessful, the value after the MQGET call represents the coded character set identifier of the unconverted message that is returned to the application.

Otherwise, this is an output field for the MQGET call, and an input field for the MQPUT and MQPUT1 calls. The initial value of this field is MQCCSI_Q_MGR.

Format (MQCHAR8)

This is a name that the sender of the message uses to indicate to the receiver the nature of the data in the message. Any characters that are in the character set of the queue manager can be specified for the name, but you must restrict the name to the following:

Uppercase A through Z
Numeric digits 0 through 9

If other characters are used, it might not be possible to translate the name between the character sets of the sending and receiving queue managers.

Pad the name with blanks to the length of the field, or use a null character to terminate the name before the end of the field; the null and any subsequent characters are treated as blanks. Do not specify a name with leading or embedded blanks. For the MQGET call, the queue manager returns the name padded with blanks to the length of the field.

The queue manager does not check that the name complies with the recommendations described above.

Names beginning MQ in upper, lower, and mixed case have meanings that are defined by the queue manager; do not use names beginning with these letters for your own formats. The queue manager built-in formats are:

MQFMT_NONE

The nature of the data is undefined: the data cannot be converted when the message is retrieved from a queue using the MQGMO_CONVERT option.

If you specify MQGMO_CONVERT on the MQGET call, and the character set or encoding of data in the message differs from that specified in the MsgDesc parameter, the message is returned with the following completion and reason codes (assuming no other errors):

Completion code MQCC_WARNING and reason code MQRC_FORMAT_ERROR if the MQFMT_NONE data is at the beginning of the message.
Completion code MQCC_OK and reason code MQRC_NONE if the MQFMT_NONE data is at the end of the message (that is, preceded by one or more MQ header structures). The MQ header structures are converted to the requested character set and encoding in this case.

For the C programming language, the constant MQFMT_NONE_ARRAY is also defined; this has the same value as MQFMT_NONE, but is an array of characters instead of a string.

MQFMT_ADMIN

The message is a command-server request or reply message in programmable command format (PCF). Messages of this format can be converted if the MQGMO_CONVERT option is specified on the MQGET call. See Using Programmable Command Formats for more information about using programmable command format messages.

For the C programming language, the constant MQFMT_ADMIN_ARRAY is also defined; this has the same value as MQFMT_ADMIN, but is an array of characters instead of a string.

MQFMT_CICS

The message data begins with the CICS information header MQCIH, followed by the application data. The format name of the application data is given by the Format field in the MQCIH structure.

[z/OS] On z/OS, specify the MQGMO_CONVERT option on the MQGET call to convert messages that have format MQFMT_CICS.

For the C programming language, the constant MQFMT_CICS_ARRAY is also defined; this has the same value as MQFMT_CICS, but is an array of characters instead of a string.

MQFMT_COMMAND_1

The message is an MQSC command-server reply message containing the object count, completion code, and reason code. Messages of this format can be converted if the MQGMO_CONVERT option is specified on the MQGET call.

For the C programming language, the constant MQFMT_COMMAND_1_ARRAY is also defined; this has the same value as MQFMT_COMMAND_1, but is an array of characters instead of a string.

MQFMT_COMMAND_2

The message is an MQSC command-server reply message containing information about the objects requested. Messages of this format can be converted if the MQGMO_CONVERT option is specified on the MQGET call.

For the C programming language, the constant MQFMT_COMMAND_2_ARRAY is also defined; this has the same value as MQFMT_COMMAND_2, but is an array of characters instead of a string.

MQFMT_DEAD_LETTER_HEADER

The message data begins with the dead-letter header MQDLH. The data from the original message immediately follows the MQDLH structure. The format name of the original message data is given by the Format field in the MQDLH structure; see MQDLH - Dead letter header for details of this structure. Messages of this format can be converted if the MQGMO_CONVERT option is specified on the MQGET call.

COA and COD reports are not generated for messages that have a Format of MQFMT_DEAD_LETTER_HEADER.

For the C programming language, the constant MQFMT_DEAD_LETTER_HEADER_ARRAY is also defined; this has the same value as MQFMT_DEAD_LETTER_HEADER, but is an array of characters instead of a string.

MQFMT_DIST_HEADER

The message data begins with the distribution-list header MQDH; this includes the arrays of MQOR and MQPMR records. The distribution-list header can be followed by additional data. The format of the additional data (if any) is given by the Format field in the MQDH structure; see MQDH - Distribution header for details of this structure. Messages with format MQFMT_DIST_HEADER can be converted if the MQGMO_CONVERT option is specified on the MQGET call.

This format is supported in the following environments:

AIX®
IBM i
Linux
Windows

and for IBM MQ MQI clients connected to these systems.

For the C programming language, the constant MQFMT_DIST_HEADER_ARRAY is also defined; this has the same value as MQFMT_DIST_HEADER, but is an array of characters instead of a string.

MQFMT_EMBEDDED_PCF

Format for a trace-route message, provided that the PCF command value is set to MQCMD_TRACE_ROUTE. Using this format allows user data to be sent along with the trace-route message, provided that their applications can cope with preceding PCF parameters.

The PCF header must be the first header, or the message will not be treated as a trace-route message. This means that the message cannot be in a group, and that trace-route messages cannot be segmented. If a trace-route message is sent in a group the message is rejected with reason code MQRC_MSG_NOT_ALLOWED_IN_GROUP.

Note that MQFMT_ADMIN can also be used for the format of a trace-route message, but in this case no user data can be sent along with the trace-route message.

MQFMT_EVENT

The message is an MQ event message that reports an event that occurred. Event messages have the same structure as programmable commands; see PCF command messages for more information about this structure, and Event monitoring for information about events.

Version-1 event messages can be converted in all environments if the MQGMO_CONVERT option is specified on the MQGET call. Version-2 event messages can be converted only on z/OS.

For the C programming language, the constant MQFMT_EVENT_ARRAY is also defined; this has the same value as MQFMT_EVENT, but is an array of characters instead of a string.

MQFMT_IMS

The message data begins with the IMS information header MQIIH, which is followed by the application data. The format name of the application data is given by the Format field in the MQIIH structure.

For details of how MQIIH structure is handled when using MQGET with MQGMO_CONVERT, see Format (MQCHAR8) and ReplyToFormat (MQCHAR8).

For the C programming language, the constant MQFMT_IMS_ARRAY is also defined; this has the same value as MQFMT_IMS, but is an array of characters instead of a string.

MQFMT_IMS_VAR_STRING

The message is an IMS variable string, which is a string of the form llzzccc, where:

ll: is a 2-byte length field specifying the total length of the IMS variable string item. This length is equal to the length of ll (2 bytes), plus the length of zz (2 bytes), plus the length of the character string itself. ll is a 2-byte binary integer in the encoding specified by the Encoding field.
zz: is a 2-byte field containing flags that are significant to IMS. zz is a byte string consisting of two MQBYTE fields, and is transmitted without change from sender to receiver (that is, zz is not subject to any conversion).
ccc: is a variable-length character string containing ll-4 characters. ccc is in the character set specified by the CodedCharSetId field.

On z/OS, the message data can consist of a sequence of IMS variable strings butted together, with each string being of the form llzzccc. There must be no bytes skipped between successive IMS variable strings. This means that if the first string has an odd length, the second string will be misaligned, that is, it will not begin on a boundary that is a multiple of two. Take care when constructing such strings on machines that require alignment of elementary data types.

Use the MQGMO_CONVERT option on the MQGET call to convert messages that have format MQFMT_IMS_VAR_STRING.

For the C programming language, the constant MQFMT_IMS_VAR_STRING_ARRAY is also defined; this has the same value as MQFMT_IMS_VAR_STRING, but is an array of characters instead of a string.

MQFMT_MD_EXTENSION

The message data begins with the message-descriptor extension MQMDE, and is optionally followed by other data (usually the application message data). The format name, character set, and encoding of the data that follow the MQMDE are given by the Format, CodedCharSetId, and Encoding fields in the MQMDE. See MQMDE - Message descriptor extension for details of this structure. Messages of this format can be converted if the MQGMO_CONVERT option is specified on the MQGET call.

For the C programming language, the constant MQFMT_MD_EXTENSION_ARRAY is also defined; this has the same value as MQFMT_MD_EXTENSION, but is an array of characters instead of a string.

MQFMT_PCF

The message is a user-defined message that conforms to the structure of a programmable command format (PCF) message. Messages of this format can be converted if the MQGMO_CONVERT option is specified on the MQGET call. See Using Programmable Command Formats for more information about using programmable command format messages.

For the C programming language, the constant MQFMT_PCF_ARRAY is also defined; this has the same value as MQFMT_PCF, but is an array of characters instead of a string.

MQFMT_REF_MSG_HEADER

The message data begins with the reference message header MQRMH, and is optionally followed by other data. The format name, character set, and encoding of the data is given by the Format, CodedCharSetId, and Encoding fields in the MQRMH. See MQRMH - Reference message header for details of this structure. Messages of this format can be converted if the MQGMO_CONVERT option is specified on the MQGET call.

This format is supported in the following environments:

AIX
IBM i
Linux
Windows

and for IBM MQ MQI clients connected to these systems.

For the C programming language, the constant MQFMT_REF_MSG_HEADER_ARRAY is also defined; this has the same value as MQFMT_REF_MSG_HEADER, but is an array of characters instead of a string.

MQFMT_RF_HEADER

The message data begins with the rules and formatting header MQRFH, and is optionally followed by other data. The format name, character set, and encoding of the data (if any) are given by the Format, CodedCharSetId, and Encoding fields in the MQRFH. Messages of this format can be converted if the MQGMO_CONVERT option is specified on the MQGET call.

For the C programming language, the constant MQFMT_RF_HEADER_ARRAY is also defined; this has the same value as MQFMT_RF_HEADER, but is an array of characters instead of a string.

MQFMT_RF_HEADER_2

The message data begins with the version-2 rules and formatting header MQRFH2, and is optionally followed by other data. The format name, character set, and encoding of the optional data (if any) are given by the Format, CodedCharSetId, and Encoding fields in the MQRFH2. Messages of this format can be converted if the MQGMO_CONVERT option is specified on the MQGET call.

For the C programming language, the constant MQFMT_RF_HEADER_2_ARRAY is also defined; this has the same value as MQFMT_RF_HEADER_2, but is an array of characters instead of a string.

MQFMT_STRING

The application message data can be either an SBCS string (single-byte character set), or a DBCS string (double-byte character set). Messages of this format can be converted if the MQGMO_CONVERT option is specified on the MQGET call.

For the C programming language, the constant MQFMT_STRING_ARRAY is also defined; this has the same value as MQFMT_STRING, but is an array of characters instead of a string.

MQFMT_TRIGGER

The message is a trigger message, described by the MQTM structure; see MQTM - Trigger message for details of this structure. Messages of this format can be converted if the MQGMO_CONVERT option is specified on the MQGET call.

For the C programming language, the constant MQFMT_TRIGGER_ARRAY is also defined; this has the same value as MQFMT_TRIGGER, but is an array of characters instead of a string.

MQFMT_WORK_INFO_HEADER

The message data begins with the work information header MQWIH, which is followed by the application data. The format name of the application data is given by the Format field in the MQWIH structure.

[z/OS] On z/OS, specify the MQGMO_CONVERT option on the MQGET call to convert the user data in messages that have format MQFMT_WORK_INFO_HEADER. However, the MQWIH structure itself is always returned in the queue manager's character set and encoding (that is, the MQWIH structure is converted whether or not the MQGMO_CONVERT option is specified).

For the C programming language, the constant MQFMT_WORK_INFO_HEADER_ARRAY is also defined; this has the same value as MQFMT_WORK_INFO_HEADER, but is an array of characters instead of a string.

MQFMT_XMIT_Q_HEADER

The message data begins with the transmission queue header MQXQH. The data from the original message immediately follows the MQXQH structure. The format name of the original message data is given by the Format field in the MQMD structure, which is part of the transmission queue header MQXQH. See MQXQH - Transmission-queue header for details of this structure.

COA and COD reports are not generated for messages that have a Format of MQFMT_XMIT_Q_HEADER.

For the C programming language, the constant MQFMT_XMIT_Q_HEADER_ARRAY is also defined; this has the same value as MQFMT_XMIT_Q_HEADER, but is an array of characters instead of a string.

This is an output field for the MQGET call, and an input field for the MQPUT and MQPUT1 calls. The length of this field is given by MQ_FORMAT_LENGTH. The initial value of this field is MQFMT_NONE.

Priority (MQLONG)

For the MQPUT and MQPUT1 calls, the value must be greater than or equal to zero; zero is the lowest priority. The following special value can also be used:

MQPRI_PRIORITY_AS_Q_DEF

If the queue is a cluster queue, the priority for the message is taken from the DefPriority attribute defined at the destination queue manager that owns the particular instance of the queue on which the message is placed.
When there are multiple instances of the cluster queue, and they differ in this attribute, the value from one of them is picked and it cannot be predicted which one will be used. You should therefore set this attribute to the same value on all instances. If this is not the case, error message AMQ9407 is issued to the queue manager logs. See also How are destination object attributes resolved for aliases, remote and cluster queues?

The value of DefPriority is copied into the Priority field when the message is placed on the destination queue. If DefPriority is changed subsequently, messages that have already been placed on the queue are not affected.
If the queue is not a cluster queue, the priority for the message is taken from the DefPriority attribute defined at the local queue manager, even if the destination queue manager is remote.
If there is more than one definition in the queue-name resolution path, the default priority is taken from the value of this attribute in the first definition in the path. This can be:
- An alias queue
- A local queue
- A local definition of a remote queue
- A queue manager alias
- A transmission queue (for example, the DefXmitQName queue)
The value of DefPriority is copied into the Priority field when the message is put. If DefPriority is changed subsequently, messages that have already been put are not affected.

The value returned by the MQGET call is always greater than or equal to zero; the value MQPRI_PRIORITY_AS_Q_DEF is never returned.

If a message is put with a priority greater than the maximum supported by the local queue manager (this maximum is given by the MaxPriority queue manager attribute), the message is accepted by the queue manager, but placed on the queue at the queue manager's maximum priority; the MQPUT or MQPUT1 call completes with MQCC_WARNING and reason code MQRC_PRIORITY_EXCEEDS_MAXIMUM. However, the Priority field retains the value specified by the application that put the message.

On z/OS, if a message with a MsgSeqNumber of 1 is put to a queue that has a message delivery sequence of MQMDS_PRIORITY and an index type of MQIT_GROUP_ID, the queue might treat the message with a different priority. If the message was placed on the queue with a priority of 0 or 1, it is processed as though it has a priority of 2. This is because the order of messages placed on this type of queue is optimized to enable efficient group completeness tests. For more information on the message delivery sequence MQMDS_PRIORITY and the index type MQIT_GROUP_ID, see MsgDeliverySequence attribute.

When replying to a message, applications must use the priority of the request message for the reply message. In other situations, specifying MQPRI_PRIORITY_AS_Q_DEF allows priority tuning to be carried out without changing the application.

This is an output field for the MQGET call, and an input field for the MQPUT and MQPUT1 calls. The initial value of this field is MQPRI_PRIORITY_AS_Q_DEF.

Persistence (MQLONG)

This indicates whether the message survives system failures and restarts of the queue manager. For the MQPUT and MQPUT1 calls, the value must be one of the following:

MQPER_PERSISTENT

The message survives system failures and restarts of the queue manager. Once the message has been put, and the unit of work in which it was put has been committed (if the message is put as part of a unit of work), the message is preserved on auxiliary storage. It remains there until the message is removed from the queue, and the unit of work in which it was got has been committed (if the message is retrieved as part of a unit of work).

When a persistent message is sent to a remote queue, a store-and-forward mechanism holds the message at each queue manager along the route to the destination, until the message is known to have arrived at the next queue manager.

Persistent messages cannot be placed on:

Temporary dynamic queues
Shared queues that map to a CFSTRUCT object at CFLEVEL(2) or below, or where the CFSTRUCT object is defined as RECOVER(NO).

Persistent messages can be placed on permanent dynamic queues, and predefined queues.

MQPER_NOT_PERSISTENT

The message does not usually survive system failures or queue manager restarts. This applies even if an intact copy of the message is found on auxiliary storage when the queue manager restarts.

In the case of NPMCLASS (HIGH) queues nonpersistent messages survive a normal queue manager shutdown and restart.

Note: In a Native HA configuration, any change of leader of a queue manager instance always results in the discarding of non-persistent messages regardless of the setting of NPMCLASS.

In the case of shared queues, nonpersistent messages survive queue manager restarts in the queue sharing group, but do not survive failures of the coupling facility used to store messages on the shared queues.

MQPER_PERSISTENCE_AS_Q_DEF

If the queue is a cluster queue, the persistence of the message is taken from the DefPersistence attribute defined at the destination queue manager that owns the particular instance of the queue on which the message is placed.
When there are multiple instances of the cluster queue, and they differ in this attribute, the value from one of them is picked and it cannot be predicted which one will be used. You should therefore set this attribute to the same value on all instances. If this is not the case, error message AMQ9407 is issued to the queue manager logs. See also How are destination object attributes resolved for aliases, remote and cluster queues?

The value of DefPersistence is copied into the Persistence field when the message is placed on the destination queue. If DefPersistence is changed subsequently, messages that have already been placed on the queue are not affected.
If the queue is not a cluster queue, the persistence of the message is taken from the DefPersistence attribute defined at the local queue manager, even if the destination queue manager is remote.
If there is more than one definition in the queue-name resolution path, the default persistence is taken from the value of this attribute in the first definition in the path. This can be:
- An alias queue
- A local queue
- A local definition of a remote queue
- A queue manager alias
- A transmission queue (for example, the DefXmitQName queue)
The value of DefPersistence is copied into the Persistence field when the message is put. If DefPersistence is changed subsequently, messages that have already been put are not affected.

Both persistent and nonpersistent messages can exist on the same queue.

When replying to a message, applications must use the persistence of the request message for the reply message.

For an MQGET call, the value returned is either MQPER_PERSISTENT or MQPER_NOT_PERSISTENT.

This is an output field for the MQGET call, and an input field for the MQPUT and MQPUT1 calls. The initial value of this field is MQPER_PERSISTENCE_AS_Q_DEF.

MsgId (MQBYTE24)

This is a byte string that is used to distinguish one message from another. Generally, no two messages should have the same message identifier, although this is not disallowed by the queue manager. The message identifier is a permanent property of the message, and persists across restarts of the queue manager. Because the message identifier is a byte string and not a character string, the message identifier is not converted between character sets when the message flows from one queue manager to another.

For the MQPUT and MQPUT1 calls, if MQMI_NONE or MQPMO_NEW_MSG_ID is specified by the application, the queue manager generates a unique message identifier (MsgId) when the message is put, and places it in the message descriptor sent with the message. The queue manager also returns this message identifier in the message descriptor belonging to the sending application. The application can use this value to record information about particular messages, and to respond to queries from other parts of the application.

Note: A MsgId generated by the queue manager consists of a 4-byte product identifier (AMQ¬ or CSQ¬ in either ASCII or EBCDIC, where ¬ represents a blank character), followed by a product-specific implementation of a unique string. In IBM MQ this contains the first 12 characters of the queue manager name, and a value derived from the system clock. All queue managers that can intercommunicate must therefore have names that differ in the first 12 characters, in order to ensure that message identifiers are unique. The ability to generate a unique string also depends on the system clock not being changed backward. To eliminate the possibility of a message identifier generated by the queue manager duplicating one generated by the application, the application must avoid generating identifiers with initial characters in the range A through I in ASCII or EBCDIC (X'41' through X'49' and X'C1' through X'C9'). However, the application is not prevented from generating identifiers with initial characters in these ranges.

If the message is being put to a topic, the queue manager generates unique message identifiers as necessary for each message published. If MQPMO_NEW_MSG_ID is specified by the application, the queue manager generates a unique message identifier to return on output. If MQMI_NONE is specified by the application, the value of the MsgId field in the MQMD is unchanged on return from the call.

See the description of MQPMO_RETAIN in Options (MQLONG) for more details about retained publications.

If the message is being put to a distribution list, the queue manager generates unique message identifiers as necessary, but the value of the MsgId field in MQMD is unchanged on return from the call, even if MQMI_NONE or MQPMO_NEW_MSG_ID was specified. If the application needs to know the message identifiers generated by the queue manager, the application must provide MQPMR records containing the MsgId field.

The sending application can also specify a value for the message identifier other than MQMI_NONE; this stops the queue manager generating a unique message identifier. An application that is forwarding a message can use this to propagate the message identifier of the original message.

The queue manager does not use this field except to:

Generate a unique value if requested, as described above
Deliver the value to the application that issues the get request for the message
Copy the value to the CorrelId field of any report message that it generates about this message (depending on the Report options)

When the queue manager or a message channel agent generates a report message, it sets the MsgId field in the way specified by the Report field of the original message, either MQRO_NEW_MSG_ID or MQRO_PASS_MSG_ID. Applications that generate report messages must also do this.

For the MQGET call, MsgId is one of the five fields that can be used to retrieve a particular message from the queue. Normally the MQGET call returns the next message on the queue, but a particular message can be obtained by specifying one or more of the five selection criteria, in any combination; these fields are:

MsgId
CorrelId
GroupId
MsgSeqNumber
Offset

The application sets one or more of these field to the values required, and then sets the corresponding MQMO_* match options in the MatchOptions field in MQGMO to use those fields as selection criteria. Only messages that have the specified values in those fields are candidates for retrieval. The default for the MatchOptions field (if not altered by the application) is to match both the message identifier and the correlation identifier.

[z/OS] On z/OS, the selection criteria that you can use are restricted by the type of index used for the queue. See the IndexType queue attribute for further details.

Normally, the message returned is the first message on the queue that satisfies the selection criteria. But if MQGMO_BROWSE_NEXT is specified, the message returned is the next message that satisfies the selection criteria; the scan for this message starts with the message following the current cursor position.

Note: The queue is scanned sequentially for a message that satisfies the selection criteria, so retrieval times are slower than if no selection criteria are specified, especially if many messages have to be scanned before a suitable one is found. The exceptions to this are:

an MQGET call by CorrelId on 64-bit Multiplatforms where the CorrelId index eliminates the need to perform a true sequential scan.
an MQGET call by IndexType on z/OS.

In both these cases, retrieval performance is improved.

See table MQGET options relating to messages in groups and segments of logical messages for more information about how selection criteria are used in various situations.

Specifying MQMI_NONE as the message identifier has the same effect as not specifying MQMO_MATCH_MSG_ID, that is, any message identifier matches.

This field is ignored if the MQGMO_MSG_UNDER_CURSOR option is specified in the GetMsgOpts parameter on the MQGET call.

On return from an MQGET call, the MsgId field is set to the message identifier of the message returned (if any).

The following special value can be used:

MQMI_NONE

No message identifier is specified.

The value is binary zero for the length of the field.

For the C programming language, the constant MQMI_NONE_ARRAY is also defined; this has the same value as MQMI_NONE, but is an array of characters instead of a string.

This is an input/output field for the MQGET, MQPUT, and MQPUT1 calls. The length of this field is given by MQ_MSG_ID_LENGTH. The initial value of this field is MQMI_NONE.

CorrelId (MQBYTE24)

The CorrelId field is property in the message header that may be used to identify a specific message or group of messages.

This is a byte string that the application can use to relate one message to another, or to relate the message to other work that the application is performing. The correlation identifier is a permanent property of the message, and persists across restarts of the queue manager. Because the correlation identifier is a byte string and not a character string, the correlation identifier is not converted between character sets when the message flows from one queue manager to another.

For the MQPUT and MQPUT1 calls, the application can specify any value. The queue manager transmits this value with the message and delivers it to the application that issues the get request for the message.

If the application specifies MQPMO_NEW_CORREL_ID, the queue manager generates a unique correlation identifier which is sent with the message, and also returned to the sending application on output from the MQPUT or MQPUT1 call.

A correlation identifier generated by the queue manager consists of a 3-byte product identifier (AMQ or CSQ in either ASCII or EBCDIC), followed by one reserved byte and a product-specific implementation of a unique string. In IBM MQ this product-specific implementation string contains the first 12 characters of the queue manager name, and a value derived from the system clock. All queue managers that can intercommunicate must therefore have names that differ in the first 12 characters to ensure that message identifiers are unique. The ability to generate a unique string also depends on the system clock not being changed backward. To eliminate the possibility of a message identifier generated by the queue manager duplicating one generated by the application, the application must avoid generating identifiers with initial characters in the range A through I in ASCII or EBCDIC (X'41' through X'49' and X'C1' through X'C9'). However, the application is not prevented from generating identifiers with initial characters in these ranges.

This generated correlation identifier is kept with the message if it is retained, and is used as the correlation identifier when the message is sent as a publication to subscribers who specify MQCI_NONE in the SubCorrelId field in the MQSD passed on the MQSUB call. See MQPMO options for more details about retained publications.

When the queue manager or a message channel agent generates a report message, it sets the CorrelId field in the way specified by the Report field of the original message, either MQRO_COPY_MSG_ID_TO_CORREL_ID or MQRO_PASS_CORREL_ID. Applications that generate report messages must also do this.

For the MQGET call, CorrelId is one of the five fields that can be used to select a particular message to be retrieved from the queue. See the description of the MsgId field for details of how to specify values for this field.

Specifying MQCI_NONE as the correlation identifier has the same effect as not specifying MQMO_MATCH_CORREL_ID, that is, any correlation identifier will match.

If the MQGMO_MSG_UNDER_CURSOR option is specified in the GetMsgOpts parameter on the MQGET call, this field is ignored.

On return from an MQGET call, the CorrelId field is set to the correlation identifier of the message returned (if any).

The following special values can be used:

MQCI_NONE

No correlation identifier is specified.

The value is binary zero for the length of the field.

For the C programming language, the constant MQCI_NONE_ARRAY is also defined; this has the same value as MQCI_NONE, but is an array of characters instead of a string.

MQCI_NEW_SESSION

Message is the start of a new session.

This value is recognized by the CICS bridge as indicating the start of a new session, that is, the start of a new sequence of messages.

For the C programming language, the constant MQCI_NEW_SESSION_ARRAY is also defined; this has the same value as MQCI_NEW_SESSION, but is an array of characters instead of a string.

For the MQGET call, this is an input/output field. For the MQPUT and MQPUT1 calls, this is an input field if MQPMO_NEW_CORREL_ID is not specified, and an output field if MQPMO_NEW_CORREL_ID is specified. The length of this field is given by MQ_CORREL_ID_LENGTH. The initial value of this field is MQCI_NONE.

Note:

You cannot pass the correlation identifier of a publication in a hierarchy. The field is used by the queue manager.

BackoutCount (MQLONG)

This is a count of the number of times that the message has been previously returned by the MQGET call as part of a unit of work, and subsequently backed out. It helps the application to detect processing errors that are based on message content. The count excludes MQGET calls that specify any of the MQGMO_BROWSE_* options.

The accuracy of this count is affected by the HardenGetBackout queue attribute; see Attributes for queues.

[z/OS] On z/OS, a value of 255 means that the message has been backed out 255 or more times; the value returned is never greater than 255.

This is an output field for the MQGET call. It is ignored for the MQPUT and MQPUT1 calls. The initial value of this field is 0.

ReplyToQ (MQCHAR48)

This is the name of the message queue to which the application that issued the get request for the message sends MQMT_REPLY and MQMT_REPORT messages. The name is the local name of a queue that is defined on the queue manager identified by ReplyToQMgr. This queue must not be a model queue, although the sending queue manager does not verify this when the message is put.

For the MQPUT and MQPUT1 calls, this field must not be blank if the MsgType field has the value MQMT_REQUEST, or if any report messages are requested by the Report field. However, the value specified (or substituted) is passed on to the application that issues the get request for the message, whatever the message type.

If the ReplyToQMgr field is blank, the local queue manager looks up the ReplyToQ name in its own queue definitions. If a local definition of a remote queue exists with this name, the ReplyToQ value in the transmitted message is replaced by the value of the RemoteQName attribute from the definition of the remote queue, and this value is returned in the message descriptor when the receiving application issues an MQGET call for the message. If a local definition of a remote queue does not exist, ReplyToQ is unchanged.

If the name is specified, it can contain trailing blanks; the first null character and characters following it are treated as blanks. Otherwise no check is made that the name satisfies the naming rules for queues; this is also true for the name transmitted, if the ReplyToQ is replaced in the transmitted message. The only check made is that a name has been specified, if the circumstances require it.

If a reply-to queue is not required, set the ReplyToQ field to blanks, or (in the C programming language) to the null string, or to one or more blanks followed by a null character; do not leave the field uninitialized.

For the MQGET call, the queue manager always returns the name padded with blanks to the length of the field.

If a message that requires a report message cannot be delivered, and the report message also cannot be delivered to the queue specified, both the original message and the report message go to the dead-letter (undelivered-message) queue (see the DeadLetterQName attribute described in Attributes for the queue manager ).

This is an output field for the MQGET call, and an input field for the MQPUT and MQPUT1 calls. The length of this field is given by MQ_Q_NAME_LENGTH. The initial value of this field is the null string in C, and 48 blank characters in other programming languages.

ReplyToQMgr (MQCHAR48)

This is the name of the queue manager to which to send the reply message or report message. ReplyToQ is the local name of a queue that is defined on this queue manager.

If the ReplyToQMgr field is blank, the local queue manager looks up the ReplyToQ name in its queue definitions. If a local definition of a remote queue exists with this name, the ReplyToQMgr value in the transmitted message is replaced by the value of the RemoteQMgrName attribute from the definition of the remote queue, and this value is returned in the message descriptor when the receiving application issues an MQGET call for the message. If a local definition of a remote queue does not exist, the ReplyToQMgr that is transmitted with the message is the name of the local queue manager.

If the name is specified, it can contain trailing blanks; the first null character and characters following it are treated as blanks. Otherwise no check is made that the name satisfies the naming rules for queue managers, or that this name is known to the sending queue manager; this is also true for the name transmitted, if the ReplyToQMgr is replaced in the transmitted message.

If a reply-to queue is not required, set the ReplyToQMgr field to blanks, or (in the C programming language) to the null string, or to one or more blanks followed by a null character; do not leave the field uninitialized.

For the MQGET call, the queue manager always returns the name padded with blanks to the length of the field.

This is an output field for the MQGET call, and an input field for the MQPUT and MQPUT1 calls. The length of this field is given by MQ_Q_MGR_NAME_LENGTH. The initial value of this field is the null string in C, and 48 blank characters in other programming languages.

UserIdentifier (MQCHAR12)

This is part of the identity context of the message. For more information about message context, see MQMD - Message descriptor and Message context.

UserIdentifier specifies the user identifier of the application that originated the message. The queue manager treats this information as character data, but does not define the format of it. For information about how the user identifier is determined from the environment, see Authentication and authorization: Operating system (application process) user IDs.

[z/OS] On z/OS, when the queue manager generates this information for an MQPUT or MQPUT1 call, the queue manager uses the AlternateUserId from the ObjDesc parameter of the MQOPEN or MQPUT1 call if the MQOO_ALTERNATE_USER_AUTHORITY or MQPMO_ALTERNATE_USER_AUTHORITY option was specified. If the relevant option was not specified, the queue manager uses a user identifier determined from the environment.

On IBM MQ for Multiplatforms, the UserIdentifier field is normally an output field generated by the queue manager, and populated with the user ID associated with the connection sending the message, which in turn is determined by the authentication mechanism and platform in use. However, for an MQPUT or MQPUT1 call you can make this field an input/output field:

This field is an input/output field if you specify MQPMO_SET_IDENTITY_CONTEXT or MQPMO_SET_ALL_CONTEXT in the PutMsgOpts parameter. Any information following a null character within the field is discarded. The queue manager converts the null character and any following characters to blanks.
if you want to specify the user ID field instead of letting the queue manager generate this information, specify MQPMO_SET_IDENTITY_CONTEXT or MQPMO_SET_ALL_CONTEXT, then specify a user ID in the UserIdentifier field.
If you do not specify MQPMO_SET_IDENTITY_CONTEXT or MQPMO_SET_ALL_CONTEXT, the UserIdentifier field is ignored on input and is an output-only field.

For IDPWOS authentication, the way in which IDs longer than 12 characters are stored in the UserIdentifier field varies by platform and IBM MQ version:

For IBM MQ 9.4.0 Long Term Support, and IBM MQ 9.4.1 and 9.4.2 Continuous Delivery, only Windows client or server applications can adopt a connection user ID that is longer than 12 characters. In this case, the user ID is indicated by storing the first 12 characters.
From IBM MQ 9.4.3, client or server applications on all Continuous Delivery platforms can adopt a connection user ID that is longer than 12 characters. On Windows, the user ID is indicated by storing the first 12 characters. On AIX, Linux and IBM MQ Appliance, you also need to set the AllowLongUID=Yes property on a queue manager. If this property is set, the user ID is indicated by storing the first 11 characters suffixed with a + symbol.

After the successful completion of an MQPUT or MQPUT1 call, this field contains the user ID that was transmitted with the message if it was put to a queue. This is the value of UserIdentifier that is kept with the message if it is retained, but is not used as the UserIdentifier when the message is sent as a publication to subscribers because they provide a value to override UserIdentifier in all publications sent to them. If the message has no context, the field is entirely blank. For more details about retained publications, see MQPMO_RETAIN in the MQPMO Options.

For the MQGET call, the UserIdentifier field is an output field. The length of this field is given by MQ_USER_ID_LENGTH. The initial value of this field is the null string in C, and 12 blank characters in other programming languages.

After a message has been received, use UserIdentifier in the AlternateUserID field of the ObjDesc parameter of a subsequent MQOPEN or MQPUT1 call to perform the authorization check for the UserIdentifier user instead of the application performing the open. For example:

A message is sent by user A.
The message is taken off a queue by application B.
Application B wants to perform further messaging activity under the authority of user A.

To achieve this, application B copies the UserIdentifier field from the MQMD of the received message into the AlternateUserID field of the MQOD for the new handle they are opening. Note that application B must also have specific authorities that permit this.

AccountingToken (MQBYTE32)

This is the accounting token, part of the identity context of the message. For more information about message context, see MQMD - Message descriptor and Message context.

AccountingToken allows an application to charge appropriately for work done as a result of the message. The queue manager treats this information as a string of bits and does not check its content.

The queue manager generates this information as follows:

The first byte of the field is set to the length of the accounting information present in the bytes that follow; this length is in the range zero through 30, and is stored in the first byte as a binary integer.
The second and subsequent bytes (as specified by the length field) are set to the accounting information appropriate to the environment.
- On z/OS the accounting information is set to:
  - For z/OS batch, the accounting information from the JES JOB card or from a JES ACCT statement in the EXEC card (comma separators are changed to X'FF'). This information is truncated, if necessary, to 31 bytes.
  - For TSO, the user's account number.
  - For CICS, the LU 6.2 unit of work identifier (UEPUOWDS) (26 bytes).
  - For IMS, the 8-character PSB name concatenated with the 16-character IMS recovery token.
- On IBM i, the accounting information is set to the accounting code for the job.
- On AIX and Linux, the accounting information is set to the numeric user identifier, in ASCII characters.
- On Windows, the accounting information is set to a Windows security identifier (SID) in a compressed format. The SID uniquely identifies the user identifier stored in the UserIdentifier field. When the SID is stored in the AccountingToken field, the 6-byte Identifier Authority (located in the third and subsequent bytes of the SID) is omitted. For example, if the Windows SID is 28 bytes long, 22 bytes of SID information are stored in the AccountingToken field.
The last byte (byte 32) of the accounting field is set to the accounting token type (in this case MQACTT_NT_SECURITY_ID, x '0b'):

MQACTT_CICS_LUOW_ID

CICS LUOW identifier.

MQACTT_NT_SECURITY_ID

Windows security identifier.

MQACTT_OS400_ACCOUNT_TOKEN

IBM i accounting token.

MQACTT_UNIX_NUMERIC_ID

UNIX numeric identifier.

MQACTT_USER

User-defined accounting token.

MQACTT_UNKNOWN

Unknown accounting-token type.

The accounting-token type is set to an explicit value only in the following environments:
- AIX
- IBM i
- Linux
- Windows
and for IBM MQ MQI clients connected to these systems. In other environments, the accounting-token type is set to the value MQACTT_UNKNOWN. In these environments use the PutApplType field to deduce the type of accounting token received.
All other bytes are set to binary zero.

For the MQPUT and MQPUT1 calls, this is an input/output field if MQPMO_SET_IDENTITY_CONTEXT or MQPMO_SET_ALL_CONTEXT is specified in the PutMsgOpts parameter. If neither MQPMO_SET_IDENTITY_CONTEXT nor MQPMO_SET_ALL_CONTEXT is specified, this field is ignored on input and is an output-only field. For more information about message context, see Message context.

After the successful completion of an MQPUT or MQPUT1 call, this field contains the AccountingToken that was transmitted with the message if it was put to a queue. This will be the value of AccountingToken that is kept with the message if it is retained (see description of MQPMO_RETAIN in Options (MQLONG) for more details about retained publications) but is not used as the AccountingToken when the message is sent as a publication to subscribers since they provide a value to override AccountingToken in all publications sent to them. If the message has no context, the field is entirely binary zero.

This is an output field for the MQGET call.

This field is not subject to any translation based on the character set of the queue manager; the field is treated as a string of bits, and not as a string of characters.

The queue manager does nothing with the information in this field. The application must interpret the information if it wants to use the information for accounting purposes.

You can use the following special value for the AccountingToken field:

MQACT_NONE

No accounting token is specified.

The value is binary zero for the length of the field.

For the C programming language, the constant MQACT_NONE_ARRAY is also defined; this has the same value as MQACT_NONE, but is an array of characters instead of a string.

The length of this field is given by MQ_ACCOUNTING_TOKEN_LENGTH. The initial value of this field is MQACT_NONE.

ApplIdentityData (MQCHAR32)

This is part of the identity context of the message. For more information about message context, see MQMD - Message descriptor and Message context.

ApplIdentityData is information that is defined by the application suite, and can be used to provide additional information about the message or its originator. The queue manager treats this information as character data, but does not define the format of it. When the queue manager generates this information, it is entirely blank.

For the MQPUT and MQPUT1 calls, this is an input/output field if MQPMO_SET_IDENTITY_CONTEXT or MQPMO_SET_ALL_CONTEXT is specified in the PutMsgOpts parameter. If a null character is present, the null and any following characters are converted to blanks by the queue manager. If neither MQPMO_SET_IDENTITY_CONTEXT nor MQPMO_SET_ALL_CONTEXT is specified, this field is ignored on input and is an output-only field. For more information about message context, see Message context.

After the successful completion of an MQPUT or MQPUT1 call, this field contains the ApplIdentityData that was transmitted with the message if it was put to a queue. This will be the value of ApplIdentityData that is kept with the message if it is retained (see description of MQPMO_RETAIN for more details about retained publications) but is not used as the ApplIdentityData when the message is sent as a publication to subscribers because they provide a value to override ApplIdentityData in all publications sent to them. If the message has no context, the field is entirely blank.

This is an output field for the MQGET call. The length of this field is given by MQ_APPL_IDENTITY_DATA_LENGTH. The initial value of this field is the null string in C, and 32 blank characters in other programming languages.

PutApplType (MQLONG)

This is the type of application that put the message, and is part of the origin context of the message. For more information about message context, see MQMD - Message descriptor and Message context.

PutApplType can have one of the following standard types. You can also define your own types, but only with values in the range MQAT_USER_FIRST through MQAT_USER_LAST.

MQAT_AIX: AIX application (same value as MQAT_UNIX).
MQAT_AMQP: AMQP protocol application
MQAT_BROKER: Broker.
MQAT_CICS: CICS transaction.
MQAT_CICS_BRIDGE: CICS bridge.
MQAT_CICS_VSE: CICS/VSE transaction.
MQAT_DOS: IBM MQ MQI client application on PC DOS.
MQAT_DQM: Distributed queue manager agent.
MQAT_GUARDIAN: Tandem Guardian application (same value as MQAT_NSK).
MQAT_IMS: IMS application.
MQAT_IMS_BRIDGE: IMS bridge.
MQAT_JAVA: Java.
MQAT_MVS: MVS or TSO application (same value as MQAT_ZOS).
MQAT_NOTES_AGENT: Lotus Notes Agent application.
MQAT_OS390: OS/390® application (same value as MQAT_ZOS).
MQAT_OS400: IBM i application.
MQAT_QMGR: Queue manager.
MQAT_UNIX: UNIX application.
MQAT_VOS: Stratus VOS application.
MQAT_WINDOWS: 16-bit Windows application.
MQAT_WINDOWS_NT: 32-bit Windows application.
MQAT_WLM: z/OS workload manager application.
MQAT_XCF: XCF.
MQAT_ZOS: z/OS application.
MQAT_DEFAULT: Default application type.
This is the default application type for the platform on which the application is running.

Note: The value of this constant is environment-specific. Because of this, always compile the application using the header, include, or COPY files that are appropriate to the platform on which the application will run.
MQAT_UNKNOWN: Use this value to indicate that the application type is unknown, even though other context information is present.
MQAT_USER_FIRST: Lowest value for user-defined application type.
MQAT_USER_LAST: Highest value for user-defined application type.

The following special value can also occur:

MQAT_NO_CONTEXT: This value is set by the queue manager when a message is put with no context (that is, the MQPMO_NO_CONTEXT context option is specified).
When a message is retrieved, PutApplType can be tested for this value to decide whether the message has context (it is recommended that PutApplType is never set to MQAT_NO_CONTEXT, by an application using MQPMO_SET_ALL_CONTEXT, if any of the other context fields are nonblank).

When the queue manager generates this information as a result of an application put, the field is set to a value that is determined by the environment. On IBM i, it is set to MQAT_OS400; the queue manager never uses MQAT_CICS on IBM i.

For the MQPUT and MQPUT1 calls, this is an input/output field if MQPMO_SET_ALL_CONTEXT is specified in the PutMsgOpts parameter. If MQPMO_SET_ALL_CONTEXT is not specified, this field is ignored on input and is an output-only field.

This is an output field for the MQGET call. The initial value of this field is MQAT_NO_CONTEXT.

PutApplName (MQCHAR28)

This is the name of application that put the message, and is part of the origin context of the message. The contents differ between platforms, and might differ between releases.

For more information about message context, see MQMD - Message descriptor and Message context.

You can specify the application name in additional programming languages. See specifying the application name in supported programming languages for more information.

The format of PutApplName depends on the value of PutApplType and can change from one release to another. Changes are rare, but do happen if the environment changes.

When the queue manager sets this field (that is, for all options except MQPMO_SET_ALL_CONTEXT), it sets the field to a value that is determined by the environment:

On z/OS, the queue manager uses:
- For z/OS batch, the 8-character job name from the JES JOB card
- For TSO, the 7-character TSO user identifier
- For CICS, the 8-character applid, followed by the 4-character tranid
- For IMS, the 8-character IMS system identifier, followed by the 8-character PSB name
- For XCF, the 8-character XCF group name, followed by the 16-character XCF member name
- For a message generated by a queue manager, the first 28 characters of the queue manager name
- For distributed queuing without CICS, the 8-character jobname of the channel initiator followed by the 8-character name of the module putting to the dead-letter queue followed by an 8-character task identifier.
The name or names are each padded to the right with blanks, as is any space in the remainder of the field. Where there is more than one name, there is no separator between them.
On Windows systems, the queue manager uses the following names:
- For a CICS application, the CICS transaction name
- For a non-CICS application, the rightmost 28 characters of the fully-qualified name of the executable
On IBM i, the queue manager uses the fully-qualified job name.
On AIX and Linux, the queue manager uses the following names:
- For a CICS application, the CICS transaction name
- For a non-CICS application, MQ asks the operating system for the name of the process. This is returned as the program file name, without full path. Then MQ places this process name in the MQMD.PutApplName field as follows:
  
  AIX
  
  If the name is less than or equal to 28 bytes, then the name is inserted, padded to the right with spaces.
  
  If the name is greater than 28 bytes, then the leftmost 28 bytes of the name are inserted.
  
  Linux
  
  If the name is less than or equal to 15 bytes, then the name is inserted, padded to the right with spaces.
  
  If the name is greater than 15 bytes, then the leftmost 15 bytes of the name are inserted, padded to the right with spaces.
  
  For example, if you run /opt/mqm/samp/bin/amqsput QNAME QMNAME, then the PutApplName is 'amqsput '. There are 21 space characters of padding in this MQCHAR28 field. Note that the full path including /opt/mqm/samp/bin is not included in the PutApplName.

For the MQPUT and MQPUT1 calls, this is an input/output field if MQPMO_SET_ALL_CONTEXT is specified in the PutMsgOpts parameter. Any information following a null character within the field is discarded. The null character and any following characters are converted to blanks by the queue manager. If MQPMO_SET_ALL_CONTEXT is not specified, this field is ignored on input and is an output-only field.

PutDate (MQCHAR8)

This is the date when the message was put, and is part of the origin context of the message. For more information about message context, see MQMD - Message descriptor and Message context.

The format used for the date when this field is generated by the queue manager is:

YYYYMMDD

where the characters represent:

YYYY: year (four numeric digits)
MM: month of year (01 through 12)
DD: day of month (01 through 31)

Greenwich Mean Time (GMT) is used for the PutDate and PutTime fields, subject to the system clock being set accurately to GMT.

If the message was put as part of a unit of work, the date is that when the message was put, and not the date when the unit of work was committed.

For the MQPUT and MQPUT1 calls, this is an input/output field if MQPMO_SET_ALL_CONTEXT is specified in the PutMsgOpts parameter. The contents of the field are not checked by the queue manager, except that any information following a null character within the field is discarded. The queue manager converts the null character and any following characters to blanks. If MQPMO_SET_ALL_CONTEXT is not specified, this field is ignored on input and is an output-only field.

This is an output field for the MQGET call. The length of this field is given by MQ_PUT_DATE_LENGTH. The initial value of this field is the null string in C, and 8 blank characters in other programming languages.

PutTime (MQCHAR8)

This is the time when the message was put, and is part of the origin context of the message. For more information about message context, see MQMD - Message descriptor and Message context.

The format used for the time when this field is generated by the queue manager is:

HHMMSSTH

where the characters represent (in order):

HH: hours (00 through 23)
MM: minutes (00 through 59)
SS: seconds (00 through 59; see note)
T: tenths of a second (0 through 9)
H: hundredths of a second (0 through 9)

Note: If the system clock is synchronized to a very accurate time standard, it is possible on rare occasions for 60 or 61 to be returned for the seconds in PutTime. This happens when leap seconds are inserted into the global time standard.

Greenwich Mean Time (GMT) is used for the PutDate and PutTime fields, subject to the system clock being set accurately to GMT.

If the message was put as part of a unit of work, the time is that when the message was put, and not the time when the unit of work was committed.

For the MQPUT and MQPUT1 calls, this is an input/output field if MQPMO_SET_ALL_CONTEXT is specified in the PutMsgOpts parameter. The queue manager does not check the contents of the field, except that any information following a null character within the field is discarded. The queue manager converts the null character and any following characters to blanks. If MQPMO_SET_ALL_CONTEXT is not specified, this field is ignored on input and is an output-only field.

This is an output field for the MQGET call. The length of this field is given by MQ_PUT_TIME_LENGTH. The initial value of this field is the null string in C, and 8 blank characters in other programming languages.

ApplOriginData (MQCHAR4)

This is part of the origin context of the message. For more information about message context, see MQMD - Message descriptor and Message context.

ApplOriginData is information that is defined by the application suite that can be used to provide additional information about the origin of the message. For example, it could be set by applications running with suitable user authority to indicate whether the identity data is trusted.

The queue manager treats this information as character data, but does not define the format of it. When the queue manager generates this information, it is entirely blank.

For the MQPUT and MQPUT1 calls, this is an input/output field if MQPMO_SET_ALL_CONTEXT is specified in the PutMsgOpts parameter. Any information following a null character within the field is discarded. The queue manager converts the null character and any following characters to blanks. If MQPMO_SET_ALL_CONTEXT is not specified, this field is ignored on input and is an output-only field.

This is an output field for the MQGET call. The length of this field is given by MQ_APPL_ORIGIN_DATA_LENGTH. The initial value of this field is the null string in C, and 4 blank characters in other programming languages.

When the message is published, although ApplOriginData is set, it is blank in the subscription that it receives.

GroupId (MQBYTE24)

This is a byte string that is used to identify the particular message group or logical message to which the physical message belongs. GroupId is also used if segmentation is allowed for the message. In all these cases, GroupId has a non-null value, and one or more of the following flags is set in the MsgFlags field:

MQMF_MSG_IN_GROUP
MQMF_LAST_MSG_IN_GROUP
MQMF_SEGMENT
MQMF_LAST_SEGMENT
MQMF_SEGMENTATION_ALLOWED

If none of these flags is set, GroupId has the special null value MQGI_NONE.

The application does not need to set this field on the MQPUT or MQGET call if:

On the MQPUT call, MQPMO_LOGICAL_ORDER is specified.
On the MQGET call, MQMO_MATCH_GROUP_ID is not specified.

These are the recommended ways of using these calls for messages that are not report messages. However, if the application requires more control, or the call is MQPUT1, the application must ensure that GroupId is set to an appropriate value.

Message groups and segments can be processed correctly only if the group identifier is unique. For this reason, applications must not generate their own group identifiers ; instead, applications must do one of the following:

If MQPMO_LOGICAL_ORDER is specified, the queue manager automatically generates a unique group identifier for the first message in the group or segment of the logical message, and uses that group identifier for the remaining messages in the group or segments of the logical message, so the application does not need to take any special action. This is the recommended procedure.
If MQPMO_LOGICAL_ORDER is not specified, the application must request the queue manager to generate the group identifier, by setting GroupId to MQGI_NONE on the first MQPUT or MQPUT1 call for a message in the group or segment of the logical message. The group identifier returned by the queue manager on output from that call must then be used for the remaining messages in the group or segments of the logical message. If a message group contains segmented messages, the same group identifier must be used for all segments and messages in the group.
When MQPMO_LOGICAL_ORDER is not specified, messages in groups and segments of logical messages can be put in any order (for example, in reverse order), but the group identifier must be allocated by the first MQPUT or MQPUT1 call that is issued for any of those messages.

On input to the MQPUT and MQPUT1 calls, the queue manager uses the value described in Physical order on a queue. On output from the MQPUT and MQPUT1 calls, the queue manager sets this field to the value that was sent with the message if the object opened is a single queue and not a distribution list, but leaves it unchanged if the object opened is a distribution list. In the latter case, if the application needs to know the group identifiers generated, the application must provide MQPMR records containing the GroupId field.

On input to the MQGET call, the queue manager uses the value described in Table 2. On output from the MQGET call, the queue manager sets this field to the value for the message retrieved.

The following special value is defined:

MQGI_NONE

No group identifier specified.

The value is binary zero for the length of the field. This is the value that is used for messages that are not in groups, not segments of logical messages, and for which segmentation is not allowed.

For the C programming language, the constant MQGI_NONE_ARRAY is also defined; this has the same value as MQGI_NONE, but is an array of characters instead of a string.

The length of this field is given by MQ_GROUP_ID_LENGTH. The initial value of this field is MQGI_NONE. This field is ignored if Version is less than MQMD_VERSION_2.

MsgSeqNumber (MQLONG)

This is the sequence number of a logical message within a group.

Sequence numbers start at 1, and increase by 1 for each new logical message in the group, up to a maximum of 999 999 999. A physical message that is not in a group has a sequence number of 1.

The application does not have to set this field on the MQPUT or MQGET call if:

On the MQPUT call, MQPMO_LOGICAL_ORDER is specified.
On the MQGET call, MQMO_MATCH_MSG_SEQ_NUMBER is not specified.

On input to the MQGET call, the queue manager uses the value shown in Table 2. On output from the MQGET call, the queue manager sets this field to the value for the message retrieved.

The initial value of this field is one. This field is ignored if Version is less than MQMD_VERSION_2.

Offset (MQLONG)

This is the offset in bytes of the data in the physical message from the start of the logical message of which the data forms part. This data is called a segment. The offset is in the range 0 through 999 999 999. A physical message that is not a segment of a logical message has an offset of zero.

The application does not need to set this field on the MQPUT or MQGET call if:

On the MQPUT call, MQPMO_LOGICAL_ORDER is specified.
On the MQGET call, MQMO_MATCH_OFFSET is not specified.

These are the recommended ways of using these calls for messages that are not report messages. However, if the application does not comply with these conditions, or the call is MQPUT1, the application must ensure that Offset is set to an appropriate value.

For a report message reporting on a segment of a logical message, the OriginalLength field (provided it is not MQOL_UNDEFINED) is used to update the offset in the segment information retained by the queue manager.

On input to the MQGET call, the queue manager uses the value shown in Table 2. On output from the MQGET call, the queue manager sets this field to the value for the message retrieved.

The initial value of this field is zero. This field is ignored if Version is less than MQMD_VERSION_2.

MsgFlags (MQLONG)

MsgFlags are flags that specify attributes of the message, or control its processing. They are divided into the following categories:

Segmentation flags
Status flags

Segmentation flags

When a message is too big for a queue, an attempt to put the message on the queue typically fails. Segmentation is a technique whereby the queue manager or application splits the message into smaller pieces called segments, and places each segment on the queue as a separate physical message. The application that retrieves the message can either retrieve the segments one by one, or request the queue manager to reassemble the segments into a single message that is returned by the MQGET call. The latter is achieved by specifying the MQGMO_COMPLETE_MSG option on the MQGET call, and supplying a buffer that is big enough to accommodate the complete message. (See MQGMO - Get-message options for details of the MQGMO_COMPLETE_MSG option.) A message can be segmented at the sending queue manager, at an intermediate queue manager, or at the destination queue manager.

You can specify one of the following to control the segmentation of a message:

MQMF_SEGMENTATION_INHIBITED

This option prevents the message being broken into segments by the queue manager. If specified for a message that is already a segment, this option prevents the segment being broken into smaller segments.

The value of this flag is binary zero. This is the default.

MQMF_SEGMENTATION_ALLOWED

This option allows the message to be broken into segments by the queue manager. If specified for a message that is already a segment, this option allows the segment to be broken into smaller segments. MQMF_SEGMENTATION_ALLOWED can be set without either MQMF_SEGMENT or MQMF_LAST_SEGMENT being set.

On z/OS, the queue manager does not support the segmentation of messages. If a message is too big for the queue, the MQPUT or MQPUT1 call fails with reason code MQRC_MSG_TOO_BIG_FOR_Q. However, the MQMF_SEGMENTATION_ALLOWED option can still be specified, and allows the message to be segmented at a remote queue manager.

When the queue manager segments a message, the queue manager turns on the MQMF_SEGMENT flag in the copy of the MQMD that is sent with each segment, but does not alter the settings of these flags in the MQMD provided by the application on the MQPUT or MQPUT1 call. For the last segment in the logical message, the queue manager also turns on the MQMF_LAST_SEGMENT flag in the MQMD that is sent with the segment.

Note: Take care when putting messages with MQMF_SEGMENTATION_ALLOWED but without MQPMO_LOGICAL_ORDER. If the message is:

Not a segment, and
Not in a group, and
Not being forwarded,

the application must reset the GroupId field to MQGI_NONE before each MQPUT or MQPUT1 call, so that the queue manager can generate a unique group identifier for each message. If this is not done, unrelated messages can have the same group identifier, which might lead to incorrect processing subsequently. See the descriptions of the GroupId field and the MQPMO_LOGICAL_ORDER option for more information about when to reset the GroupId field.

The queue manager splits messages into segments as necessary so that the segments (plus any required header data) fit on the queue. However, there is a lower limit for the size of a segment generated by the queue manager, and only the last segment created from a message can be smaller than this limit (the lower limit for the size of an application-generated segment is one byte). Segments generated by the queue manager might be of unequal length. The queue manager processes the message as follows:

User-defined formats are split on boundaries that are multiples of 16 bytes; the queue manager does not generate segments that are smaller than 16 bytes (other than the last segment).
Built-in formats other than MQFMT_STRING are split at points appropriate to the nature of the data present. However, the queue manager never splits a message in the middle of an IBM MQ header structure. This means that a segment containing a single MQ header structure cannot be split further by the queue manager, and as a result the minimum possible segment size for that message is greater than 16 bytes.
The second or later segment generated by the queue manager begins with one of the following:
- An MQ header structure
- The start of the application message data
- Part of the way through the application message data
MQFMT_STRING is split without regard for the nature of the data present (SBCS, DBCS, or mixed SBCS/DBCS). When the string is DBCS or mixed SBCS/DBCS, this might result in segments that cannot be converted from one character set to another. The queue manager never splits MQFMT_STRING messages into segments that are smaller than 16 bytes (other than the last segment).
The queue manager sets the Format, CodedCharSetId, and Encoding fields in the MQMD of each segment to describe correctly the data present at the start of the segment; the format name is either the name of a built-in format, or the name of a user-defined format.
The Report field in the MQMD of segments with Offset greater than zero is modified. For each report type, if the report option is MQRO_*_WITH_DATA, but the segment cannot contain any of the first 100 bytes of user data (that is, the data following any IBM MQ header structures that may be present), the report option is changed to MQRO_*.

The queue manager follows the above rules, but otherwise splits messages unpredictably; do not make assumptions about where a message is split.

For persistent messages, the queue manager can perform segmentation only within a unit of work:

If the MQPUT or MQPUT1 call is operating within a user-defined unit of work, that unit of work is used. If the call fails during the segmentation process, the queue manager removes any segments that were placed on the queue as a result of the failing call. However, the failure does not prevent the unit of work being committed successfully.
If the call is operating outside a user-defined unit of work, and there is no user-defined unit of work in existence, the queue manager creates a unit of work just for the duration of the call. If the call is successful, the queue manager commits the unit of work automatically. If the call fails, the queue manager backs out the unit of work.
If the call is operating outside a user-defined unit of work, but a user-defined unit of work exists, the queue manager cannot perform segmentation. If the message does not require segmentation, the call can still succeed. But if the message requires segmentation, the call fails with reason code MQRC_UOW_NOT_AVAILABLE.

For nonpersistent messages, the queue manager does not require a unit of work to be available in order to perform segmentation.

Take special care when converting data in messages that might be segmented:

If the receiving application converts data on the MQGET call, and specifies the MQGMO_COMPLETE_MSG option, the data-conversion exit is passed the complete message for the exit to convert, and the fact that the message was segmented is apparent to the exit.
If the receiving application retrieves one segment at a time, the data-conversion exit is invoked to convert one segment at a time. The exit must therefore convert the data in a segment independently of the data in any of the other segments.
If the nature of the data in the message is such that arbitrary segmentation of the data on 16-byte boundaries might result in segments that cannot be converted by the exit, or the format is MQFMT_STRING and the character set is DBCS or mixed SBCS/DBCS, the sending application must create and put the segments, specifying MQMF_SEGMENTATION_INHIBITED to suppress further segmentation. In this way, the sending application can ensure that each segment contains sufficient information to allow the data-conversion exit to convert the segment successfully.
If sender conversion is specified for a sending message channel agent (MCA), the MCA converts only messages that are not segments of logical messages; the MCA never attempts to convert messages that are segments.

This flag is an input flag on the MQPUT and MQPUT1 calls, and an output flag on the MQGET call. On the latter call, the queue manager also echoes the value of the flag to the Segmentation field in MQGMO.

The initial value of this flag is MQMF_SEGMENTATION_INHIBITED.

Status flags

These are flags that indicate whether the physical message belongs to a message group, is a segment of a logical message, both, or neither. One or more of the following can be specified on the MQPUT or MQPUT1 call, or returned by the MQGET call:

MQMF_MSG_IN_GROUP

Message is a member of a group.

MQMF_LAST_MSG_IN_GROUP

Message is the last logical message in a group.

If this flag is set, the queue manager turns on MQMF_MSG_IN_GROUP in the copy of MQMD that is sent with the message, but does not alter the settings of these flags in the MQMD provided by the application on the MQPUT or MQPUT1 call.

It is valid for a group to consist of only one logical message. If this is the case, MQMF_LAST_MSG_IN_GROUP is set, but the MsgSeqNumber field has the value one.

MQMF_SEGMENT

Message is a segment of a logical message.

When MQMF_SEGMENT is specified without MQMF_LAST_SEGMENT, the length of the application message data in the segment ( excluding the lengths of any IBM MQ header structures that might be present) must be at least one. If the length is zero, the MQPUT or MQPUT1 call fails with reason code MQRC_SEGMENT_LENGTH_ZERO.

On z/OS, this option is not supported if the message is being put on a queue that has an index type of MQIT_GROUP_ID.

MQMF_LAST_SEGMENT

Message is the last segment of a logical message.

If this flag is set, the queue manager turns on MQMF_SEGMENT in the copy of MQMD that is sent with the message, but does not alter the settings of these flags in the MQMD provided by the application on the MQPUT or MQPUT1 call.

A logical message can consist of only one segment. If so, MQMF_LAST_SEGMENT is set, but the Offset field has the value zero.

When MQMF_LAST_SEGMENT is specified, the length of the application message data in the segment ( excluding the lengths of any header structures that might be present) can be zero.

On z/OS, this option is not supported if the message is being put on a queue that has an index type of MQIT_GROUP_ID.

The application must ensure that these flags are set correctly when putting messages. If MQPMO_LOGICAL_ORDER is specified, or was specified on the preceding MQPUT call for the queue handle, the settings of the flags must be consistent with the group and segment information retained by the queue manager for the queue handle. The following conditions apply to successive MQPUT calls for the queue handle when MQPMO_LOGICAL_ORDER is specified:

If there is no current group or logical message, all these flags (and combinations of them) are valid.
Once MQMF_MSG_IN_GROUP has been specified, it must remain on until MQMF_LAST_MSG_IN_GROUP is specified. The call fails with reason code MQRC_INCOMPLETE_GROUP if this condition is not satisfied.
Once MQMF_SEGMENT has been specified, it must remain on until MQMF_LAST_SEGMENT is specified. The call fails with reason code MQRC_INCOMPLETE_MSG if this condition is not satisfied.
Once MQMF_SEGMENT has been specified without MQMF_MSG_IN_GROUP, MQMF_MSG_IN_GROUP must remain off until after MQMF_LAST_SEGMENT has been specified. The call fails with reason code MQRC_INCOMPLETE_MSG if this condition is not satisfied.

Physical order on a queue shows the valid combinations of the flags, and the values used for various fields.

These flags are input flags on the MQPUT and MQPUT1 calls, and output flags on the MQGET call. On the latter call, the queue manager also echoes the values of the flags to the GroupStatus and SegmentStatus fields in MQGMO.

You cannot use grouped or segmented messages with Publish/Subscribe.

Default flags

The following can be specified to indicate that the message has default attributes:

MQMF_NONE: No message flags (default message attributes).
This inhibits segmentation, and indicates that the message is not in a group and is not a segment of a logical message. MQMF_NONE is defined to aid program documentation. It is not intended that this flag be used with any other, but as its value is zero, such use cannot be detected.

The MsgFlags field is partitioned into subfields; for details see Report options and message flags.

The initial value of this field is MQMF_NONE. This field is ignored if Version is less than MQMD_VERSION_2.

OriginalLength (MQLONG)

This field is relevant only for report messages that are segments. It specifies the length of the message segment to which the report message relates; it does not specify the length of the logical message of which the segment forms part, or the length of the data in the report message.

Note: When generating a report message for a message that is a segment, the queue manager and message channel agent copy into the MQMD for the report message the GroupId, MsgSeqNumber, Offset, and MsgFlags, fields from the original message. As a result, the report message is also a segment. Applications that generate report messages must do the same, and set the OriginalLength field correctly.

The following special value is defined:

MQOL_UNDEFINED: Original length of message not defined.

OriginalLength is an input field on the MQPUT and MQPUT1 calls, but the value that the application provides is accepted only in particular circumstances:

If the message being put is a segment and is also a report message, the queue manager accepts the value specified. The value must be:
- Greater than zero if the segment is not the last segment
- Not less than zero if the segment is the last segment
- Not less than the length of data present in the message
If these conditions are not satisfied, the call fails with reason code MQRC_ORIGINAL_LENGTH_ERROR.
If the message being put is a segment but not a report message, the queue manager ignores the field and uses the length of the application message data instead.
In all other cases, the queue manager ignores the field and uses the value MQOL_UNDEFINED instead.

This is an output field on the MQGET call.

The initial value of this field is MQOL_UNDEFINED. This field is ignored if Version is less than MQMD_VERSION_2.