IT30321: MQ JMS poison message handling fails with messages using little endian encoding, MQMD.encoding = 0x222

APAR status

• Closed as program error.

Error description

• An IBM MQ classes for JMS application is consuming a message
  from a queue using an asynchronous MessageListener, which was
  put to the queue by an unmanaged subscription from an MQ Topic
  running on the MQ Appliance.
  
  The application rolls back the message to the queue from within
  the MessageListener to test the MQ classes for JMS poison
  message handling, using the JMS method:
  
    javax.jms.Session.recover()
  
  When the backout count of the message is equal to or exceeds the
  backout threshold (BOTHRESH) of the queue, it was expected that
  the message would be moved to the backout queue (BOQNAME).
  
  If the message's MQMD.format is set to "MQSTR   ", then the
  message is moved to the backout queue.  However if the message's
  MQMD.format is set to "MQHRF2  ", the message is not moved to
  the backout queue and is discarded.
  
  An IBM MQ Classes for JMS trace shows the following exception
  occurred:
  
  JMSCMQ0001: IBM MQ call failed with compcode '2' ('MQCC_FAILED')
  reason '2142' ('MQRC_HEADER_ERROR'). [com.ibm.mq.MQException]
  at:
  com.ibm.msg.client.wmq.common.internal.Reason.createException(Re
  ason.java:203)
  com.ibm.msg.client.wmq.internal.WMQPoison.checkJmqiCallSuccess(W
  MQPoison.java:1423)
  com.ibm.msg.client.wmq.internal.WMQPoison.put(WMQPoison.java:984
  )
  com.ibm.msg.client.wmq.internal.WMQPoison.backoutRequeue(WMQPois
  on.java:769)
  com.ibm.msg.client.wmq.internal.WMQPoison.handlePoisonMessage(WM
  QPoison.java:434)
  
  
  The destination which the MessageListener was consuming messages
  from was configured with the options:
  
    mdWriteEnabled=true
    mdReadEnabled=true
  
  with a  queue URI of the form:
  
  queue:///MYQUEUE?mdReadEnabled=true&mdWriteEnabled=true
  

Local fix

• Disable the use of the Destination boolean properties:
  
    mdWriteEnabled
    mdReadEnabled
  
   if not required by the application.
  

Problem summary

• ****************************************************************
  USERS AFFECTED:
  Users of IBM MQ classes for JMS, who are consuming messages from
  a JMS Destination where the following set of conditions are all
  met:
  
  (1) JMS Destination is configured to both read and write the
  MQMD properties, with the following properties defined on the
  Destination:
    mdWriteEnabled = true
    mdReadEnabled = true
  
  (2) An asynchronous MessageListener is being used to consume the
  messages from the Destination.
  
  (3) The message being consumed has an "MQMD.encoding" field
  which is not set to big-endian encoding, 0x111.  For example, a
  message generated by the queue manager's publish/subscribe
  engine running on a little endian system, such as Windows, Linux
  (x86-64) or the MQ Appliance.
  
  (4) Poison message handling is activated, by the message on the
  queue having a backout count equal or greater to the queue's
  backout threshold (BOTHRESH).
  
  
  Platforms affected:
  MultiPlatform
  
  ****************************************************************
  PROBLEM DESCRIPTION:
  When an IBM MQ classes for JMS application is consuming messages
  from a JMS Destination, the Destination can be configured to
  permit the application to set properties on the JMS message
  which are then reflected into the MQ message's MQMD field when
  the MQ message is generated.
  
  Similarly another property results in the MQMD field values
  being stored as object properties on the JMS message when the
  message is consumed.
  
  To permit this, the following Destination properties can be set
  programatically in the application:
  
  MQQueue.setBooleanProperty(WMQConstants.WMQ_MQMD_READ_ENABLED,
  true);
  MQQueue.setBooleanProperty(WMQConstants.WMQ_MQMD_WRITE_ENABLED,
  true);
  
  which results in a queue URI representation of the Destination
  being of the form:
  
    queue:///MY.QUEUE?mdReadEnabled=true&mdWriteEnabled=true
  
  
  With this property set on the Destination, when an MQ message is
  consumed and transformed into an MQ-JMS message, a number of
  properties will be defined on the MQ-JMS message with values
  taken from the MQMD, including the property:
  
         JMS_IBM_MQMD_Encoding
  
  which allows access to the "MQMD.encoding" field from the
  consumed MQ message.
  
  
  When a poison message is consumed by an asynchronous
  MessageListener, meaning a message where the backout count
  equals or exceeds the backout threshold defined on the MQ queue,
  the IBM MQ classes for JMS attempt to send the message to the
  backout queue, or the dead letter queue if the backout queue is
  not defined or available.
  
  To do this, the IBM MQ classes for JMS constructed a new MQ
  message and populated it with the content of the consumed
  message.  If the Destination was configured to allow both
  reading the MQMD properties, and writing them when sending the
  message, the MQMD.encoding field was updated with the value of
  the received message.
  
  For example, if the message being consumed by the
  MessageListener had the MQMD value:
  
    MQMD.encoding = 0x222
  
  then it would update the MQMD.encoding field with this value
  when sending the message to the backout queue.  However, the
  RFH2 header which follows the MQMD had already been written
  prior to setting this encoding field, which resulted in an MQMD
  which incorrectly described the numerical encoding of the RFH2
  field.
  
  The queue manager detected this discrepency, and rejected the
  MQPUT operation to the backout queue with an MQRC 2142
  'MQRC_HEADER_ERROR' error.
  
  The IBM MQ classes for JMS would then attempt to send the
  message to the dead letter queue, which would also fail, and
  depending on the transactional configuration of the JMS Session
  the JMS would then be discarded, or rolled back to the source
  queue to repeat the cycle.
  
  This problem did not occur if consuming the message
  synchronously, due to the way the MQ message was constructed in
  that scenario.
  

Problem conclusion

• The IBM MQ classes for JMS have been updated so that the field:
  
    MQMD.encoding
  
  is updated from the JMS message property:
  
         JMS_IBM_MQMD_Encoding
  
  prior to building the RFH2 header which follows the MQMD in the
  general case.
  
  This also has the effect of allowing an IBM MQ classes for JMS
  application to send a new message to an MQ queue or topic, while
  manipulating the MQMD.encoding field through the use of the JMS
  message property:
  
        JMS_IBM_MQMD_Encoding
  
  where the JMS Destination has been configured to update the MQMD
  from the JMS message property (mdWriteEnabled = true).
  
  
  This results in the RFH2 (or subsequent header which follows the
  MQMD) from being constructed using the numerical encoding as
  specified in the MQMD - resulting in a well formed MQ message.
  
  ---------------------------------------------------------------
  The fix is targeted for delivery in the following PTFs:
  
  Version    Maintenance Level
  v9.1 CD    9.1.4
  v9.1 LTS   9.1.0.4
  
  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

  IBM MQ BASE MP

• Fixed component ID

  5724H7271

Applicable component levels