IBM Support

Collecting a WebSphere MQ classes for JMS trace of the JMS API calls made by an application

Technote (FAQ)


Question

You have written an application that uses the WebSphere MQ classes for JMS to communicate with a WebSphere MQ queue manager. The application is not behaving as you expect it to. Are there any diagnostics that you can collect from the WebSphere MQ classes for JMS that show what JMS API calls your application is making?

Answer

The WebSphere MQ classes for JMS provide a diagnostic trace facility that can be used to diagnose problems. The level of detail that will be written to the trace is controlled by the WebSphere MQ classes for JMS configuration file.

It is possible to configure the WebSphere MQ classes for JMS trace facility to just generate trace information about the JMS API calls made by an application. This is useful for application developers who want to see the code path taken by their JMS applications.

To enable a JMS API trace, complete the following steps:

  • Create a new WebSphere MQ classes for JMS configuration file.
  • Set the following properties in the WebSphere MQ classes for JMS configuration file:
    • com.ibm.msg.client.commonservices.trace.status=ON
    • com.ibm.msg.client.commonservices.trace.outputName=[the name of the trace file. This can either be a full or relative path]
    • com.ibm.msg.client.commonservices.trace.level=8
    • com.ibm.msg.client.commonservices.trace.include=com.ibm.mq.jms
    • com.ibm.msg.client.commonservices.trace.exclude=ALL
    • com.ibm.msg.client.commonservices.trace.searchString=.*PropertyContext.*|.*PropertyValidator.*|.*validate.*|.*Canonical.*|.*JmqiDC.*|.*MQRoot.*|.*<init>.*
  • Save the modified WebSphere MQ classes for JMS configuration file.
  • Run the WebSphere MQ classes for JMS application, using the following command:

      java -Dcom.ibm.msg.client.config.location= config_file_url application_name

    where config_file_url is a URI that points to the WebSphere MQ classes for JMS configuration file, and application_name is the name of the WebSphere MQ classes for JMS application to be traced.

To identify the JMS API calls made by an application, look for the entries in the trace file that contain either a { or a } character in the fifth column.

Trace statements that have a { character in the fifth column are an entry trace statement, and are generated when an application calls the method shown in the trace statement.

Trace statements which have the } character in the fifth column are an exit trace point. These trace points are written when the JMS API call mentioned in the trace exits and returns control back to the application.

Trace statements where the { or } characters in the fifth column are prefixed by one or more hyphen characters (-) indicate that the WebSphere MQ classes for JMS have called some internal methods on behalf of the application. These trace points can be ignored.


Entry trace statements show the parameters that are passed into the JMS API call. Exit trace statements show the values returned by the WebSphere MQ classes for JMS to the application.

Here is an example of the output that is generated by a WebSphere MQ classes for JMS application when a JMS API trace has been enabled:

@77807780  c.i.mq.jms.MQQueueConnection(MQConnection)            {  start()
@77807780  c.i.mq.jms.MQQueueConnection(MQConnection)            }  start()
@77807780  c.i.mq.jms.MQQueueConnection                          {  
               createQueueSession(boolean,int)
               [false] [1]
@77807780 c.i.mq.jms.MQQueueConnection                           }
               createQueueSession(boolean,int) returns      
               [c.i.mq.jms.MQQueueSession@2f212f21]
@49f449f4  c.i.mq.jms.MQQueueSession                             {  
               createReceiver(Queue)
               [queue:///testQueue?targetClient=1]
@3b6c3b6c  c.i.mq.jms.MQQueue(JmsDestinationImpl)                -  {
               getName()
@3b6c3b6c  c.i.mq.jms.MQQueue(JmsDestinationImpl)                -  }  
               getName()<exitIndex 1> returns
               [testQueue] String
@3b6c3b6c  c.i.mq.jms.MQQueue(JmsDestinationImpl)                -  {  
               setProviderDestination()
@3b6c3b6c  c.i.mq.jms.MQQueue(JmsDestinationImpl)                --  {  
               setProviderDestination(String)
               <null>
@3b6c3b6c  c.i.mq.jms.MQQueue(JmsDestinationImpl)                --  }  
               setProviderDestination(String)
@3b6c3b6c  c.i.mq.jms.MQQueue(JmsDestinationImpl)                -  }  
               setProviderDestination()
@3b6c3b6c  c.i.mq.jms.MQQueue(JmsDestinationImpl)                -  {
               incrementUseCount()
@3b6c3b6c  c.i.mq.jms.MQQueue(JmsDestinationImpl)                -  }  
               incrementUseCount()
@49f449f4  c.i.mq.jms.MQQueueSession                             }
               createReceiver(Queue) returns
               [c.i.mq.jms.MQQueueReceiver@27d027d0]
@689b689b  c.i.mq.jms.MQQueueReceiver(MQMessageConsumer)         {  
               receive(long)
               [2000]
static  c.i.mq.jms.MessageProxy                                  -  {  
               wrapMessage(Message)
               <null>
static  c.i.mq.jms.MessageProxy                                  -  }  
               wrapMessage(Message)
@689b689b  c.i.mq.jms.MQQueueReceiver(MQMessageConsumer)         }
               receive(long)
               [
  ProviderMessage class: jms_text
  JMSType:         null
  JMSDeliveryMode: 1
  JMSExpiration:   0
  JMSPriority:     0
  JMSMessageID:    ID:414d51207061756c74202020202020203e15e6522003b502
  JMSTimestamp:    1390938232900
  JMSCorrelationID:null
  JMSDestination:  null
  JMSReplyTo:      null
  JMSRedelivered:  false
    JMSXAppID: Sphere MQ\bin\MQExplorer.exe
    JMSXDeliveryCount: 1
    JMSXUserID: myuser      
    JMS_IBM_Character_Set: UTF-8
    JMS_IBM_Encoding: 546
    JMS_IBM_Format: MQSTR  
    JMS_IBM_MsgType: 8
    JMS_IBM_PutApplType: 11
    JMS_IBM_PutDate: 20140128
    JMS_IBM_PutTime: 19435290
               ]
In this example, a WebSphere MQ classes for JMS application has made the following JMS API calls:
  • MQQueueConnection.start();
  • MQQueueConnection.createSession(false, 1);
  • MQQueueSession.createReceiver(queue://testQueue);
  • MQQueueReceiver.receive(2000);

The call to MQQueueReceiver.receive(2000) returned a JMS Text Message with the message identifier
414d51207061756c74202020202020203e15e6522003b502.

Document information

More support for: WebSphere MQ
Java

Software version: 7.0, 7.0.1, 7.1

Operating system(s): AIX, HP-UX, IBM i, Linux, Solaris, Windows, z/OS

Reference #: 1663158

Modified date: 26 February 2014