Field details for MQDLH

The MQDLH Dead letter header structure describes the information that prefixes the application message data of messages on the dead letter (undelivered-message) queue. A message can arrive on the dead letter queue either because the queue manager or message channel agent has redirected it to the queue, or because an application has put the message directly on the queue.

StrucId (MQCHAR4)

This is the structure identifier of the dead letter header structure. It is always an input field. Its value is MQDLH_STRUC_ID.

The value must be:

MQDLH_STRUC_ID: Identifier for the dead letter header structure.
For the C programming language, the constant MQDLH_STRUC_ID_ARRAY is also defined. This has the same value as MQDLH_STRUC_ID, but is an array of characters instead of a string.

Version (MQLONG)

Version is the structure version number.

The value must be:

MQDLH_VERSION_1: Version number for dead-letter header structure.

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

MQDLH_CURRENT_VERSION: Current version of dead-letter header structure.

The initial value of this field is MQDLH_VERSION_1.

Reason (MQLONG)

The Reason field identifies the reason why the message was placed on the dead-letter queue instead of on the original destination queue.

This identifies the reason why the message was placed on the dead-letter queue instead of on the original destination queue. It should be one of the MQFB_* or MQRC_* values (for example, MQRC_Q_FULL). See the description of the Feedback field in MQMD - Message descriptor for details of the common MQFB_* values that can occur.

If the value is in the range MQFB_IMS_FIRST through MQFB_IMS_LAST, the actual IMS error code can be determined by subtracting MQFB_IMS_ERROR from the value of the Reason field.

Some MQFB_* values occur only in this field. They relate to repository messages, trigger messages, or transmission-queue messages that have been transferred to the dead-letter queue. These are:

MQFB_APPL_CANNOT_BE_STARTED ( X'00000109'): An application processing a trigger message cannot start the application named in the ApplId field of the trigger message (see MQTM - Trigger message ).
On z/OS®, the CKTI CICS® transaction is an example of an application that processes trigger messages.
MQFB_APPL_TYPE_ERROR ( X'0000010B'): An application processing a trigger message cannot start the application because the ApplType field of the trigger message is not valid (see MQTM - Trigger message ).
On z/OS, the CKTI CICS transaction is an example of an application that processes trigger messages.
MQFB_BIND_OPEN_CLUSRCVR_DEL ( X'00000119'): The message was on the SYSTEM.CLUSTER.TRANSMIT.QUEUE intended for a cluster queue that was opened with the MQOO_BIND_ON_OPEN option, but the remote cluster-receiver channel to be used to transmit the message to the destination queue was deleted before the message could be sent. Because MQOO_BIND_ON_OPEN was specified, only the channel selected when the queue was opened can be used to transmit the message. As this channel is no longer available, the message is placed on the dead-letter queue.
MQFB_NOT_A_REPOSITORY_MSG ( X'00000118'): The message is not a repository message.
MQFB_STOPPED_BY_CHAD_EXIT ( X'00000115'): The message was stopped by channel auto-definition exit.
MQFB_STOPPED_BY_MSG_EXIT ( X'0000010D'): The message was stopped by channel message exit.
MQFB_TM_ERROR ( X'0000010A'): The Format field in MQMD specifies MQFMT_TRIGGER, but the message does not begin with a valid MQTM structure. For example, the StrucId mnemonic eye-catcher might not be valid, the Version might not be recognized, or the length of the trigger message might be insufficient to contain the MQTM structure.
On z/OS, the CKTI CICS transaction is an example of an application that processes trigger messages and can generate this feedback code.
MQFB_XMIT_Q_MSG_ERROR ( X'0000010F'): A message channel agent has found that a message on the transmission queue is not in the correct format. The message channel agent puts the message on the dead-letter queue using this feedback code.; One common cause is that a message has been put directly to the transmission queue, so the message does not have the expected XQH header. Messages should be put to a transmission queue through a remote queue, unless the application builds the MQXQH header.

The initial value of this field is MQRC_NONE.

DestQName (MQCHAR48)

DestQName is the name of the message queue that was the original destination for the message.

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.

DestQMgrName (MQCHAR48)

DestQMgrName is the name of the queue manager that was the original destination for the message.

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.

Encoding (MQLONG)

Encoding is the numeric encoding of the data that follows the MQDLH structure (usually the data from the original message); it does not apply to numeric data in the MQDLH structure itself.

On the MQPUT or MQPUT1 call, the application must set this field to the value appropriate to the data.

The initial value of this field is 0.

CodedCharSetId (MQLONG)

CodedCharSetId is the character set identifier of the data that flows through the MQDLH structure (usually the data from the original message); it does not apply to character data in the MQDLH structure itself.

On the MQPUT or MQPUT1 call, the application must set this field to the value appropriate to the data. The following special value can be used:

MQCCSI_INHERIT

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 MQCCSI_INHERIT is not returned by the MQGET call.

You cannot use MQCCSI_INHERIT if the value of the PutApplType field in MQMD is MQAT_BROKER.

This value is supported in the following environments:

AIX®
IBM® i
Linux®
Windows

and for IBM MQ clients connected to these systems.

The initial value of this field is MQCCSI_UNDEFINED.

Format (MQCHAR8)

Format is the format name of the data that follows the MQDLH structure (usually the data from the original message).

On the MQPUT or MQPUT1 call, the application must set this field to the value appropriate to the data. The rules for coding this field are the same as those rules for coding the Format field in MQMD.

The length of this field is given by MQ_FORMAT_LENGTH. The initial value of this field is MQFMT_NONE.

PutApplType (MQLONG)

PutApplType is the type of application that put the message on the dead-letter (undelivered-message) queue.

This field has the same meaning as the PutApplType field in the message descriptor MQMD (see MQMD - Message descriptor for details).

If the queue manager redirects the message to the dead-letter queue, PutApplType has the value MQAT_QMGR.

The initial value of this field is 0.

PutApplName (MQCHAR28)

PutApplName is the name of the application that put the message on the dead-letter (undelivered-message) queue.

The format of the name depends on the PutApplType field. The format can vary release to release. See the description of the PutApplName field in MQMD - Message descriptor.

If the queue manager redirects the message to the dead-letter queue, PutApplName contains the first 28 characters of the queue manager name, padded with blanks if necessary.

The length of this field is given by MQ_PUT_APPL_NAME_LENGTH. The initial value of this field is the null string in C, and 28 blank characters in other programming languages.

PutDate (MQCHAR8)

PutDate is the date when the message was put on the dead-letter (undelivered-message) queue.

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.

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 eight blank characters in other programming languages.

PutTime (MQCHAR8)

PutTime is the time when the message was put on the dead-letter (undelivered-message) queue.

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

HHMMSSTH

where the characters represent:

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 an 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.

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 eight blank characters in other programming languages.