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, and a destination. Typically this element is used when expressing a set of files or directories to move or copy.
Nested by:
- The fte:filecopy task
- The fte:filemove task
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.
- dstfile
- Specifies a file as the destination for a file operation.
- dstfilespace
- Specifies a file space as the destination for a file operation.
- 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.
Source option attributes
- 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
If you do not specify the srcencoding attribute, the character set of the source system is used for text transfers.text.
- 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.
text
. If you do not specify the srceol attribute, text transfers automatically determine the correct value based on the operating system of the source agent. -
- 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 valuetext
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 oftext
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 IBM® 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.
- 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
- dstAttributes
- Optional. Specifies a semicolon-separated list of file attributes
associated with the destination files in the transfer. You can specify
attributes with or without a value.
For example, attributes without a value:
dstAttributes="ATTRIBUTE1;ATTRIBUTE2"
For example, attributes with a value:dstAttributes="ATTRIBUTE1(VALUE);ATTRIBUTE2(VALUE)"
For example, one attribute with a value and one attribute without a value:dstAttributes="ATTRIBUTE1;ATTRIBUTE2(VALUE)"
For information about file attributes for WebSphere MQ Managed File Transfer on IBM 4690, see File distribution attributes.
- 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
If the dstencoding attribute is not specified, the character set of the destination system is used for text transfers.text.
- 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
If you do not specify the dsteol attribute, text transfers automatically determine the correct value based on the operating system of the destination agent.text.
-
- dstmsgdelimbytes
- Optional. Specifies the hexadecimal delimiter to use when splitting
a binary file into multiple messages. All the messages have the same IBM WebSphere MQ group ID; the
last message in the group has the IBM 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 IBM WebSphere MQ
group ID; the last message in the group has the IBM 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 Managed File Transfer.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 IBM 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 IBM WebSphere MQ group ID; the last message
in the group has the IBM 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 totext
.fail
– do not continue with the transfer operation. The file is recorded as having failed to transfer. This is the default.
- 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.
MD5
is used. - 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. Thesrcencoding
,dstencoding
,srceol
anddsteol
attributes influence the conversion that is applied.
binary
is specified. - overwrite
- Optional. Determines whether an existing destination file can be overwritten by the operation.
When you specify a value of
true
, any existing destination file are overwritten. When you specify a value offalse
, the existence of a duplicate file at the destination results in the operation failing. If the overwrite attribute is not specified, a default value offalse
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 offalse
, the transfer does not recurse into subdirectories. If the recurse attribute is not specified, a default value offalse
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"/>