Overview for MQMDE
Availability: All IBM MQ systems, plus IBM MQ clients connected to these systems.
Purpose: The MQMDE structure describes the data that sometimes occurs preceding the application message data. The structure contains those MQMD fields that exist in the version-2 MQMD, but not in the version-1 MQMD.
Format name: MQFMT_MD_EXTENSION.
Character set and encoding: Data in MQMDE must be in the character set and encoding of the local queue manager; these are given by the CodedCharSetId queue manager attribute and MQENC_NATIVE for the C programming language.
Set the character set and encoding of the MQMDE into the CodedCharSetId and Encoding fields in:- The MQMD (if the MQMDE structure is at the start of the message data), or
- The header structure that precedes the MQMDE structure (all other cases).
If the MQMDE is not in the queue manager's character set and encoding, the MQMDE is accepted but not honored, that is, the MQMDE is treated as message data.
Note: On Windows, applications compiled with Micro Focus COBOL use a value of MQENC_NATIVE that is different from the queue manager's encoding. Although numeric fields in the MQMD structure on the MQPUT, MQPUT1, and MQGET calls must be in the Micro Focus COBOL encoding, numeric fields in the MQMDE structure must be in the queue manager's encoding. This latter is given by MQENC_NATIVE for the C programming language, and has the value 546. Usage: Applications that use a version-2 MQMD will not encounter an MQMDE structure. However, specialized applications, and applications that continue to use a version-1 MQMD, might encounter an MQMDE in some situations. The MQMDE structure can occur in the following circumstances:- Specified on the MQPUT and MQPUT1 calls
- Returned by the MQGET call
- In messages on transmission queues
MQMDE specified on MQPUT and MQPUT1 calls: On the MQPUT and MQPUT1 calls, if the application provides a version-1 MQMD, the application can optionally prefix the message data with an MQMDE, setting the Format field in MQMD to MQFMT_MD_EXTENSION to indicate that an MQMDE is present. If the application does not provide an MQMDE, the queue manager assumes default values for the fields in the MQMDE. The default values that the queue manager uses are the same as the initial values for the structure; see Table 1. If the application provides a version-2 MQMD and prefixes the application message data with an MQMDE, the structures are processed as shown in Table 1.
| MQMD version | Values of version-2 fields | Values of corresponding fields in MQMDE | Action taken by queue manager |
|---|---|---|---|
| 1 | - | Valid | MQMDE is honored |
| 2 | Default | Valid | MQMDE is honored |
| 2 | Not default | Valid | MQMDE is treated as message data |
| 1 or 2 | Any | Not valid | Call fails with an appropriate reason code |
| 1 or 2 | Any | MQMDE is in the wrong character set or encoding, or is an unsupported version | MQMDE is treated as message data |
| Note: On z/OS, if the application specifies a version-1 MQMD with an MQMDE, the queue manager validates the MQMDE only if the queue has an IndexType of MQIT_GROUP_ID. | |||
There is one special case. If the application uses a version-2 MQMD to put a message that is a segment (that is, the MQMF_SEGMENT or MQMF_LAST_SEGMENT flag is set), and the format name in the MQMD is MQFMT_DEAD_LETTER_HEADER, the queue manager generates an MQMDE structure and inserts it between the MQDLH structure and the data that follows it. In the MQMD that the queue manager retains with the message, the version-2 fields are set to their default values.
Several of the fields that exist in the version-2 MQMD but not the version-1 MQMD are input/output fields on MQPUT and MQPUT1. However, the queue manager does not return any values in the equivalent fields in the MQMDE on output from the MQPUT and MQPUT1 calls; if the application requires those output values, it must use a version-2 MQMD.
MQMDE returned by MQGET call: On the MQGET call, if the application provides a version-1 MQMD, the queue manager prefixes the message returned with an MQMDE, but only if one or more of the fields in the MQMDE has a nondefault value. The queue manager sets the Format field in MQMD to the value MQFMT_MD_EXTENSION to indicate that an MQMDE is present.
If the application provides an MQMDE at the start of the Buffer parameter, the MQMDE is ignored. On return from the MQGET call, it is replaced by the MQMDE for the message (if one is needed), or overwritten by the application message data (if the MQMDE is not needed).
If the MQGET call returns an MQMDE, the data in the MQMDE is usually in the queue manager's character set and encoding. However the MQMDE might be in some other character set and encoding if:- The MQMDE was treated as data on the MQPUT or MQPUT1 call (see Table 1 for the circumstances that can cause this).
- The message was received from a remote queue manager connected by a TCP connection, and the receiving message channel agent (MCA) was not set up correctly.
Note: On Windows, applications compiled with Micro Focus COBOL use a value of MQENC_NATIVE that is different from the queue manager's encoding (see above).
MQMDE in messages on transmission queues: Messages on transmission queues are prefixed with the MQXQH structure, which contains within it a version-1 MQMD. An MQMDE might also be present, positioned between the MQXQH structure and application message data, but it is usually present only if one or more of the fields in the MQMDE has a nondefault value.
Other MQ header structures can also occur between the MQXQH structure and the application message data. For example, when the dead-letter header MQDLH is present, and the message is not a segment, the order is:Parent topic: MQMDE - Message descriptor extension