File Transfer Program Interface

The File Transfer Programming Interface permits the transfer of files between local systems and mainframe hosts. The host operating system can be VM/CMS, MVS/TSO, CICS/VS, VSE/ESA, or VSE/SP with the corresponding version of the 3270 File Transfer Program (IND$FILE) installed. The application program can transfer a file from the local system to the host (uploading) or from the host to the local system (downloading). The program interface is a library linked with a user application program that can be written in C, Pascal, or FORTRAN. HCON provides a set of include files or header files that must be included in the user's application program to use the programmatic file transfer. The header files include data structures and constants used by the file transfer function.

The file transfer programming interface consists of library routines that are linked with a user application program written in C, Pascal, or FORTRAN. The file transfer routines are:

Restart Files and Interruptions

When the fxfer program, invoked from the command line, is interrupted for some reason (either a user or operating-system generated interruption or a host-generated interruption), a restart file is created. However, when programs using the file transfer program interface are interrupted for some reason, no restart files are created. Also, if restart files do exist due to previous file transfers, the file transfer program interface does not invoke the restart option (available in the fxfer command), but the file transfer fails and returns a status code of 202.

Note: The file transfer status code returns are described in the table of "File Transfer Error Codes".

Synchronous and Asynchronous File Transfers

Synchronous and asynchronous file transfers differ in these respects:

• Synchronous file transfers are processed immediately. If a current file transfer has not completed, additional synchronous file transfer requests generate a host connection busy message.
• Asynchronous file transfers are processed in the background. If a current file transfer is not complete, additional asynchronous file transfer requests to the same session are placed in a queue. Each request is processed after the preceding file transfer has completed.
• Do not attempt a synchronous transfer while any other file transfer is being processed.

Security

The file transfer program protects the user and host logons, as well as the integrity of the files. Passwords for any host logon are solicited from the terminal. The password is not displayed on the screen and is not maintained in any file. If a password is maintained in memory for any length of time, it is disguised by the fxfer program.

A logical path created by the file transfer program is destroyed when the session is stopped by logging off, the associated queue is emptied, and the time specified in the file transfer wait period within the session profile has expired. If the associated queue is not empty, the logical path is not destroyed until all the queued requests are processed and the specified wait period has expired.

The fxfer function does not replace existing files unless the FXC_REPL option is specified. This option replaces, or overwrites, the contents of an existing file. If the replace option is not specified and the destination file exists, the function stops with an error condition. It is not necessary to specify the FXC_REPL option when uploading to a communication interrupt control program (CICS) host, in which the replace option is the default.

The file transfer program interface includes a file protection mechanism when downloading files to the local system. This ensures the destination file, which exists before the file transfer begins, is not destroyed or altered if the file transfer is interrupted. This protection mechanism is not available when uploading files to the host.

File Transfer Programming Header Files

All file transfer programs use a defined data structure (provided in header files) for each language. File transfer header (include) files are as follows:

File Transfer Data Structures

The C and Pascal program interfaces for the fxfer function use data structures that are defined in header files. The C Program Interface uses the /usr/include/fxfer.h file. The Pascal Program Interface uses the /usr/include/fxfer.inc file.

Note: The FORTRAN Program Interface does not use include files. Check the syntax provided by the fxfer and cfxfer functions to determine how to handle the FORTRAN implementation.