fte:filespec Ant nested element
The fte:filespec parameter is used as a nested element in other tasks. Use fte:filespec to describe a mapping between one or more source files, directories or data sets, and a destination. Typically this element is used when expressing a set of files or directories or data sets to move or copy.
Nested by:
- The fte:filecopy task
- The fte:filemove task
Source specification attributes
You must specify one of srcfilespec or srcqueue.
- srcfilespec
- Specifies the source of the file operation. The value of this attribute can include a wildcard.
- srcqueue
- Specifies the source of the transfer is a queue. The transfer moves data from messages stored on
the queue specified by this attribute. We cannot specify this attribute if the
fte:filespec task is nested within the fte:filecopy
task.
The srcqueue attribute is not supported when the source agent is a protocol bridge agent.
Destination specification attributes
You must specify one of dstdir, dstds, dstfilespace, dstfile, dstqueue or dstpds.
- dstdir
- Specifies a directory as the destination for a file operation.
- dstds
- Specifies a data set as the destination for a file operation.
This attribute is supported only when the destination agent is running on the z/OS® platform.
- dstfile
- Specifies a file as the destination for a file operation.
- dstfilespace
- Specifies a file space as the destination for a file operation.
- dstpds
- Specifies a partitioned data set as the destination for a file operation.
This attribute is supported only when the destination agent is running on the z/OS platform.
- dstqueue
-
Specifies a queue as the destination for a file to message operation. We can optionally include a queue manager name in this specification, using the format QUEUE@QUEUEMANAGER. If we do not specify a queue manager name the destination agent queue manager is used if we have not set the enableClusterQueueInputOutput agent property to true. If the enableClusterQueueInputOuput property is set to true, the destination agent uses standard IBM MQ procedures to determine where the queue is located. You must specify a valid queue name that exists on the queue manager.
Source option attributes
- srcencoding
- Optional. The character set encoding used by the file to transfer.
We can specify this attribute only when the conversion attribute is set to a value of text.
If we do not specify the srcencoding attribute, the character set of the source system is used for text transfers. - srceol
- Optional. The end of line delimiter used by the file being transferred. The valid values are as
follows:
- CRLF - Use a carriage return character followed by a line-feed character as the end of line delimiter. This convention is typical for Windows systems.
- LF - Use a line-feed character as the end of line delimiter. This convention is typical for UNIX systems.
- srckeeptrailingspaces
- Optional. Determines whether trailing spaces are kept on source records read from a
fixed-length-format data set as part of a text mode transfer. The valid values are as follows:
- true - trailing spaces are kept.
- false - trailing spaces are stripped.
We can specify this attribute only if you also specify the srcfilespec attribute and you set the conversion attribute to a value of text.
- srcmsgdelimbytes
- 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,
srcmsgdelimbytes=
x08,xA4
. We can specify the srcmsgdelimbytes attribute only if we have also specified the srcqueue attribute. We cannot specify the srcmsgdelimbytes attribute if we have also specified the value text for the conversion attribute. - srcmsgdelimtext
- Optional. Specifies a sequence of text to insert as the delimiter when appending multiple
messages to a text file. We can include Java escape sequences
for String literals in the delimiter. For example, srcmsgdelimtext=
\u007d\n
. The text delimiter is inserted after each message by the source agent. The text delimiter is encoded to binary format using the source encoding of the transfer. Each message is read in binary format, the encoded delimiter is appended in binary format to the message, 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. We can only specify the srcmsgdelimtext attribute if we have also specified the srcqueue attribute and a value of text for the conversion attribute. - srcmsgdelimposition
- Optional. Specifies the position that the text or binary delimiter is inserted into. The valid
values are as follows:
- prefix - the delimiters are inserted into the destination file before the data from each message.
- postfix - the delimiters are inserted into the destination file after the data from each message.
We can specify the srcmsgdelimposition attribute only if we have also specified one of the srcmsgdelimbytes or srcmsgdelimtext attributes.
- srcmsggroups
- Optional. Specifies that the messages are grouped by IBM MQ group ID. The first complete group is written to the destination file. If this attribute is not specified, all messages on the source queue are written to the destination file. We can specify the srcmsggroups attribute only if you have also specified the srcqueue attribute.
- srcqueuetimeout
- Optional. Specifies the time, in seconds, to wait for one of the following conditions to be met:
- For a new message to be written to the queue.
- If the srcmsggroups attribute was specified, for a complete group to be written on the queue.
For information about setting the srcqueuetimeout value, see Guidance for specifying a wait time on a message-to-file transfer.
- srcrecdelimbytes
- Optional. Specifies one or more byte values to insert as the delimiter when appending multiple
records from a record-oriented source file to a binary file. You must specify each value as two
hexadecimal digits in the range 00-FF, prefixed by x. Multiple bytes must be comma-separated. For
example:
srcrecdelimbytes="x08,xA4"
We can specify the srcrecdelimbytes attribute only if the transfer source file is record oriented, for example a z/OS data set, and the destination file is a normal, non-record-oriented file. We cannot specify the srcrecdelimbytes attribute if we have also specified the value text for the conversion attribute. - srcrecdelimpos
- Optional. Specifies the position that the binary delimiter is inserted into. The valid values
are as follows:
- prefix - the delimiters are inserted into the destination file before the data from each source record-oriented file record.
- postfix - the delimiters are inserted into the destination file after the data from each source record-oriented file record.
Destination option attributes
- dstencoding
- Optional. The character set encoding to use for the transferred file.
We can specify this attribute only when the conversion attribute is set to a value of text.
If the dstencoding attribute is not specified, the character set of the destination system is used for text transfers. - dsteol
- Optional. The end of line delimiter to use for the transferred file. The valid values are as
follows:
- CRLF - Use a carriage return character followed by a line-feed character as the end of line delimiter. This convention is typical for Windows systems.
- LF - Use a line-feed character as the end of line delimiter. This convention is typical for UNIX systems.
We can specify this attribute only when the conversion attribute is set to a value of text.
If we do not specify the dsteol attribute, text transfers automatically determine the correct value based on the operating system of the destination agent. - dstmsgdelimbytes
- 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. We 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.
We can specify the dstmsgdelimbytes attribute only if we have also specified the dstqueue attribute and the transfer is in binary mode. We can specify only one of the dstmsgsize, dstmsgdelimbytes, and dstmsgdelimpattern attributes.
- dstmsgdelimpattern
- 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 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. We can change this behavior using the maxDelimiterMatchLength agent property. For more information, see Advanced agent properties.
We can specify the dstmsgdelimpattern attribute only if we have also specified the dstqueue attribute and the transfer is in text mode. We can specify only one of the dstmsgsize, dstmsgdelimbytes, and dstmsgdelimpattern attributes.
- dstmsgdelimposition
- Optional. Specifies the position that the text or binary delimiter is expected to be in. The
valid values are as follows:
- prefix - The delimiters are expected at the beginning of each line.
- postfix - The delimiters are expected at the end of each line.
We can specify the dstmsgdelimposition attribute only if we have also specified the dstmsgdelimpattern attribute.
- dstmsgincludedelim
- Optional. Specifies whether to include the delimiter that is used to split the file into multiple messages in the messages. If the dstmsgincludedelim attribute 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. We can specify the dstmsgincludedelim attribute only if we have also specified one of the dstmsgdelimpattern and dstmsgdelimbytes attributes.
- dstmsgpersist
- Optional. Specifies whether messages written to the destination queue are persistent. The valid
values are as follows:
- true - Write persistent messages to the destination queue. This is the default value.
- false - Write non-persistent messages to the destination queue.
- qdef - The persistence value is taken from the DefPersistence attribute of the destination queue.
We can specify this attribute only when the dstqueue attribute is also specified.
- dstmsgprops
- Optional. Specifies whether the first message written to the destination queue by the transfer
has IBM MQ message properties set. Possible values are:
- true - Set message properties on the first message created by the transfer.
- false - Do not set message properties on the first message created by the transfer. This is the default value.
We can specify this attribute only when the dstqueue attribute is also specified.
- dstmsgsize
- Optional. Specifies whether to split the file into multiple fixed-length messages. All of 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 dstmsgsize. The format of
dstmsgsize 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 - Kibibytes. This is equivalent to 1024 bytes.
- M - Mebibytes. This is equivalent to 1024 kibibytes.
We can specify the dstmsgsize attribute only if we have also specified the dstqueue attribute. We can specify only one of the dstmsgsize, dstmsgdelimbytes, and dstmsgdelimpattern attributes.
- dstunsupportedcodepage
- Optional. Specifies the action to take if the destination queue manager, as specified by the
dstqueue attribute, does not support the code page used when transferring file
data to a queue as a text transfer. The valid values for this attribute are as follows:
- binary - continue the transfer but do not apply code page conversion to the data being transferred. Specifying this value is equivalent to not setting the conversion attribute to text.
- fail - do not continue with the transfer operation. The file is recorded as having failed to transfer. This is the default.
- dsttruncaterecords
- Optional. Specifies that destination records longer than the LRECL data set attribute are truncated. If set to true, the records are truncated. If set to false, the records are wrapped. The default setting is false. This parameter is valid only for text mode transfers where the destination is a data set.
Other attributes
- checksum
- Optional. Determines the algorithm used to checksum transferred files.
- MD5 - use the MD5 hashing algorithm.
- NONE - do not use a checksum algorithm.
- conversion
- Optional. Specifies the type of conversion to apply to the file as it is being transferred.
Possible values are:
- binary - apply no conversion.
- text - apply code page conversion between the source and destination systems. Also apply conversion of line delimiters. The srcencoding, dstencoding, srceol and dsteol attributes influence the conversion that is applied.
- overwrite
- Optional. Determines whether an existing destination file or data set can be overwritten by the operation. When you specify a value of true, any existing destination file or data sets are overwritten. When you specify a value of false, the existence of a duplicate file or data set at the destination results in the operation failing. If the overwrite attribute is not specified, a default value of false is specified.
- recurse
- Optional. Determines whether the file transfer recurses into subdirectories. When you specify a value of true, the transfer recurses into subdirectories. When you specify a value of false, the transfer does not recurse into subdirectories. If the recurse attribute is not specified, a default value of false is specified.
Example
This example specifies a fte:filespec with a source file of file1.bin and a destination file of file2.bin.<fte:filespec srcfilespec="/home/fteuser/file1.bin" dstfile="/home/fteuser/file2.bin"/>