File Transfers (JOBF)

File Transfer objects let you exchange any file from one system to another. They require two Agents, one on the source and another on the target computer. 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.

Object class: Executable object

Object type/Short form: JOBF

This page includes the following:

Defining File Transfers

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

Note:

  • The execution status of the File Transfer object does not describe the status of the transferred files. If the execution completes correctly but the transferred files have issues, the return code is still 0.

Character Conversion During File Transfer

Converting characters is only relevant for File Transfers of type Text. Binary File Transfers are not affected by character conversion. This section briefly explains how character conversion works in Automic Automation.

To transfer files between two Operating Systems and/or applications that use different character encoding pages, you must configure the File Transfer object to do the necessary character conversion. Automic Automation caters for this situation as follows:

  • Character Conversion at Agent Level

    When configuring an Agent, your Automic Automation administrator specifies the Agent's character encoding set in its INI file. The Agent uses it to convert characters as needed when the machine where an Agent runs uses a different character encoding set than the Automation Engine Server.

  • Character Conversion at Object Level

    When you configure a File Transfer object, you can assign it a specific character conversion set on its Attributes page. The character set that you specify here overrides the one specified in the Agent's INI file.

  • Character Conversion at Transfer Level

    If you want to transfer files between two Agents that use different character encoding pages, you can define specific character encoding sets in the Code fields (Source and Destination) on the object's File Transfer page. This definition overrides the encoding set specified on the Attributes page for this specific File Transfer. However, this is valid only temporarily and exclusively for the affected File Transfer. Subsequent File Transfers are not affected.

To perform the conversion, Automic Automation provides two mechanisms:

  • Code Table objects

  • Standard character conversion sets.

For more information, see Code Tables and Standard Character Conversion Sets.

For more information about Code Table objects, see Code Tables (CODE).

Defining File Transfer-Specific Settings

  1. In the Source/Destination Settings section, specify the file to be transferred and its origin:

    • Agent

      Source: Agent where the file that you want to transfer is located.

      Destination: Agent to which the file should be transferred

      You can select an Agent or an Agent Group. 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 information that the File Transfer needs to log on to the target systems

    • Code

      Code Table object or standard character encoding set with which the conversion will be done. This list is only available for Text File Transfers (see description of the Transfer Settings section later in this topic).

      The entries available in the Destination Settings > Code list depend on your selection in the Source Settings > Code list. The following table specifies the possible Source/Destination combinations:

      Source Agent Destination Agent Comment
      <UTF-8> Disabled

      There is no need to perform a conversion.

      Only the line breaks are converted, if required, to transfer files between different OS.
      CODE object CODE object

      A single byte character mapping is performed according to the CODE object definitions.
      Empty Empty

      If a conversion is required, the Agent default setting is applied.

      <UTF-8> or

      <ISO-8859-1> or

      <ISO-8859-15>or

      <UCS-2BE> or

      <UCS-2LE> or

      <WINDOWS-1252>

      		 Disabled

      The destination Agent stores the text data as it is sent by the source Agent. No code page conversion is performed.

      Although the combinations in the following table are possible, they result in either a failing File Transfer or they have no impact at all:

      Source Agent Destination Agent Comment
      CODE object

      <ISO-8859-15> or

      <ISO-8859-1> or

      <WINDOWS-1252>

      The File Transfer will fail.

      UC_CODE

      <UTF-8> or

      <ISO-8859-15> or

      <ISO-8859-1> or

      <WINDOWS-1252>

      This combination has no impact on the File Transfer.

      Note:  If a source or destination Agent does not support UTF-8 and you use either <ISO-8859-15> or <ISO-8859-1> or <WINDOWS-1252>, the File Transfer will fail or abort as failed. This is because non-UTF-8 Agents do not know the standard code pages.

      For more information about Automic Automation and UTF-8 support, see Universal Language Support (Unicode).

    • File

      Replace the ghost text (SrcFile or DstFile) with the file names. You can also enter a path.

      Allowed characters: * for the file name but NOT for paths

      Note: For a Partially Qualified File Transfer, use a filter that comprises wildcard characters and fixed parts of the file name instead of specifying a complete file

      Source:

      • 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 must comply with the EBCDIC International encoding. Otherwise, file names on the target may be incorrect.

      • UNIX: For parameters to be used and conditions that apply to file transfers under UNIX Agents, see Call API Unix.

      Destination:

      You can use the following variable in the target file name: &$SRC_AGENT#. For example:

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

      The File Transfer replaces the variable with the name of the file's original agent.

    • File Attributes

      You can apply additional attributes or formatting commands to the source/destination file.

      For more information, see:

  2. In the Transfer Settings section, specify the settings that govern the transfer:

    • File Format

      Format with which the file should be transferred

      • Text: Only the content of the file is copied. Use this option if you transfer files with a different syntax from one Operating System to another. For example, to transfer files from Windows to UNIX. In this case, the conversion is automatically done.

      • Binary: The files and not just their contents are transferred.

    • Keep Original File Attributes

      Keeps the file attributes of the source file. The file attributes of the destination files are overwritten.

      Take into account that different Operating Systems have different attributes. For this option to work, the source and the destination Operating System must have the same attrbutes.

      Important!

      • In BS2000, OS/400, and z/OS, you cannot overwrite the original attributes with additional specifications in the File Transfer object in the Destination Agent. Any attempt to do so results in an error message, and the file transfer fails.

      • In z/OS, setting this option with files on tape/VTL is unsupported. 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

      Whether transferred files are compressed:

      • Default value:

        Applies the value defined in the UC_HOSTCHAR_DEFAULT (FT_COMPRESS setting) 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.

        Tip: When using compression, balance the effort (time required for compression) and the benefit (gain of time because of reduced transfer time). Take the available bandwidth of your network connection into account. 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 result in a performance increase.

        Important! Your setting here overwrites the value defined in the Agent/system variable.

    • If file exists at destination

      • Cancel transfer

        The transfer is canceled if the file already exists in the target system.

      • Overwrite file

        If the file already exists in the target system, the file is replaced (deleted and re-created) by the one 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 in the source system.

      Important!

      • Specific rights are required under UNIX if this file should be deleted. For more information, 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 characters:

      • Abort at First Error

        The file transfer stops if an error occurs during the transfer.

      • Include Sub-Directories

        The content of sub-directories is also transferred.

      • Transfer Complete Folder Structure

        Relevant for partially qualified transfers. By default, empty folders are not considered when subdirectories are transferred. Activate this option to include empty directories in transfers.

        Note: This option is available only if you have activated Include sub-directories.

  3. Save your changes.

Modifying File Transfer Settings at Runtime

While the File Transfer executes, you can read and modify its settings using script elements that access the object attributes. Activate the Display Attribute Dialog checkbox on the Attributes Page to enable this function.

For technical details on how File Transfer objects are processed, see File Transfer Procedure.

File Transfers Between TLS/SSL and Non-TLS/SSL Agents

File Transfers between TLS/SSL and non-TLS/SSL Agents do not require special attention, as they run automatically, aided by the TLS Gateway, see TLS Gateway. If a TLS Gateway is used during a File Transfer, it is reflected in the File Transfer log.

Next Steps

Execute the File Transfer

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 Workflows (JOBP)).

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

Monitor 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. For more information, see Show in Process Monitoring.

In the Process Monitoring perspective, you can follow their progress and access their reports and statistical information. For more information, see Working with Tasks.

See also: