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.
- 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
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.
<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.
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.
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.
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.
<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
<request>
followed by <managedTransfer>
element.
To convert this task definition to a valid <managedCall>
structure,
follow these steps:Procedure
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.
<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.