|
|
|
ctCopyFile
Description:
Server-to-server file copy.
ctCopyFile() makes a copy of a c-tree data or index file, or a c-tree data file and its associated index files. The caller specifies the source and destination file names and options that affect the behavior of the file copy. c-tree copies the files synchronously. That is, the copy call does not return until the file copy is completed.
Prototype:
NINT ctCopyFile(pCPYFIL pcpyfil);
Parameters:
ctCopyFile() accepts one parameter: a pointer to a file copy option structure, CPYFIL (see definitions below).
Returns:
ctCopyFile() returns zero indicating all files were successfully copied or a non-zero value to indicate one or more files failed to copy. The caller can supply an optional error message buffer and buffer size. If an error message buffer is supplied and an error occurs, the file copy function writes an error message to the error message buffer.
Notes:
The caller can optionally specify a callback function that is periodically called for displaying user feedback progress bars. The callback function is called at the start of the file copy, for each 1% of the file that has been copied, and at the end of the file copy. The callback function must return zero to permit the file copy to continue, and it can return a non-zero error code in order to terminate the file copy operation.
To copy a file, a caller must be authorized by c-tree (including the file system) to open a file for read access. ADMIN user is always granted read permission for all files. (c-tree file permissions are only supported in the client/server model and not with standalone usage.)
c-tree attempts to open the file in exclusive mode, while still allowing other connections to open the file for read access. If the file is already open, c-tree flushes updates to disk and sets the update flag to zero to indicate that the file is in a clean, consistent state. If c-tree cannot open the file in exclusive mode, the copy operation fails.
An option provides a way to open the file in shared mode. This option indicates the server should try to open the files to copy in shared mode if the files can't be opened in exclusive mode. To use this option, OR the ctCFallowSharedOpen bit into the cpoptions field of the CPYPRM structure passed to ctCopyFile()
Note: Files with an .FCS extension (such as FAIRCOM.FCS, SYSLOGDT.FCS, L0000001.FCS, SNAPSHOT.FCS, etc.) are considered to be a c-tree internal system housekeeping files. The file copy function does not allow copying from or to c-tree internal system files. An attempt to copy such a file fails with error code 1013 (SCPY_ERR).
Copying c-tree files
When copying a c-tree file, c-tree assigns a new file ID to the copy of the file so that the file ID does not match the original file’s ID, and c-tree sets the data and index file and directory names in the data file’s IFIL resource to the names of the new copies of the files. Other than those differences, the copied file is identical to the original file: it contains the same active and deleted data records or index nodes and key values, resources, and has the same properties as the original file, including:
The caller indicates what action to take when a file already exists with the same name as the specified destination file. By default, the file copy fails in this situation, but the caller can specify that the existing file should be deleted instead.
When copying multiple files (for example when copying a data file and its associated index files), if an error occurs c-tree stops the file copy operation and deletes all files that were successfully copied. If desired, the caller can specify an option to keep all the successfully copied files in case of an error.
Limitations
The following operations are not currently supported:
File Copy Options
ISAM or Low-Level Copy
Choose either an ISAM-level or a low-level file copy:
Use one of these options to select the desired behavior:
Copy with file opened in shared mode
Copy to Directory or File Names
Choose to either copy the file(s) to a specified directory or to copy the specified file(s) to the specified new file name(s).
Copying to a specified directory requires the caller to specify the source file name and the destination directory name. In order to use this option for an ISAM file copy, the data and index files must all reside in the same directory.
Copying to the specified new file names requires the caller to specify the source file name and the destination file name. When using this option for an ISAM file copy, the caller must supply source and destination file names for the data file and all its index files.
Use one of these options to select the desired behavior:
Destination File Exists
Choose the desired behavior when the destination file exists. By default, if the destination file exists, the file copy function leaves the destination file unchanged and returns an error. The caller can instead choose to delete the destination file by using the following option:
Create Destination Directory
By default, if a destination directory does not exist, the file copy fails. The caller can choose to create the destination directory by using the following option:
Keep Successfully-Copied Files if One Fails
By default, when a c-tree data file and its associated index files are being copied, if one of the files fails to be copied, all the successfully-copied files are deleted. The caller can choose to keep the successfully-copied files by using the following option value:
Remote File Copy
By default, a FairCom DB server creates the destination file on its own filesystem (a local file copy). Files can be copied to another server (a remote file copy) by specifying the following option and specifying the user ID, user password, and server name in the server parameter block or the appropriate API function to set server parameters:
Your remote server must have ENABLE_TRANSFER_FILE_API YES in the configuration file or you will receive error NSUP_ERR (454, Feature not supported).
You will also need a multithreaded client library in the local server (mtclient.dll for Windows or libmtclient.so for Unix/Linux) or you will receive error TR_CLIL_ERR (850, "Transactional replication: Failed to start c-tree remote client subsystem: see CTSTATUS.FCS for details").
If you are logged on as a non-ADMIN user, you also need COMPATIBILITY NONADMIN_TRANSFER_FILE specified or you receive error LADM_ERR (589, Admin logon required).
Note: SYSCFG() has been updated with state bits to check for library availability as well as if the copy feature is enabled. Refer to SYSCFG() documentation for usage.
Verify
If you wish to verify that the source and destination files are identical after the file has been successfully copied, use the following option:
Note: This option is not yet supported for a remote file copy operation.
File Copy Function Call Structure Definitions
typedef struct cpyfil {
LONG versn; /* Structure version */
LONG ncpyprm; /* Number of file copy param lists */
LONG errbufsiz; /* Size of optional error buffer */
LONG reserved; /* Reserved for future use */
pCPYPRM pcpyprm; /* File copy parameter lists */
pCPYFNC pcpyfnc; /* Callback function */
pTEXT errbuf; /* Optional error message buffer */
} CPYFIL, ctMEM * pCPYFIL;
versn must be initialized to value CPYFIL_VERS_CUR.
File Name Structure Definition:
typedef struct ctfnam {
TEXT name[MAXFNAME]; /* Directory or file name. */
} CTFNAM, *pCTFNAM;
File Copy Parameter Structure Definition:
typedef struct ctcpyprm {
LONG versn; /* Structure version */
ULONG cpoptions; /* File copy options */
ULONG fboptions; /* File block options */
LONG filnamcnt; /* Number of file names */
pTEXT fileword; /* File password */
SRVPRM srvprm; /* Server parameters */
pCTFNAM srcfilnam; /* Source file names */
pCTFNAM dstfilnam; /* Destination dir or file names */
} CPYPRM, ctMEM * pCPYPRM, ctMEM ** ppCPYPRM;
versn must be initialized to value CPYPRM_VERS_CUR
File Copy Server Parameter Definition:
typedef struct srvprm {
NINT versn; /* Structure version */
TEXT userid[32]; /* User id */
TEXT userword[64]; /* User password */
TEXT servname[256]; /* Server name */
} SRVPRM, ctMEM * pSRVPRM;
versn must be initialized to value SRVPRM_VERS_CUR.
File Copy Callback Function Parameters:
typedef struct cpystt {
pCPYFIL pcpyfil; /* options passed to file copy function */
pTEXT filnam; /* name of the source file being copied */
COUNT val; /* percent complete or error code */
TEXT opcode; /* operation code */
} CPYSTT, *pCPYSTT;
File Copy Callback Function Prototype:
typedef NINT (*pCPYFNC)(pCPYSTT pcpystt);
File Copy Callback Function Operation Codes:
Notes:
Error Codes
New error codes introduced with the ctCopyFile() function:
Value |
Symbolic Constant |
Explanation |
|---|---|---|
1013 |
SCPY_ERR |
The file copy API function does not allow copying a FairCom system file. |
1014 |
DCPY_ERR |
When using the file copy API option to copy files to a new directory, the source data and index files must all reside in one directory. |
1015 |
CBKTRM_ERR |
A user-defined callback function terminated the operation. |
1016 |
GFSZ_ERR |
Error getting file size. Check sysiocod for system error code value. |
1017 |
FDIF_ERR |
The file comparison detected differences between the two files. |
Existing error codes that the ctCopyFile() function can return:
Value |
Symbolic Constant |
Explanation |
|---|---|---|
43 |
FVER_ERR |
The version of the CPYFIL, CPYPRM, or SRVPRM structure passed to the file copy function is not supported. |
See Also
