fteCreateTemplate (create new file transfer template)

Purpose

The transfer template that you create using the fteCreateTemplate command is not the same as the XML message that you create using the -gt parameter on the fteCreateTransfer command. You cannot use the two different types of template interchangeably.

You can run the fteCreateTemplate command from any system that can connect to the IBM MQ network and then route to the coordination queue manager. Specifically for the command to run, you must have installed Managed File Transfer on this system and you must have configured the Managed File Transfer component on this system to communicate with the IBM MQ network.

From IBM MQ 9.2.4, this command uses the coordination.properties file to connect to the coordination queue manager for the Managed File Transfer topology. If the coordination.properties file contains the coordinationQMgrHost property, then the command connects to the coordination queue manager using the CLIENT transport. Otherwise, the command connects to the coordination queue manager using the BINDINGS transport. For more information, see The MFT corodination.properties file.

Note: This change does not apply to you if you are using the IBM MQ 9.2 Long Term Support release, or if you are using a Continuous Delivery release prior to IBM MQ 9.2.4, in which case the command still connects to the command queue manager.

You can specify multiple source files for a file transfer but only one destination agent; transferring one file to multiple destination agents is not supported. However, you can transfer multiple source files to multiple destination files on a single destination agent.

For guidance about how to transfer files, see Guidelines for transferring files.

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 as shown in the final two examples Examples, or escape the special characters using the escape sequence of the command shell.

Relative paths

The fteCreateTemplate command supports the use of relative file paths. On distributed systems and z/OS® UNIX System Services by default paths are considered to be relative to the home directory of the user that the agent is running as. To change the directory that path names are evaluated relative to, set the transferRoot 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:

transferRoot=directory_name

You must escape Windows paths or write them in UNIX format. For example, specify C:\TransferRoot as C:\\TransferRoot or C:/TransferRoot.

On z/OS, by default the user name that the agent is currently 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

-sa source_agent_name

Optional. The name of the agent that the source file is transferred from. If you do not specify this agent name when you create the template, you must specify the source agent name when you use the template.

-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 used is determined by the set of configuration options in use, based on the source agent name. If the queue manager name cannot be determined using these options, the transfer template creation fails. For example, the template creation fails if the agent.properties file for the source agent cannot be found.

-da destination_agent_name

Optional. The name of the agent that the file is transferred to. If you do not specify the destination agent name when you create the template, you must specify the destination agent name when you use the template.

-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 used is determined by the set of configuration options in use, based on the destination agent name. If the queue manager name cannot be determined using these options, the transfer template creation fails. For example, the template creation fails if the agent.properties file for the destination agent cannot be found.

-td transfer_definition_file

Optional. The name of the XML document that defines one or more source and destination file specifications for the transfer.

One of the -td, -df, -dd, -ds, -dq, -du, and -dp parameters is required. If you specify the -td parameter, you cannot specify source files, or specify the -df, -dd, -ds, -dp, -dq, -du, -sd, -r, -de, -t, or -cs parameters.

The fteCreateTemplate 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.

Alternatively, this parameter can be the name of the XML document that contains a managed transfer request. An XML task definition is created with the -gt parameter of the fteCreateTransfer command.

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. Specify a file name that is valid on the system where the destination agent is running.

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.

One of the -td, -df, -dd, -ds, -dq,-du, and -dp parameters is required. If you specify the -df parameter, you cannot specify the -td, -dd, -dp, -dq, -du, or -ds parameters because these parameters are mutually exclusive.

-dd destination_directory

Optional. The name of the directory the file is transferred to. Specify a directory name that is valid 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.

One of the -td, -df, -dd, -ds, -dq, -du, and -dp parameters is required. If you specify the -dd parameter, you cannot specify the -td, -df, -dp, -dq, -du, or -ds parameters because these parameters are mutually exclusive.

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

One of the -td, -df, -dd, -ds, -dq, -du, and -dp parameters is required. If you specify the -ds parameter, you cannot specify the -td, -dd, -df, -dq, -du, or -dp parameters because these parameters are mutually exclusive.

The syntax for the data set name is as follows:

 //data_set_name{;attribute;..;attribute} 

or

 //pds_data_set_name(member_name){;attribute;..;attribute}

That is, a data set name specifier prefixed with // and optionally followed by a number of attributes separated by semicolons.

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.

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), where numeric_file_descriptor is a file descriptor 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. Note 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 bpxwdynAllocAdditionalOptions property in the agent.properties file. For a list of these properties, see BPXWDYN properties you must not use with MFT.

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 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 -ds parameter is not supported when the destination agent is a protocol bridge agent.

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

One of the -td, -df, -dd, -ds, -dq, -du, and -dp parameters is required. If you specify the -dp parameter, you cannot specify the -td, -dd, -df, -dq, -du, or -ds parameters because these parameters are mutually exclusive.

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.

-du destination_user

Optional. The name of the user whose destination file space the files are transferred into. .

One of the -td, -df, -dd, -ds, -dp, -du, and -dq parameters is required. If you specify the -du parameter, you cannot specify the -td, -dd, -df, -dp, -dq, or -ds parameters because these parameters are mutually exclusive.

The -du parameter is not supported when the destination agent is a protocol bridge agent or a Connect:Direct bridge agent.

-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, using the format QUEUE@QUEUEMANAGER. If you do not specify a queue manager name, the destination agent queue manager name is used if you have not set the enableClusterQueueInputOutput agent property to true. If you have set the enableClusterQueueInputOutput agent property to true, the destination agent uses standard IBM MQ resolution procedures to determine where the queue is located. You must specify a valid queue name that exists on the queue manager.

One of the -td, -df, -dd, -ds, -dp, -du, and -dq parameters is required. If you specify the -dq parameter, you cannot specify the -td, -dd, -df, -dp, -du, or -ds parameters because these parameters are mutually exclusive.

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.

-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 take from the DefPersistence attribute of the destination queue.

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

-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 created by the transfer.

false

Does not set message properties on the first message created by the transfer. This is the default value.

You can only specify the -qmp parameter if you have also specified 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 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 you specify the value text for the -t parameter and the file 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 only specify the -qs parameter if you have also specified the -dq parameter. You can only specify one of the -qs, -dqdb, and -dqdt parameters.

-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 only specify the -dqdb parameter if you have also specified the -dq parameter and the transfer is in binary mode. You can only specify one of the -qs, -dqdb, and -dqdt parameters.

-dqdt pattern

Optional. Specifies the 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 enclosed in parentheses, (regular_expression). The value of this parameter is evaluated as a Java 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 using the maxDelimiterMatchLength agent property. For more information, see Advanced agent properties.

You can only specify the -dqdt parameter if you have also specified the -dq parameter and the value text for the -t parameter. You can specify only one of the -qs, -dqdb, and -dqdt parameters.

-dqdp

Optional. Specifies the expected position of destination text and binary delimiters when splitting files. You can only specify the -dqdp parameter if you have also specified 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.

-qi

Optional. Specifies whether to include the delimiter that is used to split the file into multiple messages in the messages. If -qi is specified, the delimiter is included at the end of the message that contains the file data preceding the delimiter. By default the delimiter is not included in the messages.

You can only specify the -qi parameter if you have also specified one of the -dqdt and -dqdb parameters.

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

-sd source_file_disposition

Optional. Specifies the action that is taken on a source file when that source file has successfully been 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 file is deleted from the source system after the source file is successfully transferred.

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.

-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 0 and by default the transfer uses the priority level of the source agent.

This value matches the message priority value used by 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.

-rt transfer_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 transferRecoveryTimeout property to the agent.properties file .

-p configuration_options

Optional. This parameter determines the set of configuration options that is used to create the transfer template. 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 associated with this non-default coordination queue manager.

If you do not specify this parameter, the set of configuration options based on the default coordination queue manager is used.

-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 directories that match the wildcard character are transferred only if you have specified 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.

-t

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. The exact conversions performed depend on the operating systems of the source agent and destination agent.

For example, a file 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.

-cs

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.

-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. The value of 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 source system. 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 recommended to use resource monitoring. You can create a resource monitor 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:

fteCreateTemplate -tn JUPITER_AGENT_TRIGGER_TEST_TEMPLATE -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.

-tl

Optional. Specifies whether trigger failures are logged. Specify one of the following options:

yes

Log entries are created for failed triggered transfers. This is the default behavior even if you do not specify the -tl parameter.

no

No log entries are created for failed triggered transfers.

-md

Optional. Specifies the user-defined metadata that is passed to the exit points of the agent. The -md parameter can take one or more name-value pairs separated by commas. Each name pair consists of name=value. You can use the -md parameter more than once in a command.

On z/OS, spaces represent delimiters so you must use underscores to separate values. For example, use kw=text1_text2_text3 rather than kw="text1 text2 text3"

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

-jn job_name

Optional. A user-defined job name identifier that is added to the log message when the transfer has started.

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

-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 has been 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 using the 24-hour clock:

yyyy-MM-ddThh:mm

hh:mm

-tn template_name

Required. The name of the template that you want to create. Use a descriptive string that allows you to select the correct template for transfers at a later date. There is no specific limit to the length of this string, but be aware that excessively long names might not be displayed properly in some user interfaces.

Do not create multiple templates with the same name.

-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 only specify the -sqgi parameter if you have also specified 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.

You can only specify the -sqdt parameter if you have also specified 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 only specify the -sqdb parameter if you have also specified the -sq parameter. You cannot specify the -sqdb parameter if you have also specified the value text for the -t parameter.

-sqdp

Optional. Specifies the position of insertion of source text and binary delimiters. You can only specify the -sqdp parameter 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 be put on the queue
• If the -sqgi parameter was specified, for a complete group to be put on the queue

If neither of these conditions are met within the time 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.

You can only specify the -sqwt parameter if you have also specified the -sq parameter.

-sq

Optional. Specifies that the source of a transfer is a queue.

-mquserid user_id

Optional. Specifies the user ID to authenticate with the coordination queue manager.

-mqpassword password

Optional. Specifies the password to authenticate with the coordination 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.

source_specification

Required if you have specified one of the -df, -dd, -dp, -dp, 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 are space delimited. File specifications can take one of five forms and can include wildcard characters. For more information about wildcard characters in WMQFTE, 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.
  To transfer files containing spaces in their file names, place double quotation marks around the file names that contain spaces. For example to transfer file a b.txt to file c d.txt specify the following text as part of the fteCreateTemplate command:

  
  -df "c d.txt" "a b.txt"

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

  File names

  The name of a file, expressed using 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 using 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 DIR1/* DIR2

  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 (//).

  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 (//).

  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.

• If you have specified 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.

-? or -h

Optional. Displays command syntax.

Return codes