fte:call
You can use the fte:call task to remotely call scripts and programs.
This task allows you to send a fte:call request to an agent. The agent processes this request by running a script or program and returning the outcome. The commands to call must be accessible to the agent. Ensure the commandPath property value in the agent.properties file includes the location of the commands to call. Any path information specified by the command nested element must be relative to the locations specified by the commandPath property. By default commandPath is empty so that the agent cannot call any commands. For more information about this property, see Using commandPath.
For more information about the agent.properties file, see The agent.properties file.
Attributes
- agent
- Required. Specifies the agent to submit the fte:call request
to. Specify the agent information in the form:
agentname@qmgrname
whereagentname
is the name of the agent andqmgrname
is the name of the queue manager that this agent is directly connected to. - cmdqm
- Optional. The command queue manager to submit the request to.
Specify this information in the form
qmgrname@host@port@channel
, where:qmgrname
is the name of the queue managerhost
is the optional host name of the system where the queue manager is runningport
is the optional port number that the queue manager is listening onchannel
is the optional SVRCONN channel to use
host
,port
, orchannel
information for the command queue manager, the connection information specified in the command.properties file is used. For more information, see The command.properties file. - idproperty
- Optional unless you have specified an
outcome
ofdefer
. Specifies the name of a property to assign the transfer identifier to. Transfer identifiers are generated at the point a transfer request is submitted and you can use transfer identifiers to track the progress of a transfer, diagnose problems with a transfer, and cancel a transfer. - jobname
- Optional. Assigns a job name to the fte:call request.
You can use job names to create logical groups of transfers. Use the fte:uuid task to generate pseudo-unique job names.
If you do not use the jobname attribute, the task
defaults to using the
com.ibm.wmqfte.ant.jobName
property value, if this property is set. If you do not set this property, no job name is associated with the fte:call request. - origuser
- Optional. Specifies the originating user identifier to associate with the fte:call request. If you do not use the origuser attribute, the task defaults to using the user ID that is used to run the Ant script.
- outcome
- Optional. Determines whether the task waits for the fte:call operation
to complete before returning control to the Ant script. Specify one
of the following options:
- await
- The task waits for the fte:call operation to
complete before returning. When an
outcome
ofawait
is specified theidproperty
attribute is optional. - defer
- The task returns as soon as the fte:call request
has been submitted and assumes that the outcome of the call operation
is dealt with later using either the awaitoutcome or ignoreoutcome tasks. When an
outcome
ofdefer
is specified theidproperty
attribute is required. - ignore
- If the outcome of the fte:call operation is
not important, you can specify a value of
ignore
. The task then returns as soon as the fte:call request has been submitted, without allocating any resources for tracking the outcome of the command. When anoutcome
ofignore
is specified theidproperty
attribute cannot be specified.
await
. - rcproperty
- Optional. Specifies the name of a property to assign the result code of the fte:call request to. The result code reflects the overall outcome of the fte:call request.
Parameters specified as nested elements
- fte:command
- Specifies the command to be called by the agent. You can only
associate a single
fte:command
element with a givenfte:call operation. The command to be called must be located on the path specified by the commandPath property in the agent's agent.properties file. - fte:metadata
- You can specify metadata to associate with the call operation. This metadata is recorded in the log messages generated by the call operation. You can only associate a single block of metadata with a given transfer element; however this block can contain many pieces of metadata.
Example
This example shows how to call a command at AGENT1 running on queue manager QM1. The command to call is the script command.sh, and the script is called with a single argument ofxyz
. The command command.sh is
located on the path specified by the commandPath property
in the agent's agent.properties
file.
<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:arg value="xyz"/>
</fte:command>
<fte:metadata>
<fte:entry name="org.foo.accountName" value="BDG3R"/>
</fte:metadata>
</fte:call>