Continuous Operation (42)

The Continuous Operation operation (B_CONTINUOUS) allows you to perform system backups without closing active transactional interface files. Any changes you make while a file is being backed up are stored in a temporary file called a delta file. Except for changes written to the delta file, the system backup includes the contents of all files placed in continuous operation mode. The transactional interface automatically rolls the delta file changes into the backed up files when those files are taken out of continuous operation mode.

Note
This operation is available only to applications running on a local engine. A client application cannot use this operation for files that are located on a remote machine.

This operation also allows you to safely copy a file while that file is still active. In a client/server set up, the client that begins Continuous Operation on a file must be the client that stops Continuous Operation on that file.

Parameters


	Op Code	Pos Block	Data Buf	Data Buf Len	Key Buffer	Key Number
Sent
Returned

Note
Values for the Data Buffer parameter and the Data Buffer Length parameter are required only if the value of the Key Number parameter is 0 (which starts continuous operation mode) or 2 (which ends continuous operation mode). The following sections discuss these Key Number values. A Data Buffer Length of zero is required for a Key Number parameter of 1.

Procedure

To start continuous operation mode, perform the following steps:

Define a file or a set of files for backup, or add a file to the set of files currently defined for backup.

Set the Operation Code to 42.

Place the names of the files you want to place in continuous operation mode into the Data Buffer parameter. Include the full pathname, excluding only the server name. Separate the names with commas and terminate the list of names with a binary 0.

The following example is for Windows servers:

f:\acct\march.mkd,f:\acct\april.mkd

Place the length of the name (or names) in the Data Buffer Length parameter. This value must be equal to or greater than the actual length of the names (including binary zeros) in the Data Buffer itself. For example, the preceding names require a Data Buffer Length of 40 or greater.

Set the Key Number parameter to 0.

Perform the backup.

End continuous operation mode.

Set the Operation Code to 42.

Set the Key Number parameter to 1.

To end continuous operation on one or more specific files, set the Key Number parameter to 2, and then place the filenames in the Data Buffer parameter as described in step 1b. Also, place the length of the name (or names) in the Data Buffer Length parameter as described in step 1c.

Details

When defining the set of files to be backed up, keep in mind the following information:

The transactional interface does not consider the absence of filenames in the Data Buffer to be an error. If it finds no filenames, the transactional interface takes no action on the Continuous Operation operation.

The presence of duplicate filenames in the Data Buffer does not affect how the Continuous Operation operation works. The MKDE places the specified file in continuous operation mode only once.

In the same directory, no two files should share the same file name and differ only in their file name extension. For example, a data file named Invoice.btr and another one named Invoice.mkd must not exist in the same directory. This restriction applies because the database engine uses the file name for various areas of functionality while ignoring the file name extension. With continuous operations, the name of the delta file uses the corresponding file's name with ".^^^" for the file name extension. The transactional interface would attempt to write to the same delta file for both files, possibly causing data corruption or status 85. Also, no files are placed into continuous operations when this condition occurs, even if the files are part of a larger list to be placed into continuous operations.

An application can iteratively call the Continuous Operation operation to add more names to the list of files to be placed in continuous operation mode. However, this action can corrupt a backup when referential integrity (RI) constraints are placed on any of the files by the SRDE. Files related by referential integrity constraints should be passed in on a single continuous operations call.

The transactional interface returns Status Code 88 if a file is specified that is already in continuous operation mode.

When writing a server-based application that calls the Continuous Operation operation, make sure you call btrvID, and use a valid client ID so you can begin and end continuous operation under the same client.

The Btrieve API allows you to define multiple backup sets by specifying a different client ID for each backup set through the btrvID function. However, two sets cannot contain the same files.

While the transactional interface rolls changes from the delta file into the data file, users can continue to update, insert, and read the transactional interface file just as they normally would. The transactional interface appends new pages to the delta file while rolling in changes, if an insert requires such an action. No changes are lost.

Note
Never delete a delta file manually.

If your application uses the btrv function, do not unload the application while any file is in continuous operation mode. If you do, you may be unable to remove the affected files from continuous operation mode. This is because the default client ID that the transactional interface originally assigned as the owner of the affected files may have been reassigned to another application. Because the transactional interface no longer knows the proper owner of the affected files, it is unable to remove those files from continuous operation mode.

If the system crashes while in continuous operation mode or while the transactional interface is rolling the changes from a delta file into the file, then the transactional interface rolls all changes into the file when it is first opened after the system is rebooted.

Result

If the Continuous Operation operation is successful, the transactional interface returns Status Code 0, but it returns no values either in the Data Buffer or in the Data Buffer Length parameter.

If the operation is unsuccessful, the transactional interface returns one of the following status codes:


11	The specified filename is invalid.
12	The transactional interface cannot find the specified file.
41	The transactional interface does not allow the attempted operation.
51	The owner name is invalid.
88	The application encountered an incompatible mode error.
91	The application encountered a server error.

In addition to the preceding codes, your application can return standard
I/O error codes such as Status Code 18.

If the transactional interface returns a nonzero status code, the Continuous Operation operation returns in the Data Buffer the portion of the input string that generated the error. If no input string was used, the Data Buffer contains the file names that caused the error. The Data Buffer Length reflects the length of the output string in the Data Buffer. At this point, the Data Buffer Length contains the length of that filename.

Positioning

The Continuous Operation operation does not establish any currency on the file.