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 you 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?.