Btrieve provides a number of methods for recovering data. Some of these methods are automatic and require no interaction from an application or an end-user. Others require some form of manual intervention.

IMPORTANT:  None of the following methods eliminate the need to back up files because none of these methods can recover data from a damaged disk. Therefore, it is imperative that backups be made to protect against the catastrophic loss of a file because of a hardware failure.

Btrieve provides the following automatic data recovery methods:

• Shadow paging or pre-imaging (depending on the file's format)
• Transaction control

For any Btrieve file using a 6.x format, Btrieve automatically guards against file corruption by using shadow paging.

Shadow paging is especially useful when Btrieve needs to perform several physical page updates to process either a single non-transactional request or an entire transaction for an application.

Without shadow paging, if Btrieve processing is interrupted during these operations by a system failure, files may be corrupted. Corrupted files may contain inconsistent index pages, and retrieving data from the file might be impossible. Shadow paging provides automatic protection against such corruption.

During the execution of a request or transaction that changes the file, Btrieve does not overwrite original pages. Instead, it creates shadow pages (copies of the original pages to be modified), then selects and locks free physical locations within the file where the pages will ultimately be stored. Btrieve then makes the requested modifications to the shadow pages where they reside in cache.

The original pages remain unchanged. When all modifications to a particular shadow page are finished, Btrieve initiates the process of writing that shadow page to a selected free physical location within the file.

For the purposes of data recovery, Btrieve bundles one or more non-transactional operations and/or committed transactions into a system transaction. A system transaction can include operations or transactions from one or more users. However, unless a system failure occurs, system transactions are completely transparent to an application.

If all changes to shadow pages are successful for a single non-transactional request, or if an End Transaction (20) operation is issued for a transaction, Btrieve commits the changes by making the shadow pages the new original pages (and therefore no longer shadow pages).

However, if partial changes made by a single request need to be rolled back, or if an Abort Transaction (21) operation is issued, Btrieve returns the space occupied by any shadow pages that are uncommitted (but that have already been written to disk) to one of Btrieve's Free Space Lists. Once on a Free Space List, pages are recycled during future operations.

A system transaction is complete when all the single requests and/or transactions in that system transaction are committed, and all the shadow pages involved in that system transaction have been written to disk. When a system transaction completes, Btrieve places the old original pages involved in that system transaction on the Free Space List.

If the system fails before a system transaction completes, Btrieve recovers all files involved in the failed system transaction.

Then, when it is first loaded (after you power up your system), Btrieve uses the yet unchanged original pages to return the files to the state they were in immediately prior to the failed system transaction. This recovery mechanism works regardless of whether the files have been flagged transactional.

NOTE:  Client-based versions of Btrieve ignore a file's NetWare transaction tracking system (TTS) flag.

All changes made by a failed system transaction are lost. However, the file is left in a consistent state, allowing the operations to be attempted again after resolving the cause of the system failure.

Pre-imaging

For any Btrieve file using the pre-6.x format, Btrieve cannot apply shadow paging to guard against file corruption. Instead, it uses pre-imaging.

The effects of pre-imaging are roughly equivalent to those of shadow paging. However, pre-imaging is more time-consuming than shadow paging (another reason to consider converting your pre-6.x files to the 6.x format).

Unlike shadow paging, pre-imaging causes Btrieve to create a temporary pre-image file in the same directory where the original Btrieve data file resides. Btrieve creates this pre-image file the first time you modify a data file or access a data file during a transaction (except when the file is opened in read-only mode).

The temporary file has the same name as the file it is protecting, except that the filename extension is .PRE. For example, if you opened the ACCTID.DTA file, the temporary filename would be ACCTID.PRE. Btrieve uses this temporary file to track changes to the actual file during a request.

Do not create filenames with the extension .PRE because they will corrupt the recovery process.

Since the name of the pre-image file is the same as the Btrieve file (except for the extension), do not create multiple Btrieve files with the same names but different extensions in the same directory.

For example, do not use a naming scheme like INVOICE.HDR and INVOICE.DET for your Btrieve files. Otherwise, Btrieve tries to use INVOICE.PRE for both files and automatic recovery becomes impossible.

During the execution of a request or transaction that changes the file, Btrieve writes the image of the original pages to be changed to the pre-image file. Btrieve makes the requested modifications to the original pages where they reside in cache, then overwrites the original pages on disk with the new images from cache.

However, if partial changes made by a single request need to be rolled back, or if an Abort Transaction (21) operation is issued, Btrieve restores the original images from the pre-image file.

IMPORTANT:  Once Btrieve creates a pre-image file, do not delete it (except as preparation for converting a Btrieve file's format from 5.x to 6.x). Without the pre-image file, Btrieve cannot recover data after an abnormal termination.

Transaction Control

By defining explicit transactions within a program, you can force Btrieve to treat multiple Btrieve operations as an atomic unit---that is, Btrieve does not complete any of the operations in an explicit transaction unless it can successfully complete all of them.

NOTE:  For operations made inside a transaction involving a Btrieve file using the pre6.0 file format, changes are immediately visible to other users reading those files. With 6.x-format files, changes are not visible to other users until the End Transaction (20) operation completes.

If the system fails during an explicit transaction (which is automatically part of a system transaction), Btrieve removes (rolls back) all the operations performed during the system transaction.

To perform this automatic recovery procedure, Btrieve creates the file BTRIEVE.TRN whenever one or more files are opened in an explicit transaction. (BTRIEVE.TRN is located in the SYS:SYSTEM directory on the server unless otherwise specified during the Btrieve setup).

When Btrieve is loaded the first time after a system failure, it automatically checks BTRIEVE.TRN to see what files were involved in a transaction at the time the failure occurred. If BTRIEVE.TRN contains any filenames, Btrieve checks each of those files for consistency and returns the inconsistent files to their pre-transactional state, if necessary.

NOTE:  Btrieve recovers each file listed in BTRIEVE.TRN with the exception of files that cannot be opened. To ensure that Btrieve can open all the files you were working on at the time of the system failure, you should log in to every server containing those files prior to restarting the application.

Occasionally, you may be unable to log in immediately to a server containing files with which you were working. In such a case, NetWare Btrieve cannot recover those files using transaction recovery (BTRIEVE.TRN). Btrieve will recover these files when someone logs into the server and opens the files. Therefore, individual files will not remain corrupted.

However, integrity between files cannot be guaranteed when files are recovered individually. Only transaction recovery can restore the integrity of the database. For this reason, if at all possible before you restart your application, log in to every server containing files you were working on at the time of the system failure.

As part of the recovery process, NetWare Btrieve prints a message to the window (or console) indicating which files are being rolled back. If a listed file cannot be opened, Btrieve prints a warning identifying the file and stating that it cannot be rolled back.

After recovery is completed, the first system transaction overwrites BTRIEVE.TRN.

Manual Data Recovery