fte:filemove
The fte:filemove task moves files between IBM® MQ Managed File Transfer agents. When a file has been successfully transferred from the source agent to the destination agent, the file is 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 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. - dst
- Required. Specifies the destination agent for the copy operation.
Specify this information in the form:
agentname@qmgrname
whereagentname
is the name of the destination agent andqmgrname
is the name of the queue manager that this agent is directly connected to. - 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 move 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 move request. - origuser
- Optional. Specifies the originating user identifier to associate with the move 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 move operation
to complete before returning control to the Ant script. Specify one
of the following options:
- await
- The task waits for the move operation to complete before returning.
When an
outcome
ofawait
is specified theidproperty
attribute is optional. - defer
- The task returns as soon as the move request has been submitted
and assumes that the outcome of the move operation is dealt with later
using either the fte:awaitoutcome or fte:ignoreoutcome task. When an
outcome
ofdefer
is specified theidproperty
attribute is required. - ignore
- If the outcome of the move operation is not important, you can
specify a value of
ignore
. The task then returns as soon as the move request has been submitted, without allocating any resources for tracking the outcome of the transfer. When anoutcome
ofignore
is specified theidproperty
attribute cannot be specified.
await
. - priority
- Optional. Specifies the priority to associate with the move 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 you 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 move request to. The result code reflects the overall outcome of the move request.
- src
- Required. Specifies the source agent for the move operation. Specify
this information in the form:
agentname@qmgrname
whereagentname
is the name of the source agent andqmgrname
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 move. You can specify more than one file specification if required. See the fte:filespec topic for more information.
- fte:metadata
- Optional. You can specify metadata to associate with the file move operation. This metadata is carried with the transfer and is recorded in the log messages generated by the transfer. You 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
- Optional. 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
- Optional. Specifies a program invocation to take place at the
destination agent before the transfer starts. You can only associate
a single
fte:predst
element with a given transfer. See the program invocation topic for more information. - fte:postsrc
- Optional. Specifies a program invocation to take place at the
source agent after the transfer has completed. You can only associate
a single
fte:postsrc
element with a given transfer. See the program invocation topic for more information. - fte:postdst
- Optional. Specifies a program invocation to take place at the
destination agent after the transfer has completed. You 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, the transfer is considered 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 move betweenagent1
and agent2
. The command
to start the file move 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 move.result
.
<fte:filemove cmdqm="qm0@localhost@1414@SYSTEM.DEF.SVRCONN"
src=agent1@qm1
dst="agent2@qm2"
rcproperty="move.result">
<fte:filespec srcfilespec="/home/fteuser1/file.bin" dstfile="/home/fteuser2/file.bin"/>
</fte:filemove>