Running the Reference Message samples

 

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

    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 i5/OS). 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 i5/OS) 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 WebSphere MQ product is installed.

    The MQSC definitions have used an AIX style for defining the exits, so if you are using MQSC on i5/OS 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

    i5/OS command syntax

    If you 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)
    i5/OS command syntax

    If you 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 above WebSphere 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 i5/OS) 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 destination file
    -q Name of queue
    -g Name of 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 above 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
    i5/OS users:

    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 you 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 instance /TEST/FILENAME creates a file called FILENAME in the directory TEST.

    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 platforms, use two backslashes (\\) instead of one to denote the destination file directory. Therefore, the above 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 is 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 WebSphere MQ for Windows as follows: 
      msgexit(‘<pathname>\amqsxrm.dll(MsgExit)’)

    This is defined on WebSphere MQ for AIX, WebSphere MQ for HP-UX, and WebSphere MQ for Solaris as follows: 

      msgexit(‘<pathname>/amqsxrm(MsgExit)’)

    If you specify a pathname, specify the complete name. If you omit the pathname, it is assumed that the program is in the path specified in the qm.ini file (or, on WebSphere MQ for Windows, the path specified in the registry). This is explained fully in WebSphere MQ Intercommunications.

  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 WebSphere MQ for AIX, WebSphere MQ for HP-UX, and WebSphere MQ for Solaris, 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 WebSphere 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


fg17350_