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:
|fxfer (C), pfxfer (Pascal), ffxfer (FORTRAN)|
|Initiates a file transfer from within an application program.|
|cfxfer(C), pcfxfer (Pascal), fcfxfer (FORTRAN)|
|Returns a completion status of the file transfer request to the program.|
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 differ in these respects:
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.
All file transfer programs use a defined data structure (provided in header files) for each language. File transfer header (include) files are as follows:
|C language file transfer include file with structures and definitions.|
|Pascal language file transfer constants.|
|Pascal language file transfer include file with structures.|
|Pascal language file transfer invocation include file.|
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.