fte:call Ant task

We 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 commandPath MFT property.

For more information about the agent.properties file, see The MFT 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 where agentname is the name of the agent and qmgrname 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 manager
• host is the optional host name of the system where the queue manager is running
• port is the optional port number that the queue manager is listening on
• channel is the optional SVRCONN channel to use

If you omit the host, port, or channel information for the command queue manager, the connection information specified in the command.properties file is used. For more information, see The MFT command.properties file.

We can use the com.ibm.wmqfte.propertySet property to specify which command.properties file to use. For more information, see com.ibm.wmqfte.propertySet.

If we do not use the cmdqm attribute, the task defaults to using the com.ibm.wmqfte.ant.commandQueueManager property, if this property is set. If the com.ibm.wmqfte.ant.commandQueueManager property is not set, a connection to the default queue manager, defined in the command.properties file, is attempted. The format of the com.ibm.wmqfte.ant.commandQueueManager property is the same as the cmdqm attribute, that is, qmgrname@host@port@channel.

idproperty

Optional unless we have specified an outcome of defer. 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 we can use transfer identifiers to track the progress of a transfer, diagnose problems with a transfer, and cancel a transfer.

We cannot specify this property if we have also specified an outcome property of ignore. However, you must specify idproperty if we have also specified an outcome property of defer.

jobname

Optional. Assigns a job name to the fte:call request. We can use job names to create logical groups of transfers. Use the fte:uuid Ant task task to generate pseudo-unique job names. If we 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 we 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 we 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 of await is specified the idproperty 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 of defer is specified the idproperty attribute is required.

ignore

If the outcome of the fte:call operation is not important, we 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 an outcome of ignore is specified the idproperty attribute cannot be specified.

If we do not specify the outcome attribute, the task defaults to using the value 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.

We cannot specify this property if we have also specified an outcome property of ignore or defer. However, you must specify rcproperty if we have specified an outcome of await.

Parameters specified as nested elements

fte:command

Specifies the command to be called by the agent. We 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

We can specify metadata to associate with the call operation. This metadata is recorded in the log messages generated by the call operation. We 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 of xyz. 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>