Monitoring a queue and using variable substitution

You can monitor a queue and transfer messages from the monitored queue to a file by using the fteCreateMonitor command. The value of any IBM® MQ message property in the first message to be read from the monitored queue can be substituted in the task XML definition and used to define the transfer behavior.

About this task

In this example, the source agent is called AGENT_VENUS, which connects to QM_VENUS. The queue that AGENT_VENUS monitors is called START_QUEUE and is located on QM_VENUS. The agent polls the queue every 30 minutes.

When a complete group of messages is written to the queue the monitor task sends the group of messages to a file at one of a number of destination agents, all of which connect to the queue manager QM_MARS. The name of the file that the group of messages is transferred to is defined by the IBM MQ message property usr.fileName on the first message in the group. The name of the agent that the group of messages is sent to is defined by the IBM MQ message property usr.toAgent on the first message in the group. If the usr.toAgent header is not set, the default value to be used for the destination agent is AGENT_MAGENTA.

When you specify useGroups=true, if you do not also specify groupId=${GROUPID}, the transfer just takes the first message on the queue. For example, if you are using variable substitution to generate the fileName, it is therefore possible that the contents of a.txt will not be correct. This is because the fileName is generated by the monitor, but the transfer actually gets a message that is not the one that should generate the file called fileName.

Procedure

Create the task XML that defines the task that the monitor performs when it is triggered.


<?xml version="1.0" encoding="UTF-8" ?>
<request version="4.00" 
         xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance" 
         xsi:noNamespaceSchemaLocation="FileTransfer.xsd">
   <managedTransfer>
     <originator>
       <hostName>reportserver.com</hostName>
       <userID>USER1</userID>
     </originator>
     <sourceAgent agent="AGENT_VENUS" QMgr="QM_VENUS"/>
     <destinationAgent agent="${toAgent}" QMgr="QM_MARS"/>
     <transferSet>
       <item mode="binary" checksumMethod="none">
         <source>
           <queue useGroups="true" groupId="${GROUPID}">START_QUEUE</queue>
         </source>
         <destination type="file" exist="overwrite">
           <file>/reports/${fileName}.rpt</file>
         </destination>
       </item>
     </transferSet>
   </managedTransfer>
</request>

The variables that are replaced with the values of IBM MQ message headers are highlighted in bold. This task XML is saved to the file /home/USER1/task.xml

Create a resource monitor to monitor the queue START_QUEUE.

Submit the following command:


fteCreateMonitor -ma AGENT_VENUS -mm QM_VENUS -mq START_QUEUE 
                 -mn myMonitor -mt /home/USER1/task.xml 
                 -tr completeGroups -pi 30 -pu minutes -dv toAgent=AGENT_MAGENTA

A user or program writes a group of messages to the queue START_QUEUE.
The first message in this group has the following IBM MQ message properties set:
```
usr.fileName=larmer
usr.toAgent=AGENT_VIOLET
```

The monitor is triggered when the complete group is written. The agent substitutes the IBM MQ message properties into the task XML.

This results in the task XML being transformed to:


<?xml version="1.0" encoding="UTF-8" ?>
<request version="4.00" 
         xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance" 
         xsi:noNamespaceSchemaLocation="FileTransfer.xsd">
   <managedTransfer>
     <originator>
       <hostName>reportserver.com</hostName>
       <userID>USER1</userID>
     </originator>
     <sourceAgent agent="AGENT_VENUS" QMgr="QM_VENUS"/>
     <destinationAgent agent="AGENT_VIOLET" QMgr="QM_MARS"/>
     <transferSet>
       <item mode="binary" checksumMethod="none">
         <source>
           <queue useGroups="true" groupId="${GROUPID}">START_QUEUE</queue>
         </source>
         <destination type="file" exist="overwrite">
           <file>/reports/larmer.rpt</file>
         </destination>
       </item>
     </transferSet>
   </managedTransfer>
</request>

Results

The transfer that is defined by the task XML is performed. The complete group of messages that are read from the START_QUEUE by AGENT_VENUS is written to a file called /reports/larmer.rpt on the system where AGENT_VIOLET is running.

What to do next

Transferring each message to a separate file

If you want to monitor a queue and have every message transferred to a separate file, you can use a similar technique to the one described previously in this topic.

Create the monitor as described previously, specifying the -tr completeGroups parameter on the fteCreateMonitor command.

In the task XML specify the following:


<queue useGroups="true" groupId="${GROUPID}">START_QUEUE</queue>

However, when you put the messages onto the source queue, do not put them in a IBM MQ group. Add IBM MQ message properties to each message. For example, specify the usr.filename property with a unique file name value for each message. This effectively causes the IBM MQ Managed File Transfer agent to treat each message on the source queue as a separate group.