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:

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.

Compiling the Reference Message Exit sample

To compile amqsxrma, use the following commands:

Note:
Throughout this section the \ character is used to split long commands over more than one line. Do not enter this character, enter each command as a single line.
On AIX

32 bit:

  $ xlc_r -o amqsxrm_32_r amqsxrma.c -I/usr/mqm/inc -L/usr/mqm/lib -lmqm_r

64 bit:

  $ xlc_r -q64 -o amqsxrm_64_r amqsxrma.c -I/usr/mqm/inc -L/usr/mqm/lib64 -lmqm_r
On HP-UX

  $ cc -c -Aa +z -I/opt/mqm/inc amqsxrma.c
  $ ld -b -o amqsxrm amqsxrma.o -z +b : -lmqm -lc
On Linux

  $ gcc -c -I/opt/mqm/inc amqsxrma.c
  $ gcc -o amqsxrm amqsxrma.o -shared \
      -L/opt/mqm/lib -lmqm
On i5/OS

To create the module use the following command:

 CRTCMOD MODULE(MYLIB/AMQSXRMA) SRCFILE(QMQMSAMP/QCSRC)
   TERASPACE(*YES *TSIFC)
Notes:
  1. To create your module so that it uses the IFS file system, add the option SYSIFCOPT(*IFSIO)
  2. To create the program for use with non-threaded channels use the following command: CRTPGM PGM(MYLIB/AMQSXRMA) BNDSRVPGM(QMQM/LIBMQM)
  3. To create the program for use with threaded channels use the following command: CRTPGM PGM(MYLIB/AMQSXRMA) BNDSRVPGM(QMQM/LIBMQM_R)
On Solaris

  $ cc -c -KPIC -I/opt/mqm/inc amqsxrma.c
  $ ld -G -o amqsxrm amqsxrma.o -dy -lmqm -lc -lnsl -ldl
On Windows systems
  cl amqsxrma.c -o amqsxrm.dll -LD -DEFAULTLIB mqm.lib mqmvx.lib amqsxrm.def