JMSException and MQ Reason Codes

J2EE (JMS) programmers who are new to IBM MQ (formally WebSphere MQ, MQSeries) sometimes are confused as to why they are getting a particular JMS exception. The problem with the JMS / MQ layer is that the useful MQ information is hidden in the JMSException. By useful MQ information, I mean the MQ Completion Code (CC) and Reason Code (RC). In particular, it is the MQ Reason Code that provides the key to why the code is having the issue.

Generally, J2EE programmers will catch the JMS exception via the JMSException clause and dump out the exception message. A typical JMSException clause:

catch (JMSException e)
{
   System.err.println(e.getLocalizedMessage());
}

The J2EE programmer may see one of the following JMS exception messages in their program’s output / log file:

javax.jms.JMSException: MQJMS1000: Failed to create JMS message
javax.jms.JMSException: MQJMS1016: an internal error has occurred.
javax.jms.JMSException: MQJMS1017: non-local MQ queue not valid for receiving or browsing
javax.jms.JMSException: MQJMS1079: Unable to write message to dead letter queue
javax.jms.JMSException: MQJMS1107: connection problem
javax.jms.JMSException: MQJMS1068: failed to obtain XAResource
javax.jms.JMSException: MQJMS2002: failed to get message from MQ queue
javax.jms.JMSException: MQJMS2005: failed to create MQQueueManager
javax.jms.JMSException: MQJMS2007: failed to send message to MQ queue
javax.jms.JMSException: MQJMS2008: failed to open MQ queue
javax.jms.JMSException: MQJMS2009: MQQueueManager.commit() failed
javax.jms.JMSException: MQJMS2014: Queue manager rejected XA client connection
javax.jms.JMSException: MQJMS3011: Failed to publish message to MQ queue
javax.jms.JMSSecurityException: MQJMS2013: invalid security authentication supplied for MQQueueManager

The problem is that there is no MQ related information in those JMS exception messages. So, the $100,000 question is: ‘How can the J2EE programmer retrieve MQ related information’?

Simple: You need to dump out the LinkedException for the JMS exception:

catch (JMSException e)
{
   System.err.println("getLinkedException()=" + e.getLinkedException());
   System.err.println(e.getLocalizedMessage());
}

The getLinkedException method will give you the MQ reason code which will help you determine what is the real issue. Using the above snippet of code, the output may look like:

getLinkedException()=com.ibm.mq.MQException: MQJE001: Completion Code 2, Reason 2035.
javax.jms.JMSException: MQJMS2007: failed to send message to MQ queue.

Now the user can look up what the reason code means. If you have WMQ Server or WMQ Client installed then you can execute the mqrc command and pass it the reason code. Open a Command prompt or Unix shell and type the following:

mqrc 2035

And the command will output:

      2035  0x000007f3  MQRC_NOT_AUTHORIZED

For more information, you can look up the MQ Reason Code in the IBM MQ Knowledge Center.

I strongly recommend that all JMSException clauses related to MQ use the getLinkedException method and dump out the MQ information (as noted in Amendent # 2 in my blog posting of Ten Commandments of IBM MQ)

Regards,
Roger Lacroix
Capitalware Inc.