Program invocation nested elements

Programs can be started using one of five nested elements: fte:presrc, fte:predst, fte:postdst, fte:postsrc, and fte:command. These nested elements instruct an agent to call an external program as part of its processing. Before we can start a program, you must ensure that the command is in a location specified by the commandPath property in the agent.properties file of the agent that runs the command.

Even though each program invocation element has a different name, they share the same set of attributes and the same set of nested elements. Programs can be started by the fte:filecopy, fte:filemove, and fte:command Ant tasks.

We cannot invoke programs from a Connect:Direct® bridge agent.

Ant tasks that can invoke programs:

• The fte:filecopy task nests program invocation parameters using the fte:predst, fte:postdst, fte:presrc, and fte:postsrc nested elements.
• The fte:filemove task nests program invocation parameters using the fte:predst, fte:postdst, fte:presrc, and fte:postsrc nested elements.
• The fte:call task nests program invocation parameters using the fte:command nested element.

Attributes

command

Required. Names the program to call. For the agent to be able to run a command, the command must be in a location specified by the commandPath property in the agent's agent.properties file. For more information, see commandPath MFT property. Any path information specified in the command attribute is considered relative to a location specified by the commandPath property. When type is executable, an executable program is expected otherwise a script appropriate for the call type is expected.

retrycount

Optional. The number of times to retry calling the program if the program does not return a success return code. The program named by the command attribute is called up to this number of times. The value assigned to this attribute must be non-negative. If we do not specify the retrycount attribute, a default value of zero is used.

retrywait

Optional. The time to wait, in seconds, before trying the program invocation again. If the program named by the command attribute does not return a success return code and the retrycount attribute specifies a non-zero value, this parameter determines the time to wait between retries. The value assigned to this attribute must be non-negative. If we do not specify the retrywait attribute, a default value of zero is used.

successrc

Optional. The value of this attribute is 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 > character to indicate a greater-than test between the number and the process return code.
• A number prefixed with a < character to indicate a less-than test between the number and the process return code.
• A number prefixed with a ! 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 we 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.

type

Optional. The value of this attribute specifies what type of program is being called. Specify one of the following options:

executable

The task calls an executable program. Can have additional arguments specified using the arg nested element. The program is expected to be accessible on the commandPath and where applicable have execute permission set. UNIX scripts can be called as long as they specify a shell program (for example, first line of shell script file is: #!/bin/sh). Command output written to stderr or stdout is sent to the Managed File Transfer log for the call. However, the amount of data output is limited by the agent configuration. The default is 10K bytes of data, but we can override this default using the agent property: maxCommandOutput.

antscript

The task runs the specified Ant script, using the fteAnt command. Properties can be specified using the property nested element. Ant targets can be specified using the target nested element. The Ant script is expected to be accessible on the commandPath. Ant output written to stderr or stdout is sent to the Managed File Transfer log for the call. However, the amount of data output is limited by the agent configuration. The default is 10K bytes of data but we can override this default using the agent property: maxCommandOutput.

jcl

The value jcl is supported on z/OS® only and runs the specified z/OS JCL script. The JCL is submitted as a job and requires the job card to be present. When the job is submitted successfully the JCL command output, written to the Managed File Transfer log, contains the following text: JOB job_name(job_id) where:

• job_name is the name of the job identified by the job card in the JCL.
• job_id is the z/OS system generated job ID.

If the job cannot be submitted successfully, the JCL script command fails and writes a message to the log indicating the reason for the failure (for example no job card is present). To understand whether the job has been run or completed successfully, use a system service such as SDSF. Managed File Transfer does not provide the information because it only submits the job; the system then determines when to run the job and how the job output is presented. Because a JCL script is submitted as a batch job it is not advisable to specify jcl for a presrc or predst nested element because we only know that the job has been submitted successfully and not whether it ran to completion successfully before the transfer starts. There are no nested elements that are valid with a type of jcl.The following example shows a JCL job:

//MYJOB JOB
//*
//MYJOB EXEC PGM=IEBGENER
//SYSPRINT DD SYSOUT=H
//SYSUT1 DD DSN=FRED.DEMO.TXT,DISP=SHR
//SYSUT2 DD DSN=BOB.DEMO.TXT,DISP=(NEW,CATLG),
// RECFM=VB,LRECL=133,BLKSIZE=2048,
// SPACE=(TRK,(30,5),RLSE)
//SYSIN DD DUMMY 

Parameters specified as nested elements

fte:arg

Only valid where the value of the type attribute is executable. Use nested fte:arg elements to specify arguments to the program that is being called as part of the program invocation. The program arguments are built from the values specified by the fte:arg elements in the order that the fte:arg elements are encountered. We can choose to specify zero or more fte:arg elements as nested elements of a program invocation.

fte:property

Only valid where the value of the type attribute is antscript. Use the name and value attributes of the nested fte:property elements to pass in name-value pairs to the Ant script. You can choose to specify zero or more fte:property elements as nested elements of a program invocation.

fte:target

Only valid where the value of the type attribute is antscript. Specify a target in the Ant script to call. We can choose to specify zero or more fte:target elements as nested elements of a program invocation.

Arg attributes

value

Required. The value of the argument to pass to the program being called.

Property attributes

name

Required. The name of a property to pass to the Ant script.

value

Required. The value to associate with the property name being passed to the Ant script.

Examples

This example shows an fte:postsrc program invocation being specified as part of an fte:filecopy task. The program invocation is for a program called post.sh and is supplied a single argument of /home/fteuser2/file.bin.

<fte:filecopy cmdqm="qm0@localhost@1414@SYSTEM.DEF.SVRCONN" 
              src=agent1@qm1 dst="agent2@qm2"
              rcproperty="copy.result">                    
		<fte:filespec srcfilespec="/home/fteuser1/file.bin" dstfile="/home/fteuser2/file.bin"/>

		<fte:postsrc command="post.sh" successrc=1 >         
				<fte:arg value="/home/fteuser2/file.bin"/>
		</fte:postsrc>

</fte:filecopy>

This example shows an fte:command program invocation being specified as part of a fte:call task. The program invocation is for an executable called command.sh, which is not passed any command-line arguments. If command.sh does not return a success return code of 1, the command is tried again after 30 seconds.

<fte:call cmdqm="qm0@localhost@1414@SYSTEM.DEF.SVRCONN"
            agent="agent1@qm1" 
            rcproperty="call.rc" 
            origuser="bob" 
            jobname="${job.id}">                
		<fte:command command="command.sh" successrc=1 retrycount="5" retrywait="30"/>		
</fte:call>

This example shows an fte:command program invocation being specified as part of a fte:call task. The program invocation is for the copy and compress targets in an Ant script called script.xml, which is passed two properties.

<fte:call cmdqm="qm0@localhost@1414@SYSTEM.DEF.SVRCONN"
            agent="agent1@qm1" 
            rcproperty="call.rc" 
            origuser="bob" 
            jobname="${job.id}">                
		<fte:command command="script.xml" type="antscript">
          <property name="src" value="AGENT5@QM5"/>
          <property name="dst" value="AGENT3@QM3"/>
          <target name="copy"/>	
          <target name="compress"/>
    </fte:command>	
</fte:call>