Product Documentation

FairCom ISAM for C

Previous Topic

Next Topic

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:

  • security (file owner, file group, file permission mask, file password)
  • data encryption
  • data compression
  • transaction control

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:

  • Copying a partition host file.
  • Copying a segmented file.
  • Copying a superfile host file.
  • Copying a non-c-tree file.

File Copy Options


ISAM or Low-Level Copy

Choose either an ISAM-level or a low-level file copy:

  • An ISAM copy specifies the name of a c-tree data file, and the data file and its associated index files are copied.
  • A low-level file copy copies only the specified file.

Use one of these options to select the desired behavior:

  • ctCFisam - Copy an ISAM data file and its index files.
  • ctCFlowlevel - Copy only the specified file.

Copy with file opened in shared mode

  • ctCFallowSharedOpen - Allow files to be opened in shared mode if possible. Available in V11.6 and later.


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:

  • ctCFtoDir - Copy files to the specified directory.
  • ctCFtoName - Copy files to the specified file names.


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:

  • ctCFifexistDelete - Delete destination file if it exists.


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:

  • ctCFcreateDirs - Create destination directories.


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:

  • ctCFiferrorKeep - Keep all successfully-copied files if a subsequent file fails to be copied.


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:

  • ctCFtoServer - Copy files to a specified server.

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:

  • ctCFverify - After copying a file, verify that the source and destination files are identical.

    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:

  • ctCPYCBKbeginfile - Start file copy
  • ctCPYCBKprogfile - File copy progress (val contains the percent complete)
  • ctCPYCBKendfile - End file copy (val contains the error code)
  • ctCPYCBKvrfyfile - File verify progress (val contains the percent complete)

Notes:

  1. If there is only one physical index file associated with a data file and the physical index file's aidxnam is NULL (so that it has the same name as the data file), the ctCFtoName option can be used with only one set of names (old data file name and new data file name).
  2. When a file copy fails because the destination file exists, error 18 is returned if a destination index file exists and error 19 is returned if the destination data file exists.

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

TOCIndex