Product Documentation

c-treeACE V10.0 Update Guide

Previous Topic

Next Topic

c-treeACE Functions to Transfer Files

It is often advantageous for applications to deal with files external to the data and index files. Consider the case of a document. While it may be considered as information related to data record, it is useful to maintain the document external to the data file. To allow a convenient method of moving these files between a client and server, a c-treeACE API function is available to transfer the file from client to server or vice versa.

ctTransferFile() is used to initiate this transfer. The complete API function description is below:

ctTransferFile()

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

Declaration

LONG ctTransferFile(pctXFRFIL pxfr);

Description

The c-treeACE API function ctTransferFile() is used to transfer a file between a c-treeACE client and the c-treeACE 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 c-treeACE 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 c-treeACE 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 c-treeACE Error Codes for a complete listing of valid c-treeACE 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);

TOCIndex