WebSphere Message Service Client for C/C++, Version 2.0.2 Operating Systems: AIX, Linux, Solaris, Windows

Poison messages

A poison message is one which cannot be processed by a receiving MDB application. If a poison message is encountered, the XMS MessageConsumer object can requeue it according to two queue properties, BOQUEUE, and BOTHRESH.

In some circumstances, a message delivered to an MDB might be rolled back onto a WebSphere MQ queue. This can happen, for example, if a message is delivered within a unit of work that is subsequently rolled back. A message that is rolled back is generally delivered again, but a badly formatted message might repeatedly cause an MDB to fail and therefore cannot be delivered. Such a message is called a poison message. You can configure WebSphere MQ so that the poison message is automatically transferred to another queue for further investigation or is discarded. For information about how to configure WebSphere MQ in this way, see Handling poison messages in ASF.

Sometimes, a badly-formatted message arrives on a queue. In this context, badly-formatted means that 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 XMS 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 re-queuing fails for any reason, the message is removed from the input queue and either requeued to the dead-letter queue, or discarded.

XMS ConnectionConsumer objects handle poison messages in the same way and using the same queue properties. If multiple connection consumers are monitoring the same queue, it is possible that the poison message may be delivered to an application more times than the threshold value before the requeue occurs. This behavior is due to the way individual connection consumers monitor queues and requeue poison messages.

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. The queue they apply to is as follows:
To set the BackoutThreshold and BackoutRequeueQName attributes, issue the following MQSC command:
ALTER QLOCAL(your.queue.name) BOTHRESH(threshold value) 
BOQUEUE(your.backout.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) 
BOQUEUE(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.


Concept topic

Terms of Use | Rate this page

Last updated: 24 May 2011

(C) Copyright IBM Corporation 2005, 2011. All Rights Reserved.