Collecting an IBM MQ classes for JMS trace by using the IBM MQ classes for JMS configuration file

If an application must run for a long period of time before an issue occurs, IBM® MQ classes for JMS trace should be collected by using the IBM MQ classes for JMS configuration file. The configuration file allows you to specify various options to control the amount of trace data that is collected.

1. Create an IBM MQ classes for JMS configuration file.
   For more information about this file, see The IBM MQ classes for JMS configuration file.
2. Edit the IBM MQ classes for JMS configuration file so that the property com.ibm.msg.client.commonservices.trace.status is set to the value ON.
3. Optional: Edit the other properties that are listed in the IBM MQ classes for JMS configuration file Java Standard Edition Trace Settings.
4. Run the IBM MQ classes for JMS application by using the following command:

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

   where config_file_url is a uniform resource locator (URL) that specifies the name and location of the IBM MQ classes for JMS configuration file. URLs of the following types are supported: http, file, ftp, and jar.

   Here is an example of a Java command:

   java -Dcom.ibm.msg.client.config.location=file:/D:/mydir/myjms.config 
   MyAppClass

   This command identifies the IBM MQ classes for JMS configuration file as the file D:\mydir\myjms.config on the local Windows system.
   By default, trace information is written to a trace file in the current working directory of the application. The name of the trace file depends upon the environment that the application is running in:

   • For IBM MQ classes for JMS for IBM MQ 9.0.0 Fix Pack 1 or earlier, trace is written to a file called mqjms_%PID%.trc.
   • From IBM MQ 9.0.0 Fix Pack 2, if the application has loaded the IBM MQ classes for JMS from the JAR file com.ibm.mqjms.jar, trace is written to a file called mqjava_%PID%.trc.
   • From IBM MQ 9.0.0 Fix Pack 2, if the application has loaded the IBM MQ classes for JMS from the relocatable JAR file com.ibm.mq.allclient.jar, trace is written to a file called mqjavaclient_%PID%.trc.
   • From IBM MQ 9.0.0 Fix Pack 10, if the application has loaded the IBM MQ classes for JMS from the JAR file com.ibm.mqjms.jar, trace is written to a file called mqjava_%PID%.cl%u.trc.
   • From IBM MQ 9.0.0 Fix Pack 10, if the application has loaded the IBM MQ classes for JMS from the relocatable JAR file com.ibm.mq.allclient.jar, trace is written to a file called mqjavaclient_%PID%.cl%u.trc.

   where %PID% is the process identifier of the application that is being traced, and %u is a unique number to differentiate files between threads running trace under different Java classloaders.

   To change the name of the trace file, and the location where it is written, ensure that the IBM MQ classes for JMS configuration file that the application uses contains an entry for the property com.ibm.msg.client.commonservices.trace.outputName. The value for the property can be either of the following:

   • The name of the trace file that is created in the application's working directory.
   • The fully qualified name of the trace file, including the directory in which the file is created.

   For example, to configure the IBM MQ classes for JMS to write trace information for an application to a file called C:\Trace\trace.trc, the IBM MQ classes for JMS configuration file that the application uses needs to contain the following entry:

   com.ibm.msg.client.commonservices.trace.outputName=C:\Trace\trace.trc