fte:filespec
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, directories, or data sets to move or copy.
Nested by:
- The fte:filecopy task
- The fte:filemove task
Attributes
Source specification attributes
- 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.
You 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
- 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. 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 is used. You must specify a valid queue name that exists on the queue manager.
If you specify the dstqueue attribute, you cannot specify the srcqueue attributes because these attributes are mutually exclusive.
The dstqueue attribute is not supported when the destination agent is a protocol bridge agent.
- srcencoding
- Optional. The character set encoding used by the file to transfer.
You can specify this attribute only when the conversion attribute is set to a value of text.
If you 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. This attribute is available only if you have enabled
the Version 7.0.4.1 function. 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.
You 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". You can specify the srcmsgdelimbytes attribute only if you have also specified the srcqueue attribute. You cannot specify the srcmsgdelimbytes attribute if you 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. You 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. You can only specify the srcmsgdelimtext attribute if you 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.
You can specify the srcmsgdelimposition attribute only if you have also specified one of the srcmsgdelimbytes or srcmsgdelimtext attributes.
- srcmsggroups
- Optional. Specifies that the messages are grouped by WebSphere 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. You 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. This attribute is available only if you have enabled
the Version 7.0.4.1 function. 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:
You 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. You cannot specify the srcrecdelimbytes attribute if you have also specified the value text for the conversion attribute.srcrecdelimbytes="x08,xA4"
- srcrecdelimpos
- Optional. This attribute is available only if you have enabled
the Version 7.0.4.1 function. 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.
- dstencoding
- Optional. The character set encoding to use for the transferred
file.
You 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.
You can specify this attribute only when the conversion attribute is set to a value of text.
If you 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 WebSphere MQ group ID; the
last message in the group has the WebSphere MQ
LAST_MSG_IN_GROUP flag set. The format for specifying a hexadecimal
byte as a delimiter is xNN, 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 dstmsgdelimbytes attribute only if you have also specified the dstqueue attribute and the transfer is in binary mode. You 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 WebSphere MQ
group ID; the last message in the group has the WebSphere MQ LAST_MSG_IN_GROUP flag set.
The format for specifying a regular expression as a delimiter is a
regular expression enclosed in parentheses, (regular_expression),
or enclosed in double quotation marks, "regular_expression".
For more information, see Regular expressions used by WebSphere MQ File Transfer Edition.
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 specify the dstmsgdelimpattern attribute only if you have also specified the dstqueue attribute and the transfer is in text mode. You 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.
You can specify the dstmsgdelimposition attribute only if you 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. You can specify the dstmsgincludedelim attribute only if you 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.
You 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 WebSphere 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.
You 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 WebSphere MQ group ID; the last message
in the group has the WebSphere MQ
LAST_MSG_IN_GROUP flag set. The size of the messages is specified
by the value of dstmsgsize. The format of dstmsgsize is <length><units>,
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.
You can specify the dstmsgsize attribute only if you have also specified the dstqueue attribute. You 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.
- 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"/>