fte:filecopy Ant task

The fte:filecopy task copies files between Managed File Transfer agents. The file is not deleted from the source agent.

Attributes

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.

dst

Required. Specifies the destination agent for the copy operation. Specify this information in the form: agentname@qmgrname where agentname is the name of the destination agent and qmgrname is the name of the queue manager that this agent is directly connected to.

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 copy 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 copy request.

origuser

Optional. Specifies the originating user identifier to associate with the copy 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 copy operation to complete before returning control to the Ant script. Specify one of the following options:

await: The task waits for the copy 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 copy request has been submitted and assumes that the outcome of the copy operation is dealt with later using either the awaitoutcome or fte:ignoreoutcome Ant task tasks. When an outcome of defer is specified the idproperty attribute is required.
ignore: If the outcome of the copy operation is not important, we can specify a value of ignore. The task then returns as soon as the copy request has been submitted, without allocating any resources for tracking the outcome of the transfer. 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.

priority

Optional. Specifies the priority to associate with the copy request. In general, higher priority transfer requests take precedence over lower priority requests. The priority value must be in the range 0 - 9 (inclusive). A priority value of 0 is the lowest priority and a value of 9 is the highest priority. If we do not specify the priority attribute, the transfer defaults to a priority of 0.

rcproperty

Optional. Specifies the name of a property to assign the result code of the copy request to. The result code reflects the overall outcome of the copy request.

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

transferRecoveryTimeout

Optional. Sets the amount of time, in seconds, during which a source agent keeps trying to recover a stalled file transfer. Specify one of the following options:

-1

The agent continues to attempt to recover the stalled transfer until the transfer is complete. Using this option is the equivalent of the default behavior of the agent when the property is not set.

0

The agent stops the file transfer as soon as it enters recovery.

>0

The agent continues to attempt to recover the stalled transfer for the amount of time in seconds as set by the positive integer value specified. For example,

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

</fte:filecopy>

indicates that the agent keeps trying to recover the transfer for 6 hours from when it enters recovery. Maximum value for this attribute is 999999999.

Specifying the transfer recovery timeout value in this way sets it on a per transfer basis. To set a global value for all transfers in a Managed File Transfer network, we can add a property to the The agent.properties file. For more information, see Timeout option for file transfers in recovery.

src

Required. Specifies the source agent for the copy operation. Specify this information in the form: agentname@qmgrname where agentname is the name of the source agent and qmgrname is the name of the queue manager that this agent is directly connected to.

Parameters specified as nested elements

fte:filespec: Required. You must specify at least one file specification that identifies the files to copy. We can specify more than one file specification if required. See the fte:filespec topic for more information.
fte:metadata: We can specify metadata to associate with the copy operation. This metadata is carried with the transfer and is recorded in the log messages generated by the transfer. We can only associate a single block of metadata with a given transfer element; however this block can contain many pieces of metadata. See the fte:metadata topic for more information.
fte:presrc: Specifies a program invocation to take place at the source agent before the transfer starts. You can only associate a single fte:presrc element with a given transfer. See the program invocation topic for more information.
fte:predst: Specifies a program invocation to take place at the destination agent before the transfer starts. We can only associate a single fte:predst element with a given transfer. See the program invocation topic for more information.
fte:postsrc: Specifies a program invocation to take place at the source agent after the transfer has completed. We can only associate a single fte:postsrc element with a given transfer. See the program invocation topic for more information.
fte:postdst: Specifies a program invocation to take place at the destination agent after the transfer has completed. We can only associate a single fte:postdst element with a given transfer. See the program invocation topic for more information.

If fte:presrc, fte:predst, fte:postsrc, fte:postdst, and exits do not return a success status, the rules are as follows in the order specified:

Run the source start exits. If source start exits fail the transfer fails and nothing further is run.
Run the pre-source call (when present). If the pre-source call fails, the transfer fails and nothing further is run.
Run the destination start exits. If the destination start exits fail the transfer fails and nothing further is run.
Run the pre-destination call (when present). If the pre-destination call fails, the transfer fails and nothing further is run.
Perform the file transfers.
Run the destination end exits. There is no failure status for these exits.
If the transfer is successful (if some files transfer successfully, it is deemed successful) run the post-destination call (if present). If the post-destination call fails, the transfer fails.
Run the source end exits. There is no failure status for these exits.
If the transfer is successful run the post-source call (if present). If the post-source call fails, the transfer fails.

Examples

This example shows a basic file transfer between agent1 and agent2. The command to start the file transfer is sent to a queue manager called qm0, using a client transport mode connection. The result of the file transfer operation is assigned to the property called copy.result.

<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:filecopy>

This example shows the same file transfer, but with the addition of metadata and a program start to take place at the source agent after the transfer has completed.

<fte:filecopy cmdqm="qm0@localhost@1414@SYSTEM.DEF.SVRCONN" 
              src="agent1@qm"1 dst="agent2@qm2"
              rcproperty="copy.result">
                    

	<fte:metadata>
			<fte:entry name="org.example.departId" value="ACCOUNTS"/>
			<fte:entry name="org.example.batchGroup" value="A1"/>
	</fte:metadata> 

	<fte:filespec srcfilespec="/home/fteuser1/file.bin" dstfile="/home/fteuser2/file.bin"/>

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