Conversion of report messages
A report message can contain varying amounts of application message data, according to the report options specified by the sender of the original message. In particular, a report message can contain either:
- No application message data
- Some of the application message data from the original message
This occurs when the sender of the original message specifies RO*D and the message is longer than 100 bytes.
- All of the application message data from the original message
This occurs when the sender of the original message specifies RO*F, or specifies RO*D 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 MDFMT field in the control information in the report message. The format name in the report message may therefore imply a length of data which is different from the length actually present in the report message (cases 1 and 2 above).
If the GMCONV option is specified when the report message is retrieved:
- For case 1 above, the data-conversion exit will not be invoked (because the report message will have no data).
- For case 3 above, the format name correctly implies the length of the message data.
- But for case 2 above, the data-conversion exit will be invoked to convert a message which is shorter than the length implied by the format name.
In addition, the reason code passed to the exit will usually be RCNONE (that is, the reason code will 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 should not use the format name to deduce the length of data passed to it; instead the exit should 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 CCOK and reason code RCNONE should be returned by the exit. The length of the message data to be converted is passed to the exit as the INLEN parameter.
Product-sensitive programming interface
If a report message contains information about an activity that has taken place, it is known as an activity report. Examples of activities are:
- an MCA sending a message from a queue down a channel
- an MCA receiving a message from a channel and putting it onto a queue
- an MCA dead-letter queuing an undeliverable message
- an MCA getting a message off a queue and discarding it
- a dead-letter handler placing a message back on a queue
- the command server processing a PCF request - a broker processing a publish request
- a user application getting a message from a queue - a user application browsing a message on a queue
Any application, including the queue manager, can add some of the message data to the activity report following the report header. The amount of data that should be supplied if some is sent is not fixed, and is decided by the application. The information returned should be useful to the application processing the activity report. Queue manager activity reports will return with them any standard MQ header structures (beginning 'MQH') contained in the original message. This includes, for example, any MQRFH2 headers that were included in the original message. Also the queue manager will return an MQCFH header found, but not the PCF parameters associated with it. This gives monitoring applications an idea of what the message was about.