Troubleshooting JMS nodes

Review possible problems with nodes using JMS transport.

Use Activity log as the first step in diagnosing a problem when something unexpected happens in a JMS message flow. Activity log shows recent activities in your message flows and associated external resources, and can show you at a high level any problems with your JMS resources. You can also view the event log for information about errors that occur.

The following errors might occur:

In all cases of error, if the underlying cause is a JMS exception that has been thrown by the JMS provider, the integration node BIP event message includes the text message from the JMS exception to help diagnosis.

Managing badly formed messages

If a message cannot be processed by the JMS input node, or has been rolled back as part of an XA coordinated transaction, the message is backed out to the source destination. The message is then delivered again to the input node.

To prevent badly formed messages from interrupting the processing of valid messages, the node properties can be configured as described in the following table.

Property	Description
Backout destination	This property specifies a JMS destination to which 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 that is sent to the backout destination. A threshold value of `3` indicates that if the input 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. See JMSInput node.

Diagnosing problems when using XA coordinated transactions

This problem is not applicable to z/OS®.

In addition to the integration node service trace, another trace log is provided to diagnose problems that could occur when a node using JMS transport participates in an XA coordinated message flow transaction. That is, at least one JMS node in the message flow has the Transaction Mode property set to Yes, and the message flow property Coordinated Transaction set to yes.

To capture the trace log, complete the following steps:

Define an environment variable called XAJMS_TRACEFILE that is available to the integration node queue manager.
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 can be configured as shown in the following example:
```
XAJMS_TRACEFILE = c:\JMSSwitchLog
```
When the integration node queue manager starts, it performs a recovery step to resolve any previous integration node 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 integration node JMSSwitch library; for more information, see JMS Transactionality.
  The previous example produces a file called JMSSwitchLog2596.txt, where the queue manager start up process ID is 2596.
- XAJMS_TRACEFILEXARecoveryTrace.txt, which is produced by the recovery component of the integration node that connects to the JMS provider.
After the integration node queue manager has completed recovery, the integration node 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 integration node JMSSwitch library; for more information, see JMS Transactionality.

Neither of these trace files require extra formatting.

Problems with JNDI Administered Objects

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

Corrective action

Verify that the JNDI bindings have been built correctly, and can be reached at the location specified in the node.
Check that the values specified in the node for the Connection Factory Name and Source Queue or Destination Queue properties exist in the JNDI bindings.
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
When the bindings are file based, do not specify the .bindings file name in the node property.
Ensure that the Initial Context Factory Class name is set correctly, as specified in the documentation for the JMS provider.
Ensure that the Initial Context Factory Class name does not include a file path.
Ensure that a JMS destination (Topic or Source Queue or Destination Queue) specified in the node property exists in the JNDI administered objects.
Ensure that the JMS Provider jarsURL property has been set correctly by using the mqsichangeproperties command. To verify the value, use the following command:
```
mqsireportproperties INODE -c JMSProviders -o JMSProvider -r
```

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.

If the problem is resolved by rebuilding the bindings, the JMS node detects the changes automatically and attempts to start.
If the problem is resolved by updating the node properties, you must redeploy the flow before it can connect successfully.

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

Corrective action:

Verify that the JMS provider server is running. If it is offline, start the server.
Verify that the JMS provider server is available from the integration node environment.
Ensure that the JMS provider Java™ .jar files have been placed into the integration node shared-classes directory on distributed systems, or that on z/OS, that these .jar files have been defined to the integration node CLASSPATH and any native libraries defined in the integration node 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 JMS node is unable to obtain a JMS destination and issues message BIP4642.

Corrective action

Investigate the cause of the problem described by the JMS exception message that might be included in the BIP event message.
Check that the name of the JMS destination that is defined in the relevant node property (Topic, Source Queue or Destination Queue) has been defined correctly in the JNDI administered objects.
Verify that the underlying system resource that is used by the JMS provider for the JMS destination has been configured correctly

Description of problem: A JMS input node does not attempt to reconnect to a JMS provider following a connection failure, or a restart of the JMS provider.

Corrective action: If the JMS provider is implemented by using a model that pushes on the JMS client, rather than a traditional polling model, the JMS provider might not throw an exception when calling receive() on an integration node connection. To resolve this problem, set the Handle connection exceptions asynchronously property of the JMS Providers policy to True for this JMS provider.