File Transfers (JOBF)

File Transfer objects let you exchange any file from one system to another. File Transfers require two Agents, one on the source and another one 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. If converting characters is required, Code Tables (CODE) are used.

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:

Common pages that are always available, no matter what type of object you are defining

Pages that are always available for executable objects

The object-specific File Transfer page described here

Notes:

While the File Transfer is executing, you can read and modify its settings by using script elements that access the object attributes. Activate the Display Attribute Dialog checkbox on the Attributes Page to enable this function.
The status of the File Transfer does not affect its return code. If a File Transfer fails, the return code is still 0.

To Define the File Transfer Object

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 that is relevant for the Agent.
  
  Source: 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 (SrcFile or DstFile) with the file names. You can also enter a path.
  
  Allowed characters: * for the file name but NOT for paths
  
  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 have to be compliant to the EBCDIC International encoding. Otherwise, file names on the target may not be correct
  - 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
  
  Notes
  - Do not use German umlauts in file names. As the agents are not Unicode aware, file names are not converted correctly when you transfer files from Windows agents to Unix agents, for example.
  - 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
- File Attributes
  
  Additional attributes or formatting commands that you apply to the source/destination file.
  
  For more information, see:
In the Transfer Settings section, specify the settings that govern the transfer:
- File Format
  
  Format with which the file should be transferred
  - Text
    
    The content of the file is copied. Use this option if you are transferring files from an Operation System to a different one with a different syntax. For example, to transfer files from Windows to UNIX.
  - Binary
    
    The files and not just their content are transferred
- Keep Original File Attributes
  
  Keeps the file attributes of the source file. The file attributes of the destination files are overwritten.
  
  Requirements for this option to work:
  - 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 combination 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
  
  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.
    
    Tip: When using compression, the effort (time required for compression) and the benefit (gain of time because of reduced transfer time) should be balanced against each other. 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 definitely 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
    
    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 (deleted and re-created) 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. 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 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
    
    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.
Save your changes.

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, seeExecuting 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 the reports and statistical information associated to them. For more information, see Working with Tasks.