DeadLetterQName (48-byte character string) on IBM i

Name of dead-letter (undelivered-message) queue.

This is the name of a queue defined on the local queue manager. Messages are sent to this queue if they cannot be routed to their correct destination.

For example, messages are put on this queue when:

  • A message arrives at a queue manager, destined for a queue that is not yet defined on that queue manager
  • A message arrives at a queue manager, but the queue for which it is destined cannot receive it because, possibly:

    • The queue is full
    • Put requests are inhibited
    • The sending node does not have authority to put messages on the queue

Applications can also put messages on the dead-letter queue.

Report messages are treated in the same way as ordinary messages; if the report message cannot be delivered to its destination queue (typically the queue specified by the MDRQ field in the message descriptor of the original message), the report message is placed on the dead-letter (undelivered-message) queue.

Note: Messages that have passed their expiry time (see the MDEXP field described in MQMD (Message descriptor) on IBM i ) are not transferred to this queue when they are discarded. However, an expiration report message (ROEXP) is still generated and sent to the MDRQ queue, if requested by the sending application.

Messages are not put on the dead-letter (undelivered-message) queue when the application that issued the put request has been notified synchronously of the problem with the reason code returned by the MQPUT or MQPUT1 call (for example, a message put on a local queue for which put requests are inhibited).

Messages on the dead-letter (undelivered-message) queue sometimes have their application message data prefixed with an MQDLH structure. This structure contains extra information that indicates why the message was placed on the dead-letter (undelivered-message) queue. See MQDLH (Dead-letter header) on IBM i for more details of this structure.

This queue must be a local queue, with a Usage attribute of USNORM.

If a dead-letter (undelivered-message) queue is not supported by a queue manager, or one has not been defined, the name is all blanks. All IBM MQ queue managers support a dead-letter (undelivered-message) queue, but by default it is not defined.

If the dead-letter (undelivered-message) queue is not defined, or it is full, or unusable for some other reason, a message which would have been transferred to it by a message channel agent is retained instead on the transmission queue.

To determine the value of this attribute, use the CADLQ selector with the MQINQ call. The length of this attribute is given by LNQN.

Parent topic: Attributes for the queue manager on IBM i