[ Next Article | Previous Article | Book Contents | Library Home | Legal | Search ]
Communications Technical Reference, 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 (xfersessionname)
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:

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:

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-850 Uses IBM code page 850 for translation in an SBCS environment.
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:
  1. All FORTRAN character array strings must be terminated by a null character, as in the following example:
    SRCF = 'rtfile'//CHAR(0)
  2. The VSE host system is not supported in a DBCS environment.
  3. 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.

Implementation Specifics

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.

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.


[ Next Article | Previous Article | Book Contents | Library Home | Legal | Search ]