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 you 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. If you have configured a Web Gateway to allow files to be uploaded to an agent, configure fte:postdst program invocations by specifying the x-fte-postdest header or using the postdest form field in the HTTP request.
You 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 The commandPath 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 you 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 you 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.
- 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 WebSphere MQ File Transfer Edition log for the call. However, the amount of data output is limited by the agent configuration. The default is 10K bytes of data, but you 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 WebSphere MQ File Transfer Edition log for the call. However, the amount of data output is limited by the agent configuration. The default is 10K bytes of data but you 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 WebSphere MQ
File Transfer Edition 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.
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. You 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. You 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>