Overview for MQDLH

Availability: All IBM MQ platforms.

Purpose: The MQDLH 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.

Format name: MQFMT_DEAD_LETTER_HEADER.

Character set and encoding: The fields in the MQDLH structure are in the character set and encoding given by the CodedCharSetId and Encoding fields. These are specified in the header structure that precedes the MQDLH, or in the MQMD structure if the MQDLH is at the start of the application message data.

The character set must be one that has single-byte characters for the characters that are valid in queue names.

If you are using the WMQ classes for Java™/JMS, and the code page defined in the MQMD is not supported by the Java virtual machine, then the MQDLH is written in the UTF-8 character set.

Usage: Applications that put messages directly on the dead-letter queue must prefix the message data with an MQDLH structure, and initialize the fields with appropriate values. However, the queue manager does not require that an MQDLH structure be present, or that valid values have been specified for the fields.

If a message is too long to put on the dead-letter queue, the application must do one of the following:

Truncate the message data to fit on the dead-letter queue.
Record the message on auxiliary storage and place an exception report message on the dead-letter queue indicating this.
Discard the message and return an error to its originator. If the message is (or might be) a critical message, do this only if it is known that the originator still has a copy of the message; for example, a message received by a message channel agent from a communication channel.

Which of the preceding actions is appropriate (if any) depends on the design of the application.

The queue manager performs special processing when a message that is a segment is put with an MQDLH structure at the front; see the description of the MQMDE structure for further details.

Putting messages on the dead-letter queue: When a message is put on the dead-letter queue, the MQMD structure used for the MQPUT or MQPUT1 call must be identical to the MQMD associated with the message (usually the MQMD returned by the MQGET call), with the exception of the following:

Set the CodedCharSetId and Encoding fields to whatever character set and encoding are used for fields in the MQDLH structure.
Set the Format field to MQFMT_DEAD_LETTER_HEADER to indicate that the data begins with a MQDLH structure.
Set the context fields (AccountingToken, ApplIdentityData, ApplOriginData, PutApplName, PutApplType, PutDate, PutTime, UserIdentifier) by using a context option appropriate to the circumstances:
- An application putting on the dead-letter queue a message that is not related to any preceding message must use the MQPMO_DEFAULT_CONTEXT option; this causes the queue manager to set all of the context fields in the message descriptor to their default values.
- A server application putting on the dead-letter queue a messagethat it has just received must use the MQPMO_PASS_ALL_CONTEXT option to preserve the original context information.
- A server application putting on the dead-letter queue a reply to a message that it has just received must use the MQPMO_PASS_IDENTITY_CONTEXT option; this preserves the identity information but sets the origin information to be that of the server application.
- A message channel agent putting on the dead-letter queue a messagethat it received from its communication channel must use the MQPMO_SET_ALL_CONTEXT option to preserve the original context information.

In the MQDLH structure itself, set the fields as follows:

Set the CodedCharSetId, Encoding, and Format fields to the values that describe the data that follows the MQDLH structure, usually the values from the original message descriptor.
Set the context fields PutApplType, PutApplName, PutDate, and PutTime to values appropriate to the application that is putting the message on the dead-letter queue; these values are not related to the original message.
Set other fields as appropriate.

Ensure that all fields have valid values, and that character fields are padded with blanks to the defined length of the field; do not end the character data prematurely by using a null character, because the queue manager does not convert the null and subsequent characters to blanks in the MQDLH structure.

Get messages from the dead-letter queue: Applications that get messages from the dead-letter queue must verify that the messages begin with an MQDLH structure. The application can determine whether an MQDLH structure is present by examining the Format field in the message descriptor MQMD; if the field has the value MQFMT_DEAD_LETTER_HEADER, the message data begins with an MQDLH structure. Be aware also that messages that applications get from the dead-letter queue might be truncated if they were originally too long for the queue.