Conversion of report messages

In general a report message can contain varying amounts of application message data, according to the report options specified by the sender of the original message. However, an activity report can contain data but without the report option mentioning *_WITH_DATA in the constant.

In particular, a report message can contain either:
  1. No application message data
  2. Some of the application message data from the original message

    This occurs when the sender of the original message specifies MQRO_*_WITH_DATA and the message is longer than 100 bytes.

  3. All the application message data from the original message

    This occurs when the sender of the original message specifies MQRO_*_WITH_FULL_DATA, or specifies MQRO_*_WITH_DATA and the message is 100 bytes or shorter.

When the queue manager or message channel agent generates a report message, it copies the format name from the original message into the Format field in the control information in the report message. The format name in the report message might therefore imply a length of data that is different from the length actually present in the report message (cases 1 and 2 previously). If the MQGMO_CONVERT option is specified when the report message is retrieved:

  • For case 1 previously, the data-conversion exit is not invoked (because the report message has no data).
  • For case 3 previously, the format name correctly implies the length of the message data.
  • But for case 2 previously, the data-conversion exit is invoked to convert a message that is shorter than the length implied by the format name.

    In addition, the reason code passed to the exit is usually MQRC_NONE (that is, the reason code does not indicate that the message has been truncated). This happens because the message data was truncated by the sender of the report message, and not by the receiver's queue manager in response to the MQGET call.

Because of these possibilities, the data-conversion exit must not use the format name to deduce the length of data passed to it; instead the exit must check the length of data provided, and be prepared to convert less data than the length implied by the format name. If the data can be converted successfully, completion code MQCC_OK and reason code MQRC_NONE must be returned by the exit. The length of the message data to be converted is passed to the exit as the InBufferLength parameter.

Product-sensitive programming interface