Dead-letter queue processing

This information contains general-use programming interface information when using dead-letter queue processing.

Dead-letter queue processing depends on local system requirements, but consider the following things when you draw up the specification:

• The message can be identified as having a dead-letter queue header because the value of the format field in the MQMD, is MQFMT_DEAD_LETTER_HEADER.
• On IBM MQ for z/OS using CICS, if an MCA puts this message to the dead-letter queue, the PutApplType field is MQAT_CICS, and the PutApplName field is the ApplId of the CICS system followed by the transaction name of the MCA.
• The reason for the message to be routed to the dead-letter queue is contained in the Reason field of the dead-letter queue header.
• The dead-letter queue header contains details of the destination queue name and queue manager name.
• The dead-letter queue header contains fields that have to be reinstated in the message descriptor before the message is put to the destination queue. These are:
  1. Encoding
  2. CodedCharSetId
  3. Format

• The message descriptor is the same as PUT by the original application, except for the three fields shown (Encoding, CodedCharSetId, and Format).

Your dead-letter queue application must do one or more of the following things:

• Examine the Reason field. A message might have been put by an MCA for the following reasons:
  • The message was longer than the maximum message size for the channel

    The reason is MQRC_MSG_TOO_BIG_FOR_CHANNEL

  • The message could not be put to its destination queue

    The reason is any MQRC_* reason code that can be returned by an MQPUT operation

  • A user exit has requested this action

    The reason code is that supplied by the user exit, or the default MQRC_SUPPRESSED_BY_EXIT

• Try to forward the message to its intended destination, where this is possible.
• Retain the message for a certain length of time before discarding when the reason for the diversion is determined, but not immediately correctable.
• Give instructions to administrators correct problems where these have been determined.
• Discard messages that are corrupted or otherwise not processible.

There are two ways to deal with the messages that we have recovered from the dead-letter queue:

1. If the message is for a local queue:
   • Carry out any code translations required to extract the application data
   • Carry out code conversions on that data if this is a local function
   • Put the resulting message on the local queue with all the detail of the message descriptor restored

2. If the message is for a remote queue, put the message on the queue.

For information about how undelivered messages are handled in a distributed queuing environment, see What happens when a message cannot be delivered?.

Parent topic: Use the dead-letter (undelivered message) queue