fteCreateTransfer (create new file transfer)
The fteCreateTransfer command creates and starts a new file transfer from the command line. This command can start a file transfer immediately, schedule a file transfer for a future time and date, repeat a scheduled transfer one or more times, and trigger a file transfer based on certain conditions.
Purpose
Use the fteCreateTransfer command to create and then start a new file transfer from a IBM® MQ Managed File Transfer agent. For guidance about how to transfer files, including text files, data sets, and generation data groups (GDGs), see Guidelines for transferring files.
You can run the fteCreateTransfer command from any system that can connect to the WebSphere® MQ network and then route to the source agent queue manager. Specifically, for the command to run, you must install a IBM MQ Managed File Transfer component (either Service or Agent) on this system and configure the IBM MQ Managed File Transfer component on this system to communicate with the WebSphere MQ network.
This command uses a properties file called command.properties to connect to the WebSphere MQ network. If the command.properties file does not contain property information, a bindings mode connection is made to the default queue manager on the local system. If the command.properties file does not exist, an error is generated. For more information, see The command.properties file.
You can specify multiple source files for a file transfer but they must originate from a single source agent and terminate at a single destination agent. Transferring a single source file to multiple destination files on the same agent or multiple different agents is not supported within a single transfer. Ant scripting can be used to send the same source file to multiple destinations at one or more agents. For more information, see Using Apache Ant with IBM MQ Managed File Transfer.
Special characters
Take care when you use parameters that contain special characters so that you avoid the command shell interpreting the characters in a way you do not expect. For example, fully qualified data set names that contain single quotation marks and source specifications that contain asterisk characters might be interpreted by the command shell rather than being passed through in the transfer request. To avoid characters being interpreted by the command shell, enclose the entire parameter in double quotation marks or escape the special characters by using the escape sequence of the command shell.
Relative paths
transferRoot=directory_name
For example, specify
C:\TransferRoot as C:\\TransferRoot or
C:/TransferRoot.
transferRootHLQ=prepend_value
However, for transfers that involve a Connect:Direct® node on a z/OS system, the data set specification is interpreted as a fully qualified name. No
high-level qualifier is added to the data set name.Syntax
Parameters for agent specification
- -sa source_agent_name
- Required. The name of the agent that the source files are transferred
from.
If you specify a protocol bridge agent as your source agent, you cannot then specify a data set as the source file specification.
If you specify the -td parameter and the transfer definition file contains the source agent that you want to use for the transfer, do not specify the -sa parameter.
- -sm source_agent_qmgr_name
- Optional. The name of the queue manager that the source agent
is connected to.
If you do not specify the -sm parameter, the queue manager that is used is determined by the set of configuration options in use, which is based on the source agent name. If the agent.properties file for the source agent cannot be found, the file transfer fails.
- -da destination_agent_name
- Required. The name of the agent that the files are transferred
to.
If you specify the -td parameter and the transfer definition file contains the destination agent that you want to use for the transfer, do not specify the -da parameter.
- -dm destination_agent_qmgr_name
- Optional. The name of the queue manager that the destination agent
is connected to.
If you do not specify the -dm parameter, the queue manager that is used is determined by the set of configuration options in use, which is based on the destination agent name. If the agent.properties file for the destination agent cannot be found, the file transfer fails.
Parameters for generating transfer templates
- -gttransfer_template_file_path
- Optional. Generates a transfer template XML message and writes this message to a file. If you
specify this parameter, no transfer request is sent to IBM MQ Managed File Transfer.
Instead, the contents of the transfer request message are written to the named XML document. You can
then use this XML document to define the task for resource monitoring. See fteCreateMonitor command for information about
how to create a resource monitor. If you do not specify this parameter, the default behavior takes
place and an actual transfer request is carried out.
You must provide the full path and name of an XML output file as input for this parameter, for example C:\templates\transfer_reports.xml
On z/OS, you must store the transfer template document in a UNIX file on z/OS UNIX System Services. You cannot store transfer template documents in z/OS sequential files or PDS members.
On IBM i, you must store the transfer template document in the integrated file system.
The transfer template XML message that you create by using the -gt parameter is not the same as the transfer you create by using the fteCreateTemplate command, which means you cannot use the two different types of template interchangeably.
Note: If you want to generate a transfer template XML document by running the fteCreateTransfer command with the -gt parameter, and then provide that transfer template XML document as input to the fteCreateTransfer command using the -td parameter, you must ensure that the transfer template XML document was generated specifying those parameters that are mutually exclusive with the -td option.The parameters mutually exclusive to the -td option are:- -dd destination_directory
- Source path
- -df destination_file
- -cschecksum
- -de destination_file_behavior
- -dq destination_queue
- -ttransfer type
- -sd source_file_disposition
For example, it is not possible to specify both the -td and -t parameters (indicating whether the transfer is a binary or text transfer) on the fteCreateTransfer command. This means that if you want to pass in a transfer template XML document to the command and specify that the transfer should be a text transfer, you should create the XML document by specifying the -gt and -t text parameters.
Parameters for scheduling transfers
- -ssschedule_start_time
- Optional. Specifies the time and date that you want
the scheduled transfer to take place. Use one of the following formats
to specify the time and date. Specify the time by using the 24-hour
clock:
yyyy-MM-ddThh:mm hh:mm
Scheduled file transfers start within a minute of the schedule start time, if there are no problems that might affect the transfer. For example, there might be issues with your network or agent that prevent the scheduled transfer starting.
- -tb
- Optional. Specifies the time base you want to
use for the scheduled file transfer. That is, whether you want to
use a system time or Coordinated Universal Time (UTC). You must use
this parameter with the -ss parameter only. Specify
one of the following options:
- admin
- The start and end times used for the scheduled transfer are based on the time and date of the system used by the local administrator. This is the default value.
- source
- The start and end times used for the scheduled transfer are based on the time and date of the system where the source agent is located.
- UTC
- The start and end times used for the scheduled transfer are based on Coordinated Universal Time (UTC).
- -oi
- Optional. Specifies the interval that the scheduled transfer occurs
at. You must use this parameter with the -ss parameter
only. Specify one of the following options:
- minutes
- hours
- days
- weeks
- months
- years
- -ofoccurrence_frequency
- Optional. Specifies the frequency that the scheduled transfer occurs at. For example, every 5 weeks or every 2 months. You must specify this parameter with the -oi and -ss parameters only. If you do not specify this parameter, a default value of 1 is used.
- -ococcurrence_count
- Optional. Specifies how many times you want this scheduled transfer
to occur. After the occurrence count is met, the scheduled transfer
is deleted.
Specify this parameter with the -oi and -ss parameters only.
If you specify the -oc parameter, you cannot specify the -es parameter because these parameters are mutually exclusive.
You can omit both the -oc and -es parameters to create a transfer that repeats indefinitely.
- -esschedule_end_time
- Optional. The time and date that a repeating scheduled transfer
ends.
You must specify this parameter with the -oi and -ss parameters only.
If you specify the -es parameter, you cannot specify the -oc parameter because these parameters are mutually exclusive.
You can omit both the -es and -oc parameters to create a transfer that repeats indefinitely.
Use one of the following formats to specify the end time and date. Specify the time by using the 24-hour clock:yyyy-MM-ddThh:mm hh:mm
Parameters for triggering transfers
- -tr
- Optional. Specifies a condition that must be true
for this file transfer to take place. If the condition is not true,
according to the source agent, the file transfer is discarded and
no transfer takes place. Specify the following format:
where condition is one of the following values:condition,namelist
- file=exist
- A minimum of one of the files in the namelist exists. That is, if any of the files in the namelist exists, the condition is true.
- file!=exist
- A minimum of one of the files in the namelist does not exist. That is, if any of the files in the namelist do not exist, the condition is true.
- filesize>=size
- A minimum of one of the files in the namelist exists and has a
minimum size as specified by size. size is an integer
with an optional size unit of KB, MB, or GB. For example,
filesize">"=10KB
. If you do not specify a size unit, the size is assumed to be bytes. On all operating systems, you must enclose the greater than symbol (>) in double quotation marks when you specify the filesize option on the command line, as shown in this example.
And where namelist is a comma-separated list of file names located on the same system as the source agent. Depending on your operating system, if you want to use path names or file names in a namelist that contain spaces, you might have to enclose the path names and file names in double quotation marks.
You can specify more than one trigger condition by using the -tr parameter more than once. However in that case, every separate trigger condition must be true for the file transfer to take place.Note: To continually monitor a resource for a trigger condition to be true, you are strongly recommended to use resource monitoring. You can create a resource monitor by using the fteCreateMonitor command.In the following example, the file file1.doc is transferred from AGENT1 to AGENT2, on condition that either file A.txt, or file B.txt, or both files exist on AGENT1 and that either file A.txt, or file B.txt, or both files are equal to or larger than 1 GB:
fteCreateTransfer -sa AGENT1 -sm QM_JUPITER -da AGENT2 -dm QM_NEPTUNE -tr file=exist,C:\export\A.txt,C:\export\B.txt -tr filesize">"=1GB,C:\export\A.txt,C:\export\B.txt -df C:\import\file1.doc C:\export\file1.doc
You can combine triggering parameters with scheduling parameters. If you do specify both types of parameters, the trigger conditions are applied to the file transfer created by the scheduling parameters.
The -tr parameter is not supported on protocol bridge agents.
- -tl
- Optional. Specifies whether trigger failures are written to the
transfer log. Specify one of the following options:
- yes
- Transfer log entries are created for failed triggered transfers. This is the default behavior even if you do not specify the -tl parameter.
- no
- No transfer log entries are created for failed triggered transfers.
Parameters for specifying transfer options
- -jnjob_name
- Optional. A user-defined job name identifier that is added to the transfer log message when the transfer starts.
- -md
- Optional. Specifies the user-defined metadata that is passed to
the exit points run by the agent. The -md parameter
can take one or more name-value pairs that are separated by commas.
Each name pair consists of name=value. You can use the -md parameter more than once
in a command.
When the agent property enableUserMetadataOptions is set to a value of true, certain user-defined metadata keys provide more options to the transfer. For more information about the user-defined metadata keys that are currently supported, see Supported user-defined metadata keys. When the enableUserMetadataOptions property is set to true, key names starting with
com.ibm.wmqfte.
are not supported for user-defined use. - -cschecksum
- Optional. Specifies whether a checksum algorithm is run on the
file transfer data to check the integrity of the transferred files.
Specify one of the following options:
- MD5
- Computes an MD5 checksum for the data. The resulting checksum for the source and destination files is written to the transfer log for validation purposes. By default, IBM MQ Managed File Transfer computes MD5 checksums for all file transfers.
- none
- No MD5 checksum is computed for the file transfer data. The transfer
log records that checksum was set to none and the value for the checksum
is blank. For example:
If you use the none option, you might improve file transfer performance, depending on your environment. However, selecting this option means that there is no validation of the source or destination files.<checksum method="none"></checksum>
If you specify the -cs parameter, you cannot specify the -td parameter because these parameters are mutually exclusive. However, you can specify checksum behavior in the transfer definition file.
- -pr transfer_priority
- Optional. Specifies the priority level of the transfer. Priority
is a value in the range 0-9, where 0 is the lowest priority. The default priority level is the priority level of the
source agent.
This value matches the message priority value of WebSphere MQ, see Getting messages from a queue: priority for more information. Message traffic for file transfer data defaults to a priority level of 0, which allows your WebSphere MQ message traffic to take priority.
- -qmp boolean
- Optional. Specifies whether the first message written to the destination queue by the transfer has WebSphere MQ message properties set. The valid options are as follows:
- true
- Sets message properties on the first message that is created by the transfer.
- false
- Does not set message properties on the first message that is created by the transfer. This is the default value.
- -qs message_size
- Optional. Specifies whether to split the file into multiple fixed-length messages. All the messages have the same WebSphere MQ group ID; the last message in the group has the WebSphere MQ LAST_MSG_IN_GROUP flag set. The size of the messages is specified by the value of message_size. The format of message_size is <length><units>, where length is a positive integer value and units is one of the following values:
B
- Bytes. The minimum value that is allowed is two times the maximum bytes-per-character value of the code page of the destination messages.
K
- This is equivalent to 1024 bytes.
M
- This is equivalent to 1048576 bytes.
You can specify the -qs parameter only if you also specify the -dq parameter. You can specify only one of the -qs, -dqdb, and -dqdt parameters.
- -qi
-
Optional. Using this option includes the delimiter that is used to split the file into multiple messages in the messages. The delimiter is included at the beginning or at the end of the message, depending on the -dqdp parameter (which specifies prefix or postfix). By default the delimiter is not included in the messages.
You can specify the -qi parameter only if you also specify one of the -dqdt and -dqdb parameters.
- -pconfiguration_options
- Optional. This parameter determines the set of configuration options
that is used to create the file transfer. Use the name of a non-default
coordination queue manager as the input for this parameter. The command
then uses the set of properties files that are associated with this
non-default coordination queue manager.
If you do not specify this parameter, the set of configuration options that are based on the default coordination queue manager is used.
- -w timeout
- Optional. Specifying the -w parameter causes the
fteCreateTransfer command to wait for a response from the agent before returning.
If you do not specify this parameter, the fteCreateTransfer command waits a
maximum of five seconds to receive an acknowledgment from the source agent for the transfer that the
agent has received the transfer request. If no acknowledgment is received during the five-second
wait, the fteCreateTransfer command returns the following warning message:
BFGCL0253W: No acknowledgment to command from agent within timeout.
The timeout argument is optional. If you specify timeout, the fteCreateTransfer command waits for up to timeout seconds for the agent to respond. If the agent does not respond before the time limit is reached, the command produces a warning and ends with a return code of 2. If you do not specify a timeout value, or you specify a timeout value of -1, then the command waits until the agent responds.
Parameters for invoking programs
For more information about how you can start a program from IBM MQ Managed File Transfer, see Specifying programs to run. For examples of specifying a program to invoke using the parameters that are described here, see Examples of using fteCreateTransfer to start programs.
- -presrc pre_source_call
- Optional. Specifies a program to invoke at the source agent before the transfer starts. Use the following format for pre_source_call:
In this syntax, the variables are:[type:]commandspec[,[retrycount][,[retrywait][,successrc]]]
- type
- Optional. Valid values
are executable, antscript, jcl, and os4690background. The default value is executable.
The jcl value is only applicable when targeted at an agent in a z/OS environment.
The antscript value is not applicable when targeted at an agent in an IBM 4690 environment.
- commandspec
- Required. The command specification. Use one of the following
formats:
- Type executable:
command[(arg1,arg2,...)]
- Type antscript:
command[(name1=var1|target1,name2=var2|target2,...)]
- Type jcl:
command
- Type os4690background:
command[(arg1,arg2,...)]
- command
- Required. The name of the program to call.
The jcl value is only applicable when targeted at an agent in a z/OS environment.
The antscript value is not applicable when targeted at an agent in an IBM 4690 environment.
Arguments in brackets ([ ]) are optional and syntax depends on command type. Parentheses, commas (,), and backslash (\) characters that are within the command or parameters must be escaped with a back slash (\) character.
- Type executable:
- retrycount
- Optional. The number of times to retry calling the program if the program does not return a successful return code. Default value is 0.
- retrywait
- Optional. The time to wait, in seconds, before trying the program invocation again. Default value is 0 (no wait between retries).
- successrc
- Optional. Expression that is used to determine when the program
invocation successfully runs. This expression can be composed of one
or more expressions. Combine these expressions with a vertical bar
character (|) to represent Boolean OR, or an ampersand (&) character
to represent Boolean AND. Each expression is of the following form:
where[>|<|!]value
- >
- Optional. A greater than test of the value.
- <
- Optional. A less than test of the value.
- !
- Optional. A not equal to test of the value.
- value
- Required. A valid integer.
- 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.
- -predst pre_destination_call
- Optional. Specifies a program to invoke at the destination agent before the transfer starts. pre_destination_call has the same format as pre_source_call.
- -postsrc post_source_call
- Optional. Specifies a program to invoke at the source agent after the transfer has completed. post_source_call has the same format as pre_source_call.
- -postdst post_destination_call
- Optional. Specifies a program to invoke at the destination agent after the transfer has completed. post_destination_call has the same format as pre_source_call.
Parameters for specifying the destination
One of the -td, -df, -dd, -ds, -dq, -du, and -dp parameters is required. You cannot specify more than one of these parameters in a transfer request; they are mutually exclusive.
- -td transfer_definition_file
- Optional. The name of the XML document that defines
one or more source and destination file specifications for the transfer.
Alternatively, the name of the XML document that contains a managed
transfer request (which might have been generated by the -gt parameter). If you specify the -td parameter and also specify any other parameters on the command line,
these other parameters override the corresponding value from the transfer
definition file.
The fteCreateTransfer command locates the transfer definition file in relation to your current directory. If you cannot use relative path notation to specify the location of the transfer definition file, use the fully qualified path and file name of the transfer definition file instead.
On z/OS, you must store the transfer definition file in a UNIX file on z/OS UNIX System Services. You cannot store transfer definition files in z/OS sequential files or PDS members.
On IBM i, you must store the transfer definition file in the integrated file system.
For more information, see Using transfer definition files.
- -df destination_file
Optional. The name of the destination file.
If the destination agent is a Connect:Direct bridge agent, the destination file is specified in the format connect_direct_node_name:file_path. The Connect:Direct bridge agent accepts only file paths that are specified in this format. If the destination agent is a Connect:Direct bridge agent and the destination is a PDS member, you must also specify the -de parameter with a value of overwrite.
Note the following information:- If the destination agent is a protocol bridge agent and you want
to specify an endpoint for a file, use the following format:
where protocol_server is the name of the protocol server (which is optional) and where file_path is the path to the file on the protocol server system. If you do not specify a protocol server, the default protocol server is used.protocol_server:file_path
- If you want to invoke any of the IBM MQ Managed File Transfer transfer I/O user exits that you have defined against the destination agent, you can use the -df parameter in a transfer.
- When the destination agent is on z/OS, if the file specified starts with
//
, it is assumed to be a partitioned z/OS data set.
- If the destination agent is a protocol bridge agent and you want
to specify an endpoint for a file, use the following format:
- -dd destination_directory
Optional. The name of the directory the file is transferred to. Specify a valid directory name on the system where the destination agent is running.
If the destination agent is a Connect:Direct bridge agent, the destination directory is specified in the format connect_direct_node_name:directory_path. If the destination agent is a Connect:Direct bridge agent and the destination is a PDS, you must also specify the -de parameter with a value of overwrite.
Note the following information:- If the destination agent is a protocol bridge agent and you want to specify a directory at a particular endpoint, use the following format:
where protocol_server is the name of the protocol server (which is optional) and where directory_path is the path to the directory on the protocol server system. If you do not specify a protocol server, the default protocol server is used.protocol_server:directory_path
If you want to invoke any of the IBM MQ Managed File Transfer transfer I/O user exits that you have defined against the destination agent, you can use the -dd parameter in a transfer.
When the destination agent is on z/OS, if the file specified starts with
//
, it is assumed to be a z/OS partitioned data set.
- -ds destination_sequential_data_set
z/OS only. Optional. The name of the sequential data set or PDS member that files are transferred into. Specify a sequential data set name or a partitioned data set member. For information about transferring data sets, see Guidelines for transferring files.
The syntax for the data set name is as follows:
or//data_set_name{;attribute(value);..;attribute(value)}
That is, a data set name specifier prefixed with // and optionally followed by a number of attributes that are separated by semicolons.//pds_data_set_name(member_name){;attribute(value);..;attribute(value)}
For example://'TEST.FILE.NAME';DSNTYPE(PDS);RECFM(F,B);BLKSIZE(800);LRECL(80);CYL;SPACE(2,2)
If the data set is located at a Connect:Direct node, you must prefix the data set name with the node name. For example:
If the destination agent is a Connect:Direct bridge agent and the destination is a PDS member, you must also specify the -de parameter with a value of overwrite. For more information about data set transfers to or from Connect:Direct nodes, see Transferring data sets to and from Connect:Direct nodes.CD_NODE1://'OBJECT.LIB';RECFM(F,B);BLKSIZE(800);LRECL(80)
For transfers that only involve IBM MQ Managed File Transfer agents, if the data set name part is enclosed by single quotation mark characters, it specifies a fully qualified data set name. If the data set name is not enclosed by single quotation mark characters, the system adds the default high-level qualifier for the destination agent (either the value for the transferRootHLQ agent property or the user ID that the agent runs under, if you have not set transferRootHLQ).Note: However, for transfers that involve a Connect:Direct node on a z/OS system, the data set specification is interpreted as a fully qualified name. No high-level qualifier is added to the data set name. This is the case even if the data set name is enclosed by single quotation mark characters.When you transfer a file or data set to tape, any existing data set that is already on the tape is replaced. The attributes for the new data set are set from attributes that are passed in the transfer definition. If no attributes are specified, attributes are set to the same as the source data set or to the default values when the source is a file. The attributes of an existing tape data set are ignored.
The data set attributes are used either to create a data set or to ensure that an existing data set is compatible. The specification of data set attributes is in a form suitable for BPXWDYN (see Requesting dynamic allocation for more information). When the agent is to create a destination data set, the following BPXWDYN attributes are automatically specified: DSN(data_set_name) NEW CATALOG MSG(numeric_file_descriptor). The value of numeric_file_descriptor is generated by IBM MQ Managed File Transfer. For a data set to data set transfer, the attributes of RECFM, LRECL, and BLKSIZE from the source are selected for a new destination data set. The SPACE setting for a new destination data set is not set by IBM MQ Managed File Transfer and system defaults are used. Therefore, you are recommended to specify the SPACE attribute when a new data set is to be created. You can use the bpxwdynAllocAdditionalProperties property in the agent.properties file to set BPXWDYN options that apply to all transfers. For more information, see The agent.properties file.
Some BPXWDYN options must not be specified when using the fteCreateTemplate command, the fteCreateTransfer command or the bpxwdynAllocAdditionalProperties property in the agent.properties file. For a list of these properties, see BPXWDYN properties you must not use with IBM MQ Managed File Transfer.
The -ds parameter is not supported when the destination agent is a protocol bridge agent.
If you want to invoke any of the IBM MQ Managed File Transfer transfer I/O user exits that you have defined against an agent, do not specify the-ds parameter in a transfer. Using the -ds parameter prevents the transfer I/O user exits from being invoked for the destination and means that the standard IBM MQ Managed File Transfer I/O is used instead.
- -dp destination_partitioned_data_set
- z/OS only. Optional. The
name of the destination PDS that files are transferred into. Specify
a partitioned data set name. If a PDS is created as a result of the
transfer, this PDS is created as a PDSE by default. You can override
the default by specifying DSNTYPE=PDS. The syntax for the PDS data set name is as follows:
//pds_data_set_name{;attribute;..;attribute}
The syntax for the data set name is the same as described for the -ds (destination_sequential_data_set) parameter. All the syntax details for specifying data sets that are located on Connect:Direct nodes also apply to the -dp parameter. If the destination agent is a Connect:Direct bridge agent, you must also specify the -de parameter with a value of overwrite.
The -dp parameter is not supported when the destination agent is a protocol bridge agent.
If you want to invoke any of the IBM MQ Managed File Transfer transfer I/O user exits that you have defined against an agent, do not specify the-dp parameter in a transfer. Using the -dp parameter prevents the transfer I/O user exits from being invoked for the destination and means that the standard IBM MQ Managed File Transfer I/O is used instead.
- -du destination_user
Optional. The name of the user whose destination file space the files are transferred into. For more information about file spaces, see File spaces.
The -du parameter is not supported when the destination agent is a protocol bridge agent or a Connect:Direct bridge agent.
If you want to invoke any of the IBM MQ Managed File Transfer transfer I/O user exits that you have defined against an agent, do not specify the-du parameter in a transfer. Using the -du parameter prevents the transfer I/O user exits from being invoked for the destination and means that the standard IBM MQ Managed File Transfer I/O is used instead.
- -dq destination_queue
Optional. The name of a destination queue that files are transferred onto. You can optionally include a queue manager name in this specification, by using the format QUEUE@QUEUEMANAGER. If you do not specify a queue manager name the destination agent queue manager name is used. You must specify a valid queue name that exists on the queue manager.
The -dq parameter is not supported when the destination agent is a protocol bridge agent or a Connect:Direct bridge agent, or when the source specification is a queue.
If you want to invoke any of the IBM MQ Managed File Transfer transfer I/O user exits that you have defined against an agent, do not specify the-dq parameter in a transfer. Using the -dq parameter prevents the transfer I/O user exits from being invoked for the destination and means that the standard IBM MQ Managed File Transfer I/O is used instead.
- -dqp persistent
- Optional. Specifies whether messages written to the destination queue are persistent. The valid options are as follows:
- true
- Writes persistent messages to the destination queue. This is the default value.
- false
- Writes non-persistent messages to the destination queue.
- qdef
- The persistence value is taken from the DefPersistence attribute of the destination queue.
- -dqdb hexadecimal_delimiter
Optional. Specifies the hexadecimal delimiter to use when splitting a binary file into multiple messages. All the messages have the same WebSphere MQ group ID; the last message in the group has the WebSphere MQ LAST_MSG_IN_GROUP flag set. The format for specifying a hexadecimal byte as a delimiter is
xNN
, whereN
is a character in the range0-9
ora-f
. You can specify a sequence of hexadecimal bytes as a delimiter by specifying a comma-separated list of hexadecimal bytes, for example:x3e,x20,x20,xbf
.You can specify the -dqdb parameter only if you also specify the -dq parameter and the transfer is in binary mode. You can specify only one of the -qs, -dqdb, and -dqdt parameters.
- -dqdt pattern
Optional. Specifies the Java™ regular expression to use when splitting a text file into multiple messages. All the messages have the same WebSphere MQ group ID; the last message in the group has the WebSphere MQ LAST_MSG_IN_GROUP flag set. The format for specifying a regular expression as a delimiter is a regular expression that is enclosed in parentheses,
(regular_expression)
, or enclosed in double quotation marks,
. For more information, see Regular expressions used by IBM MQ Managed File Transfer.regular_expression
By default, the length of the string that the regular expression can match is limited by the destination agent to five characters. You can change this behavior by editing the maxDelimiterMatchLength agent property. For more information, see Advanced agent properties.
You can specify the -dqdt parameter only if you also specify the -dq parameter and the value
text
for the -t parameter. You can specify only one of the -qs, -dqdb, and -dqdt parameters.- -dqdp position
-
Optional. Specifies the expected position of destination text and binary delimiters when splitting files. You can specify the -dqdp parameter only if you also specify one of the -dqdt and -dqdb parameters.
Specify one of the following options:- prefix
- The delimiters are expected at the beginning of each line.
- postfix
- The delimiters are expected at the end of each line. This is the default option.
- -de destination_file_behavior
- Optional. Specifies the action that is taken if a destination file exists on the destination
system. The valid options are as follows:
- error
- Reports an error and the file is not transferred. This is the default value.
- overwrite
- Overwrites the existing destination file.
If you specify the -de parameter, you cannot specify the -td parameter because these parameters are mutually exclusive. However, you can specify destination file exists behavior in the transfer definition file.
- -ttransfer type
- Optional. Specifies the type of file transfer: binary mode or
text mode.
- binary
- The data in the file is transferred without any conversion. This is the default value.
- text
- The code page and end-of-line characters of the file are converted.
You can specify which code page and line ending to use for the conversion
with the -sce, -dce or -dle parameters. If you do not specify the -sce, -dce or -dle parameters,
the exact conversions performed depend on the operating system of
the source agent and destination agent.
For example, a file that is transferred from Windows to z/OS has its code page converted from ASCII to EBCDIC. When a file is converted from ASCII to EBCDIC, the end-of-line characters are converted from ASCII carriage return (CR) and line feed (LF) character pairs to an EBCDIC new line (NL) character.
For more information about how z/OS data sets are transferred, see Transferring files and data sets between z/OS and distributed systems. and Transferring between data sets.
If you specify the -t parameter, you cannot specify the -td parameter because these parameters are mutually exclusive. However, you can specify transfer mode behavior in the transfer definition file.
- -dce destination_character_encoding
- Optional. Specifies which character encoding to use to write the
file at the destination. This option is only applicable to text files
and so -t text must also be specified. The code
pages available for conversion depend on the platform of the destination
agent. For a list of available code pages, see the topic Available code pages.
- noswaplfnl
- By default WebSphere MQ Managed File Transfer uses swaplfnl with supported EBCDIC character sets. Using swaplfnl changes the behavior of the character set mapping from and to the EBCIDIC LF 0x25 character. However, this can sometimes result in a mapping that is not desired. Use noswaplfnl to override this behavior.
- -dle destination_line_ending
- Optional. Specifies the end-of-line characters that are used when
the file is written at the destination. This option is applicable
to text files only and so you must also specify the -t text parameter. The valid options are:
- LF
- Line feed. This is the default for UNIX platforms and for z/OS UNIX System Services files. When you use the standard EBCDIC code pages that are supplied with IBM MQ Managed File Transfer for EBCDIC files, the end-of-line characters are mapped to a NL character (0x15) and not to a LF character (0x25).
- CRLF
- Carriage return followed by line feed. This is the default for Microsoft Windows.
- -dtr
- Optional. Specifies that destination records longer than the LRECL data set attribute are truncated. If this parameter is not specified, the records are wrapped. This parameter is valid only for text mode transfers where the destination is a data set.
- -dfa attributes
- Optional. Specifies
a semicolon separated list of file attributes that are associated
with the destination files in the transfer. The -dfa parameter can be specified with or without a value. For example,
without a value:
-dfa ATTRIBUTE1;ATTRIBUTE2
For example, with a value:-dfa ATTRIBUTE1(VALUE);ATTRIBUTE2(VALUE)
For example, one attribute with a value and one without:You can use the -dfa parameter more than once in a command.-dfa ATTRIBUTE1;ATTRIBUTE2(VALUE)
For more information about file attributes, see File distribution attributes.
Parameters for security
- -mquserid(userID)
- Optional. Specifies the user ID to authenticate with the command queue manager.
- -mqpassword(password)
- Optional. Specifies the password to authenticate with the command queue manager. You must also specify the -mquserid parameter. If you specify -mquserid, but do not specify -mqpassword, you will be prompted to supply the associated password. The password will not be displayed.
Parameters for specifying the source
- -sd source_file_disposition
- Optional.
Specifies
the action that is taken on a source file in file-to-file or file-to-message transfers when that
source file is successfully transferred to its destination. The valid options are as follows:
- leave
- The source files are left unchanged. This is the default value.
- delete
- The source files are deleted from the source system after the source files are successfully transferred.
Note: For message-to-file transfers, the messages on the source queue are always deleted once they have been successfully transferred. This means that if the -sd parameter is set to leave for a message-to-file transfer, the value is ignored.On z/OS, if the source is a tape data set and you specify the delete option, the tape is remounted to delete the data set. This behavior is because of the behavior of the system environment.
If the source is a queue and you specify the leave option, the command returns an error and a transfer is not requested.
If the source agent is a Connect:Direct bridge agent and you specify the delete option, the behavior is different to the usual source disposition behavior. One of the following cases occurs:- If Connect:Direct uses a process that is generated by IBM MQ Managed File Transfer to move the file or data set from the source, specifying the delete option causes the transfer to fail. To specify that the source file is deleted, you must submit a user-defined Connect:Direct process. For more information, see Submitting a user-defined Connect:Direct process from a file transfer request.
- If Connect:Direct uses a user-defined process to move the file or data set from the source, this parameter is passed to the process through the %FTEFDISP intrinsic symbolic variable. The user-defined process determines whether the source is deleted. The result that the transfer returns depends on the result that is returned by the user-defined process.
If you specify the -sd parameter, you cannot specify the -td parameter because these parameters are mutually exclusive. However, you can specify source disposition behavior in the transfer definition file.
- -r
- Optional. Recursively transfer files in subdirectories when source_specification contains wildcard characters. When IBM MQ Managed File Transfer is presented with a wildcard
character as a source_specification, any subdirectories
that match the wildcard character are transferred only if you specify
the -r parameter. When source_specification matches a subdirectory, all files in that directory and its subdirectories
(including hidden files) are always transferred.
For more information about how IBM MQ Managed File Transfer handles wildcard characters, see Using wildcard characters
If you specify the -r parameter, you cannot specify the -td parameter because these parameters are mutually exclusive. However, you can specify recursive behavior in the transfer definition file.
- -sce source_character_encoding
- Optional. Specifies which character encoding to use to read the
source file when performing character conversion. This option is only
applicable to text files and so -t text must
also be specified. The code pages available for conversion depend
on the platform of the destination agent, because the conversion is
performed on the destination system. For a list of available code
pages, see the topic Available code pages.
- noswaplfnl
- By default WebSphere MQ Managed File Transfer uses swaplfnl with supported EBCDIC character sets. Using swaplfnl changes the behavior of the character set mapping from and to the EBCIDIC LF 0x25 character. However, this can sometimes result in a mapping that is not desired. Use noswaplfnl to override this behavior.
- -skeep
- Optional. Specifies that trailing spaces are kept on source records that are read from a fixed-length-format record-oriented file (for example, a z/OS data set) as part of a text mode transfer. If you do not specify this parameter, trailing spaces are stripped from source records.
- -srdb delimiter
- Optional. For source files that are record oriented (for example, z/OS data sets), specifies one or more byte values to insert as the delimiter when appending records into a binary file. You must specify each value as two hexadecimal digits in the range 00-FF, prefixed by x. Separate multiple bytes with commas. For example:
or-srdb x0A
You must configure the transfer in binary mode.-srdb x0D,x0A
- -srdp position
Optional. Specifies the position to insert source record delimiters. You can specify the -srdp parameter only if you also specify the -srdb parameter.
Specify one of the following options:- prefix
- The delimiters are inserted at the start of each record.
- postfix
- The delimiters are inserted at the end of each record. This is the default option.
- -sq
Optional. Specifies that the source of a transfer is a queue.
If you want to invoke any of the IBM MQ Managed File Transfer transfer I/O user exits that you have defined against an agent, do not specify the-sq parameter in a transfer. Using the -sq parameter prevents the transfer I/O user exits from being invoked for the source and means that the standard IBM MQ Managed File Transfer I/O is used instead.
- -sqgi
Optional. Specifies that the messages are grouped by WebSphere MQ group ID. The first complete group is written to the destination file. If this parameter is not specified, all messages on the source queue are written to the destination file.
You can specify the -sqgi parameter only if you also specify the -sq parameter.
- -sqdttext_delimiter
Optional. Specifies a sequence of text to insert as the delimiter when appending multiple messages to a text file. You can include Java escape sequences for String literals in the delimiter. For example,
-sqdt \u007d\n
.The text delimiter is encoded to binary format by using the source encoding of the transfer. Each message is read in binary format. The encoded delimiter is prepended or appended in binary format to the message (as specified by the -sqdp parameter) and the result is transferred in binary format to the destination agent. If the source agent code page includes shift-in and shift-out states, the agent assumes that each message is in the shift-out state at the end of the message. At the destination agent the binary data is converted in the same way as a file to file text transfer.
You can specify the -sqdt parameter only if you also specify the -sq parameter and the value
text
for the -t parameter.- -sqdbhexadecimal_delimiter
Optional. Specifies one or more byte values to insert as the delimiter when appending multiple messages to a binary file. Each value must be specified as two hexadecimal digits in the range
00-FF
, prefixed byx
. Multiple bytes must be comma-separated. For example,-sqdb x08,xA4
.You can specify the -sqdb parameter only if you also specify the -sq parameter. You cannot specify the -sqdb parameter if you also specify the value
text
for the -t parameter.- -sqdp position
Optional. Specifies the position of insertion of source text and binary delimiters. You can specify the -sqdp parameter only if you have also specified one of the -sqdt and -sqdb parameters.
Specify one of the following options:- prefix
- The delimiters are inserted at the start of each message
- postfix
- The delimiters are inserted at the end of each message. This is the default option.
- -sqwtwait_time
- Optional. Specifies the time, in seconds, to wait for one of the following conditions to be met:
- For a new message to appear on the queue
- If the -sqgi parameter was specified, for a complete group to appear on the queue
For information about using the -sqwt parameter, see Guidance for specifying a wait time on a message-to-file transfer.
You can specify the -sqwt parameter only if you also specify the -sq parameter.
- source_specification
- One or more file specifications that determine the source, or
sources, for the file transfer.
Required if you specify one of the -df, -dd, -dp, -dq, -du, or -ds parameters. If you specify the -td parameter, do not specify source_specification.
If you have not specified the -sq parameter, source_specification is one or more file specifications that determine the source, or sources, for the file transfer. File specifications can take one of five forms and can include wildcard characters. For more information about wildcard characters, see Using wildcard characters. You can escape asterisks that are part of the file specification by using two asterisk characters (**) in the file specification.
You can specify multiple source file specifications separated by the space character. However, if you specify multiple source specifications for the -df or -ds parameters and also specify -de overwrite, the destination will contain only the data for the source file that you specified last. If you do not specify -de overwrite the transfer can only be partially successful. If the destination file did not previously exist, it will contain the data for the source file that you specified first.
To transfer files that contain spaces in their file names, for exampleEach file specification must be in one of the following categories:a b.txt
to filec d.txt
, place double quotation marks around the file names that contain spaces. Specify the following text as part of the fteCreateTransfer command:-df "c d.txt" "a b.txt"
- File names
- The name of a file, expressed in the appropriate notation for the system where the source agent is running. When a file name is specified as a source file specification, the contents of the file are copied.
- Directories
- The name of a directory, expressed in the appropriate notation for the system where the source agent is running. When a directory is specified as a source file specification, the contents of the directory are copied. More precisely, all files in the directory and in all its subdirectories, including hidden files, are copied.
- Sequential data set
- (z/OS only). The name of
a sequential data set or partitioned data set member. Denote data
sets by preceding the data set name with two forward slash characters
(//).
If you specify a protocol bridge agent as your source agent, you cannot then specify a data set as the source file specification.
- Partitioned data set
- (z/OS only). The name of
a partitioned data set. Denote data set names by preceding the data
set name with two forward slash characters (//).
If you specify a protocol bridge agent as your source agent, you cannot then specify a data set as the source file specification.
- File name or directory at a Connect:Direct node
- (Connect:Direct bridge
agent only). The name of a Connect:Direct node, a colon
character (:), and a file or directory path on the system that is
hosting the Connect:Direct node. For example, connect_direct_node_name:file_path.
If the source agent is a Connect:Direct bridge agent, it will only accept source specifications in this form.
Note: Wildcard characters are not supported in file paths when the source agent is a Connect:Direct bridge agent. - File name or directory on a protocol file server
- The name of a protocol file server, a colon character (:), and
a file or directory path on the protocol server system. For example, protocol_server:file_path.
If you do not specify a protocol server, the default protocol server is used.
- If you specify the -sq parameter, source_specification is the name of a local queue on the source agent queue manager. You can specify only one source queue. The source queue is specified in the format:
The queue manager name is not included in the source queue specification, because the queue manager must be the same as the source agent queue manager.QUEUE_NAME
- If the source
agent is on z/OS, source files
that start with
//
are assumed to be z/OS partitioned data sets.
Other parameters
- -? or -h
- Optional. Displays command syntax.
Examples
In this basic example, the file originalfile.txt is transferred from AGENT1 to AGENT2 on the same system and renamed to transferredfile.txtfteCreateTransfer -sa AGENT1 -da AGENT2 -df C:\import\transferredfile.txt C:\export\originalfile.txt
In this example, the files originalfile.txt and originalfile2.txt are transferred from AGENT1 to AGENT2 on the same system, to the
directory C:\import
fteCreateTransfer -sa AGENT1 -da AGENT2 -dd C:\import C:\export\originalfile.txt C:\export\originalfile2.txt
In this example, the file originalfile.txt is transferred from AGENT1's system to
AGENT2's system. The file transfer is scheduled to take place at 09:00
based on the system time of the source agent's system and occurs every
two hours four times:fteCreateTransfer -sa AGENT1 -sm QM_JUPITER -da AGENT2 -dm QM_NEPTUNE
-tb source -ss 09:00 -oi hours -of 2 -oc 4
-df C:\import\transferredfile.txt C:\export\originalfile.txt
In this example, the file originalfile.txt is transferred from AGENT1 to AGENT2, on condition that the file A.txt exists on AGENT1:fteCreateTransfer -sa AGENT1 -sm QM_JUPITER -da AGENT2 -dm QM_NEPTUNE
-tr file=exist,C:\export\A.txt -df C:\import\transferredfile.txt C:\export\originalfile.txt
fteCreateTransfer -t text -sa AGENT1 -da AGENT2
-ds "//TRANS.FILE.TXT;RECFM(V,B);BLKSIZE(6144);LRECL(1028);
SPACE(5,1)" C:\export\originalfile.txt
fteCreateTransfer -t text -sa AGENT1 -da AGENT2 -df /tmp/IEEUJV.txt "//'SYS1.SAMPLIB(IEEUJV)'"
fteCreateTransfer -sa AGENT1 -da BRIDGE1 -df accountshost.ibm.com:/tmp/file.bin /tmp/file.bin
.txt
are transferred to directory C:\import
on AGENT2. The file names remain unchanged.fteCreateTransfer -sa AGENT1 -da AGENT2 -dd C:\import *.txt
.txt
are transferred to directory C:\import
on AGENT2. The file names remain unchanged.fteCreateTransfer -sa AGENT1 -da AGENT2 -dd C:\import "*.txt"
fteCreateTransfer -sa AGENT1 -da AGENT2 -dfa NAME1(VALUE1);NAME2(VALUE2) -dd c:\adx_test xyz.tx
fteCreateTransfer -sa AGENT1 -da AGENT2 -dfa NAME1(VALUE1) -dfa NAME2(VALUE2) -dd c:\adx_test xyz.tx
Return codes
Return code | Description |
---|---|
0 | Command completed successfully. |
1 | Command ended unsuccessfully. |
2 | Command ended with a timeout. The command sent a message to the agent, but the agent did not respond within the time specified. |
20 | Command completed with partial success and some files were transferred. |
21 | The queue manager that the fteCreateTransfer command was connected to was stopped before the transfer result was determined. |
40 | Failed. None of the files specified were transferred. |
41 | The transfer was canceled. |
42 | The transfer did not take place because the transfer was conditional and the required condition was not met. |
43 | The transfer request message was malformed. |
44 | The source agent did not have sufficient capacity to carry out the transfer. |
45 | The destination agent did not have sufficient capacity to carry out the transfer. |
46 | The number of files that are being transferred exceeded the source agent's limit. |
47 | The number of files transferred exceeds the destination agent's limit. |