Btrieve Files

A file is the highest-level database entity you can access using Btrieve. Btrieve allows a maximum file size of approximately four gigabytes. You can create Btrieve data files and define their characteristics by using either of the following:

This section discusses the following information about files:

File Components

Btrieve files consist of a series of pages. A page is the unit of storage that Btrieve transfers between memory and disk. You specify a fixed size for each page when you create a file. The page size is always a multiple of 512 bytes, up to 4,096 bytes.

As discussed in the following sections, a Btrieve file is composed of these types of pages:

FCR Pages

The first two pages in every Btrieve 6.x file are the File Record Control (FCR) pages. At any given time, Btrieve considers one of the FCR pages to be current. The current FCR page contains the latest information about the file, such as the file size, page size, alternate collating sequence (ACS) name (if any), and other characteristics of the file.

Page Allocation Table Pages

Page Allocation Table (PAT) pages are part of Btrieve 6.x's internal implementation for converting between physical and logical page numbers in a Btrieve file.

Btrieve knows the specified page length of every Btrieve file. Therefore, it can determine the location of each page by knowing that page's physical page number. For example, if the page size of a Btrieve file is 4,096 bytes, page 0 starts at offset 0, page 1 starts at offset 0x1000 (4096), page 2 at offset 0x2000 (8192), and so on.

Since this tracking deals with a page's physical location within the Btrieve file, these page numbers are called physical page numbers.

However, as records are modified in a Btrieve file (or as indexes are created or deleted), information changes location within the file. For example, a record describing employee Cliff Jones might be on physical page 34 when you begin an update, but on physical page 38 when you finish the update.

To keep track of information as it moves around the Btrieve file, Btrieve uses the concept of logical page numbers. Records always reside on the same logical page, even though they move from one physical page to another as modifications occur.

The PAT tracks the mapping of logical page numbers to physical page numbers.

Data Pages and Variable Pages

When your application inserts a record into a file, Btrieve stores that record on either a data page or on both a data page and a variable page. Data pages contain fixed-length records; variable pages contain variable-length records. (Records are discussed in “Records”.)

If a file does not allow variable-length records (described in “Variable-Length Records”) or data compression (described in “Data Compression”), it will have data pages but no variable pages.

Each data page may contain one or more data records. The number of records per page depends on the record length. Btrieve does not split the fixed-length portion of a record across two data pages.

If a file allows variable-length records or data compression (or both), it will contain both data pages and variable pages. The data pages contain only the fixed-length portions of the records. The variable pages contain only the variable-length portions of the records.

If the variable-length portion of a record is longer than the defined page size (minus overhead) for the file, Btrieve splits the variable-length portion over multiple variable pages.

Index Pages

Index pages are nodes in a B-tree structure. Each node contains key values for the data records. Generally, index pages contain many different key values.

Each key value on the page has a record address. Btrieve uses this address to retrieve records containing a specified key value.

NOTE: When you enable linked-duplicatable keys (discussed in “Linked-Duplicatable and Repeating-Duplicatable Keys”), each key value on the page has two record addresses that Btrieve uses when retrieving records.

Alternate Collating Sequence Page

If any index in a Btrieve file uses an alternate collating sequence (ACS), the file will have at least one ACS page. (ACSs are described in “Alternate Collating Sequence”.

File Types

Btrieve allows you to create three different types of files:

Standard Btrieve Files

A standard Btrieve 6.x file contains two FCR pages followed by a number of PAT pages, index pages, data pages, and possibly variable pages. As this implies, you can create a standard Btrieve file for use with either fixed- or variable-length records.

Because standard Btrieve files contain all the index structures and data records, Btrieve can dynamically maintain all the index information for the records in the file. You can use any of the Btrieve record retrieval operations to access the information stored in a standard Btrieve file.

Data-Only Files

Btrieve also lets you create data-only files that hold only data. When you create a data-only file, you do not specify any key information, and Btrieve allocates no index pages for the file (only the two FCR pages and the PAT pages). This results in a smaller initial file size than for standard Btrieve files.

When an application inserts records into the file, Btrieve stores them in the chronological order of insertion.

IMPORTANT: The chronological ordering of records can change when you delete records and insert new ones, or when the Btrieve file is rebuilt. An application should not depend on the chronological ordering of records in a Btrieve file.

Btrieve does not maintain or create any index pages as the records are inserted. At this point, an application can access the records using only the Step operations or the Get Direct/Record (23) operation, all of which use the physical location to find records.

At any time after creating a data-only file, you can add an index using the Btrieve Maintenance utility command SINDEX, or an application can issue a Create Index (31) operation. Then, the new index can be used to retrieve records with the Get operations.

Key-Only Files

Key-only files contain only FCR pages followed by a number of PAT pages and index pages. If a key-only file has an ACS, it may also have an ACS page. Similarly, if anyone has used the Scalable SQLTM relational data access system to define referential integrity (RI) constraints on the file, the file may contain one or more variable pages.

In a key-only file, the entire record is stored with the key, so no data pages are required. Key-only files are useful when your records contain a single key, and that key takes up most of each record. Another common use for a key-only file is as an external index for a standard Btrieve file.

The following restrictions apply to key-only files:

File Space Allocation

Btrieve automatically reallocates file space when you insert or delete Btrieve records. The following paragraphs explain how Btrieve dynamically allocates space and uses free space.

Dynamic Expansion

Btrieve allocates disk space as needed. If there is not enough room in the file when an application inserts new records, Btrieve dynamically allocates additional data and index pages to the file. The size of each allocated page is the same as the page size with which the file was created.

Btrieve also updates directory structures to reflect the new file size.

Once Btrieve allocates space to a file, that space remains allocated as long as the file exists. To reduce the space required for a file from which numerous records have been deleted, you can create a new file with the same characteristics as the original file using the Maintenance utility command CLONE (described in “CLONE”).

Then use one of the following Maintenance utility commands or command sequences to read the records from the original file and insert them into the new file:

For detailed information about using these commands, refer to “NetWare Btrieve Maintenance Utility Commands” in Chapter 5, "Using NetWare Btrieve Utilities."

Free Space Utilization

When you delete a record, the disk space it formerly occupied is put on a free space list. When an application inserts new records, Btrieve uses the free space instead of allocating additional pages to the file. Btrieve's method of reusing free space eliminates the need to reorganize files to reclaim disk space.

Special File Considerations

The following sections describe types of files that require special consideration when used with different versions of Btrieve:

Transactional Files

NetWare Btrieve uses the NetWare TTS feature to ensure the physical integrity of a file. When you use TTS to guard your files, your files have the transactional attribute set and are called transactional files.

To set up your files as transactional, set a transactional bit in NetWare with the NetWare FLAG command, which flags an existing Btrieve file (or files) as transactional. A file can also be flagged transactional at the time of its creation is the proper parameter was set when Btrieve was loaded.

For information on NetWare TTS or the FLAG command, refer to your NetWare documentation.

Btrieve 6.x and Pre-image Files

Btrieve 6.x creates a pre-image file when writing to a Btrieve file that was created in either one of two ways:

However, the format of a pre-image file created by Btrieve 6.x differs from the format of a pre-image file created by pre-6.x versions of Btrieve. This means that the earlier versions of Btrieve will not be able to accurately interpret a pre-image file created by Btrieve 6.x. Also, Btrieve 6.x will not be able to accurately interpret a pre-image file created with an earlier version of Btrieve.

If you need to change from running Btrieve 5.x to running Btrieve 6.x (or vice versa) and your application will be accessing pre-6.x Btrieve files, you must delete all pre-image files prior to changing Btrieve versions.

For detailed information about this process, see “Checking for and Removing Extraneous Pre-Image Files” in Chapter 3, "Installing and Configuring NetWare Btrieve."

For additional information about pre-image files, see “Pre-imaging” in this appendix.