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.
- 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.