Technical Reference: Communications, Volume 1

fxfer Function

Purpose

Initiates a file transfer from within a program.

Library

File Transfer Library (libfxfer.a)

C Syntax

#include <fxfer.h>

fxfer ( xfer, sessionname)

struct fxc *xfer;

char *sessionname;

Pascal Syntax

%include /usr/include/fxfer.inc

%include /usr/include/fxhfile.inc

%include /usr/include/fxconst.inc

function pfxfer (var xfer : fxc; sessionname : stringptr) : integer; external;

FORTRAN Syntax

INTEGER FFXFER

EXTERNAL FFXFER

CHARACTER*XX SRCF, DSTF, LOGID, INPUTFLD, CODESET, SESSIONNAME

INT FLAGS, RECL, BLKSIZE, SPACE, INCR, UNIT, RC

RC = FFXFER ( SRCF, DSTF, LOGID, FLAGS, RECL, BLKSIZE,

+ SPACE, INCR, UNIT, INPUTFLD, CODESET, SESSIONNAME)

Description

The fxfer function transfers a file from a specified source to a specified destination. The file transfer is accomplished as follows:

In the C or Pascal language, the fxfer or pfxfer function transfers a file specified by the fxc_src variable to the file specified by the fxc_dst variable. Both variables are defined in the fxc structure.
In the FORTRAN language, the FFXFER function transfers a file specified by the SRCF variable to the file specified by the DSTF variable.

The fxfer function is part of the Host Connection Program (HCON).

The fxfer function requires one or more adapters used to connect to a host.

This function requires one of the following operating system environments be installed on the mainframe host: VM/SP CMS, VM/XA CMS, MVS/SP TSO/E, MVS/XA, TSO/E, CICS/VS, VSE/ESA, or VSE/SP.

This function requires that the System/370 Host-Supported File Transfer Program (IND$FILE or its equivalent) be installed on the mainframe host.

The file names are character strings. The local-system file names must be in operating system format. The host file names must conform to the host naming convention, which must be one of the following formats:

Format	Description
VM/CMS	FileName FileType FileMode
MVS/TSO	DataSetName [(MemberName)][/Password]
CICS/VS	FileName (up to 8 characters)
VSE/ESA	FileName (up to 8 characters) Note The VSE host is not supported in a double-byte character set (DBCS) environment.

C Parameters

xfer

Specifies a pointer to the fxc structure defined in the fxfer.h file.

sessionname

Points to the name of a session. The session profile for that session specifies the host connectivity to be used by the file transfer programming interface. The session name is a single character in the range of a through z. Capital letters are interpreted as lowercase letters. Session variables are defined in a HCON session profile. If the value of the sessionname parameter is set to a null value, the fxfer function assumes you are running in an e789 subshell.

Pascal Parameters

xfer Specifies a record of fxc type within the fxfer.inc file.

sessionname Points to the name of a session. The session profile indicated by the sessionname parameter defines the host connectivity to be used by the file transfer programming interface. The session name is a single character in the range of a through z. Capital letters are interpreted as lowercase letters. Session variables are defined in an HCON session profile. If the sessionname parameter is set to char(0), the pfxfer function assumes you are running in an e789 subshell.

FORTRAN Parameters

SRCF	Specifies a character array of XX length containing the source file name.
DSTF	Specifies a character array of XX length containing the destination file name.
LOGID	Specifies a character array of XX length containing the host logon ID.
SESSIONNAME	Points to the name of a session. The SESSIONNAME parameter names a session profile that defines the host connectivity to be used by the file transfer programming interface. The session name is a single character in the range of a through z. Capital letters are interpreted as lowercase letters. Session variables are defined in a HCON session profile. If the SESSIONNAME parameter is set to `char(0)`, the FFXFER function assumes you are running in an e789 subshell.
FLAGS	Contains the option flags value, which is the sum of the desired option values: 1 Upload 2 Download 4 Translate on 8 Translate carriage return line feed 16 Replace 32 Append 64 Queue 128 Fixed-length records 256 Variable-length records 512 Undefined length (TSO only) 1024 Host system TSO 2048 Host system CMS 4096 Host system CICS/VS 8192 Host system VSE/ESA
RECL	Specifies the logical record length.
BLKSIZE	Specifies the block size.
SPACE	Specifies the allocation space.
INCR	Specifies the allocation space increment.
UNIT	Specifies the unit of allocation: -1 Specifies the number of TRACKS. -2 Specifies the number of CYLINDERS. A positive number indicates the number of bytes to allocate.
INPUTFLD	Specifies the host input table field.
CODESET	Specifies an alternate code set to use for ASCII to EBCDIC and EBCDIC to ASCII translations: CHAR(0) Uses current operating-system ASCII code page. IBM-932 Uses IBM code page 932 for translation in a DBCS environment. ISO8859-1 Uses ISO 8859-1 Latin alphabet number 1 code page. ISO8859-7 Uses ISO 8859-7 Greek alphabet. ISO8859-9 Uses ISO 8859-9 Turkish alphabet. IBM-eucJP Uses IBM Extended UNIX code for translation in the Japanese Language environment. IBM-eucKR Translates Korean language. IBM-eucTW Translates traditional Chinese language.

Notes:

All FORTRAN character array strings must be terminated by a null character, as in the following example:
```
SRCF = 'rtfile'//CHAR(0)
```
The VSE host system is not supported in a DBCS environment.
The unique DBCS file-transfer flags are not supported by this function.

Return Values

If the fxfer function is called synchronously, it returns a value of 0 when the transfer is completed. The application program can then issue a cfxfer function call to obtain the status of the file transfer.

If the fxfer function is called asynchronously, it returns 0. The application program can issue a cfxfer function call to determine when the file transfer is completed and to obtain the status of the file transfer. If the status cannot be reported by the cfxfer function due to an I/O error on the fx_statxxxxxx status file, the cfxfer function returns a -1. If the status is not ready, the cfxfer function returns a -2.

The fx_statxxxxxx status file contains the status of each file transfer request made by the application program. The fxfer function fills in the xxxxxx portion of the fx_stat file based on random letter generation and places the file in the $HOME directory.

Files

$HOME/fx_statxxxxxx	Temporary file used for status information.
/usr/lib/libfxfer.a	Library containing C, FORTRAN, and Pascal interface file-transfer functions.
/usr/include/fxfer.h
	C file-transfer include file with structures and definitions.
/usr/include/fxfer.inc
	Pascal file-transfer include file with structures.
/usr/include/fxconst.inc
	Pascal file-transfer function constants.
/usr/include/fxhfile.inc
	Pascal file-transfer invocation include file.

Related Information

The file-transfer check status function is the cfxfer function.