fteCreateTransfer (start a new file transfer)

Purpose

For guidance about how to transfer files, see Guidelines for transferring files. For the z/OS platform, you can transfer text files, data sets, and generation data groups (GDGs).

You can run the fteCreateTransfer command from any system that can connect to the IBM® MQ network and then route to the source agent queue manager. Specifically, for the command to run, you must install a Managed File Transfer component (either Service or Agent) on this system and configure the Managed File Transfer component on this system to communicate with the IBM MQ network.

This command uses a properties file called command.properties to connect to the IBM 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 MFT 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 MFT.

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.

On z/OS, by default the user name that the agent is running under is added as a high-level qualifier prefix to data set specifications that have not been fully qualified. For example: //ABC.DEF. To change the value that is added as a prefix to the data set name, set the transferRootHLQ property in the agent.properties file. This file is located in the MQ_DATA_PATH/mqft/config/coordination_qmgr/agents/agent_name directory. Add the following line to the file:

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.

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

-gt transfer_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 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
• -cs checksum
• -de destination_file_behavior
• -dq destination_queue
• -t transfer_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.

This parameter is not supported in the REST API.

Parameters for scheduling transfers

-ss schedule_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

-of occurrence_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.

-oc occurrence_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.

-es schedule_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:

condition,namelist

where condition is one of the following values:

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, or in the CreateTransfer REST API.

-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

-jn job_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 enableUserMetadataOptions: Supported MFT 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.

Any user metadata provided on the fteCreateTransfer command is made available as an environment variable to a process called through the presrc, postsrc, predst, and postdst parameters.

For example, the following transfer results in an environment variable called procname being set to compress (procname=compress) and is available to the proc.sh script:

fteCreateTransfer -sa ESBPA1 -sm ESBP10 -da INFOPA1 
-dm INFOP1 -md procname=compress -df /home/mqm/hosts.out /etc/hosts -de overwrite 
-postdst /home/mqm/proc.sh

-cs checksum

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

<checksum method="none"></checksum>

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.

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 IBM 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 IBM MQ message traffic to take priority.

-qmp boolean

Optional. Specifies whether the first message written to the destination queue by the transfer has IBM 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.

You can specify the -qmp parameter only if you also specify the -dq parameter. For more information, see MQ message properties set by MFT on messages written to destination queues

-qs message_size

Optional. Specifies whether to split the file into multiple fixed-length messages. All the messages have the same IBM MQ group ID; the last message in the group has the IBM 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 lengthunits, 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.

If the file is transferred in text mode, and is in a double-byte character set or multibyte character set, the file is split into messages on the closest character boundary to the specified message size.

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.

-p configuration_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.

This parameter is not supported in the REST API interface.

-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 return code will be 0, unless you used the -w option on the command line.

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 or 3. If you do not specify a timeout value, or you specify a timeout value of -1, then the command waits until the agent responds.

The REST service does not provide an equivalent option for this parameter, as ideal wait time is not recommended in a REST service implementation.

-rt recovery_timeout

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,

-rt 21600

indicates that the agent keeps trying to recover the transfer for 6 hours from when it enters recovery. The maximum value for this parameter 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, you can add a property to the The agent.properties file.

Parameters for invoking programs

For more information about how you can start a program from Managed File Transfer, see Specifying programs to run with MFT. 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:

[type:]commandspec[,[retrycount][,[retrywait][,successrc]]]

In this syntax, the variables are:

type

Optional. Valid values are executable, antscript, and jcl. The default value is executable.

The jcl value is only applicable when targeted at an agent in a z/OS environment. In this case, the command refers to either a ZFS file, or a QSAM-readable dataset, or a member of a PDS. The contents should be JCL that can be submitted.

commandspec

Required. The command specification. Use one of the following formats:

• Type executable: command[(arg1,arg2,...)]

  If arguments contain variable substitutions, like ${FilePath} or ${FileName}, which are valid only if the substitution is initiated by a resource monitor, the variables are substituted with the first item in the transfer request.

  For example, if a transfer request consists of files "reports01.csv, reports02.csv, reports03.csv", and the destination directory is "/output", the following transfer request:

  
  fteCreateTransfer -sa 1 -da 2 -presrc "executable:archive(${FileName})" 
  -dd TargetDir "${FilePath}" -gt task.xml

  is replaced with

  
  fteCreateTransfer -sa 1 -da 2 -presrc "executable:archive(reports01.csv)" 
  -dd TargetDir "/ouptut" -gt task.xml

• Type antscript: command[(name1=var1|target1,name2=var2|target2,...)]
• Type jcl: command

where:

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.

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.

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:

[>|<|!]value

where

>

Optional. A greater than test of the value.

<

Optional. A less than test of the value.

!

Optional. A not equal test of the value.

value

Required. A valid integer.

If you do not specify this parameter, a default value of 0 is used.

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

  protocol_server:file_path

  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.
• If you want to invoke any of the 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.

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

  
  protocol_server:directory_path

  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.

• If you want to invoke any of the 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:

 //data_set_name{;attribute(value);..;attribute(value)} 

or

 //pds_data_set_name(member_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.

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:

CD_NODE1://'OBJECT.LIB';RECFM(F,B);BLKSIZE(800);LRECL(80)

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.

For transfers that only involve 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 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 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 MFT 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 MFT.

The -ds parameter is not supported when the destination agent is a protocol bridge agent.

If you want to invoke any of the 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 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 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 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 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 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.

You can specify the -dqp parameter only if you also specify the -dq parameter.

-dqdb hexadecimal_delimiter

Optional. Specifies the hexadecimal delimiter to use when splitting a binary file into multiple messages. All the messages have the same IBM MQ group ID; the last message in the group has the IBM MQ LAST_MSG_IN_GROUP flag set. The format for specifying a hexadecimal byte as a delimiter is xNN, where N is a character in the range 0-9 or a-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 IBM MQ group ID; the last message in the group has the IBM 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, regular_expression. For more information, see Regular expressions used by MFT.

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.

-t transfer 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 on z/OS.

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 Available code pages for MFT.

noswaplfnl

By default 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 what you want. 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 the following platforms:

• AIX® and Linux® platforms
• z/OS UNIX System Services files

When you use the standard EBCDIC code pages that are supplied with 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 Windows.

If the destination of the transfer is a z/OS data set, this option is ignored.

-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. When transferring to an IBM MQ 8.0 Managed File Transfer agent running on 4690, this parameter is used to specify 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:

-dfa ATTRIBUTE1;ATTRIBUTE2(VALUE)

You can use the -dfa parameter more than once in a command.

For more information about file attributes on 4690, see File distribution attributes in the IBM MQ 8.0 documentation.

Parameters for security

-mquserid user_id

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 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 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 Managed File Transfer handles wildcard characters, see Using wildcard characters with MFT

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 Available code pages for MFT.

noswaplfnl

By default 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 what you want. 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:

 -srdb x0A 

or

 -srdb x0D,x0A

You must configure the transfer in binary mode.

-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 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 Managed File Transfer I/O is used instead.

-sqgi

Optional. Specifies that the messages are grouped by IBM 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.

-sqdt text_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.

-sqdb hexadecimal_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 by x. 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.

-sqwt wait_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

If neither of these conditions is met within the time that is specified by wait_time, the source agent stops reading from the queue and completes the transfer. If the -sqwt parameter is not specified, the source agent stops reading from the source queue immediately if the source queue is empty or, in the case where the -sqgi parameter is specified, if there is no complete group 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, 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 with MFT. 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 example a b.txt to file c 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"

  Each file specification must be in one of the following categories:

  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.

  For example, to copy the contents of DIR1 to DIR2 only, specify fteCreateTransfer ... -dd DIR2 DIR1/*

  Sequential data set

  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

  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:

  QUEUE_NAME

  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.
• 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.

Return codes