Handling Poison Messages With WebSphere MQ

Not all messages which are placed on a queue are guaranteed to be processed.

Something might go wrong while messages are picked up from the queue by listener

programs. For example, consider a scenario when a badly formatted message is

dropped on a queue; the application program may not be able to process such a

message. The program which de-queues the message backs out the message receipt

and places the message back on the queue. Such messages are called poison

messages. As the name suggests, a poison message indicates some payload

malformation. Furthermore, poison messages may cause deadlocks and badly impact

the application performance. If a poison message is not removed from the queue,

the receiving application can get stuck in an infinite loop. WebSpehere MQ

provides nifty techniques to handle such poison messages. MQ can re-queue the

poison messages on a separate queue (called backout queue) which can be later

debugged and cleared. In this article, we'll demonstrate the configuration

modifications required for WebSpehere MQ to deal with poison messages and walk

through with an application code which shall demonstrate message backout and

redelivery.

Configuring MQ backout queue



As discussed, a backout queue is a special type of local queue object which is
intended to store poison messages. To begin with, we'll create a local queue

named inbound.alerts and a backout queue called failed.payload. The MQ Script

Commands (MQSC) required to create the local and backout queue are depicted in

figure.

Notice carefully that the runmqsc script command is executed without

specifying any queue manager name. WebSphere MQ will choose the default queue

manager object- PCQuest. All MQ script commands are then run against the PCQuest

queue manager object. We begin by defining two local queues- inbound.alerts and

failed.payload. The ALTER QLOCAL script command is then issued to alter

properties of the inbound.alerts queue to designate failed.payload as a backout

queue.

After running the above mentioned MQ script commands, we'll have the two

local queue objects defined and configured. The WebSphere MQ explorer view ID is

shown in the figure.

As an administrator, you can configure MQSC commands for creating the backout queue.

Notice that MQ doesn't use any special icon for the backout queue. It's just

like any ordinary local queue object. To validate the MQSC commands you can also

review the properties of the inbound.alerts queue object, as shown in the figure

Backing out poison messages



For the sake of demonstration, we'll present a code snippet to describe the
backout operation and then move the poison message (assuming that the backout

counter has reached the threshold value) to the backout queue object.

After running the MQ script commands, we'll have the local queue objects defined and configured.

while (true) {



myMessage.clearMessage();


myMessage.correlationId = MQC.MQCI_NONE;


myMessage.messageId = MQC.MQMI_NONE;


myQueue.get(myMessage, gmo);


//check for the threshold counter


if (myMessage.backoutCount <= boThresh) {


System.out.println("BackoutCount: "


+ myMessage.backoutCount + " of " + boThresh); /*


* increase backout count by one and put the message back on the queue */


qMgr.backout();


} else {


System.out.println ("Message is poison, moving to "+ backoutQueueName);


int openPutOptions = MQC.MQOO_


OUTPUT+ MQC.MQOO_FAIL_ IF_QUIESCING


+ MQC.MQOO_PASS _ALL_CONTEXT;


MQQueue myPutQueue = qMgr.accessQueue (backoutQueueName, openPutOptions, null,
null, null);



MQPutMessageOptions pmo = new MQPutMessageOptions();


pmo.options = pmo.options | MQC.MQPMO_SYNCPOINT | MQC.MQPMO _PASS_ALL_CONTEXT;


pmo.contextReference = myQueue;


myPutQueue.put(myMessage, pmo);


/* * close the current transaction and release message(s) held by the syncpoint
control */



qMgr.commit();


myPutQueue.close();


break; }}

The program opens the alerts.inbound queue to inquire the backout queue name

and the threshold value. The message retrieval operation is wrapped in a

transaction. This is done to avoid reading the messages in destructive mode. The

program gets the first message on the queue and then backs it out until the

backout threshold is reached. The program output is shown in the figure.

These are the Local queue properties. Note that the default threshold value is 5.

Conclusion



If poison messages stay on top of queue, other messages will never get a chance
to be de-queued by listener programs. As a matter of practice, if message

processing fails, it's always a good idea to retry, but not indefinitely. If

messages still fail, messages should be moved out to another queue to be

debugged later by an admin. A backout queue offers an excellent buffer for

storing such poison messages to let the application run at a normal pace.

WebSphere MQ keeps track of number of times a message has been backed out. Once

this configurable threshold value is reached, they can be moved to a backout

queue. Note that MQ will not automatically move poison messages; it's the

responsibility of the application program to move them to a backout queue.

The Eclipse view of the output of sample app. The program gets the first message on the queue and then backs it out until the backout threshold is reached.