FairCom ISAM for C

ctTransferFile

Transfers a file between a FairCom DB client and server. This function works on non-c-tree files as well as c-tree files.

Declaration

LONG ctTransferFile(pctXFRFIL pxfr);

Description

The FairCom DB API function ctTransferFile() is used to transfer a file between a FairCom DB client and the FairCom DB database server.

Note:

The file transfer function allows the calling client process to read the contents of any c-tree or non-c-tree file that the operating system allows the c-tree Server process to open for read access.
The file transfer function allows the calling client to write to any c-tree or non-c-tree file that the operating system allows the c-tree Server process to open for write access.
pxfr is a pointer to a file transfer request structure, which is defined as follows in FairCom DB V10.3.1 and later:

typedef struct ctxfrfil {

LONG ver; /* Version of this structure */

LONG mode; /* Transfer mode */

pTEXT srcnam; /* Name of source file */

pTEXT dstnam; /* Name of destination file */

LONG blksiz; /* Transfer block size */

LONG ackint; /* Acknowledgment interval */

pXFRFNC xfrfnc; /* File transfer callback func */

pXFRINF xfrinf; /* File transfer callback data */

pVOID xfrufn; /* File transfer user callback */

pVOID xfrudt; /* File transfer user data */

} ctXFRFIL;

For security reasons, this feature is disabled, by default, and requires the calling user to be a member of the ADMIN group. To enable this feature, specify the following in the FairCom DB configuration file:

ENABLE_TRANSFER_FILE_API YES

A NSUP_ERR error code is returned if ENABLE_TRANSFER_FILE_API YES is not in ctsrvr.cfg.

To allow a non-ADMIN user to call ctTransferFile() specify the following configuration keyword:

COMPATIBILITY NONADMIN_TRANSFER_FILE_API

To use the file transfer function, allocate a ctXFRFIL structure and set its fields as follows:

ver - The version structure ctXFRFIL_VERS_CUR.
Note: Future updates to the ctTransferFile() function might change this structure. An application must set the version field of the structure to the macro ctXFRFIL_VERS_CUR, which c-tree defines to its current version of the file transfer request structure definition.
mode - Set to one of the following:

#define ctXFRFIL_SEND 0x00000001 /* send file to server */

#define ctXFRFIL_RECV 0x00000002 /* receive file from server */

#define ctXFRFIL_RAW 0x00000004 /* raw file transfer */

#define ctXFRFIL_CTREE 0x00000008 /* c-tree file transfer */

#define ctXFRFIL_OVRWRT 0x00000010 /* overwrite existing file */

#define ctXFRFIL_MASTER 0x00000020 /* perform transfer with master */

#define ctXFRFIL_CLBK 0x00000040 /* use callback function */

#define ctXFRFIL_CREDIR 0x00000080 /* create non-existent directories */

#define ctXFRFIL_CPYFIL 0x00000100 /* used for remote file copy */

OR in the ctXFRFIL_OVRWRT option if you wish the destination file to be overwritten if it exists.

srcnam - The source file name. When sending a file, this is the name of the file on the client system that the client reads and sends to the server. When receiving a file, this is the name of the file on the server system that the server reads and sends to the client.
dstnam - The destination file name. When sending a file, this is the name of the file on the server system that the server creates and writes with the data received from the client. When receiving a file, this is the name of the file on the client system that the client creates and writes with the data received from the server.
blksiz - The block size, in bytes, to be used when transferring the file. A buffer of the specified block size is allocated by both the client and server processes.
ackint - The acknowledgment interval. A value of 0 or 1 causes the receiving process to send an acknowledgment message to the sending process after each file transfer message it receives. A value greater than 1 causes the receiving process to send an acknowledgment only after receiving the specified number of file transfer messages from the sending process. This option is ignored for shared memory connections.

Important: The file transfer ctXFRFIL_OVRWRT mode causes the specified destination file to be overwritten, so if the destination file exists before the file transfer, its original contents are lost (replaced by the transferred data).

Return

Value	Symbolic Constant	Explanation
0	NO_ERROR	Successful operation.
454	NSUP_ERR	Operation or service not supported. Using an option unavailable to this library.
871	XFR_SOPN_ERR	The file transfer operation failed because the source file could not be opened for reading. Check sysiocod for the system error code.
872	XFR_DOPN_ERR	The file transfer operation failed because the destination file could not be opened for writing. Check sysiocod for the system error code.
873	XFR_READ_ERR	The file transfer operation failed because the source file could not be read. Check sysiocod for the system error code.
874	XFR_WRITE_ERR	The file transfer operation failed because the destination file could not be written. Check sysiocod for the system error code.
875	XFR_BCON_ERR	A bound database connection called the file transfer function, but this function is supported for client connections only.
876	XFR_BSIZ_ERR	The file transfer operation failed because the caller specified an invalid file transfer block size.
877	XFR_SFNM_ERR	The file transfer operation failed because the caller specified a NULL or empty source file name.
878	XFR_DFNM_ERR	The file transfer operation failed because the caller specified a NULL or empty destination file name.
879	XFR_VER_ERR	The version of the file transfer structure supplied by the caller is not compatible with the c-tree library's structure definition. Check sysiocod for the required file transfer structure version.
880	XFR_DEXS_ERR	The file transfer operation failed because the destination file exists and the caller did not specify that the destination file is to be overwritten.
881	XFR_TREP_ERR	The file transfer operation between a local and master server failed because the server does not support the transactional replication feature.
882	XFR_TRLC_ERR	The file transfer operation between a local and master server failed because the server is not configured as a local server. Use the REPL_MAPPINGS configuration keyword option to configure the server as a local server.
454

See FairCom DB Error Codes for a complete listing of valid FairCom DB error values.

Example

pctXFRFL xferfile;

char srcnam[80];

char dstnam[80];

NINT rc = 0;

memset(srcnam, 0, 80);

memset(dstnam, 0, 80);

strcpy(srcnam, "custmast.dat");

strcpy(dstnam, "custmast.dat");

xferfile = (pctXFRFL) malloc (sizeof(ctXFRFL));

if (!xferfile)

Handle_Error("Bad malloc on xferfile", 0);

xferfile->ver = ctXFRFL_CUR;

xferfile->mode = ctXFRFIL_RECV | ctXFRFIL_OVRWRT;

xferfile->srcnam = srcnam;

xferfile->dstnam = dstnam;

xferfile->blksiz = 32768;

xferfile->ackint = 0;

rc = ctTransferFile(xferfile);

if (rc)

Handle_Error("File transfer failed.", rc);