Creating a task definition XML manually according to the schema

You can manually create a task definition XML file according to the schema FileTransfer.xsd.

About this task

The schema FileTransfer.xsd 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 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.
os4690background: This value must be for an IBM MQ 8.0 or earlier Managed File Transfer agent, running on the 4690 operating system. This operating system is no longer supported and the value is no longer used.

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.