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
, andfte:postsrc
nested elements. - The fte:filemove task nests program invocation parameters
using the
fte:predst
,fte:postdst
,fte:presrc
, andfte: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. Whentype
isexecutable
, 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 theretrycount
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 theretrycount
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 theretrywait
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.
>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 thesuccessrc
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. - priority
- Optional (os4690background only). The priority level to assign to a background task on an IBM 4690 system. Default value is 5 and valid values are within the range 1 - 9.
- message
- Optional (os4690background only). The status message to display on an IBM 4690 system background control screen for the executed command.
- 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 IBM MQ 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 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 IBM MQ 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.
jcl
for apresrc
orpredst
nested element because you 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 ofjcl
.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
- os4690background
- The task calls an OS4690BACKGROUND program. Transfer program calls on an IBM® 4690 system can be run in background. These call types support the running of native IBM 4690 applications and batch command scripts. If you run a batch script the COMMAND.286 application is used with the -C option as the application, passing the batch script and any specified arguments as the parameters.
Parameters specified as nested elements
- fte:arg
- Only valid where the value of the
type
attribute is executable. Use nestedfte: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 thefte:arg
elements in the order that thefte:arg
elements are encountered. You can choose to specify zero or morefte:arg
elements as nested elements of a program invocation. - fte:property
- Only valid where the value of the
type
attribute is antscript. Use thename
andvalue
attributes of the nestedfte:property
elements to pass in name-value pairs to the Ant script. You can choose to specify zero or morefte: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 morefte: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 anfte: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>