Overview

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

Character set and encoding: The fields in the MQDLH structure are in the character set and encoding given by the MDCSI and MDENC fields in the header structure that precedes MQDLH, or by those fields 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.

Usage: Applications that put messages directly on the dead-letter queue should 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 should consider doing 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, this should be done 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 above is appropriate (if any) depends on the design of the application.

The queue manager performs special processing when a message which 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 should be identical to the MQMD associated with the message (usually the MQMD returned by the MQGET call), with the exception of the following:

• The MDCSI and MDENC fields must be set to whatever character set and encoding are used for fields in the MQDLH structure.

• The MDFMT field must be set to FMDLH to indicate that the data begins with a MQDLH structure.

• The context fields (MDACC, MDAID, MDAOD, MDPAN, MDPAT, MDPD, MDPT, MDUID) should be set 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 should use the PMDEFC 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 message it has just received should use the PMPASA option, in order to preserve the original context information.

  • A server application putting on the dead-letter queue a reply to a message it has just received should use the PMPASI 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 message it received from its communication channel should use the PMSETA option, to preserve the original context information.

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

• The DLCSI, DLENC and DLFMT fields should be set to the values that describe the data that follows the MQDLH structure, usually the values from the original message descriptor.

• The context fields DLPAT, DLPAN, DLPD, and DLPT should be set 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.

• Other fields should be set as appropriate.

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

Getting messages from the dead-letter queue: Applications that get messages from the dead-letter queue should verify that the messages begin with an MQDLH structure. The application can determine whether an MQDLH structure is present by examining the MDFMT field in the message descriptor MQMD; if the field has the value FMDLH, the message data begins with an MQDLH structure. Applications that get messages from the dead-letter queue should also be aware that such messages may have been truncated if they were originally too long for the queue.