Btrieve allows you to access records from a file based on either the record's physical address within the file or a key value contained in the record. Btrieve also allows you to access portions of a record by using chunk operations.
Record accessing by physical location is faster for the following reasons:
The following sections explain physical currency (the effect on positioning when accessing records by physical location) and the Step operations (the record operations used to access a record by its physical location).
When you insert a record into a Btrieve file, Btrieve writes the record into the first free space available in the file, regardless of any key values contained in the record. This location is referred to as the physical location, or address, of the record. The record remains in this location until you delete it from the file.
The physical location of the records in the file determines the physical order of the records. The Btrieve Step operations use the physical location to access records.
The physical current, next, and previous locations together form the physical currency within the file.
An application can use the Step operations to access records based on their physical location within a file.
For example, the Step First (33) operation retrieves the record that is stored in the first, or lowest, physical location in the file. The Step Next (24) operation retrieves the record stored in the next higher physical location.
The Step Previous operation retrieves the record stored in the next lower physical location in the file. The Step Last (34) operation retrieves the record that is stored in the last, or highest, physical location in the file.
The Step Next Extended (38) and Step Previous Extended (39) operations retrieve one or more records from the physical location following or preceding the current record.
The Step operations are useful for traversing a Btrieve file quickly if an application does not need to retrieve the records in a specific order.
Accessing records by key value allows you to retrieve records based on their values for a specified key. The following sections discuss these topics:
When you insert a record into a file, Btrieve updates each B-tree index for which the appropriate key in the record has a non-null value. Each key of a file determines a logical ordering of the records. The ordering can be from low to high or from high to low, depending on whether the key is defined as ascending or descending. The record accessed last is not only the physical current record, but also the logical current record. For example, when you insert a record, that record becomes the physical current record. It also becomes the logical current record (unless you perform a no-currency change Insert operation or the inserted record's key value is null). Relative to any logical current record based on a certain key, the record next in the defined logical sequence is the logical next record and the record previous in the defined logical sequence is the logical previous record. NOTE: The logical previous of the logical first record does not exist---nor does the logical next of the logical last record.
The logical current, next, and previous locations together form the logical currency within the file. The Btrieve Get record operations use the logical locations when accessing records. An application can use the Get operations to retrieve records based on their values for a specified key. The appropriate Get operation can retrieve a specific record from a file or retrieve records in a certain order. For example, the Get First (12) operation retrieves the first record by the key specified in the key number parameter. Likewise, the Get Last (13) operation retrieves the last record according to the logical order based on the specified key. Some Get operations, such as Get Equal (5) or Get Less Than (10), return a record based on a key value your application specifies in the key buffer parameter. Get operations establish Btrieve's logical currency in an index. In addition to establishing logical currency, all Get operations except Get Position also establish the physical currency. Btrieve uses an area of memory called the position block to maintain logical positioning information for use in accessing records. Btrieve maintains positioning and other necessary information associated with each open file. It stores this information in a 128-byte block of memory that passes between Btrieve and your application. Some of the information contained in the position block is as follows:
Many of the Btrieve operations modify the contents of the position block to reflect the new position within the file. Btrieve uses positioning information to read sequentially through the file by a given key. An application should maintain a 128-byte position block for every Btrieve file that is open. A chunk is a set of logically contiguous bytes that is defined by its offset and length within a record and that can be accessed by the Btrieve Get Direct/Chunk (23) operation or by an Update Chunk (53) operation. This ability to operate on a chunk (rather than on the entire record) is a feature introduced in Btrieve 6.1 and is applicable to any 6.x file. NOTE: Chunks are defined only for the duration of the operation that defines them.
A chunk's offset and length need not correspond to any of the internal structures of a record that are known to Btrieve, such as key segments, the fixed-length portion of a record, or a variable tail (discussed in Storing Variable-Length Records: Variable Tails and VATs). Also, a chunk need not correspond to any portion of the record defined by the application (for example, a field), although you may find it useful to update such defined portions as chunks. Probably the main reason to use chunks in an application is to overcome the restrictions imposed by the Btrieve data buffer length parameter. Essentially, an application can pass no more than 65,535 bytes in the Btrieve data buffer at one time (sometimes less). Therefore, if the records in an application exceed this length, you cannot pass an entire record in a single Btrieve operation. The application can, however, divide that record into chunks. An application using chunk operations also allows a workstation that makes calls to a remote Btrieve server to use a smaller value for its requester's Maximum Data Buffer Length parameter. This smaller value lowers the requester's requirement for memory on the workstation. Btrieve provides two operations that allow an application to access chunks: Get Direct/Chunk (23) and Update Chunk (53).Logical Currency
Get Operations
Position Block
Accessing Records by Chunks