IBM Support

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

Subscribe to this APAR

By subscribing, you receive periodic emails alerting you to the status of the APAR, along with a link to the fix after it becomes available. You can track this item individually or track all items by product.

Notify me when this APAR changes.

Notify me when an APAR for this component changes.


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:
    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
    JMSCMQ0001: IBM MQ call failed with compcode '2' ('MQCC_FAILED')
    reason '2142' ('MQRC_HEADER_ERROR'). []
    The destination which the MessageListener was consuming messages
    from was configured with the options:
    with a  queue URI of the form:

Local fix

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

Problem summary

  • ****************************************************************
    Users of IBM MQ classes for JMS, who are consuming messages from
    a JMS Destination where the following set of conditions are all
    (1) JMS Destination is configured to both read and write the
    MQMD properties, with the following properties defined on the
      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:
    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:
    which results in a queue URI representation of the Destination
    being of the form:
    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:
    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
    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:
    is updated from the JMS message property:
    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:
    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
    The latest available maintenance can be obtained from
    'WebSphere MQ Recommended Fixes'
    If the maintenance level is not yet available information on
    its planned availability can be found in 'WebSphere MQ
    Planned Maintenance Release Dates'

Temporary fix


APAR Information

  • APAR number


  • Reported component name


  • Reported component ID


  • Reported release


  • Status


  • PE




  • Special Attention

    NoSpecatt / Xsystem

  • Submitted date


  • Closed date


  • Last modified date


  • 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


  • Fixed component ID


Applicable component levels

[{"Business Unit":{"code":"BU053","label":"Cloud & Data Platform"},"Product":{"code":"SSYHRD","label":"IBM MQ"},"Component":"","ARM Category":[],"Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"910","Edition":"","Line of Business":{"code":"LOB45","label":"Automation"}}]

Document Information

Modified date:
27 September 2019