Configuring monitor tasks to start commands and scripts

Resource monitors are not limited to performing file transfers as their associated task. You can also configure the monitor to call other commands from the monitoring agent, including executable programs, Ant scripts or JCL jobs. To call commands, edit the monitor task definition XML to include one or more command elements with corresponding command call parameters, such as arguments and properties.

About this task

The file path to the executable program, Ant script, or JCL job that you want the monitoring agent to call must be included in the commandPath of the monitoring agent. For information about the command path property, see The commandPath property.

You can create the task definition XML document in one of the following ways:

Create the task definition XML document manually according to the FileTransfer.xsd schema. For more information, see Create the task definition XML manually according to the schema.
Edit the XML document generated by the fteCreateTransfer -gt parameter as the basis for your task definition. For more information, see Creating a task definition document by modifying a generated document.

Whether you want a transfer task or a command task, the task definition must start with a <request> root element. The child element of <request> must be either <managedTransfer> or <managedCall>. You would typically choose <managedCall> when there is a single command or script to run, and <managedTransfer> if you want the task to include a file transfer and optionally up to four command calls.

Create the task definition XML manually according to the schema

About this task

You can manually create a task definition XML file according to the schema FileTransfer.xsd. This schema can be found in the MQ_INSTALLATION_PATH/mqft/samples/schema. For more information about this schema, see File transfer request message format.

Example

The following example shows an example task definition XML document saved as cleanuptask.xml, which uses the <managedCall> element to call an Ant script called RunCleanup.xml. The RunCleanup.xml Ant script must be located on the commandPath of the monitoring agent.

<?xml version="1.0" encoding="UTF-8"?>
<request version="4.00" xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance" 
  xsi:noNamespaceSchemaLocation="FileTransfer.xsd">
   <managedCall>
     <originator>
       <hostName>hostName</hostName>
       <userID>userID</userID>
       <mqmdUserID>mqmdUserID</mqmdUserID>
     </originator>
     <agent QMgr="QM1" agent="AGENT1"/>
     <reply QMGR="QM1">reply</reply>
     <transferSet priority="1">
       <metaDataSet>
         <metaData key="name1">value1</metaData>
       </metaDataSet>
       <call>
       	<command name="RunCleanup.xml" type="antscript" retryCount="2" 
          retryWait="30" successRC="0">
       	<target>check_exists</target>
       	<target>copy_to_archive</target>
       	<target>rename_temps</target>
   	      <target>delete_files</target>
       	<property name="trigger.filename" value="${FileName}"/>
       	<property name="trigger.path" value="${FilePath}"/>
       	</command>
       </call>
     </transferSet>
     <job>
       <name>JOBCLEAN1</name>
     </job>
   </managedCall>
</request>

The <agent> element specifies the IBM MQ Managed File Transfer agent that is configured with the named Ant script on its commandPath.

The <call><command>... structure defines the executable or script you want to run. The command takes an optional type attribute that can have one of the following values:

antscript: Run an Ant script in a separate JVM.

executable: Invoke an executable program.

jcl: Invoke a JCL job.

If you omit the type attribute, the default value executable is used.

The name attribute specifies the name of the Ant script, executable, or JCL job you want to run, without any path information. The agent searches for the script or program in the locations specified by the commandPath property in the agent's agent.properties file.

The retrycount attribute specifies the number of times to try calling the program again if the program does not return a success return code. The value assigned to this attribute must not be negative. If you do not specify the retrycount attribute, a default value of zero is used.

The retrywait attribute specifies the time to wait, in seconds, before trying the program invocation again. The value assigned to this attribute must not be negative. If you do not specify the retrywait attribute, a default value of zero is used.

The successrc attribute is an expression used to determine when the program invocation successfully runs. The process return code for the command is evaluated using this expression. The value can be composed of one or more expressions combined with a vertical bar (|) character to signify Boolean OR, or an ampersand (&) character to signify Boolean AND. Each expression can be one of the following types of expression:

A number to indicate an equality test between the process return code and the number.
A number prefixed with a greater than character (>) to indicate a greater-than test between the number and the process return code.
A number prefixed with a less than character (<) to indicate a less-than test between the number and the process return code.
A number prefixed with an exclamation point character (!) to indicate a not-equal-to test between the number and the process return code. For example: >2&<7&!5|0|14 is interpreted as the following return codes being successful: 0, 3, 4, 6, 14. All other return codes are interpreted as being unsuccessful.

If you do not specify the successrc attribute, a default value of zero is used. This means that the command is judged to have successfully run if, and only if, it returns a code of zero.

For an Ant script, you would typically specify <target> and <property> elements. The <target> element values must match the target names in the Ant script.

For executable programs, you can specify <argument> elements. Nested argument elements specify arguments to pass to the program that is being called as part of the program invocation. The program arguments are built from the values specified by the argument elements in the order that the argument elements are encountered. You can specify zero or more argument elements as nested elements of a program invocation.

The administrator defines and starts the monitor as normal using the task definition XML document that includes the <managedCall> element. For example:

fteCreateMonitor -ma AGENT1 -mm QM1 -md /monitored -mn MONITOR01 -mt 
   /tasks/cleanuptask.xml -pi 30 -pu seconds -tr match,*.go

The path to the transfer definition XML document must be on the local file system that you run the fteCreateMonitor command from (in this example /tasks/cleanuptask.xml). The cleanuptask.xml document is used to create the resource monitor only. Any tasks that the cleanuptask.xml document references (Ant scripts or JCL jobs) must be in the command path of the monitoring agent. When the monitor trigger condition is satisfied, any variables in the task definition XML are substituted with actual values from the monitor. So for example ${FilePath} is replaced in the request message sent to the agent with /monitored/cleanup.go. The request message is put on the agent command queue. The command processor detects that the request is for a program call and starts the specified program. If a command of type antscript is called, a new JVM is started and the Ant task runs under the new JVM. For more information about using variable substitution, see Customizing tasks with variable substitution.

Creating a task definition document by modifying a generated document

About this task

You can create the monitor task definition document by modifying the XML document generated by the -gt option of fteCreateTransfer. The generated document has a <request> followed by <managedTransfer> element. To convert this task definition to a valid <managedCall> structure, follow these steps:

Procedure

Replace the <managedTransfer> start and end tags with <managedCall> tags.
Remove any <schedule> element and child nodes.
Replace the <sourceAgent> start and end tags with <agent> to match the monitoring agent configuration details.
Remove <destinationAgent> and <trigger> elements.
Remove <item> elements.

Insert a new <call>...</call> structure within the <transferSet> element. This structure contains the command definition as shown in the following example:

<call>
       	<command name="RunCleanup.xml" type="antscript" retryCount="2" 
          retryWait="30" successRC="0">
       	<target>check_exists</target>
       	<target>copy_to_archive</target>
       	<target>rename_temps</target>
   	      <target>delete_files</target>
       	<property name="trigger.filename" value="${FileName}"/>
       	<property name="trigger.path" value="${FilePath}"/>
       	</command>
       </call>

Example

You can also retain the <managedTransfer> element including all the file transfer details, and insert up to four command calls. In this case you insert any selection of the following call elements between the <metaDataSet> and <item> elements:

preSourceCall: Call a program on the source agent before starting the transfer.
postSourceCall: Call a program on the source agent after completing the transfer.
preDestinationCall: Call a program on the destination agent before starting the transfer.
postDestinationCall: Call a program on the destination agent after completing the transfer.

Each of these elements takes the <command> element structure as described in the earlier example. The FileTransfer.xsd schema defines the types used by the various call elements.

The following example shows preSourceCall, postSourceCall, preDestinationCall, and postDestinationCall in a task definition document:


⋮
    <transferSet priority="1">
       <metaDataSet>
         <metaData key="key1">value1</metaData>
       </metaDataSet>
       <preSourceCall>
         <command name="send.exe" retryCount="0" retryWait="0" successRC="0"  
           type="executable">
           <argument>report1.pdf</argument>
           <argument>true</argument>
         </command>
       </preSourceCall>
       <postSourceCall>
         <command name="//DO_IT.JCL" retryCount="0" retryWait="0" successRC="0" 
           type="jcl">
           <argument>argument</argument>
         </command>
       </postSourceCall>
       <preDestinationCall>
         <command name="ant_script.xml" retryCount="0" retryWait="0" successRC="0" 
           type="antscript">
           <target>step1</target>
           <property name="name" value="value"/>
         </command>
       </preDestinationCall>
       <postDestinationCall>
         <command name="runit.cmd" retryCount="0" retryWait="0" successRC="0"/>
       </postDestinationCall>
       <item checksumMethod="none" mode="binary">
⋮

You can mix different types of command into the transfer. Argument, target, and property elements are optional.