Btrieve uses keys to identify specific records in a file. By using a key, Btrieve can efficiently select the record you want from the entire collection of records in a file. Because Btrieve has no way of knowing the exact structure of the records in each file, you define each key by identifying its offset in bytes from the beginning of the record, and specifying the number of bytes you want to use for that key.
For example, suppose a particular key begins at the eighth byte of the record and extends for four bytes. When you insert the record into the file, Btrieve will read four bytes, beginning with the eighth byte, and use the value it finds there to position the record in the index. The keys you define may overlap each other in the record.
When you create a file, you can specify six different attributes for each key in the file. The six key attributes are duplicate, modifiable, segmented,
descending, null, and manual.
2-6 20l/Revl.OO
(
Btrieve File Management
DUPLICATE KEYS
You can define a duplicate key to identify a subset of records, all of which can contain the same value for a particular key. If you specify that a key not allow duplicates, Btrieve does not allow an application to add multiple records to the file with the same value in the key field. Btrieve stores
duplicate key values in the chronological order of insertion into the file. If one segment ofa segmented key allows duplicates, all of the segments must allow duplicates.
For example, in a file containing customer records you can define the zip code field as a duplicate key so that many different records can contain the same value for zip code. However, if you also make the field for the customer number a key field, you probably would not want to allow duplicates, since each customer should have a unique number.
MODIFIABLE KEYS
You can also define a key as modifiable. Btrieve then allows your application to update an existing record and change the value of the key field. For example, if account balance is a key field, you may allow a program to modify the value of the field as the customer makes purchases and payments.
However, you probably would make a field such as the account number a non-modifiable key since the customer's account number should never change. If one segment of a key is modifiable, all of the segments must be modifiable.
SEGMENTED KEYS
Keys can consist of one or more segments in each record. A segment generally corresponds to a field in the record and the segments do not have to be contiguous. The total length of a key is equal to the sum of the length of the key segments. The maximum total length is 255 characters. Different key segments may overlap each other in the record.
2011Revl.OO 2-7
A Btrieve file is restricted to a maximum number of key segments rather than a maximum number of keys. The maximum number of key segments allowed depends on the page size. You can define as many as eight key
segments if the page size is 512 bytes. For a file with a page size of 1024 bytes or greater, you can define up to 24 key segments. (See "Determining Record Length and Page Size" on page 2-12 for more information about page size.) A file with a page size of 512 bytes or greater may contain one key with eight segments, eight keys with one segment each, or any combination in between.
If a file has a page size of 1,024 bytes or greater, it may contain one key with 24 segments, 24 keys with one segment, or any combination in between.
The key type can be different for each segment in the key. The sort order, either ascending or descending, can be different for each segment as well.
DESCENDING KEYS
Btrieve normally orders key values in ascending order (lowest to highest).
However, you can specify that Btrieve order the key values in descending order (highest to lowest) when you define the key segment.
Btrieve operations produce results based on the order of the key values in the index, not on the result of a comparison of key values. For example, when you perform a Get Greater operation on a descending key, Btrieve returns the record corresponding to the first key value that is lower than the key value you specify in the key buffer. Likewise, when you perform a Get Less Than operation using a descending key, Btrieve returns the record with the next higher key value than the one you specify in the key buffer.
NULL KEYS
You can direct Btrieve to exclude certain records from an index by defining null keys. When you define a null key, you specify a value that you want Btrieve to recognize as the null value for that key. If every byte of the key contains the null value, Btrieve will not include the record in the index for that key. If you define one segment of a key with the null attribute, you must define all segments of that key with the null attribute.
2-8 201lRevl.OO
(
(
Btrieve File Management
Btrieve will treat a key as null only if ~
bl1&
in the key contains the null value. If the key is segmented, every byte in~ segment must contain the null value in order for Btrieve to exclude the key from the index. You can define different null values for different segments in a segmented key. The most commonly used null values are ASCII blank (hex 20) and binary 0 (hex 0).You can use a null value in a key when the data for the key is unavailable, or when you do not want Btrieve to include that record in the index for that key.
Null keys allow you to avoid searching through meaningless records in an index path, and eliminate the overhead time required to update the index each time a blank key is inserted. When the data becomes available, or when you want to include the record in the index, you can update the record, replacing the null value with another value.
MANUAL KEYS
The manual key is a modified form of the null key, and can be used to exclude particular records from the index. Like a null key, you must define a value that indicates whether you want Btrieve to include the record in the index. If you define one segment of a key with the manual attribute, you must define all segments of that key with the manual attribute.
Manual keys have all the attributes of a null key, with one exception. In a manual key, if every byte of.aIlX.ane. segment contains the null value, Btrieve will exclude the key from the index.
For example, you can use a manual key segment as a flag to indicate whether the key is to be indexed. If the segment contains only the null value that you defined for that segment, Btrieve will not include the key in the index, even though the rest of the segments in the key contain non-null values. By updating the flag segment with any value other than the specified null value, you can instruct Btrieve to include the record in the index.
You can define a key as being both null and manual. In this case, the null value will always be the same for both the null and manual attributes.
However, the manual attribute will always override the null attribute.
201lRevl.OO 2-9