IBM Support

IV91716: Issues with IBM MQ Classes for Java trace

Subscribe

You can track all active APARs for this component.

 

APAR status

  • Closed as program error.

Error description

  • There are a number of issues with WebSphere MQ classes for Java
    trace:
    
    Issue 1:
    ----------------------------------------------------------------
    The WebSphere MQ V7.1 classes for Java use the WebSphere MQ
    common services trace facility.  The topic:
    
    Tracing WebSphere MQ classes for Java programs
    
    in the WebSphere MQ V7.1 section of IBM Knowledge Center that
    describes how to use this trace facility can be found at the
    following URI:
    
    https://www.ibm.com/support/knowledgecenter/SSFKSJ_7.1.0/com.ibm
    .mq.doc/ja11410_.htm
    
    This topic is confusing, and does not provide enough detail for
    users to turn on trace.
    
    Issue 2:
    ----------------------------------------------------------------
    In WebSphere MQ V7.5 and later, the classes for Java have been
    changed to use the WebSphere MQ messaging client trace mechanism
    rather than the WebSphere MQ Common Services trace facility.
    However, the:
    
    Tracing WebSphere MQ classes for Java programs
    
    topic in the WebSphere MQ V7.5 section of IBM Knowledge Center,
    which can be found at the following URI:
    
    https://www.ibm.com/support/knowledgecenter/SSFKSJ_7.5.0/com.ibm
    .mq.dev.doc/q031310_.htm
    
    has not been updated to indicate how to configure and use this
    trace mechanism. The topic still informs customers that they
    need to use a WebSphere MQ common services trace file, and the
    methods:
    
    - MQEnvironment.enableTracing(int)
    - MQEnvironment.disableTracing()
    
    to control trace, which is incorrect.
    
    Issue 3:
    ----------------------------------------------------------------
    The WebSphere MQ V7.5 classes for Java, and IBM MQ V8.0 and V9.0
    classes for Java, write trace to a file called mqjms_%PID%.trc.
    The filename is confusing, as it implies that the application
    being traced is using the IBM MQ classes for JMS, and not the
    IBM MQ classes for Java.
    
    Issue 4:
    ----------------------------------------------------------------
    The topic:
    
    The IBM MQ classes for Java configuration file
    
    in the MQ V8.0 and V9.0 sections of IBM Knowledge Center
    indicate that a sample configuration file called:
    
    mqjava.config
    
    is installed with the product, and can be used to control MQ
    classes for Java trace. However, this file is not actually
    shipped.
    

Local fix

Problem summary

  • ****************************************************************
    USERS AFFECTED:
    This issue affects users of:
    
    - The WebSphere MQ V7.1 classes for Java.
    
    - The WebSphere MQ V7.5 classes for Java.
    - The WebSphere MQ V7.5 classes for Java OSGi bundle
          com.ibm.mq.osgi.java_<version number>.jar
    
    - The IBM MQ V8.0 classes for Java.
    - The IBM MQ V8.0 classes for Java OSGi bundle
          com.ibm.mq.osgi.java_<version number>.jar
    - The IBM MQ V8.0 relocatable JAR file
          com.ibm.mq.allclient.jar.
    - The IBM MQ V8.0 OSGi bundle
          com.ibm.mq.osgi.allclient.java_<version number>.jar
    
    
    - The IBM MQ V9.0 classes for Java.
    - The IBM MQ V9.0 classes for Java OSGi bundle
          com.ibm.mq.osgi.java_<version number>.jar
    - The IBM MQ V9.0 relocatable JAR file
          com.ibm.mq.allclient.jar.
    - The IBM MQ V9.0 OSGi bundle
          com.ibm.mq.osgi.allclient.java_<version number>.jar
    
    who are asked by the IBM Support Organization to collect a
    trace.
    
    
    Platforms affected:
    MultiPlatform
    
    ****************************************************************
    PROBLEM DESCRIPTION:
    This APAR addresses a number of issues with MQ classes for Java
    trace:
    
    Issue 1:
    ----------------------------------------------------------------
    The topic called "Tracing WebSphere MQ classes for Java
    programs" in the WebSphere MQ V7.1 section of IBM Knowledge
    Center described how to configure the WebSphere MQ classes for
    Java to use the WebSphere MQ Common Services trace facility in
    order to collect a trace. The instructions were not very clear,
    and IBM Support had to regularly help customers collect the
    trace.
    
    Issue 2:
    ----------------------------------------------------------------
    The WebSphere MQ V7.5 classes for Java were changed to use the
    WebSphere MQ messaging client trace mechanism rather than the
    WebSphere MQ Common Services trace facility. However, the
    "Tracing WebSphere MQ classes for Java programs" topic in the
    WebSphere MQ V7.5 section of IBM Knowledge Center was not
    updated to document how to configure and use the WebSphere MQ
    messaging client trace mechanism. The topic still informed users
    that they had to use the WebSphere MQ Common Services trace
    facility. Although following these instructions would still
    result in a trace file being created, users were not able to
    take advantage of some of the functionality provided by the
    WebSphere MQ messaging client trace mechanism, such as wrapping
    trace.
    
    Issue 3:
    ----------------------------------------------------------------
    When using the WebSphere MQ V7.5 classes for Java, and the IBM
    MQ V8.0 and V9.0 classes for Java, the default trace filename
    started with the mqjms prefix. This was confusing, as it implied
    that the trace file actually contained trace information from
    the MQ classes for JMS rather than the MQ classes for Java.
    
    Issue 4:
    ----------------------------------------------------------------
    The "Tracing IBM WebSphere MQ classes for Java applications"
    topic in the IBM MQ V8.0 and V9.0 sections of IBM Knowledge
    Center, which described how to enable MQ classes for Java trace
    using the WebSphere MQ messaging client trace mechanism, linked
    to another topic, called "The IBM MQ classes for Java
    configuration file". This topic contained information about the
    configuration file used to control tracing, and stated the
    following:
    
    A sample configuration file called mqjava.config is supplied in
    the bin subdirectory of the IBM MQ classes for Java installation
    directory.
    
    The sample configuration file was only shipped as part of MQ for
    z/OS V8 and V9. The configuration file was missing in MQ V8 and
    V9 on distributed platforms.
    

Problem conclusion

  • The following changes have been made as a result of this APAR:
    
    Change 1:
    ----------------------------------------------------------------
    The information in the topic called:
    
      Tracing WebSphere MQ classes for Java programs
    
    in the WebSphere MQ V7.1 section of IBM Knowledge Center have
    been updated to provide more detailed instructions on how to
    collect trace of the WebSphere MQ classes for Java.
    
    The URI for this topic is shown below:
    
    https://www.ibm.com/support/knowledgecenter/SSFKSJ_7.1.0/com.ibm
    .mq.doc/ja11410_.htm
    
    Change 2:
    ----------------------------------------------------------------
    The information in the topic:
    
      Tracing WebSphere MQ classes for Java programs
    
    in the WebSphere MQ V7.5 section of IBM Knowledge Center have
    been updated to describe how to collect trace using the
    WebSphere MQ messaging client trance mechanism. The URI for this
    topic is shown below:
    
    http://www.ibm.com/support/knowledgecenter/SSFKSJ_7.5.0/com.ibm.
    mq.dev.doc/q031310_.htm
    
    Change 3:
    ----------------------------------------------------------------
    The:
    
    - WebSphere MQ V7.5 classes for Java
    - IBM MQ V8.0 classes for Java
    - IBM MQ V8.0 classes for Java OSGi bundle
          com.ibm.mq.osgi.java_<version number>.jar
    - IBM MQ 9.0 classes for Java
    - IBM MQ V9.0 classes for Java OSGi bundle
          com.ibm.mq.osgi.java_<version number>.jar
    
    have been updated so that, by default, MQ classes for Java trace
    is written to a file called:
    
      mqjava_%PID%.trc
    
    where %PID% is the process identifier of the MQ classes for Java
    application that is being traced.
    
    Change 4:
    ----------------------------------------------------------------
    The:
    
    - IBM MQ V8.0 relocatable JAR file
          com.ibm.mq.allclient.jar
    - IBM MQ V8.0 OSGi bundle
          com.ibm.mq.osgi.allclient.java_<version number>.jar
    - IBM MQ V9.0 relocatable JAR file
          com.ibm.mq.allclient.jar
    - IBM MQ V9.0 OSGi bundle
          com.ibm.mq.osgi.allclient.java_<version number>.jar
    
    have been modified so that if either MQ classes for Java or MQ
    classes for JMS trace is enabled for an application that is
    using the relocatable JAR file, the default name of the trace
    file is:
    
      mqjavaclient_%PID%.trc
    
    where %PID% is the process identifier of the application that is
    being traced.
    
    Change 5:
    ----------------------------------------------------------------
    The file:
    
      mqjava.config
    
    is now shipped on all  platforms for WebSphere MQ V7.5, MQ V8.0
    and V9.0.
    
    ---------------------------------------------------------------
    The fix is targeted for delivery in the following PTFs:
    
    Version    Maintenance Level
    v7.5       7.5.0.9
    v8.0       8.0.0.7
    v9.0 CD    9.0.5
    v9.0 LTS   9.0.0.2
    
    The latest available maintenance can be obtained from
    'WebSphere MQ Recommended Fixes'
    http://www-1.ibm.com/support/docview.wss?rs=171&uid=swg27006037
    
    If the maintenance level is not yet available information on
    its planned availability can be found in 'WebSphere MQ
    Planned Maintenance Release Dates'
    http://www-1.ibm.com/support/docview.wss?rs=171&uid=swg27006309
    ---------------------------------------------------------------
    

Temporary fix

Comments

APAR Information

  • APAR number

    IV91716

  • Reported component name

    WMQ LIN X86 V7

  • Reported component ID

    5724H7224

  • Reported release

    710

  • Status

    CLOSED PER

  • PE

    NoPE

  • HIPER

    NoHIPER

  • Special Attention

    NoSpecatt / Xsystem

  • Submitted date

    2016-12-22

  • Closed date

    2017-05-23

  • Last modified date

    2018-08-02

  • APAR is sysrouted FROM one or more of the following:

  • APAR is sysrouted TO one or more of the following:

Fix information

  • Fixed component name

    WMQ LIN X86 V7

  • Fixed component ID

    5724H7224

Applicable component levels

  • R710 PSY

       UP

[{"Line of Business":{"code":"LOB36","label":"IBM Automation"},"Business Unit":{"code":"BU053","label":"Cloud & Data Platform"},"Product":{"code":"SSFKSJ","label":"WebSphere MQ"},"Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"7.1"}]

Document Information

Modified date:
09 March 2021