WebSphere Message Brokers
File: ac24877_
Writer: John Cooper

Reference topic

This build: July 31, 2007 21:19:45

Troubleshooting JMS nodes

Review possible problems with JMS nodes.

In all cases of error, if the underlying cause is a JMSException that has been thrown by the JMS provider, the broker bip event message includes the text message from the JMSException to help your diagnosis.

Managing badly formed messages

If a message cannot be processed by the JMSInput node, or has been rolled back as part of a global transaction, the message is backed out to the source destination. The message is then redelivered to the JMSInput node.

To prevent badly formed messages from interrupting the processing of valid messages, the node properties can be configured as follows:

Backout Destination This property specifies a JMS destination where backed out messages are routed if the JMS message property JMSX_DeliveryCount, which is set by the JMS provider, exceeds the backout threshold.

The JMS destination must be applicable to the message model being used by the node; for example, if a subscription topic has been configured on the node, the JMS destination must also be a topic.

Backout Threshold This property specifies the integer value that controls a message is sent to the backout destination. A threshold value of 3 means that, if the JMSInput node receives a Message where the value of the JMSX_DeliveryCount property exceeds 3, the message is sent to the backout destination and is removed from the source destination.

Diagnosing problems when using globally coordinated transactions:

In addition to the broker service trace, another trace log is provided to diagnose problems that could occur when a JMSInput or JMSOutput node participates in a global message flow transaction. That is, at least one JMSInput or JMSOutput node in the message flow has the Transaction Mode property set to global and the message flow property Coordinated Transaction set to yes.

To capture the trace log, complete the following steps:
  1. Define an environment variable called XAJMS_TRACEFILE that is available to the broker queue manager.
  2. Set the value of the environment variable. This value must be a character string that represents the location and file name of the trace log. For example, on Windows, the variable could be configured as follows:
    XAJMS_TRACEFILE = c:\JMSSwitchLog
  3. When the broker queue manager starts, it performs a recovery step to resolve any previous broker transactions that the JMS provider considers to be in-doubt. This queue manager process writes to two trace logs during this stage. The two trace logs are:
    • XAJMS_TRACEFILE valuePID.txt, where PID is the process ID of the queue manager start process. This file is produced from the broker’s JMSSwitch library; see JMS Transactionality for more information.

      Using the above example value for the variable produces a file called JMSSwitchLog2596.txt, where the queue manager start up process ID was 2596.

    • XAJMS_TRACEFILEXARecoveryTrace.txt which is produced by the broker’s recovery component that connects to the JMS provider.
  4. After the broker's queue manager has completed recovery, the broker starts and creates a file called XAJMS_TRACEFILE valuePID.txt, where PID is the process ID of the queue manager start process. This file is produced from the broker’s JMSSwitch library, see JMS Transactionality for more information.

Neither of these trace files require extra formatting.

This problem is not applicable on z/OS.

Problems with JNDI Administered Objects

Description of problem: The JMSInput or JMSOutput node is unable to obtain the Initial Context Factory or a JNDI administered object such as the Connection Factory or JMS destination, and a BIP4640 message is issued.

Corrective action
  1. Verify that the JNDI bindings have been correctly built, and can be reached at the location specified in the node.
  2. Check that the values specified in the node for the Initial Context, Connection Factory Name, and Source Queue or Destination Queue exist in the JNDI bindings.
  3. Ensure that the correct keyword is used to match the location of the bindings:
    • file:/ when the administered objects have been created in a .bindings file
    • ldap:/ when the administered objects exist in an LDAP directory
    • iiop:/ when corba is used to access the administered objects
  4. When the bindings are file based do not specify the .bindings filename in the node property.
  5. Ensure that the Initial Context Factory name does not include a filepath.
  6. Ensure that a JMS destination (Topic or Source Queue or Destination Queue) specified in the node property exists in the JNDI administered objects.
  7. Ensure that the JMS Provider Java .jar files have been placed into the broker shared-classes directory on distributed platforms, or on z/OS that these .jar files have been defined to the broker CLASSPATH and any native libraries defined in the broker LIBPATH.
The JMS Nodes continue to attempt to obtain the JNDI administered objects. Correct any problems and rebuild the bindings. The JMS node should automatically detect the changes and attempt to start.

Description of problem: A JMSInput or JMSOutput node is unable to connect for a JMS provider and issues a BIP4648 message.

Corrective action:
  1. Verify that the JMS Provider server is running. If it is offline, start the server.
  2. Verify that the JMS Provider server is available from the broker environment.
  3. Ensure that the JMS Provider Java .jar files have been placed into the broker shared-classes directory on distributed platforms, or that on z/OS, that these .jar files have been defined to the broker CLASSPATH and any native libraries defined in the broker LIBPATH.
The JMS nodes continue to attempt to connect to the JMS provider. Correct any problems and the JMS node should automatically detect the changes and attempt to connect to the provider.

Description of problem: A JMSInput or JMSOutput node is unable to obtain a JMS destination and issues a BIP4642 message.

Corrective action
  1. Investigate the cause of the problem described by the JMS exception message that might be included in the BIP event message.
  2. Check that the name of the JMS destination that is defined in the relevant node property (Topic or Source Queue or Destination Queue) has been correctly defined in the JNDI administered objects.
  3. Verify that the underlying system resource used by the JMS provider for the JMS destination has been configured correctly
Related concepts
JMS Transactionality
Notices | Trademarks | Downloads | Library | Support | Feedback

Copyright IBM Corporation 1999, 2007Copyright IBM Corporation 1999, 2007. All Rights Reserved.
This build: July 31, 2007 21:19:45

ac24877_ This topic's URL is: