Running the Reference Message samples

Use this example to find out how to run Reference Message sample application AMQSPRM on UNIX, Linux, and Windows, or AMQSPRMA on IBM i. The example shows how Reference Messages can be put to a queue, received by message exits, and taken from a queue.

The Reference Message samples run as follows:
Figure 1. Running the Reference Message samples
  1. Set up the environment to start the listeners, channels, and trigger monitors, and define your channels and queues.

    For the purposes of describing how to set up the Reference Message, this example refers to the sending machine as MACHINE1 with a queue manager called QMGR1 and the receiving machine as MACHINE2 with a queue manager called QMGR2.

    Note: The following definitions allow a Reference Message to be built to send a file with an object type of FLATFILE from queue manager QMGR1 to QMGR2 and to re-create the file as defined in the call to AMQSPRM (or AMQSPRMA on IBM i). The Reference Message (including the file data) is sent using channel CHL1 and transmission queue XMITQ and placed on queue DQ. Exception and COA reports are sent back to QMGR1 using the channel REPORT and transmission queue QMGR1.

    The application that receives the Reference Message (AMQSGRM or AMQSGRMA on IBM i ) is triggered using the initiation queue INITQ and process PROC. Ensure that the CONNAME fields are set correctly and the MSGEXIT field reflects your directory structure, depending on machine type and where the IBM MQ product is installed.

    The MQSC definitions have used an AIX style for defining the exits, so if we are using MQSC on IBM i, we need to modify these accordingly. It is important to note that the message data FLATFILE is case sensitive and the sample will not work unless it is in uppercase.

    On machine MACHINE1, queue manager QMGR1

    MQSC syntax 
    define chl(chl1) chltype(sdr) trptype(tcp) conname('machine2') xmitq(xmitq)
msgdata(FLATFILE) msgexit('/usr/lpp/mqm/samp/bin/amqsxrm(MsgExit)
')

define ql(xmitq) usage(xmitq)

define chl(report) chltype(rcvr) trptype(tcp) replace

define qr(qr) rname(dq) rqmname(qmgr2) xmitq(xmitq) replace

    IBM i command syntax

    Note: If we do not specify a queue manager name the system uses the default queue manager. 
    CRTMQMCHL CHLNAME(CHL1) CHLTYPE(*SDR) MQMNAME(QMGR1) +
            REPLACE(*YES) TRPTYPE(*TCP) +
            CONNAME('MACHINE2(60501)') TMQNAME(XMITQ) +
            MSGEXIT(QMQM/AMQSXRM4) MSGUSRDATA(FLATFILE)

CRTMQMQ   QNAME(XMITQ) QTYPE(*LCL) MQMNAME(QMGR1) +
            REPLACE(*YES) USAGE(*TMQ)

CRTMQMCHL CHLNAME(REPORT) CHLTYPE(*RCVR) +
            MQMNAME(QMGR1) REPLACE(*YES) TRPTYPE(*TCP)

CRTMQMQ   QNAME(QR) QTYPE(*RMT) MQMNAME(QMGR1) +
            REPLACE(*YES) RMTQNAME(DQ) +
            RMTMQMNAME(QMGR2) TMQNAME(XMITQ)

    On machine MACHINE2, queue manager QMGR2

    MQSC syntax 
    define chl(chl1) chltype(rcvr) trptype(tcp)
msgexit('/usr/lpp/mqm/samp/bin/amqsxrm(MsgExit)')
        msgdata(flatfile)

define chl(report) chltype(sdr) trptype(tcp) conname('MACHINE1')
        xmitq(qmgr1)

define ql(initq)

define ql(qmgr1) usage(xmitq)

define pro(proc) applicid('/usr/lpp/mqm/samp/bin/amqsgrm')

define ql(dq) initq(initq) process(proc) trigger trigtype(first)
    IBM i command syntax Note: On IBM i, if we do not specify a queue manager name the system uses the default queue manager. 
    CRTMQMCHL CHLNAME(CHL1) CHLTYPE(*RCVR) MQMNAME(QMGR2) +
REPLACE(*YES) TRPTYPE(*TCP) +
MSGEXIT(QMQM/AMQSXRM4) MSGUSRDATA(FLATFILE)

CRTMQMCHL CHLNAME(REPORT) CHLTYPE(*SDR) MQMNAME(QMGR2) +
REPLACE(*YES) TRPTYPE(*TCP) +
CONNAME('MACHINE1(60500)') TMQNAME(QMGR1)

CRTMQMQ  QNAME(INITQ) QTYPE(*LCL) MQMNAME(QMGR2) +
REPLACE(*YES) USAGE(*NORMAL)

CRTMQMQ  QNAME(QMGR1) QTYPE(*LCL) MQMNAME(QMGR2) +
REPLACE(*YES) USAGE(*TMQ)

CRTMQMPRC PRCNAME(PROC) MQMNAME(QMGR2) REPLACE(*YES) +
APPID('QMQM/AMQSGRM4')

CRTMQMQ  QNAME(DQ) QTYPE(*LCL) MQMNAME(QMGR2) +
REPLACE(*YES) PRCNAME(PROC) TRGENBL(*YES) +
INITQNAME(INITQ)
  2. Once the IBM MQ objects have been created:
    1. Where applicable to the platform, start the listener for the sending and receiving queue managers
    2. Start the channels CHL1 and REPORT
    3. On the receiving queue manager start the trigger monitor for the initiation queue INITQ

  3. Invoke the put Reference Message sample program AMQSPRM (AMQSPRMA on IBM i ) from the command line using the following parameters:

      -m
      Name of the local queue manager; this defaults to the default queue manager

      -i
      Name and location of source file

      -o
      Name and location of the destination file

      -q
      Name of the queue

      -g
      Name of the queue manager where the queue, defined in the -q parameter exists. This defaults to the queue manager specified in the -m parameter.

      -t
      Object type

      -w
      Wait interval, that is, the waiting time for exception and COA reports from the receiving queue manager

    For example, to use the sample with the objects defined previously you would use the following parameters: 

    -mQMGR1 -iInput File -oOutput File -qQR -tFLATFILE -w120
    Increasing the waiting time allows time for a large file to be sent across a network before the program putting the messages times out. 
    amqsprm -q QR -m QMGR1 -i d:\x\file.in -o d:\y\file.out -t FLATFILE
    IBM i users: On IBM i, complete the following steps:
    1. Use the following command: 
      CALL    PGM(QMQM/AMQSPRM4) PARM('-mQMGR1' +
'-i/refmsgs/rmsg1' +
'-o/refmsgs/rmsgx' '-qQR' +
'-gQMGR1' '-tFLATFILE' '-w15')
      This assumes that the original file rmsg1 is in IFS directory /refmsgs and that we want the destination file to be rmsgx in IFS directory /refmsgs on the target system.
    2. Create your own directory using the CRTDIR command rather than using the root directory.
    3. When you call the program that puts data, remember that the output file name needs to reflect the IFS naming convention; for example /TEST/FILENAME creates a file called FILENAME in the directory TEST.

    Note: On IBM i, we can use either a forward slash (/) or a dash (-) when specifying parameters. For example: 

    amqsprm /i d:\files\infile.dat /o e:\files\outfile.dat /q QR
/m QMGR1 /w 30 /t FLATFILE
    For UNIX and Linux platforms, we must use two backslashes (\\) instead of one to denote the destination file directory. Therefore, the amqsprm command looks like this: 
    amqsprm -i /files/infile.dat -o e:\\files\\outfile.dat -q QR
-m QMGR1 -w 30 -t FLATFILE
    Running the put Reference Message program does the following:

    • The Reference Message is put to queue QR on queue manager QMGR1.
    • The source file and path are d:\files\infile.dat and exists on the system where the example command is issued.
    • If the queue QR is a remote queue, the Reference Message is sent to another queue manager, on a different system, where a file is created with the name and path e:\files\outfile.dat. The contents of this file are the same as the source file.
    • amqsprm waits for 30 seconds for a COA report from the destination queue manager.
    • The object type is flatfile, so the channel used to move messages from the queue QR must specify this in the MsgData field.

  4. When you define your channels, select the message exit at both the sending and receiving ends to be amqsxrm. This is defined on Windows as follows: 
    msgexit(' pathname\amqsxrm.dll(MsgExit)')
    This is defined on AIX as follows: 
    msgexit(' pathname/amqsxrm(MsgExit)')

    If you specify a path name, specify the complete name. If we omit the path name, it is assumed that the program is in the path specified in the qm.ini file (or, on IBM MQ for Windows, the path specified in the registry).

  5. The channel exit reads the Reference Message header and finds the file that it refers to.
  6. The channel exit can then segment the file before sending it down the channel along with the header.

    On AIX, change the group owner of the target directory to 'mqm' so that the sample message exit can create the file in that directory. Also, change the permissions of the target directory to allow mqm group members to write to it. The file data is not stored on the IBM MQ queues.

  7. When the last segment of the file is processed by the receiving message exit, the Reference Message is put to the destination queue specified by amqsprm. If this queue is triggered (that is, the definition specifies Trigger, InitQ, and Process queue attributes), the program specified by the PROC parameter of the destination queue is triggered. The program to be triggered must be defined in the ApplId field of the Process attribute.
  8. When the Reference Message reaches the destination queue (DQ), a COA report is sent back to the putting application (amqsprm).
  9. The Get Reference Message sample, amqsgrm, gets messages from the queue specified in the input trigger message and checks the existence of the file.

Parent topic: The Reference Message sample programs