Poison messages in XMS
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 an IBM 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. We can configure IBM MQ so that the poison message is automatically transferred to another queue for further investigation or is discarded. For information about how to configure IBM 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 IBM MQ queue manager keeps a record of the number of times that each message has 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.
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 IBM MQ queue. The names of the attributes are BackoutThreshold and BackoutRequeueQName. The queue they apply to is as follows:- For point-to-point messaging, this is the underlying local queue. This is important when message consumers and connection consumers use queue aliases.
- For publish/subscribe messaging in IBM MQ messaging provider normal mode, it is the model queue from which the Topic's managed queue is created.
- For publish/subscribe messaging in IBM MQ messaging provider migration mode, it is the CCSUB queue defined on the TopicConnectionFactory object, or the CCDSUB queue defined on the Topic object.
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, if the message is nonpersistent, 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.
Configure your system to perform poison message handling
The queue that XMS .NET uses when inquiring the BOTHRESH and BOQNAME attributes depends on the style of messaging being performed:- For point-to-point messaging, this is the underlying local queue. This is important when an XMS .NET application is consuming messages from either alias queues or cluster queues.
- For publish/subscribe messaging, a managed queue is created to hold the messages for an
application. XMS .NET queries the managed
queue to determine the values for the BOTHRESH and BOQNAME
attributes. The managed queue is created from a model queue associated with the Topic object that
the application has subscribed to, and inherits the values of the BOTHRESH and
BOQNAME attributes from the model queue. The model queue that is used depends
on whether the receiving application has taken out a durable or non-durable subscription:
- The model queue used for durable subscriptions is specified by the MDURMDL attribute of the Topic. The default value of this attribute is SYSTEM.DURABLE.MODEL.QUEUE.
- For non-durable subscriptions, the model queue that is used is specified by the MNDURMDL attribute. The default value of the MNDURMDL attribute is SYSTEM.NDURABLE.MODEL.QUEUE.
- Opens the local queue, or the target queue for an alias queue.
- Inquires the BOTHRESH and BOQNAME attributes.
- Closes the local queue, or the target queue for an alias queue.
- For Version 9.0.0, Fix Pack 8, and earlier, if the local queue, or
the target queue for an alias queue, is a cluster queue, then XMS .NET opens the queue with the
MQOO_INPUT_AS_Q_DEF, MQOO_INQUIRE and
MQOO_FAIL_IF_QUIESCING options. This means that the user running the receiving
application must have inquire and get access to the local instance of the cluster queue.
XMS .NET opens all other types of local queue with the open options MQOO_INQUIRE and MQOO_FAIL_IF_QUIESCING. In order for XMS .NET to query the values of the attributes, the user running the receiving application must have inquire access on the local queue.
When using XMS .NET
from Version 9.0.0, Fix Pack 9, the user running the receiving
application must have inquire access on the local queue, regardless of the type of the queue.
To move poison messages to either a backout requeue queue or the queue manager's dead letter queue, you must grant the user running the application put and passall authorities.