Table 7. Summary of Description File Elements

Record Length

Format: record=nnnn

Range: 4 through 4,088 bytes

Command: CREATE

The Record Length element defines the logical data record length in bytes. For fixed-length records, this value should correspond to the length of the data buffer parameter that performs operations on the file. For variable-length records, this value should correspond to the fixed-length portion of the record.

The data record length must be at least 4 bytes and must be large enough to contain all the keys defined for the file. The record length (including its duplicate key overhead and usage count overhead) plus 6 bytes must not exceed the file's page size.

Variable-Length Records

Format: variable=<y|n>

Range: Not applicable

Command: CREATE

The Variable-Length Records element specifies whether the file will contain variable-length records. If a record is variable length, the maximum fixed-length record is decreased by 4 bytes. Specify y if you want the file to allow variable-length records; otherwise, specify n.

Reserved Duplicate Pointer

Format: dupkey=nnn

Range: 1 through 119

Command: CREATE

The Reserved Duplicate Pointer element is optional. It specifies the number of duplicate key pointers to preallocate for the file when it is created. Each reserved duplicate pointer adds 8 bytes of extra storage space to the fixed record length. These reserved pointers can be used when keys that allow duplicates are added after the file is created and if you do not specify y for the Repeating Duplicates element.

Blank Truncation

Format: truncate=<y|n>

Range: Not applicable

Command: CREATE

The Blank Truncation element is optional. It specifies whether Btrieve performs blank truncation on variable-length records. The truncate element has an effect only if you specify y for the Variable-Length Records element.

Specify y if you want Btrieve to use blank truncation. Otherwise, either specify n or omit this element from your description file.

Data Compression

Format: compress=<y|n>

Range: Not applicable

Command: CREATE

The Data Compression element is optional. It specifies whether Btrieve performs data compression on records that are inserted into the file.

Specify y if you want Btrieve to perform data compression. Otherwise, either specify n or omit this element from your description file.

Key Count

Format: key=nnn

Table 8. Key Segment Count Values

Page Size

Format: page=nnnn

Range: 512 through 4,096 bytes

Command: CREATE

The Page Size element specifies the physical page size (in bytes) for the file. You can specify any multiple of 512, up to 4,096.

HINT:  For optimum performance, set the page size to 512, 1,024, 2,048, or 4,096 bytes.

Format: allocation=nnnnn

Range: 1 through 65,535

Command: CREATE

The Page Preallocation element is optional. It specifies the number of pages to preallocate to the file. If you do not want to preallocate any pages, either specify n or omit this element from your description file.

Replace Existing File

Format: replace=<y|n>

Range: Not applicable

Command: CREATE

The Replace Existing File element is optional. If you do not want to create a new, empty file over an existing Btrieve file of the same name, specify n. If you want to replace an existing Btrieve file with a new, empty file of the same name, either specify y or omit this element from your description file.

Include Data

Format: data=<y|n>

Range: Not applicable

Command: CREATE

The Include Data element is optional. It specifies the file type that the utility creates. To create a key-only file, specify n. To create a standard file, either specify y or omit the element from the description file. To create a data-only file, specify y and set the Key Count element to 0.

Free Space Threshold

Format: fthreshold=<10|20|30>

Range: Not applicable

Command: CREATE

Btrieve stores the variable-length portions of records on their own pages (called variable pages), separate from the fixed-length portion of the record (which is stored on a data page). Btrieve maintains the Free Space List for variable pages. The Free Space List indicates which variable pages contain the same or more free space than that specified by the Free Space Threshold file specification.

You can specify a value for the Free Space Threshold element when you create the file. This value is expressed as a percentage and tells Btrieve how much free space must remain on a variable page in order for that page to appear on the Free Space List. When Btrieve adds new variable-length records to the file, it uses pages in the Free Space List before using new variable pages.

After each Insert, Update, or Delete operation, Btrieve rechecks the remaining space on the affected variable page to see if it is still above the threshold to qualify for the Free Space List.

The free space threshold feature provides a means of reducing the fragmentation of variable-length records across several pages. A higher free space threshold reduces fragmentation at the cost of requiring more disk space for the file.

You can specify any two-digit number for this element, and the utility rounds it to 10, 20, or 30.

Btrieve uses a default free space threshold of 5 percent if either of the following is true:

• You specify a value less than 10.

• You do not specify a value here but have specified y for the Variable-Length Records element.

  NOTE:  If the Btrieve file does not allow variable-length records, do not include this element in the description file.

Format: huge=<y|n>

Range: Not applicable

Command: CREATE

The Variable-tail Allocation Tables (VATs) element is optional. Btrieve v6.1 allows an application to create Btrieve files that contain structures called Variable-tail Allocation Tables (VATs), which are implemented as linked lists.

To accelerate random access to portions of records, Btrieve uses VATs with each record. VATs are also helpful in files using data compression to limit the size of the compression buffer that Btrieve uses. If you want to create a file that uses VATs, specify y. Otherwise, either specify n or omit this element from your description file.

NOTE:  For more information about VATs, refer to the Btrieve Programmer's Manual.

Format: balance=<y|n>

Range: Not applicable

Commands: CREATE

The Balanced Index element is optional. This feature allows you to use index balancing. With index balancing, Btrieve looks for available space in sibling index pages each time an index page becomes full and then rotates values from the full page into the pages with space available.

Index balancing increases index page utilization, results in fewer pages, and produces an even distribution of keys among nodes on the same level, thus enhancing performance during Get operations. However, the use of this feature also means that Btrieve requires extra time to examine more index pages and may require more disk I/O during Insert, Update, and Delete operations.

NOTE:  You can specify index balancing on a file-by-file basis when the file is created. When you specify index balancing for a specific file, Btrieve will always balance that file's keys. You can also turn index balancing on and off for files that are not flagged as balanced by specifying Yes to the Perform Index Balancing configuration option in the Setup utility.

To use index balancing, specify y. Otherwise, either specify n or omit this element from the description file.

Format: position=nnnn

Range: 1 through value specified for Record Length element (up to 4,088)

Commands: CREATE, INDEX, SINDEX

The Key Position element indicates the position of the key segment in the record. The key position value must be at least 1 and cannot exceed the value you specified for the Record Length element.

Key Length

Format: length=nnn

Range: 1 through limit determined by key type

Commands: CREATE, INDEX, SINDEX

The Key Length element defines the length of the key or key segment field. The value you specify here cannot exceed the limit dictated by the key type, which the Key Type element specifies. The key length must be an even number if the key is a binary key type. The total of the key's length and starting position cannot exceed the file's defined record length.

Duplicate Key Values

Format: duplicates=<y|n>

Range: Not applicable

Commands: CREATE, INDEX, SINDEX

The Duplicate Key Values element specifies whether more than one record in the file can contain the same value for this key field. Specify y if you want to allow duplicate values for the key field; otherwise, specify n.

NOTE:  If you define duplicate key values for one segment of a segmented key, you must define duplicate key values for every segment of that key. For a segmented key that does not allow duplicates, the segments may contain duplicates between multiple records only if the key value is unique for each record.

Format: modifiable=<y|n>

Range: Not applicable

Commands: CREATE, INDEX, SINDEX

The Modifiable Key Values element specifies whether the key value can be modified during an Update operation. Specify y if you want the values for this key to be modifiable; otherwise, specify n.

NOTE:  If you define modifiable key values for one segment of a segmented key, you must define modifiable key values for every segment of that key because the key, as a whole, is modifiable.

Format: type=validBtrieveKeyType

Range: Not applicable

Commands: CREATE, INDEX, SINDEX

The Key Type element specifies the Btrieve data type for the key. This element determines how Btrieve will sort the bytes specified for this key segment. Btrieve does not perform any validation on the data inserted. You can specify the entire word (as in float) or just the first three letters of the word (as in flo for float). The Btrieve key types are as follows:

NOTE:  STS (sign trailing separate) is a COBOL data type. It is basically a numeric data type, represented as an ASCII string. STS is right justified and padded with leading ASCII zeros, and it has the sign byte at the end.

Format: descending=<y|n>

Range: Not applicable

Commands: CREATE, INDEX, SINDEX

The Descending Sort Order element is optional. It specifies whether Btrieve will collate the index or index segment in descending order.

Specify y if you want Btrieve to collate the key values in descending order. If you want Btrieve to collate the index in ascending order, either specify n or omit this element from the description file.

Alternate Collating Sequence

Format: alternate=<y|n>

Range: Not applicable

Commands: CREATE, INDEX, SINDEX

The Alternate Collating Sequence element is optional. This element allows you to specify one or more alternate collating sequences for a given file. An alternate collating sequence specifies whether Btrieve will sort a key by a collating sequence other than the standard ASCII sequence.

You can specify a different alternate collating sequence for each key. However, each segment of the key can have only one alternate collating sequence. Alternate collating sequences are valid only for string, lstring, and zstring key types. If you want the key to take advantage of an alternate collating sequence, specify y. Otherwise, either specify n or omit this element from the description file.

When using a description file to create an additional index for an existing Btrieve file, if you want the index to use an alternate collating sequence file other than the first one in the Btrieve file, specify alternate=y and caseinsensitive=y.

If you specify alternate=y and caseinsensitive=n and use an alternate collating sequence file other than the first one in the Btrieve file, the index will not be created.

Case-Insensitive Key

Format: caseinsensitive=<y|n>

Range: Not applicable

Commands: CREATE, INDEX, SINDEX

The Case-Insensitive Key element is optional. It specifies that the key (or key segment) you are defining is case insensitive. You can specify this key element only for keys that are of type string, zstring, or lstring.

By default, Btrieve is case sensitive when sorting key strings; that is, it sorts string key values based on whether the letters are uppercase or lowercase. Btrieve sorts the values by placing the uppercase value first, followed by the lowercase value. For example, key values starting with A would appear before those starting with a in the index.

Case sensitivity, however, does not apply if Btrieve sorts a key according to the collating sequence specified with the Alternate Collating Sequence element.

To specify that Btrieve ignore case when sorting the key value, specify y for this element. Otherwise, either specify n or omit this element from the description file.

Repeating Duplicates

Format: repeatdup=<y|n>

Range: Not applicable

Commands: CREATE, INDEX, SINDEX

Btrieve uses two methods for storing duplicatable keys internally. The keys are stored as either linked-duplicatable keys or repeating-duplicatable keys.

• Linked-duplicatable key---In a Btrieve v6.1 file, Btrieve stores duplicatable keys as linked-duplicatable keys by default on a Create operation. (On a Create Index operation, Btrieve uses linked-duplicatable keys if they are available; otherwise, it uses repeating-duplicatable keys, as explained in the following section.) Using this method, Btrieve stores the key extracted from the first record of a duplicatable key on an index page.

  Other records with keys containing duplicate values are stored in the form of a linked list, with pointers at the end of each record in a data page pointing to the next and the previous records that have the same duplicate key values.

• Repeating-duplicatable key---If no room is available to create a linked-duplicatable key (that is, if no duplicate pointers were reserved at file creation, or if no index has been dropped to free existing pointers), Btrieve stores duplicatable keys as repeating-duplicatable keys. Using this method, Btrieve stores every key value of a repeating-duplicatable key both in a data page and in an index page.

NOTE:  Key-only files always use repeating-duplicatable keys because the key-only files use only the index pages and not the data pages.

Specify y to create repeating-duplicatable keys. Otherwise, either specify n or omit this element from the description file.

NOTE:  For a segmented key, all segments must have the same repeatdup=y/n specification. For a nonsegmented key, if you specify repeatdup=y, you must also specify duplicate=y.

Format: manual=<y|n>

Range: Not applicable

Commands: CREATE, INDEX, SINDEX

The Manual Key element is optional. It specifies that the key or key segment you are defining is manual. A manual key is a modified form of the null key and can be used to exclude particular records from the index.

Manual keys have all the attributes of a null key with one exception: in a manual key, if every byte of one segment of the key contains the null value, Btrieve excludes the key from the index even if other segments do not contain this null value.

If you define one segment of a key as a manual key, you must define a null value for that segment, and you must define all other segments of that key as manual. However, Btrieve allows you to define different null values for different segments in a segmented key.

To create a manual key or key segment, specify y; otherwise, specify n or omit this element from your description file.

NOTE:  The Btrieve Programmer's Manual refers to manual keys as any-segment null keys.

Format: null=<y|n>

Range: Not applicable

Commands: CREATE, INDEX, SINDEX

The Null Key element specifies whether the key you are defining has a null value. You can include the Null Key element in a description file for the INDEX command. However, to maintain consistent formats for the CREATE, INDEX, and SINDEX description files, INDEX disregards any null value you specify.

If you define a null value for one segment of a segmented key, you must define a null value for every segment of that key. However, Btrieve allows you to define different null values for different segments in a segmented key.

Specify y if you want to define a null value for this key. Otherwise, specify n.

NOTE:  The Btrieve Programmer's Manual refers to null keys as all-segment null keys.

Format: value=nn

Range: Any 1-byte hexadecimal value

Commands: CREATE, INDEX, SINDEX

The Null Key Value element specifies the null character value (in hexadecimal) for the key. Typical null values are 20 hexadecimal (blank) and 0 hexadecimal (binary zero). Include this element only if you defined the key as allowing null values. If you specify n for both the Null Key element and the Manual Key element, the Null Key Value element is not required in the description file.

Segmented Key

Format: segment=<y|n>

Range: Not applicable

Commands: CREATE, INDEX, SINDEX

The Segmented Key element specifies whether the key you are defining has any more segments. Specify y if the key has another segment. Specify n if you are defining either a nonsegmented key or the last segment of a segmented key.

Alternate Collating Sequence Filename/ID

Format: name=sequenceFile or countryid=nnn codepageid=nnn

Range: Any valid, fully qualified pathname; or a valid country ID and code page ID; or -1 (the default)

Commands: CREATE, INDEX, SINDEX

The Alternate Collating Sequence Filename/ID element specifies the pathname of the file that contains an alternate collating sequence for the file you are creating. You can include up to 256 bytes of directory levels in the pathname (plus the filename).

If you specified n for the Alternate Collating Sequence element for every key, do not include this element in your description file. If you specified y for the Alternate Collating Sequence element for a key, you must supply either an alternate collating sequence filename or a country ID and a code page ID.

If you want all the keys in the file to use the same alternate collating sequence filename, you can either specify this element as the last element in the description file or specify the alternate collating sequence name for each key.

If you want to use different alternate collating sequences, you must specify this element for each key that uses an alternate collating sequence.

You can specify only one alternate collating sequence per key, and each segment of the key should have an alternate= and name= pair.

To use an alternate collating sequence ID, you must specify countryid=nnn and codepageid=nnn. Use a valid country ID and code page ID. If you want to use the current locale, specify countryid=-1 and codepageid=-1.

Table 9. Alternate Collating Sequence File Format

For example, assume you want to insert a character with a 5Dh between the letters U (55h) and V (56h) in your sequence. In this case, byte 5Dh in the sequence should contain the value 56h, and bytes 56h through 5Ch in the sequence should contain the values 57h through 5Dh.