IC97482: WMQ CLASSES FOR JAVA SEGMENTSTATUS FIELD MAY BE INCORRECT WHEN RECEIVING MESSAGES LARGER THAN 4KB

WebSphere MQ V7.5 Fix Pack 7.5.0.3
WebSphere MQ V7.0 Fix Pack 7.0.1.12
Fix Pack 7.1.0.5 for WebSphere MQ V7.1

APAR status

• Closed as program error.

Error description

• WMQ 7.1 SegmentStatus field is found to be incorrect when
  using the WebSphere MQ classes for Java API.
  The observation was that the SegmentStatus returned indicated
  that the message was segmented ('S'), although the message
  was not segmented.
  MessageFlags were set for grouping: MESSAGE_IN_GROUP +
  LAST_MESSAGE_IN_GROUP.
  

Local fix

Problem summary

• ****************************************************************
  USERS AFFECTED:
  This issue affects users of the WebSphere MQ classes for Java,
  who are receiving messages from WebSphere MQ which are larger
  than the initial message buffer size (which defaults to 4KB),
  where the application is checking the message segmentation flags
  returned from the MQGET API call.
  
  
  Platforms affected:
  MultiPlatform
  
  ****************************************************************
  PROBLEM SUMMARY:
  When using the WebSphere MQ classes for Java, the application
  can choose to check the message segmentation status flag which
  is returned within the MQGetMessageOptions object.
  
  For example, consider the following code snippet:
  
  -----------------------------------------------------------
  MQGetMessageOptions gmo = new MQGetMessageOptions();
  MQMessage returnedMsg = new MQMessage();
  
  // Set the MQGET options
  gmo.options = MQC.MQGMO_SYNCPOINT |
                MQC.MQGMO_LOGICAL_ORDER |
                MQC.MQGMO_ALL_MSGS_AVAILABLE |
                MQC.MQGMO_ALL_SEGMENTS_AVAILABLE |
                CMQC.MQGMO_PROPERTIES_FORCE_MQRFH2;
  
  // Issue the MQGET on "com.ibm.mq.MQQueue" object "queue"
  queue.get(responseMsg, gmo);
  
  // Check the Segmentation Status of the updated GMO
  char msgSegmentationStatus = gmo.segmentStatus;
   -----------------------------------------------------------
  
  This message segmentation flag is set to one of the following
  character values:
  
  MQC.MQSS_NOT_A_SEGMENT, ' ', to indicate that the message
  returned is not a segment of a logical message.
  
  MQC.MQSS_SEGMENT, 'S', to indicate that the message returned
  is a segment of a logical message.
  
  MQC.MQSS_LAST_SEGMENT, 'L', to indicate that the segment is
  the last segment of a logical message.
  
  The application can then make use of this data to determine if
  further MQGETs are required to receive the entire logical
  message.
  
  
  However, if the MQGET method invoked on the
  "com.ibm.mq.MQDestination" object was of the signature type:
  
  com.ibm.mq.MQDesintation.get(com.ibm.mq.MQMessage,
                               com.ibm.mq.MQGetMessageOptions)
  
  as opposed to the one which also specifies the maximum message
  size to receive, AND the message being consumed is bigger than
  the buffer size initially set by the WebSphere MQ classes for
  Java (which defaults to 4kB), then the MQGET is broken into
  two parts internally:
  
  (a) First MQGET is made which internally receives a MQRC 2080
  'MQRC_TRUNCATED_MSG_FAILED' and tells the WebSphere MQ classes
  for Java the actual size of the message.
  
  (b) Second MQGET successfully consumes the message.
  
  then in rare circumstances, the message segmentation status,
  com.ibm.mq.MQGetMessageOptions.segmentStatus, (and also the
  com.ibm.mq.MQGetMessageOptions.segmentation field) may not
  have reflected the true status of the returned message.
  
  This problem was only seen when the message was too large to fit
  into the initially specified buffer size. A similar problem
  could also be seen when the alternative MQGET method call was
  used:
  
  com.ibm.mq.Destination.get(com.ibm.mq.MQMessage,
                             com.ibm.mq.MQGetMessageOptions,
                             int)
  
  where the third parameter is the maximum size of the message. If
  the application specifies a value smaller than the message size,
  such that a MQRC 2080 is received, then the segmentStatus and
  segmentation fields of the GMO may have had incorrect values
  with respect to the true status of the message. This second
  similar issue is not addressed by this APAR. The values returned
  by the queue manager for these fields may not be correctly
  populated if an error code is also returned with the message,
  such as the MQRC 2080. The application should not rely on the
  values set for these fields when an error code is also returned.
  

Problem conclusion

• The WebSphere MQ classes for Java have been updated so that
  the true value of the fields:
  
  com.ibm.mq.MQGetMessageOptions.segmentStatus
  com.ibm.mq.MQGetMessageOptions.segmentation
  
  are set on the GMO, when the message has been successfully
  received without an error code being returned from the queue
  manager.
  
  ---------------------------------------------------------------
  The fix is targeted for delivery in the following PTFs:
  
  Version    Maintenance Level
  v7.1       7.1.0.5
  v7.0       7.0.1.12
  v7.5       7.5.0.3
  
  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

• R710 PSY

     UP