File Transfers (JOBF)

The File Transfer object is a powerful and flexible tool to define parameters to exchange any file from one system to another. For File Transfer objects to work, an Agent must be installed on the source computer and on the target computer respectively. The transfer can be structured, thus enabling the exchange of files with packed and binary fields in heterogeneous system environments. All network transfers are encoded by default.

If converting characters is required, this is automatically done using a Code Tables (CODE).

Object class: Executable object

Object type/Short form: JOBF

This page includes the following:

Defining File Transfers

An File Transfer definition is made up of the following pages:

Notes:

To Define a File Transfer Object

  1. In the Source Settings section specify the file to be transferred and its origin.

    • Agent

      Select here the name of the Agent where the file to be transferred is located. See Combo Boxes.

      You can select an Agent or an Agent Group. Please take into account that Agent Groups can be either source or target but not both. For more information, see Agent Groups in File Transfers.

    • Login

      Login object that contains the necessary information for the file transfer to be able to log on to the target system.

    • Code

      Select the Code Table that is relevant for the Agent. When you enter a string, the find as you type function is available and list all hits containing the string you entered.

      In addition to the available Code Table objects, this list contains further options that can be used to transfer Unicode files:

      • <UTF-8>
      • <UCS-2BE>
      • <UCS-2LE>

      If you select any of these, the Code dropdown list in Destination Settings is not available and a code template is set in File.

    • File

      Replace the ghost text with the file name(s). You can also enter a path. You can use wildcard for the file name, but not in the path.

      Partially Qualified File Transfer: Use a filter that comprises wildcard characters and fixed parts of the file name instead of specifying a complete file.

      Take into account the following:

      • VMS

        VMS agents do not resolve logical names. Specify here the directory and file name as, otherwise, the file cannot be found.

      • z/OS

        The specification of z/OS files depends on the file system that you use (USS or Host). For example:

        • USS file system (absolute path): /dir1/dir2/datei
        • USS file system (relative path): ./dir1/dir2/datei
        • Host file system: FLQN.DATASET.NAME

        Important! On the USS file system file names have to be compliant to the EBCDIC International encoding. Otherwise file names on the target may not be correct

      • UNIX

        Please refer to the Call API Unix for parameters to be used and conditions that apply to file transfers under UNIX agents.

    • File Attributes

      Additional entries for file attributes. Which attributes you can specify depends on the object's operating system. Please refer to Platform Specific Features for details.

  2. In the Destination Settings section specify the target of the transfer.

    • Agent

      Select here the name of the agent to which the file will be transferred.

      You can select an agent or an agent group. Please take into account that agent groups can be either source or target but not both.

    • Login

      Login object that contains the necessary information for the file transfer to be able to log on to the target system.

    • Code

      Select the Code Table that is relevant for the agent. When you enter a string, the find as you type function is available and list all hits containing the string you entered.

      If you have selected UTF-8, UCS 2BE or UCS 2LE as code of the source file, this field is not available.

    • File

      Replace the ghost text with the file name(s). You can also enter a path. You can use wildcard for the file name, but not in the path.

      You can use the following variables in the target file name: &$SRC_AGENT#. The file transfer replaces this variable with the name of the file's original agent. For example:

      C:\temp\&$SRC_AGENT#_test*.txt

      Partially Qualified File Transfer: Use a filter that is composed of wildcard characters and fixed parts of the file name instead of specifying a complete file.

    • File Attributes

      Additional entries for file attributes. Which attributes you can specify depends on the object's operating system. See Platform Specific Features for details.

      If you have selected UTF-8, UCS 2BE or UCS 2LE as code of the source file, this field is not available.

  3. In the Transfer Settings section specify the settings that will govern the transfer.

    • File Format

      Select the format, how the file will be transferred.

      • Text

        Activate this option button if the file is a text file

      • Binary

        Activate this option if the file is a binary file.

    • Keep Original File Attributes

      Select this option to keep the file attributes of the source file. The file attributes of the destination files are overwritten.

      This option only works if:

      • both the source and the destination platform comply
      • the new file transfer protocol is used (source and target agent are of Automation Engine version 9.00A or later).

      Important!

      • In BS2000, OS/400 and z/OS, you cannot overwrite the original attributes with additional specifications in the File Transfer object (target). Any attempt to do so results in an error message and the file transfer fails.
      • In z/OS, setting this option in conjunction with files that are located on tape/VTL is not supported. This option requires the dataset to be on a disk.

      It is recommended to activate this setting because the target file can become corrupt if the attributes are not sent or modified when you transfer text files between two OS/400 computers.

    • Compression

      Select whether transferred files are compressed:

      • Default value:

        Applies the value that has been defined in the in the UC_HOSTCHAR_DEFAULT (setting FT_COMPRESS) Agent variable. The files are transferred in compressed mode if the two agents have different settings. For example:

        WIN01 = No compression
        UNIX01 = Active compression

        The files are transferred in compressed form.

        The Agent uses the LZP+Huffman procedure for the compression.

        Note: When using compression, make sure that effort (time required for compression) and benefit (gain of time because of reduced transfer time) are balanced against each other. An important component for your decision is the available bandwidth of your network connection. You cannot increase performance with fast networks (100 Mbit) because the compression process is more time-consuming than the gain achieved by reducing the network time. With an available bandwidth of 10MBit or less, compression will definitely result in a performance increase.

      • Yes: Files are compressed
      • No: Files are not compressed

      Yes and not overwrite the value defined in the agent/system variable

    • If file exists at destination

      Select the action taken, if the file already exists at the destination. You can:

      • Cancel transfer

        If the file already exists in the target system, the transfer is canceled.

      • Overwrite file

        If the file already exists in the target system, the file is replaced by the one that is being transferred.

      • Append file

        If the file already exists in the target system, the file that is being transferred is appended to the existing one.

    • Erase Source File

      Select this option if you do not want to keep the original file at the source system.

      Important!

      • Specific rights are required under UNIX if this file should be deleted. See Rights for Deleting Source Files in File Transfers.
      • A File Transfer also ends with the status ENDED_OK if all files have been successfully transferred but the source file could not be deleted.

    • Use Wildcards

      Activate this option to be able to transfer files using wildcard character:

      • Abort at First Error: If an error occurs during the transfer, the file transfer stops.
      • Include Sub-Directories: The content of sub-directories is also transferred.
      • Transfer Complete Folder Structure: All contents are transferred.

File Transfer Procedure

The Automation Engine sends the complete File Transfer request to the source Agent. This request also includes wildcard specifications in partially qualified file transfers. The source Agent is responsible for resolving this request and retrieving the files that should be sent.

Establishing a Connection

  1. The source Agent (sender) first tries to establish a connection to the target Agent (receiver).

    • If it succeeds, it transfers the files to the receiver.
    • If it fails, the sender notifies the Automation Engine.
  2. The Automation Engine sends the file transfer request to the receiver, which tries to establish a connection to the sender. When the connection is established, the receiver transfers the request to the sender.

Checking the Disk Space

Depending on the OS, the Automation Engine system checks the disk space on the target platform before it starts the file transfer. If there is not enough disk space, it is allocated.

Handling File Transfers

Each File Transfer establishes its own connection between the Agents. The files are always sent one after the other and, if the affected Agent supports this functionality, each file transfer is handled in a separate thread or process. This means that several file transfers are handled independently.

The Agents of the following operating systems support threads:

NSK handles each file transfer with a separate process. Therefore, the NSK Agent has a second port that is specifically used for file transfers.

Note: File Transfers continue even if a connection error occurs between the Automation Engine and the Agents. When the connection is re-established, the actual status of the File Transfer is sent to the Automation Engine.

Checks to Ensure Reliable Transfers

The following procedures ensure the reliable transfer of files:

Status Store Files

Depending on the Agent platform, the status store files are stored in the following directories:

Platform Specific Features

You can also specify file attributes for the file names of file transfer target:

Next steps:

Executing the Object

File Transfer objects can be included in Schedules (JSCH) and thus be executed automatically at predefined dates or intervals. Likewise, they can be part of workflows (see Designing Workflows (JOBP)).

You can also execute, restart or stop them manually. For details see Executing File Transfers.

Monitoring the File Transfer

Immediately after executing the object you can start monitoring it. Right-click it to select Monitoring and open the pre-filtered list of tasks to display this one. See Show in Process Monitoring.

In the Process Monitoring perspective you can follow their progress and access the reports and statistical information associated to them. See Working with Tasks.

See also: