The dead-letter queue handler on IBM i

What is the IBM i dead-letter queue handler, and how do you invoke it?

A dead-letter queue (DLQ), sometimes referred to as an undelivered-message queue, is a holding queue for messages that cannot be delivered to their destination queues. Every queue manager in a network should have an associated DLQ. Note: It is often preferable to avoid placing messages on a DLQ. For information about the use and avoidance of DLQs, see Work with dead-letter queues.

Queue managers, message channel agents, and applications can put messages on the DLQ. All messages on the DLQ must be prefixed with a dead-letter header structure, MQDLH. Messages put on the DLQ by a queue manager or by a message channel agent always have an MQDLH. Always supply an MQDLH to applications putting messages on the DLQ. The Reason field of the MQDLH structure contains a reason code that identifies why the message is on the DLQ.

In all IBM MQ environments, there must be a routine that runs regularly to process messages on the DLQ. IBM MQ supplies a default routine, called the dead-letter queue handler (the DLQ handler), which you invoke using the STRMQMDLQ command. A user-written rules table supplies instructions to the DLQ handler, for processing messages on the DLQ. That is, the DLQ handler matches messages on the DLQ against entries in the rules table. When a DLQ message matches an entry in the rules table, the DLQ handler performs the action associated with that entry.


Invoking the DLQ handler

Use the STRMQMDLQ command to invoke the DLQ handler. You can name the DLQ that we want to process and the queue manager that we want to use in two ways:

  • As parameters to STRMQMDLQ from the command prompt. For example: 
    STRMQMDLQ UDLMSGQ(ABC1.DEAD.LETTER.QUEUE) SRCMBR(QRULE) SRCFILE(library/QTXTSRC)
MQMNAME(MY.QUEUE.MANAGER)
  • In the rules table. For example: 
    INPUTQ(ABC1.DEAD.LETTER.QUEUE)

Note: The rules table is a member within a source physical file that can take any name.

The examples apply to the DLQ called ABC1.DEAD.LETTER.QUEUE, owned by the default queue manager.

If we do not specify the DLQ or the queue manager as shown, the default queue manager for the installation is used along with the DLQ belonging to that queue manager.

The STRMQMDLQ command takes its input from the rules table.

We must be authorized to access both the DLQ itself, and any message queues to which messages on the DLQ are forwarded, in order to run the DLQ handler. We must also be authorized to assume the identity of other users, for the DLQ to put messages on queues with the authority of the user ID in the message context.

Parent topic: Processing messages on an IBM MQ dead-letter queue


Related information