WMQ Poison Message, Dead Letter Queue and Backout Queue

Dead-letter queues
The dead-letter queue (or undelivered-message queue) is the queue to which messages are sent if they cannot be routed to their correct destination.

Messages are put on this queue when they cannot be put on the destination queue. For example, because the queue does not exist, or because it is full. Dead-letter queues are also used at the sending end of a channel, for data-conversion errors.

Consider defining a dead-letter queue for each queue manager. If you do not, and the MCA is unable to put a message, it is left on the transmission queue and the channel is stopped.

Also, if fast, non-persistent messages (see Fast, nonpersistent messages) cannot be delivered, and no dead-letter queue exists on the target system, these messages are discarded.

However, using dead-letter queues can affect the sequence in which messages are delivered, and so you might choose not to use them.

You can use the USEDLQ channel attribute to determine whether the dead-letter queue is used when messages cannot be delivered. This attribute can be configured so that some functions of the queue manager use the dead-letter queue, while other functions do not. For more information about the use of the USEDLQ channel attribute on different MQSC commands, see DEFINE CHANNEL, DISPLAY CHANNEL, ALTER CHANNEL, and DISPLAY CLUSQMGR.


Use Dead-Letter Queue (USEDLQ)
This attribute determines whether the dead-letter queue (or undelivered message queue) is used when messages cannot be delivered by channels.

Possible values are:
NO
Messages that cannot be delivered by a channel are treated as a failure. The channel either discards these messages, or the channel ends, in accordance with the setting of NPMSPEED.
YES (default)
If the queue manager DEADQ attribute provides the name of a dead-letter queue, then it is used, otherwise the behaviour is as for NO.


Handling poison messages in WebSphere MQ classes for JMS
A poison message is one which cannot be processed by a receiving MDB application. If a poison message is encountered, the JMS MessageConsumer and ConnectionConsumer objects can requeue it according to two queue properties, BOQNAME, and BOTHRESH.

Sometimes, a badly formatted message arrives on a queue, the receiving application cannot process the message correctly. Such a message can cause the receiving application to fail and to back out this badly formatted message. The message can then be repeatedly delivered to the input queue and repeatedly backed out by the application. These messages are known as poison messages. The JMS MessageConsumer object detects poison messages and reroutes them to an alternative destination.

The WebSphere® MQ queue manager keeps a record of the number of times that each message has been backed out. When this number reaches a configurable threshold value, the message consumer requeues the message to a named backout queue. If this requeuing fails for any reason, the message is removed from the input queue and either requeued to the dead-letter queue, or discarded.

The threshold value and the name of the back out queue are attributes of a WebSphere MQ queue. The names of the attributes are BackoutThreshold and BackoutRequeueQName.

To set the BackoutThreshold and BackoutRequeueQName attributes, issue the following MQSC command:
ALTER QLOCAL(your.queue.name) BOTHRESH(threshold value) BOQNAME(your.backout.queue.name)

If the BackoutThreshold attribute is set to a value other than zero, to avoid unexpected behavior set the BackoutRequeueQName attribute to a valid queue name.

For publish/subscribe messaging, if your system creates a dynamic queue for each subscription, these attribute values are obtained from the WebSphere MQ classes for JMS model queue, SYSTEM.JMS.MODEL.QUEUE. To alter these settings, use:
ALTER QMODEL(SYSTEM.JMS.MODEL.QUEUE) BOTHRESH(threshold value) BOQNAME(your.backout.queue.name)

If the backout threshold value is zero, poison message handling is disabled, and poison messages remain on the input queue. Otherwise, when the backout count reaches the threshold value, the message is sent to the named backout queue. If the backout count reaches the threshold value, but the message cannot go to the backout queue, the message is sent to the dead-letter queue or it is discarded. This situation occurs if the backout queue is not defined, or if the MessageConsumer object cannot send the message to the backout queue

IBM WebSphere MQ Series Important Concepts

QueueManager:
QueueManager is responsible for storing and routing messages to other Queue Manager within MQ and it also communicate with outside world e.g. Java program or any other MQ client.

Channel:
Queue Manager use channel to transmit messages to other QueueManager. Channel carries one way traffic in MQ Series (i.e. channels are uni directional). You can have either sending channel or receiving channel in MQ

Dead Letter Queue:
A queue which is used by QueueManager to archive messages for a non existent queue. Also, if a local queue is full, in that case also, messages are routed to Dead Letter Queue.

CCDT file (Client Channel Definition table):
CCDT file is a binary file which contains connection details required by MQ clients e.g. Java application using JMS to connect to MQ Server. In order to connect to MQ Server, MQ clients needs MQ Server host name, MQ Server port name and server channel name. All these details are encapsulated in CCDT file named as AMQCLCHL.TAB. In order to create MQ Connection, MQ clients needs location of this file, which is provided as configuration. most of MQ errors comes either with incorrect CCDT files.

SSLPEER (SSL Peer):
SSLPEER is a String usually DN (Distinguished name) of MQ Client which connect to QueueManager securely using QueueManager. This is a mechanism WMQ uses to identify client. In case of Java or JMS client, SSLPEER is DN of client certificate stored in its keyStore and sent to server during SSL handshake.

Backout Queue:
Dead letter queue is used to store messages which is received for non existent queue. On the other hand backout queue are application specific queue.If MQ client is not able to process message and ask for redelivery, message is redelivered to client with incremented delivery count. Once this deliveryCount crossed a configured threshold, message is moved to back-out queue for later processing or error handling. In short if MQ Series not able to deliver message to client after a preconfigured attempt, WMQ moves message to backout queue.

If the application is unable to move the message to the Back Out Queue (BOQ) for some reason, then an attempt is made to move the queue to the Dead Letter Queue (DLQ).  For example, there are some permission issues on the Back Out Queue, so the message could not be written to the BOQ and it will be moved to Dead letter Queue.

Binding connection and Client Connection:
If MQ clients sits on same physical server where QueueManager is located than it can create binding connection which is relatively faster than client connection, which is usually created by MQ clients residing on same network but not same host. Most of application uses MQ client connection to connect QueueMangaer, which is easy and flexible.

Local Queue and Remote Queue:
local queues are queue on same QueueManager while remote queue refers to queue on different QueueManager.