IT24521: Activation Specifications that consume request messages without an MQRFH2 results in reply messages omitting an MQRFH2

APAR status

• Closed as program error.

Error description

• An Activation Specification is defined within an application
  server to use the IBM MQ Resource Adapter to consume messages
  from an MQ destination.
  
  For messages which do not contain an MQRFH2 header on the MQ
  destination which are consumed by the corresponding message
  driven bean (MDB), the JMS Destination created from the
  "JMSReplyTo" field of the Activation Specification delivered
  message has the "Target Client" property set to the value "1".
  
  The result of this is that reply messages sent to that JMS
  Destination will do not contain an MQRFH2 header.  Subsequently,
  any message properties which the application defines on the JMS
  reply message are not included in the MQ message when it is
  sent, and are lost.
  
  The Activation Specification does not provide a configuration
  property to change this behaviour.
  

Local fix

• Instead of using the JMS Destination created by calling the
  method:
  
    javax.jms.Message.getJMSReplyTo()
  
  on the incoming request message, either:
  
    - Lookup a JMS Destination object from the JEE application
  server's JNDI repository that has the MQ configuration property
  "Target Client" set to the value 0 (for JMS),
  
  or
  
    - Programmatically create and configure a JMS Destination
  object from a JMS Session using the methods:
  
    com.ibm.mq.jms.MQSession.createQueue(String)
  
    com.ibm.mq.jms.MQSession.createTopic(String)
  
  
  or the equivalent "javax.jms.JMSContext" class if using the JMS
  v2.0 interface.
  

Problem summary

• ****************************************************************
  USERS AFFECTED:
  This issue affects message-driven bean (MDB) applications that
  consume messages which do not contain an MQRFH2 header, via an
  IBM MQ JCA Resource Adapter Activation Specification, and
  subsequently send reply messages to the JMS Destination created
  from the "JMSReplyTo" field of the request message.
  
  
  Platforms affected:
  MultiPlatform
  
  ****************************************************************
  PROBLEM DESCRIPTION:
  The reply message sent to the JMS Destination identified by the
  JMSReplyTo field of the incoming request message did not contain
  an MQRFH2 header, despite the application setting message
  properties, because the "Target Client" property, as documented
  in the Knowledge Center, on the following URI:
  
  https://www.ibm.com/support/knowledgecenter/en/SSFKSJ_9.0.0/com.
  ibm.mq.dev.doc/q032240_.htm
  
  was being set to the value:
  
    1 (Messages do not contain an MQRFH2 header.)
  
  when the application called:
  
    javax.jms.Message.getJMSReplyTo();
  
  		
  The String representation of the JMS Destination's URI was
  therefore of the form:
  
    queue://<qmgr_name>/<queue_name>?targetClient=1
  
  The result of this was that messages sent to using that JMS
  Destination object did not contain an MQRFH2 header.
  
  
  The "targetClient=1" configuration property was being added to
  the JMS Destination because, by default, reply messages
  identified by the JMSReplyTo header field of an incoming request
  message match the format of the incoming message.  This is known
  as "Target Client Matching".  As the incoming request message
  did not have an MQRFH2 header, neither did the reply message.
  
  For "com.ibm.mq.jms.MQConnectionFactory" objects (as used by
  WebSphere Application Server (WSAS) Listener Ports) the matching
  behaviour concerning MQRFH2 headers between a request message
  and the reply message sent to the JMS Destination create from
  its JMSReplyTo field, is controlled by a property called
  "targetClientMatching":
  
  https://www.ibm.com/support/knowledgecenter/en/SSFKSJ_9.0.0/com.
  ibm.mq.dev.doc/q031680_.htm
  
  https://www.ibm.com/support/knowledgecenter/SSFKSJ_9.0.0/com.ibm
  .mq.javadoc.doc/WMQJMSClasses/com/ibm/msg/client/wmq/common/Comm
  onConstants.html?view=kc#WMQ_TARGET_CLIENT_MATCHING
  
  The default value of the "targetClientMatching" property is:
  
    true
  
  Activation Specifications provided by the IBM MQ JCA Resource
  Adapter (MQ-RA) did not use the "targetClientMatching" property,
  and did not permit it to be configured for inbound messaging.
  

Problem conclusion

• The IBM MQ JCA Resource Adapter (MQ-RA) has been updated such
  that the "targetClientMatching" property can be configured for
  an Activation Specification.  The default value is "true", which
  matches the existing behaviour prior to the code change
  associated with this APAR.
  
  When the property value is set to the value "false", an MQRFH2
  header can be included in a reply message sent to a JMS
  Destination created from the JMSReplyTo header of an incoming
  request messages that does not contain an MQRFH2.  This is
  because the targetClient property on the JMS Destination will be
  set to the value "0" (meaning messages will contain an MQRFH2
  header).  The presence of the MQRFH2 header in the outbound
  message permits the storage of user defined message properties
  on the message when sent to the MQ queue.
  
  
  In traditional WebSphere Application Server, the
  "targetClientMatching" property can now be defined as a custom
  property on the MQ Activation Specification.  Using the
  Administration Console, this can be achieved using the following
  breadcrumb trail:
  
    Resources --> JMS --> Activation specifications
      --> <name_of_act_spec> --> Customer properties --> New...
  
  The name of the property should be set to "targetClientMatching"
  of type java.lang.Boolean with the value "false".
  
  
  In WebSphere Liberty, the targetClientMatching property can be
  specified on the definition of an Activation Specification
  within the server.xml.  For example:
  
  &#09;<jmsActivationSpec
  id="SimpleMDBApplication/SimpleEchoMDB/SimpleEchoMDB">
  &#09;&#09;<properties.wmqJms destinationRef="MDBRequestQ"
  &#09;&#09;&#09;queueManager="MY_QMGR" transportType="BINDINGS"
  targetClientMatching="false"/>
  &#09;&#09;<authData password="********" user="tom" />
  &#09;</jmsActivationSpec>
  
  ---------------------------------------------------------------
  The fix is targeted for delivery in the following PTFs:
  
  Version    Maintenance Level
  v7.5       7.5.0.9
  v8.0       8.0.0.10
  v9.0 LTS   9.0.0.5
  
  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 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 WINDOWS V7

• Fixed component ID

  5724H7220

Applicable component levels