March 31, 2013
From Here to There – The c-treeACE File Transfer API
Note: c-treeACE became FairCom DB in November 2020.
Applications occasionally have a need to move entire files between the client and server. These files may be c‑tree files or not. Consider reports that are run server side or centralized configuration files.
When using the c‑treeACE Replication Agent applications usually expect the replication activity to commence from a consistent state between two servers. There are multiple ways to copy a data file, including the c‑treeACE Dynamic Dump, or system level utilities. Some developers have even custom coded file copy routines into the CTUSER() feature using the c‑treeACE Server SDK.
c‑treeACE V10 introduced an alternative utility function to easily move files where needed.
ctTransferFile
The c‑treeACE API function ctTransferFile() can be used to transfer a file between a c‑treeACE client and the c‑treeACE database server.
The ctTransferFile() function handles either sending or receiving a file as well as a configurable communication block size for efficient transfer. A simple structure (ctXFRFL) is defined with all of the parameters required and then passed to the function. An overwrite mode is necessary to prevent overwriting existing destination files.
File Security
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
To allow a non-ADMIN user to call ctTransferFile() specify the following configuration keyword:
COMPATIBILITY NONADMIN_TRANSFER_FILE_API
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);