Design of the Reference Message Exit sample (amqsxrma.c, AMQSXRM4)
This sample recognizes Reference Messages with an object type that matches the object type in the message exit user data field of the channel definition. For these messages, the following happens:
- At the sender or server channel, the specified length of data is copied from the specified offset of the specified file into the space remaining in the agent buffer after the Reference Message. If the end of the file is not reached, the Reference Message is put back on the transmission queue after updating the DataLogicalOffset field.
- At the requester or receiver channel, if the DataLogicalOffset field is zero and the specified file does not exist, it is created. The data following the Reference Message is added to the end of the specified file. If the Reference Message is not the last one for the specified file, it is discarded. Otherwise, it is returned to the channel exit, without the appended data, to be put on the target queue.
For sender and server channels, if the DataLogicalLength field in the input Reference Message is zero, the remaining part of the file, from DataLogicalOffset to the end of the file, is to be sent along the channel. If it is not zero, only the length specified is sent.
If an error occurs (for example, if the sample cannot open a file), MQCXP.ExitResponse is set to MQXCC_SUPPRESS_FUNCTION so that the message being processed is put to the dead-letter queue instead of continuing to the destination queue. A feedback code is returned in MQCXP.Feedback and returned to the application that put the message in the Feedback field of the message descriptor of a report message. This is because the putting application requested exception reports by setting MQRO_EXCEPTION in the Report field of the MQMD.
If the encoding or CodedCharacterSetId (CCSID) of the Reference Message is different from that of the queue manager, the Reference Message is converted to the local encoding and CCSID. In our sample, amqsprm, the format of the object is MQFMT_STRING, so amqsxrm converts the object data to the local CCSID at the receiving end before the data is written to the file.
Do not specify the format of the file being transferred as MQFMT_STRING if the file contains multibyte characters (for example, DBCS or Unicode). This is because a multibyte character could be split when the file is segmented at the sending end. To transfer and convert such a file, specify the format as something other than MQFMT_STRING so that the Reference Message exit does not convert it and convert the file at the receiving end when the transfer is complete.
Parent topic:
The Reference Message sample programs
fg17370_