File transfer request message format

File transfers are initiated by XML messages arriving at an agent command queue, typically as a result of a user issuing a file transfer command or by using the IBM MQ Explorer. The transfer request XML must conform to the FileTransfer.xsd schema and have the <request> element as the root element. The FileTransfer.xsd schema document is located in the MQ_INSTALLATION_PATH/mqft/samples/schema directory. The FileTransfer.xsd schema imports fteutils.xsd, which is in the same directory.

File transfer messages can have one of following three root elements:

<request> - for new file transfer requests, managed call requests, or deleting scheduled transfers that are pending
<cancel> - for canceling file transfers in progress
<transferSpecifications> - for specifying multiple transfer file groups, used by the fteCreateTransfer command

For information about specifying multiple transfer groups by using the transferSpecifications element, see Use transfer definition files.

Schema

The following schema describes which elements are valid in a transfer request XML message.

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<xsd:include schemaLocation="fteutils.xsd"/>

    <!--
        Defines the request of a managed transfer and version number
        <request version="1.00" ...
            <managedTransfer>
                ...
            </managedTransfer>
        </request>
     -->
    <xsd:element name="request">
        <xsd:complexType>
            <xsd:choice>
                <xsd:element name="managedTransfer" type="managedTransferType"/>
                <xsd:element name="deleteScheduledTransfer" type="deleteScheduledTransferType" />
                <xsd:element name="managedCall" type="managedCallType"/>
            </xsd:choice>
            <xsd:attribute name="version" type="versionType" use="required" />
        </xsd:complexType>
    </xsd:element>

    <!--
        Defines the cancel request of a managed transfer and version number
        <cancel version="1.00"
                  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                  xsi:noNamespaceSchemaLocation="FileTransfer.xsd">
            <originator>
                <hostName>myMachine</hostName>
                <userID>myUserId</userID>
            </originator>     - Delete a scheduled transfer.
            
            <transfer>
               Transfer ID to Cancel
            </transfer>
        </cancel>
     -->
    <xsd:element name="cancel">
        <xsd:complexType>
            <xsd:sequence>
                <xsd:element name="originator" type="hostUserIDType" maxOccurs="1" minOccurs="1" />
                <xsd:choice> 
                    <xsd:element name="transfer" type="IDType" maxOccurs="1" minOccurs="1" />
                    <xsd:element name="call"     type="IDType" maxOccurs="1" minOccurs="1" />
                </xsd:choice>
                <xsd:element name="reply"      type="replyType"      maxOccurs="1" minOccurs="0" />
            </xsd:sequence>
            <xsd:attribute name="version" type="versionType" use="required" />
        </xsd:complexType>
    </xsd:element>

    <!--
        Defines the transfer definition element structure.
        <transferSpecifications>
            <item ...
            <item ...
        </transferSpecifications>
     -->
    <xsd:element name="transferSpecifications">
        <xsd:complexType>
            <xsd:sequence>
                <xsd:element name="item" type="itemType" minOccurs="1" maxOccurs="unbounded" />
            </xsd:sequence>
        </xsd:complexType>
    </xsd:element>

    <!--
        Define a managed transfer of an instigator and request
        <managedTransfer>

            <originator>
                ...
            </originator>

            <schedule>
                <submit timebase="source"|"UTC">2008-12-07T16:07"</submit>
                <repeat>
                    <frequency interval="hours">2</frequency>
                    <expireTime>2008-12-0816:07</expireTime>
                </repeat>
            </schedule>

            <sourceAgent agent="here" QMgr="near" />
            <destinationAgent agent="there" QMgr="far" />

            <trigger>
            ...
            </trigger>

            <transferSet>
                ...
            </transferSet>
        </managedTransfer>
     -->

     <xsd:complexType name="managedTransferType">
         <xsd:sequence>
            <xsd:element name="originator"       type="origTransferRequestType"  maxOccurs="1" minOccurs="1"/>
            <xsd:element name="schedule"         type="scheduleType"     maxOccurs="1" minOccurs="0"/>
            <xsd:element name="sourceAgent"      type="agentType"        maxOccurs="1" minOccurs="1"/>
            <xsd:element name="destinationAgent" type="agentClientType"  maxOccurs="1" minOccurs="1" />
            <xsd:element name="trigger"          type="triggerType"      maxOccurs="1" minOccurs="0" />
            <xsd:element name="reply"            type="replyType"        maxOccurs="1" minOccurs="0" />
            <xsd:element name="transferSet"      type="transferSetType"  maxOccurs="1" minOccurs="1" />
            <xsd:element name="job"              type="jobType"          maxOccurs="1" minOccurs="0"/>
        </xsd:sequence>
    </xsd:complexType>

    <!--
         This is a modified form of origRequestType which is used on a managed transfer request.
         The hostName and userID are mandatory attributes in this case.
     -->
    <xsd:complexType name="origTransferRequestType">
        <xsd:sequence>
            <xsd:element name="hostName" type="xsd:string" minOccurs="1" maxOccurs="1"/>
            <xsd:element name="userID" type="xsd:string" minOccurs="1" maxOccurs="1"/>
            <xsd:element name="mqmdUserID" type="xsd:string" minOccurs="0" maxOccurs="1"/>
            <xsd:element name="webBrowser" type="xsd:string" minOccurs="0" maxOccurs="1"/>
            <xsd:element name="webUserID" type="xsd:string" minOccurs="0" maxOccurs="1"/>
        </xsd:sequence>
    </xsd:complexType>

    <!--
        Defines the transferset of source and destination agent and one or more files
        <transferset priority="1">
            <metaDataSet>
                <metaData key="keyname">keyvalue</metaData>
                <metaData key="keyname">keyvalue</metaData>
            </metaDataSet>

            <item>
                ...
            </item>
        </transferset>
     -->
    <xsd:complexType name="transferSetType">
        <xsd:sequence>
            <xsd:element name="metaDataSet"         type="metaDataSetType" maxOccurs="1" minOccurs="0" />
            <xsd:element name="preSourceCall"       type="commandActionType" maxOccurs="1" minOccurs="0" />
            <xsd:element name="postSourceCall"      type="commandActionType" maxOccurs="1" minOccurs="0" />
            <xsd:element name="preDestinationCall"  type="commandActionType" maxOccurs="1" minOccurs="0" />
            <xsd:element name="postDestinationCall" type="commandActionType" maxOccurs="1" minOccurs="0" />
            <xsd:element name="item" type="itemType" maxOccurs="unbounded" minOccurs="0" />
        </xsd:sequence>
        <xsd:attribute name="priority" type="priorityType" use="optional" />
    </xsd:complexType>


    <!--
        Define a file pair with source and destination
        <item mode=[binary|text]>
            <source recursive="false" disposition="leave">
                <file>filename</file>
            </source>

            <destination type="file" exist="error">
                <file>filename</file>
            </destination>

        </item>
    -->
    <xsd:complexType name="itemType">
        <xsd:sequence>
            <xsd:element name="source"      type="fileSourceType"       maxOccurs="1" minOccurs="1" />
            <xsd:element name="destination" type="fileDestinationType"  maxOccurs="1" minOccurs="1" />
        </xsd:sequence>
        <xsd:attribute name="mode" type="modeType" use="required" />
        <xsd:attribute name="checksumMethod" type="checkSumMethod" use="required" />
    </xsd:complexType>

    <!--
        Defines the request to delete scheduled file transfer.
        <deleteScheduledTransfer>
            <originator>
                <delete>
                    <hostName>myMachine</hostName>
                    <userID>myUserId</userID>
                </delete>
            </originator>
            <ID>56</ID>
        </deleteScheduledTransfer>
     -->
    <xsd:complexType name ="deleteScheduledTransferType">
        <xsd:sequence>
            <xsd:element name="originator" type="origDeleteType" maxOccurs="1" minOccurs="1" />
            <xsd:element name="ID"         type="idType"         maxOccurs="1" minOccurs="1" />
            <xsd:element name="reply"      type="replyType"      maxOccurs="1" minOccurs="0" />
        </xsd:sequence>
    </xsd:complexType>


    <xsd:complexType name="managedCallType">
        <xsd:sequence>
            <xsd:element name="originator"  type="origRequestType"  maxOccurs="1" minOccurs="1"/>
            <xsd:element name="agent"       type="agentType"        maxOccurs="1" minOccurs="1"/>
            <xsd:element name="reply"       type="replyType"        maxOccurs="1" minOccurs="0" />
            <xsd:element name="transferSet" type="callTransferSetType"  maxOccurs="1" minOccurs="1" />
            <xsd:element name="job"         type="jobType"          maxOccurs="1" minOccurs="0"/>
        </xsd:sequence>
    </xsd:complexType>

    <xsd:complexType name="callTransferSetType">
        <xsd:sequence>
            <xsd:element name="metaDataSet" type="metaDataSetType" maxOccurs="1" minOccurs="0" />
            <xsd:element name="call" type="commandActionType" maxOccurs="1" minOccurs="1" />
        </xsd:sequence>
        <xsd:attribute name="priority" type="priorityType" use="optional" />
    </xsd:complexType>
</xsd:schema>

Understand the transfer request message

The elements and attributes used in transfer request messages are described in the following list:

Element descriptions

<request>

Group element containing all the elements required to specify a file transfer request.


Attribute	Description
version	Specifies the version of this element as supplied by Managed File Transfer.

<managedTransfer>

Group element that contains all the elements required for a single file transfer or single group of file transfers.

<deleteScheduledTransfer>

Group element that contains originator and ID information to cancel a schedule transfer.

<managedCall>

Group element that contains all the elements required for a single managed call of a program or executable.

<ID>

Unique identifier that specifies the transfer request to delete from the list of pending scheduled transfers.

<originator>

Group element that contains the elements specifying the originator of the request.

<hostName>

The host name of the system where the source file is located.

<userID>

The user ID that originated the file transfer.

<mqmdUserID>

Optional. The IBM MQ user ID that was supplied in the message descriptor (MQMD).

<schedule>

Group element describing the scheduled time for the file transfer, the repeat behavior, and when the next occurrence is due.

<submit>

Specifies the date and time that the scheduled transfer is due to start.

Attribute

Description

timebase

Specifies which time zone to use. This attribute can have one of the following values:

source - use the time zone of the source agent
admin - use the time zone of the administrator issuing the command
UTC - use Coordinated Universal Time

timezone

The time zone description according to the timebase value

<repeat>

Group element that contains details about how often a scheduled transfer repeats, how many times a scheduled transfer repeats, and when a scheduled transfer stops repeating.

<frequency>

The time period that must elapse before the transfer repeats.

Attribute

Description

interval

The interval units, which must be one of the following values:

minutes
hours
days
weeks
months
years

<expireTime>

Optional element that specifies the date and time that a repeating scheduled transfer stops. This element and the <expireCount> element are mutually exclusive.

<expireCount>

Optional element that specifies the number of times the scheduled file transfer occurs before stopping. This element and the <expireTime> element are mutually exclusive.

<sourceAgent>

Specifies the name of the agent on the system where the source file is located.


Attribute	Description
agent	Specifies the name of the agent.
QMgr	The name of the agent queue manager.

<destinationAgent>

Specifies the name of the agent on the system we want to transfer the file to.


Attribute	Description
agent	Specifies the name of the agent.
QMgr	The name of the agent queue manager.
hostName	The host name or IP address of the agent queue manager.
portNumber	The port number used for client connections to the destination agent queue manager.
channel	The channel name used to connect to the destination agent queue manager.

<trigger>

Optional element that specifies a condition that must be true for the file transfer to take place.

Attribute

Description

log

A flag indicating whether trigger failures are logged. The valid values are as follows:

yes - log entries are created for failed triggered transfers
no - log entries are not created for failed triggered transfers

<fileExist>

Specifies a comma-separated list of file names located on the same system as the source agent. If a file in this name list satisfies the condition of the trigger, the transfer occurs. This element and the <fileSize> element are mutually exclusive.

Attribute

Description

comparison

Indicates how to evaluate source file names against the name list. The valid values are as follows:

= at least one file name in the name list must match
!= a minimum of one of the files in the name list does not exist

value

Indicates the comparison type:

exist: file must exist

<fileSize>

Attribute

Description

comparison

Indicates how to evaluate source file names against the name list. The valid value is as follows:

>= one of the file names in the name list exists and has a minimum size as specified in the value attribute

value

File size specified as an integer value with units specified as one of the following:

B - bytes
KB - kilobytes
MB - megabytes
GB - gigabytes

(the units value is not case-sensitive)

<reply>

Specifies the name of the temporary reply queue generated for synchronous file transfers (specified with the -w parameter on the command line). The name of the queue is defined by the key dynamicQueuePrefix in the command.properties configuration file or the default of WMQFTE.* if not specified.


Attribute	Description
detailed	Whether detailed transfer result information is required in the reply message. Multiple reply messages for each transfer can be generated. The valid values are as follows: true - detailed reply information is required. The format of the information is the same as that published to the transfer log in the progress messages, that is, the <transferSet> element. For more information, see File transfer log message formats. Detailed reply information is present only when the transfer source agent has the enableDetailedReplyMessages property set to true. false - detailed reply information is not required. The default value is false.
QMGR	The name of the command queue manager on which the temporary dynamic queue is generated to receive replies.
persistent	Whether the message written to the reply queue is persistent. The valid values are as follows: true - the message is persistent false - the message is not persistent qdef - the persistence of the message is defined by the properties of the reply queue The default value is false.

<transferSet>

Specifies a group of file transfers we want to perform together or a group of managed calls that we want to perform together. During transmission <transferSet> is a group element containing <item> elements.


Attribute	Description
priority	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.

<metaDataSet>

Optional group element containing one or more metadata items.

<metaData>

Specifies the user-defined metadata that is passed to the exit points called by the agent. The element contains the metadata value as a string.


Attribute	Description
key	Metadata name as a string

<call>

Group element that contains <command> elements specifying the program or executable to call.

<command>

Specifies the program or executable to call. The command must be located on the agent command path. For more information, see Advanced agent properties. This element can contain optional <argument> elements.


Attribute	Description
name	The name of the command.
successRC	The successful return code that this command returns. Default is 0.
retryCount	The number of times that the command is to be retried if it fails.
retryWait	The time, in seconds, to wait between retries of the command.
type	The type of program to be called. The valid values are antscript, jcl, or executable.

<argument>

Specifies an argument to pass to the command.

<item>

Group element that contains elements specifying the source and destination file names and locations.


Attribute	Description
mode	Specifies the transfer mode as either binary or text.
checksumMethod	Specifies the type of hash algorithm that generates the message digest to create the digital signature. The valid values are MD5 or none.

<source>

Group element that specifies files on the source system and whether they are removed after the transfer completes

Attribute

Description

recursive

Specifies that files are transferred recursively in subdirectories when the <source> element is a directory or contains wildcard characters.

disposition

Specifies the action that is taken on the <source> element when <source>has successfully been transferred to its destination. The valid values are as follows:

leave - the source files are left unchanged.
delete - the source files are deleted from the source system after the source file is successfully transferred.

<file>

Specifies the transfer source. For Multiplatforms, the transfer source can be a file or a directory name. For the z/OS platform, the transfer source can be a file, directory, data set, or PDS name. Use the fully qualified path in the format consistent with your operating system, for example C:/from/here.txt. Do not use file URIs.


Attribute	Description
alias	Specifies an alias for the source file. This alias is the name of the source file, excluding any directory path specified for the transfer.
EOL	Specifies the end of line marker for text transfers. Valid values are: LF - line feed character only CRLF - carriage return and line feed character sequence
encoding	The encoding of the source file for a text file transfer.
delimiter	Specifies the delimiter that is included between records in record-oriented source files, for example, z/OS data sets. Specify the delimiter value as two hexadecimal digits in the range 00-FF, prefixed by x. For example, x12 or x03,x7F.
delimiterType	Specifies the type of delimiter that is included in the destination file after individual message data. The valid values is as follows: binary - a hexadecimal delimiter This attribute is available only if you have enabled the V7.0.4.1 function.
delimiterPosition	Specifies the position to insert delimiters when writing record-oriented source file records to a normal file. The valid values are as follows: prefix - the delimiter is inserted into the destination file before the data from each source record-oriented file record. postfix - the delimiter is inserted into the destination file after the data from each source record-oriented file record.
includeDelimiterInFile	Specifies whether to include a delimiter between records in record-oriented source files.
keepTrailingSpaces	Specifies whether trailing spaces are to be kept on source records read from a fixed-length-format data set as part of a text mode transfer. The default is that trailing spaces are stripped. The valid values are as follows: true - trailing spaces are kept on source records read from a fixed-length-format data set false - trailing spaces are stripped from source records read from a fixed-length-format data set

<queue>

When used with the <source> element, specifies the name of the queue to transfer from, which must be located on the source agent queue manager. Use the format QUEUE. Do not include the queue manager name, the queue must be present on the source agent queue manager. We cannot use the <queue> element inside the <source> element, if you have used it inside of the <destination> element.


Attribute	Description
useGroups	Specifies whether to transfer only the first complete group of messages from the source queue. The valid values are as follows: true - transfer only the first complete group of messages false - transfer all messages on the source queue
groupId	Specifies the group of messages to read from the source queue. This attribute is valid only when the value of the useGroups attribute is true.
delimiterType	Specifies the type of delimiter that is included in the destination file after individual message data. The valid values are as follows: text - a text or Java literal delimiter binary - a hexadecimal delimiter
delimiter	Specifies the delimiter that is included in the destination file between individual message data.
delimiterPosition	Specifies whether the delimiter is included in the destination file before or after individual message data. The valid values are as follows: prefix - the delimiter is included before the data postfix - the delimiter is included after the data
encoding	Specifies the source queue encoding.
waitTime	Specifies the time, in seconds, for the source agent to wait for either: a message to appear on the source queue, if the queue is empty or has become empty a complete group to appear on the source queue, if the useGroups attribute has been set to true For information about setting the waitTime value, see Guidance for specifying a wait time on a message-to-file transfer.

<destination>

Group element that specifies the destination and the behavior if files exist at the destination agent.

You can specify only one of <file> and <queue> as a child element of destination.

Attribute

Description

type

The type of destination. The valid values are as follows:

file - specifies a file as the destination
directory - specifies a directory as the destination
dataset - specifies a z/OS data set as the destination
pds - specifies a z/OS partitioned data set as the destination
queue - specifies an IBM MQ queue as the destination
filespace - specifies a file space as the destination

The value queue is valid only when the <destination> element has a child element of <queue>.

The value filespace is valid only when the <destination> element has a child element of <filespace>.

The other values are valid only when the <destination> element has a child element of <file>.

exist

Specifies the action that is taken if a destination file exists on the destination system. The valid values are as follows:

error - reports an error and the file is not transferred.
overwrite - overwrites the existing destination file.

This attribute is not valid if the <destination> element has a child element of <queue> or <filespace>.

<file>

Specifies additional settings for the previously-described <destination> element. Use the fully qualified path in the format consistent with your operating system, for example C:/from/here.txt. Do not use file URIs.


Attribute	Description
alias	Specifies an alias for the <destination> file. This alias is the name of the source file, excluding any directory path specified for the transfer.
encoding	The encoding of the <destination> file for a text file transfer.
EOL	Specifies the end of line marker for text transfers. Valid values are: LF - line feed character only CRLF - carriage return and line feed character sequence
truncateRecords	Optional. Specifies that <destination> records longer than the LRECL data set attribute are truncated. True - the records are truncated False - the records are wrapped The default setting is false.

<queue>

When used with the <destination> element, specifies the name of the queue to transfer to, which can be located on any queue manager that is connected to the destination agent queue manager. Use the format QUEUE@QM where QUEUE is the name of the queue to put the messages on and QM is the queue manager where the queue is located. We cannot use the <queue> element inside the <destination> element, if you have used it inside of the <source> element.


Attribute	Description
delimiter	The delimiter to split the file into multiple messages.
delimiterType	Specifies the type of delimiter. The valid values are as follows: text - a Java regular expression binary - a sequence of hexadecimal bytes size - a number of bytes, kibibytes, or mebibytes. For example, 1 B, 1 K, or 1 M.
delimiterPosition	Specifies whether the delimiter is expected before or after the data to include in individual messages. The valid options are as follows: prefix - the delimiter is expected before the data postfix - the delimiter is expected after the data
includeDelimiterInMessage	A boolean specifying whether to include the delimiters that were used to split the file into multiple messages at the end of the messages.
encoding	Specifies the destination queue encoding.
persistent	Specifies whether the messages are persistent. The valid values are as follows: true - the messages are persistent false - the messages are not persistent qdef - the persistence value of the messages is defined by the settings on the destination queue
setMqProps	A boolean specifying whether IBM MQ message properties are set on the first message in a file, and any messages written to the queue when an error occurs.
unrecognisedCodePage	Specifies whether a text mode transfer fails or conversion is performed, if the code page of the data is not recognized by the destination queue manager. The valid values are as follows: fail - the transfer reports a failure binary - the data is converted to the destination code page and the IBM MQ message header describing the format of the data is set to MQFMT_NONE. The default behavior is fail.

<filespace>

Group element specifying the name of the file space to transfer to.

<name>

When used with the <filespace> element, the value of this element specifies the name of the file space.

<preSourceCall>

Group element specifying a command to call at the source of the transfer, before the transfer starts.

<postSourceCall>

Group element specifying a command to call at the source of the transfer, after the transfer completes.

<preDestinationCall>

Group element specifying a command to call at the destination of the transfer, before the transfer starts.

<postDestinationCall>

Group element specifying a command to call at the destination of the transfer, after the transfer completes.

<command>

When used with the <preSourceCall>, <postSourceCall>, <preDestinationCall>, or <postDestinationCall> element, this element specifies the command to be called. The command must be located on the agent command path. For more information, see Advanced agent properties.


Attribute	Description
name	The name of the command to run.
successRC	The return code that is expected if the command runs successfully.

<argument>

When used with the <command> element, this element specifies an argument to be passed in to the command. We can have any number of <argument> elements inside a <command> element.

<job>

Optional group element containing job information for the entire transfer specification. <job> is a user-defined job name identifier that is added to the log message when the transfer has started. This <job> element is the same as the <job> element that appears in the transfer log message, which is described in the following topic: File transfer log message formats.

<name>

When used with the <job> element, the value of this element specifies the name of the job.

<transferSpecifications>

Group element that contains <item> elements for multiple transfer groups. See Use transfer definition files for further details about how to use this element.

<cancel>

Group element containing all the elements required to cancel a file transfer in progress.


Attribute	Description
version	Specifies the version of this element as supplied by Managed File Transfer.

<transfer>

When used with the <cancel> element, the value of this element specifies the transfer request ID to be canceled.

<job>

Group element containing job information.

<jobName>

Specifies logical job identifier.

File transfer cancel message format

A file transfer request returns a 48-character ID that identifies the transfer for a specific agent. This ID is used to cancel transfers.

Understand the transfer cancel message

The elements and attributes used in transfer cancel messages are described:

<cancel>

Group element containing all the elements required to cancel a file transfer in progress.


Attribute	Description
version	Specifies the version of this element as supplied by Managed File Transfer.

<originator>

Group element that contains the elements specifying the originator of the request.

<hostName>

The host name of the system where the source file is located.

<userID>

The user ID that originated the file transfer.

<mqmdUserID>

Optional. The IBM MQ user ID that was supplied in the message descriptor (MQMD).

<transfer>

When used with the <cancel> element, the value of this element specifies the transfer request ID to be canceled.

<job>

Optional. Group element containing job information.

<jobName>

Specifies logical job identifier.

Examples

Examples of XML messages that conform to this schema are provided for each of the following requests:

File transfer request message examples
Examples of the messages that we can put on the agent command queue to request that the agent create or cancel a transfer.
Scheduled file transfer message examples
Examples of the messages that we can put on the agent command queue to request that the agent create or delete a schedule.
MFT agent call request message examples
Examples of the messages that we can put on the agent command queue to request that the agent creates a managed call or creates a transfer that calls programs.

Parent topic: XML message formats used by MFT

File transfer request message format

Schema

Understand the transfer request message

Element descriptions

File transfer cancel message format

Understand the transfer cancel message

Examples

Related reference