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:
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:
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.
#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.
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);