Dead-letter queue processing

 

The rest of this chapter contains general-use programming interface information.

Dead-letter queue processing depends on local system requirements, but consider the following 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 WebSphere 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 above.

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

• 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 (or MQRC_MSG_TOO_BIG_FOR_Q_MGR if you are using CICS for distributed queuing on WebSphere MQ for z/OS)

  • 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 on how undelivered messages are handled in a distributed queuing environment, see WebSphere MQ Intercommunications.

 

Parent topic:

Using the dead-letter (undelivered message) queue

fg11360_