Using transfer definition files

You can specify a transfer definition file which can be used to create a file transfer. The transfer definition file is an XML file that defines some or all of the information required to create the transfer.

Transfer definition files are useful when you want to specify multiple source files and multiple destination files in a single transfer operation. You can use a transfer definition file to submit a complex file transfer. You can reuse and share the transfer definition file.

You can use two formats for a transfer definition file, and while these formats vary slightly, both conform to the FileTransfer.xsd schema. You can find this schema in the samples\schema directory of the IBM® MQ Managed File Transfer installation.

The following two formats of transfer definition files are supported:

A definition of the source and destination files for a transfer. This definition uses a <transferSpecifications> element as the root.
A definition of the entire transfer, including source and destination files and the source and destination agents. This definition uses a <request> element as the root.
- Files with this format can be generated from the fteCreateTransfer command by using the -gt parameter.

The following example shows a transfer definition file format that specifies only the source and destination files for a transfer:

<?xml version="1.0" encoding="UTF-8"?>
<transferSpecifications xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance" 
   xsi:noNamespaceSchemaLocation="FileTransfer.xsd">
  <item checksumMethod="MD5" mode="text">
    <source recursive="false" disposition="leave">
      <file>textTransferTest.txt</file>
    </source>
    <destination type="directory" exist="overwrite">
      <file>c:\targetfiles</file>
    </destination>
  </item>
</transferSpecifications>

To submit this format of transfer definition file you must specify the source and destination agents on the command line:

fteCreateTransfer -sa AGENT1 -sm agent1qm -da AGENT2 -dm agent2qm -td 
  c:\definitions\example1.xml

The following example is a transfer definition file format that specifies all information required for a transfer:


<?xml version="1.0" encoding="UTF-8"?>
<request version="3.00" xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance" 
  xsi:noNamespaceSchemaLocation="FileTransfer.xsd">
  <managedTransfer>
    <originator>
      <hostName>example.com.</hostName>
      <userID>fteuser</userID>
    </originator>
    <sourceAgent agent="AGENT1" QMgr="agent1qm"/>
    <destinationAgent agent="AGENT2" QMgr="agent2qm"/>
    <transferSet>
      <item mode="binary" checksumMethod="MD5">
        <source recursive="false" disposition="leave">
          <file>c:\sourcefiles\*.jpg</file>
        </source>
        <destination type="directory" exist="error">
          <file>/targetfiles/images</file>
        </destination>
      </item>
    </transferSet>
  </managedTransfer>
</request>

You can generate a file with this format by using the -gt parameter on the fteCreateTransfer command. When you submit a transfer definition file with this format, you do not need to specify anything else on the command line:


fteCreateTransfer -td c:\definitions\example2.xml

You can override the source and destination agent information about the command line by passing in the normal parameters in addition to the transfer definition file. For example:


fteCreateTransfer -da AGENT9 -dm agent9qm -td c:\definitions\example2.xml

This example uses the command-line options to override the destination agent defined inside the transfer definition file with AGENT9 and the destination queue manager defined in the transfer definition file as agent9qm.

Both of the formats described can contain one or more <item> elements. For further information about the <item> element, see File transfer request message format. Each of these transfer items defines a source and destination file pair with additional attributes to control the behavior of the transfer. For example, you can specify the following behavior:

Whether the transfer uses a checksum
Whether the transfer is text or binary
Whether to delete the source file after the transfer has completed
Whether to overwrite the destination file if the file exists

An advantage of using transfer definition files is that you can specify additional options that are not available from the command line. For example, when you are carrying out message-to-file transfers, you can specify the groupId attribute by using a transfer definition file. This attribute specifies the WebSphere® MQ group ID of the messages that are read from the queue. Another advantage of transfer definition files is that you can specify different options for each file pair. For example, you can specify whether a checksum is used, or whether the file is transferred in text or binary mode, on a file-by-file basis. If you use the command line, the same options apply for every file in a transfer.

For example:


  <item checksumMethod="none" mode="binary">
    <source disposition="leave">
      <file>c:\sourcefiles\source1.doc</file>
    </source>
    <destination type="file" exist="error">
      <file>c:\destinationfiles\destination1.doc</file>
    </destination>
  </item>

  <item checksumMethod="MD5" mode="text">
    <source disposition="delete">
      <file>c:\sourcefiles\source2.txt</file>
    </source>
    <destination type="file" exist="overwrite">
      <file encoding="UTF8" EOL="CRLF">c:\destinationfiles\destination2.txt</file>
    </destination>
  </item>

  <item checksumMethod="none" mode="text">
    <source recursive="false" disposition="leave">
      <file>c:\originfiles\source3.txt</file>
    </source>
    <destination type="file" exist="overwrite">
      <file>c:\targetfiles\destination3.txt</file>
    </destination>
  </item>

You can use items to transfer a file from a distributed system to a z/OS® system:


  <item checksumMethod="none" mode="text">
    <source recursive="false" disposition="leave">
      <file>textTransferTest.txt</file>
    </source>
    <destination type="dataset" exist="overwrite">
      <file encoding="IBM-1047">//TEXT.TRANS.TEST</file>
    </destination>
  </item>

This example transfers the file textTransferTest.txt from the source agent to the data set //TEXT.TRANS.TEST on the destination agent in text mode. This transfer converts the source data from the default encoding of the source agent (no source encoding attribute is specified) to code page: IBM-1047.