MQMD - Message descriptor
The MQMD 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.
Availability
All IBM® MQ systems, plus IBM MQ MQI clients connected to these systems.
Version
The current version of MQMD is MQMD_VERSION_2. Applications that are intended to be portable between several environments must ensure that the required version of MQMD is supported in all the environments concerned. Fields that exist only in the more-recent versions of the structure are identified as such in the descriptions that follow.
The header, COPY, and INCLUDE files provided for the supported programming languages contain the
most-recent version of MQMD that is supported by the environment, but with the initial value of the
Version
field set to MQMD_VERSION_1. To use fields that are not
present in the version-1 structure, the application must set the
Version
field to the version number of the version required.
A declaration for the version-1 structure is available with the name MQMD1.
Character set and encoding
Data in MQMD 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. However, if the application is running as an IBM MQ MQI client, the structure must be in the character set and encoding of the client.
If the sending and receiving queue managers use different character sets or encodings, the data in MQMD is converted automatically. It is not necessary for the application to convert the MQMD.
Using different versions of MQMD
- 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.Note: Several of the fields that exist in the version-2 MQMD but not the version-1 MQMD are input/output fields on the MQPUT and MQPUT1 calls. 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. - 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 non-default
value. The
Format
field in MQMD will have the value MQFMT_MD_EXTENSION to indicate that an MQMDE is present.
When a message is on a transmission queue, some of the fields in MQMD are set to particular values; see MQXQH - Transmission-queue header for details.
Message context
- Identity context relates to the application that originally put the message
- Origin context relates to the application that most recently put the message.
Although identity and origin context typically have the meanings described, the content of both types of context fields in MQMD depends on the MQPMO_*_CONTEXT options that are specified when the message is put. As a result, identity context does not necessarily relate to the application that originally put the message, and origin context does not necessarily relate to the application that most-recently put the message; it depends on the design of the application suite.
The message channel agent (MCA) never alters message context. MCAs that receive messages from remote queue managers use the context option MQPMO_SET_ALL_CONTEXT on the MQPUT or MQPUT1 call. This allows the receiving MCA to preserve exactly the message context that traveled with the message from the sending MCA. However, the result is that the origin context does not relate to either of the MCAs that sent and received the message. The origin context refers to an earlier application that put the message. If all the intermediate applications have passed the message context, the origin context refers to the originating application itself.
In the descriptions, the context fields are described as though they are used as described previously. For more information about message context, see Message context.
Fields
Field name and description | Name of constant | Initial value (if any) of constant |
---|---|---|
StrucId (structure identifier) | MQMD_STRUC_ID | 'MD' |
Version (structure version number) | MQMD_VERSION_1 | 1 |
Report (options for report messages) | MQRO_NONE | 0 |
MsgType (message type) | MQMT_DATAGRAM | 8 |
MQMD - Expiry field (message lifetime) | MQEI_UNLIMITED | -1 |
MQMD - Feedback field (feedback or reason code) | MQFB_NONE | 0 |
Encoding (numeric encoding of message data) | MQENC_NATIVE | Depends on environment |
CodedCharSetId (character set identifier of message data) | MQCCSI_Q_MGR | 0 |
Format (format name of message data) | MQFMT_NONE | Blanks |
Priority (message priority) | MQPRI_PRIORITY_AS_Q_DEF | -1 |
Persistence (message persistence) | MQPER_PERSISTENCE_AS_Q_DEF | 2 |
MQMD - MsgId field (message identifier) | MQMI_NONE | Nulls |
CorrelId (correlation identifier) | MQCI_NONE | Nulls |
BackoutCount (backout counter) | None | 0 |
ReplyToQ (name of reply queue) | None | Null string or blanks |
ReplyToQMgr (name of reply queue manager) | None | Null string or blanks |
UserIdentifier (user identifier) | None | Null string or blanks |
AccountingToken (accounting token) | MQACT_NONE | Nulls |
ApplIdentityData (application data relating to identity) | None | Null string or blanks |
PutApplType (type of application that put the message) | MQAT_NO_CONTEXT | 0 |
PutApplName (name of application that put the message) | None | Null string or blanks |
PutDate (date when message was put) | None | Null string or blanks |
PutTime (time when message was put) | None | Null string or blanks |
ApplOriginData (application data relating to origin) | None | Null string or blanks |
Note: The remaining fields are ignored if
Version is less than
MQMD_VERSION_2. |
||
GroupId (group identifier) | MQGI_NONE | Nulls |
MsgSeqNumber (sequence number of logical message within group) | None | 1 |
Offset (offset of data in physical message from start of logical message) | None | 0 |
MQMD - MsgFlags field (message flags) | MQMF_NONE | 0 |
OriginalLength (length of original message) | MQOL_UNDEFINED | -1 |
Notes:
|
Language declarations
C declaration for MQMD
typedef struct tagMQMD MQMD;
struct tagMQMD {
MQCHAR4 StrucId; /* Structure identifier */
MQLONG Version; /* Structure version number */
MQLONG Report; /* Options for report messages */
MQLONG MsgType; /* Message type */
MQLONG Expiry; /* Message lifetime */
MQLONG Feedback; /* Feedback or reason code */
MQLONG Encoding; /* Numeric encoding of message data */
MQLONG CodedCharSetId; /* Character set identifier of message
data */
MQCHAR8 Format; /* Format name of message data */
MQLONG Priority; /* Message priority */
MQLONG Persistence; /* Message persistence */
MQBYTE24 MsgId; /* Message identifier */
MQBYTE24 CorrelId; /* Correlation identifier */
MQLONG BackoutCount; /* Backout counter */
MQCHAR48 ReplyToQ; /* Name of reply queue */
MQCHAR48 ReplyToQMgr; /* Name of reply queue manager */
MQCHAR12 UserIdentifier; /* User identifier */
MQBYTE32 AccountingToken; /* Accounting token */
MQCHAR32 ApplIdentityData; /* Application data relating to
identity */
MQLONG PutApplType; /* Type of application that put the
message */
MQCHAR28 PutApplName; /* Name of application that put the
message */
MQCHAR8 PutDate; /* Date when message was put */
MQCHAR8 PutTime; /* Time when message was put */
MQCHAR4 ApplOriginData; /* Application data relating to origin */
MQBYTE24 GroupId; /* Group identifier */
MQLONG MsgSeqNumber; /* Sequence number of logical message
within group */
MQLONG Offset; /* Offset of data in physical message
from start of logical message */
MQLONG MsgFlags; /* Message flags */
MQLONG OriginalLength; /* Length of original message */
};
COBOL declaration for MQMD
** MQMD structure
10 MQMD.
** Structure identifier
15 MQMD-STRUCID PIC X(4).
** Structure version number
15 MQMD-VERSION PIC S9(9) BINARY.
** Options for report messages
15 MQMD-REPORT PIC S9(9) BINARY.
** Message type
15 MQMD-MSGTYPE PIC S9(9) BINARY.
** Message lifetime
15 MQMD-EXPIRY PIC S9(9) BINARY.
** Feedback or reason code
15 MQMD-FEEDBACK PIC S9(9) BINARY.
** Numeric encoding of message data
15 MQMD-ENCODING PIC S9(9) BINARY.
** Character set identifier of message data
15 MQMD-CODEDCHARSETID PIC S9(9) BINARY.
** Format name of message data
15 MQMD-FORMAT PIC X(8).
** Message priority
15 MQMD-PRIORITY PIC S9(9) BINARY.
** Message persistence
15 MQMD-PERSISTENCE PIC S9(9) BINARY.
** Message identifier
15 MQMD-MSGID PIC X(24).
** Correlation identifier
15 MQMD-CORRELID PIC X(24).
** Backout counter
15 MQMD-BACKOUTCOUNT PIC S9(9) BINARY.
** Name of reply queue
15 MQMD-REPLYTOQ PIC X(48).
** Name of reply queue manager
15 MQMD-REPLYTOQMGR PIC X(48).
** User identifier
15 MQMD-USERIDENTIFIER PIC X(12).
** Accounting token
15 MQMD-ACCOUNTINGTOKEN PIC X(32).
** Application data relating to identity
15 MQMD-APPLIDENTITYDATA PIC X(32).
** Type of application that put the message
15 MQMD-PUTAPPLTYPE PIC S9(9) BINARY.
** Name of application that put the message
15 MQMD-PUTAPPLNAME PIC X(28).
** Date when message was put
15 MQMD-PUTDATE PIC X(8).
** Time when message was put
15 MQMD-PUTTIME PIC X(8).
** Application data relating to origin
15 MQMD-APPLORIGINDATA PIC X(4).
** Group identifier
15 MQMD-GROUPID PIC X(24).
** Sequence number of logical message within group
15 MQMD-MSGSEQNUMBER PIC S9(9) BINARY.
** Offset of data in physical message from start of logical message
15 MQMD-OFFSET PIC S9(9) BINARY.
** Message flags
15 MQMD-MSGFLAGS PIC S9(9) BINARY.
** Length of original message
15 MQMD-ORIGINALLENGTH PIC S9(9) BINARY.
PL/I declaration for MQMD
dcl
1 MQMD based,
3 StrucId char(4), /* Structure identifier */
3 Version fixed bin(31), /* Structure version number */
3 Report fixed bin(31), /* Options for report messages */
3 MsgType fixed bin(31), /* Message type */
3 Expiry fixed bin(31), /* Message lifetime */
3 Feedback fixed bin(31), /* Feedback or reason code */
3 Encoding fixed bin(31), /* Numeric encoding of message
data */
3 CodedCharSetId fixed bin(31), /* Character set identifier of
message data */
3 Format char(8), /* Format name of message data */
3 Priority fixed bin(31), /* Message priority */
3 Persistence fixed bin(31), /* Message persistence */
3 MsgId char(24), /* Message identifier */
3 CorrelId char(24), /* Correlation identifier */
3 BackoutCount fixed bin(31), /* Backout counter */
3 ReplyToQ char(48), /* Name of reply queue */
3 ReplyToQMgr char(48), /* Name of reply queue manager */
3 UserIdentifier char(12), /* User identifier */
3 AccountingToken char(32), /* Accounting token */
3 ApplIdentityData char(32), /* Application data relating to
identity */
3 PutApplType fixed bin(31), /* Type of application that put the
message */
3 PutApplName char(28), /* Name of application that put the
message */
3 PutDate char(8), /* Date when message was put */
3 PutTime char(8), /* Time when message was put */
3 ApplOriginData char(4), /* Application data relating to
origin */
3 GroupId char(24), /* Group identifier */
3 MsgSeqNumber fixed bin(31), /* Sequence number of logical
message within group */
3 Offset fixed bin(31), /* Offset of data in physical
message from start of logical
message */
3 MsgFlags fixed bin(31), /* Message flags */
3 OriginalLength fixed bin(31); /* Length of original message */
High Level Assembler declaration for MQMD
MQMD DSECT
MQMD_STRUCID DS CL4 Structure identifier
MQMD_VERSION DS F Structure version number
MQMD_REPORT DS F Options for report messages
MQMD_MSGTYPE DS F Message type
MQMD_EXPIRY DS F Message lifetime
MQMD_FEEDBACK DS F Feedback or reason code
MQMD_ENCODING DS F Numeric encoding of message data
MQMD_CODEDCHARSETID DS F Character set identifier of message
* data
MQMD_FORMAT DS CL8 Format name of message data
MQMD_PRIORITY DS F Message priority
MQMD_PERSISTENCE DS F Message persistence
MQMD_MSGID DS XL24 Message identifier
MQMD_CORRELID DS XL24 Correlation identifier
MQMD_BACKOUTCOUNT DS F Backout counter
MQMD_REPLYTOQ DS CL48 Name of reply queue
MQMD_REPLYTOQMGR DS CL48 Name of reply queue manager
MQMD_USERIDENTIFIER DS CL12 User identifier
MQMD_ACCOUNTINGTOKEN DS XL32 Accounting token
MQMD_APPLIDENTITYDATA DS CL32 Application data relating to identity
MQMD_PUTAPPLTYPE DS F Type of application that put the
* message
MQMD_PUTAPPLNAME DS CL28 Name of application that put the
* message
MQMD_PUTDATE DS CL8 Date when message was put
MQMD_PUTTIME DS CL8 Time when message was put
MQMD_APPLORIGINDATA DS CL4 Application data relating to origin
MQMD_GROUPID DS XL24 Group identifier
MQMD_MSGSEQNUMBER DS F Sequence number of logical message
* within group
MQMD_OFFSET DS F Offset of data in physical message
* from start of logical message
MQMD_MSGFLAGS DS F Message flags
MQMD_ORIGINALLENGTH DS F Length of original message
*
MQMD_LENGTH EQU *-MQMD
ORG MQMD
MQMD_AREA DS CL(MQMD_LENGTH)
Visual Basic declaration for MQMD
Type MQMD
StrucId As String*4 'Structure identifier'
Version As Long 'Structure version number'
Report As Long 'Options for report messages'
MsgType As Long 'Message type'
Expiry As Long 'Message lifetime'
Feedback As Long 'Feedback or reason code'
Encoding As Long 'Numeric encoding of message data'
CodedCharSetId As Long 'Character set identifier of message'
'data'
Format As String*8 'Format name of message data'
Priority As Long 'Message priority'
Persistence As Long 'Message persistence'
MsgId As MQBYTE24 'Message identifier'
CorrelId As MQBYTE24 'Correlation identifier'
BackoutCount As Long 'Backout counter'
ReplyToQ As String*48 'Name of reply queue'
ReplyToQMgr As String*48 'Name of reply queue manager'
UserIdentifier As String*12 'User identifier'
AccountingToken As MQBYTE32 'Accounting token'
ApplIdentityData As String*32 'Application data relating to identity'
PutApplType As Long 'Type of application that put the'
'message'
PutApplName As String*28 'Name of application that put the'
'message'
PutDate As String*8 'Date when message was put'
PutTime As String*8 'Time when message was put'
ApplOriginData As String*4 'Application data relating to origin'
GroupId As MQBYTE24 'Group identifier'
MsgSeqNumber As Long 'Sequence number of logical message'
'within group'
Offset As Long 'Offset of data in physical message'
'from start of logical message'
MsgFlags As Long 'Message flags'
OriginalLength As Long 'Length of original message'
End Type