MQMDE (Message descriptor extension) on IBM i

Overview

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: FMMDE.

Character set and encoding: Data in MQMDE must be in the character set given by the CodedCharSetId queue manager attribute and encoding of the local queue manager given by ENNAT for the C programming language.

The character set and encoding of the MQMDE must be set into the MDCSI and MDENC 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.

Usage: Normal applications should use a version-2 MQMD, in which case they will not encounter an MQMDE structure. However, specialized applications, and applications that continue to use a version-1 MQMD, may 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
MQMDE returned by MQGET call
MQMDE in messages on transmission queues
Fields
Initial values
RPG declaration

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 MDFMT field in MQMD to FMMDE 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 2. 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

There is one special case. If the application uses a version-2 MQMD to put a message that is a segment (that is, the MFSEG or MFLSEG flag is set), and the format name in the MQMD is FMDLH, 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 MDFMT field in MQMD to the value FMMDE 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 an MQMDE is returned by the MQGET call, the data in the MQMDE is typically in the queue manager's character set and encoding. However the MQMDE may 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 (see Security of IBM MQ for IBM i objects for further information).

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 may also be present, positioned between the MQXQH structure and application message data, but it will typically be present only if one or more of the fields in the MQMDE has a nondefault value.

Other IBM 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:

MQXQH (containing a version-1 MQMD)
MQMDE
MQDLH
Application message data

Fields

The MQMDE structure contains the following fields; the fields are described in alphabetical order:

MECSI (10-digit signed integer)

Character-set identifier of data that follows MQMDE.

This specifies the character set identifier of the data that follows the MQMDE structure; it does not apply to character data in the MQMDE structure itself.

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 this field is valid. The following special value can be used:

CSINHT

Inherit character-set identifier of this structure.

Character data in the data following this structure is in the same character set as this structure.

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

CSINHT cannot be used if the value of the MDPAT field in MQMD is ATBRKR.

The initial value of this field is CSUNDF.

MEENC (10-digit signed integer)

MEENC (10-digit signed integer)

This specifies the numeric encoding of the data that follows the MQMDE structure; it does not apply to numeric data in the MQMDE structure itself.

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. See the MDENC field described in MQMD (Message descriptor) on IBM i for more information about data encodings.

The initial value of this field is ENNAT.

MEFLG (10-digit signed integer)

General flags.

The following flag can be specified:

MEFNON: No flags.

The initial value of this field is MEFNON.

MEFMT (8-byte character string)

Format name of data that follows MQMDE.

This specifies the format name of the data that follows the MQMDE structure.

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 this field is valid. See the MDFMT field described in MQMD (Message descriptor) on IBM i for more information about format names.

The initial value of this field is FMNONE.

MEGID (24-byte bit string)

Group identifier.

See the MDGID field described in MQMD (Message descriptor) on IBM i. The initial value of this field is GINONE.

MELEN (10-digit signed integer)

Length of MQMDE structure.

The following value is defined:

MELEN2: Length of version-2 message descriptor extension structure.

The initial value of this field is MELEN2.

MEMFL (10-digit signed integer)

Message flags.

See the MDMFL field described in MQMD (Message descriptor) on IBM i. The initial value of this field is MFNONE.

MEOFF (10-digit signed integer)

Offset of data in physical message from start of logical message.

See the MDOFF field described in MQMD (Message descriptor) on IBM i. The initial value of this field is 0.

MEOLN (10-digit signed integer)

Length of original message.

See the MDOLN field described in MQMD (Message descriptor) on IBM i. The initial value of this field is OLUNDF.

MESEQ (10-digit signed integer)

Sequence number of logical message within group.

See the MDSEQ field described in MQMD (Message descriptor) on IBM i. The initial value of this field is 1.

MESID (4-byte character string)

Structure identifier.

The value must be:

MESIDV: Identifier for message descriptor extension structure.

The initial value of this field is MESIDV.

MEVER (10-digit signed integer)

Structure version number.

The value must be:

MEVER2: Version-2 message descriptor extension structure.

The following constant specifies the version number of the current version:

MEVERC: Current version of message descriptor extension structure.

The initial value of this field is MEVER2.

Initial values

Field name	Name of constant	Value of constant
MESID	MESIDV	'MDE¬'
MEVER	MEVER2	2
MELEN	MELEN2	72
MEENC	ENNAT	Depends on environment
MECSI	CSUNDF	0
MEFMT	FMNONE	Blanks
MEFLG	MEFNON	0
MEGID	GINONE	Nulls
MESEQ	None	1
MEOFF	None	0
MEMFL	MFNONE	0
MEOLN	OLUNDF	-1
Notes: The symbol ¬ represents a single blank character.

RPG declaration

     D*..1....:....2....:....3....:....4....:....5....:....6....:....7..
     D*
     D* MQMDE Structure
     D*
     D* Structure identifier
     D  MESID                  1      4    INZ('MDE ')
     D* Structure version number
     D  MEVER                  5      8I 0 INZ(2)
     D* Length of MQMDE structure
     D  MELEN                  9     12I 0 INZ(72)
     D* Numeric encoding of data that followsMQMDE
     D  MEENC                 13     16I 0 INZ(273)
     D* Character-set identifier of data thatfollows MQMDE
     D  MECSI                 17     20I 0 INZ(0)
     D* Format name of data that followsMQMDE
     D  MEFMT                 21     28    INZ('        ')
     D* General flags
     D  MEFLG                 29     32I 0 INZ(0)
     D* Group identifier
     D  MEGID                 33     56    INZ(X'00000000000000-
     D                                     0000000000000000000000-
     D                                     000000000000')
     D* Sequence number of logical messagewithin group
     D  MESEQ                 57     60I 0 INZ(1)
     D* Offset of data in physical messagefrom start of logical message
     D  MEOFF                 61     64I 0 INZ(0)
     D* Message flags
     D  MEMFL                 65     68I 0 INZ(0)
     D* Length of original message
     D  MEOLN                 69     72I 0 INZ(-1)

Parent topic: Data type descriptions on IBM i