Table 21. Summary of Description File Elements

Element	Format	Range	Command
Comment Block	/*. . .*/	5,120 bytes	CREATE
Record Length	record=nnnn	4-4,088	CREATE
Variable-Length Records	variable=<y|n>	N/A	CREATE
Reserved Duplicate Pointer	dupkey=<nnn>	1-119	CREATE
Blank Truncation	truncate=<y|n>	N/A	CREATE
Data Compression	compress=<y|n>	N/A	CREATE
Key Count	key=nnn	0-118	CREATE
Page Size	page=nnnn	512-4,096	CREATE
Page Preallocation	allocation=nnnnn	1-65,535	CREATE
Replace Existing File	replace=<y|n>	N/A	CREATE
Include Data	data=<y|n>	N/A	CREATE
Free Space Threshold	fthreshold=<10|20|30>	N/A	CREATE
Variable-tail Allocation Tables (VATs)	vats=<y|n>	N/A	CREATE
Balanced Index	balance=<y|n>	N/A	CREATE
Key Position	position=nnnn	1-4,088	CREATE, INDEX, SINDEX
Key Length	length=nnn	key type limit	CREATE, INDEX, SINDEX
Duplicate Key Values	duplicates=<y|n>	N/A	CREATE, INDEX, SINDEX
Modifiable Key Values	modifiable=<y|n>	N/A	CREATE, INDEX, SINDEX
Key Type	type=validBtrieveKeyTy pe	N/A	CREATE, INDEX, SINDEX
Descending Sort Order	descending=<y|n>	N/A	CREATE, INDEX, SINDEX
Alternate Collating Sequence	alternate=<y|n>	N/A	CREATE, INDEX, SINDEX
Case-Insensitive Key	caseinsensitive=<y|n>	N/A	CREATE, INDEX, SINDEX
Repeating Duplicates	repeatdup=<y|n>	N/A	CREATE, SINDEX
Any Segment Null	nullkey=anyseg	N/A	CREATE, INDEX, SINDEX
All Segments Null	nullkey=allsegs | n	N/A	CREATE, INDEX, SINDEX
Null Key Value	value=nn	1-byte hex	CREATE, INDEX, SINDEX
Segmented Key	segment=<y|n>	N/A	CREATE, INDEX, SINDEX
Alternate Collating Sequence Filename/ID	name=sequenceFile or countryid=nnn and codepageid=nnn	valid path or values valid to operating system or - 1 (default)	CREATE, INDEX, SINDEX

Comment Block

Format: /* . . .*/

Range: 5,120 bytes

The optional Comment Block element provides a section at the beginning of the description file in which you can enter comments about that file, or any other type of relevant information.

You can enter up to 5,120 bytes of data in this section.

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. A record represents a set of logically associated items in a Btrieve file. Generally, a record is the unit transferred between an application and Btrieve in a single operation.

There is no inherent restriction on the number of records allowed in a Btrieve file. A record can consist entirely of a fixed-length portion (a fixed-length record), or it can consist of a fixed-length portion followed by a variable-length portion (a variable-length record).

NOTE:  All the keys defined for the file must be located within the fixed-length portion of the record.

The logical record length is the number of bytes of fixed-length data you allow a record in the specified Btrieve file to hold. To determine this value, calculate how many bytes of data you need to store in the fixed-length portion of each record.

• For fixed-length records, the value for this element should correspond to the length of the data buffer parameter that performs operations on the file.
• For variable-length records, the value for this element should correspond to the fixed-length portion of the record.

In a file that uses fixed-length records, the length of each record in that file must be the same. The maximum length of a fixed-length record depends on the physical page size and the number of duplicate keys you define for the file. Btrieve allows a fixed-length record to contain up to 4,088 bytes (4,096 minus 6 bytes for page overhead information and 2 bytes for the record usage count).

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.

Variable-length records store data of indeterminate length. When you create a Btrieve file, you can specify that you want the file to use variable-length records.

A variable-length record has a fixed-length portion and a variable-length portion. While the fixed-length portion of all variable-length records in a file must be the same size, the variable-length portion can vary. This means that the overall length of each variable-length record in the file can vary.

When you create a Btrieve file that uses variable-length records, you specify the length in bytes of the fixed-length portion of each record. This fixed-length amount is the minimum length of each record; you do not define the maximum record length.

Beginning with Btrieve v6.1, the maximum length of variable-length records is limited only by Btrieve's file size limit: 4 gigabytes. However, an application's ability to insert, update, and retrieve long records is influenced by several factors.

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.

You can use these reserved pointers when you add keys that allow duplicates 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.

When you define a file that allows variable-length records, you can specify that Btrieve use a blank truncation method for sorting the records in order to conserve disk space.

The truncate element has an effect only if you also specify y for the Variable-Length Records element. Btrieve ignores blank truncation if you specify data compression.

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.

If you specify data compression when you create a Btrieve file, Btrieve compresses the file's records before inserting or updating them, and uncompesses the records when it retrieves them.

Because the final length of a compressed record cannot be determined until the record is written to the file, Btrieve always creates a compressed file as a variable-length record file.

NOTE:  A compressed fixed-length-record file differs from a compressed variable-length-record file only in that Btrieve prevents insert and update operations from producing a record longer than a compressed fixed-length-record file's specified record length.

Since the compressed images of the records are stored as variable-length records, individual records may become fragmented across several file pages if an application performs frequent insertions, updates, and deletions. The fragmentation can result in slower access times because Btrieve may need to read multiple file pages to retrieve a single record.

However, data compression can also result in a significant reduction of the space needed to store records that contain many repeating characters. Btrieve compresses 5 or more of the same continguous characters into 5 bytes.

Btrieve does not use data compression with key-only files (nor is there blank truncation with key-only files).

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 22. Key Segment Count Values

Page Size (in bytes)	Maximum Number of Key Segments
512	8
1,024	23
1,536	24
2,048- 3,584	54
4,096	119

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.

NOTE:  NetWare Btrieve specifies that 6.0 and 6.1x files with a page size of 512 can be no larger than 2 gigabytes in size. However, NetWare Btrieve does not enforce this limit. Therefore, when a file grows beyond the 512 page-size limit, NetWare Btrieve returns Status Code 132 (The file is full).

All pages in a Btrieve data file are the same size. Therefore, when you determine what size the pages should be in your file, you must choose a size that meets the following criteria:

• What page size is the smallest that will allow index pages to hold your largest key definition?
• What page size is the optimum size for data pages?

Once you have these values, you can select a page size that best fits your file.

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

Page Preallocation

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. (Btrieve allows you to preallocate up to 65,535 pages when you create a data file.) Preallocation guarantees that disk space will be available when Btrieve needs it.

You can enhance the speed of file operations if a data file occupies a contiguous area on the disk. The increase in speed is most noticeable on very large files.

To preallocate contiguous disk space for a file, the device on which you are creating the file must have the required number of bytes of contiguous free space available. Note, however, that Btrieve preallocates the number of pages you specify whether or not the space on the disk is contiguous.

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 type of file (key-only, standard, or data-only) that the utility creates.

Key-only files contain only File Control Record (FCR) pages followed by a number of Page Allocation Table (PAT) pages. If a key-only file has an alternate collating sequence, then it may also have an alternate collating sequence page.

Similarly, if anyone has used Scalable SQL to define referential integrity (RI) constraints on the file, then the file may contain one or more variable pages.

Free Space Threshold

Format: fthreshold=<5|10|20|30>

Range: 5 through 30 percent

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.

Format: vats=<y|n>

Range: Not applicable

Command: CREATE

The Variable-tail Allocation Table (VAT) element is optional. Btrieve v6.1x allows an application to create Btrieve files that contain structures called Variable-tail Allocation Tables (VATs). A VAT, which is implemented as a linked list, is an array of pointers to the variable-length portion of Btrieve records. For this reason, VATs are enabled only when you have specified the Variable Records element.

Btrieve uses VATs not only to accelerate random access to the variable-length portions of records, but also to limit the size of the compression buffer used during data compression. If you have specified data compression, you may also want to specify VATs.

If you want to create a file that uses VATs, specify y. Otherwise, either specify n or omit this element from your description file.

Balanced Index

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.

By default, Btrieve does not use index balancing. This means that each time a current index page becomes full, Btrieve must create a new index page. When you specify index balancing, Btrieve can often avoid creating a new index page each time a current index page is filled.

Specifying index balancing forces Btrieve to look for available space on adjoining index pages. If space is available on one of those pages, Btrieve moves keys from the full index page to the page with free space.

Index balancing increases index page utilization, results in fewer index pages, and produces more densely populated indexes. It also results in better overall disk usage and a faster response time on most read operations. In addition, index balancing produces an even distribution of keys among nodes on the same level, thus enhancing performance during get operations.

However, using index balancing also means that Btrieve requires extra time to examine more index pages in the file and may require more disk I/O during insert, update, and delete operations.

Although the exact effects of balancing indexes vary in different situations, performance on write operations typically degrades by about 5%-10% if you use index balancing.

NOTE:  You can specify index balancing on a file-by-file basis when the file is created, or you can specify index balancing for all files. 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.

Key Position

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.

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.

Modifiable Key Values

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.

Key Type

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 keywords for the Btrieve key types are as follows:

autoinc	integer	string
bfloat	logical	time
date	lstring	unsigned binary
decimal	money	zstring
float	numeric	sign trailing separate

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.

Descending Sort Order

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.

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.

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 (ACSs) for a given file. An alternate collating sequence (ACS) specifies whether Btrieve will sort a key by a collating sequence other than the standard ASCII sequence.

You can specify a different ACS for each key. However, each segment of the key needs to have the same ACS. ACSs 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 ACS file other than the first one in the Btrieve file, specify alternate=y.

If you specify alternate=y and caseinsensitive=n and use an ACS 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.

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.

Any Segment Null

Format: nullkey=anyseg

Range: Not applicable

Commands: CREATE, INDEX, SINDEX

The Any Segment Null element is optional. It specifies that the key or key segment you are defining contains a user-defined null character. An any segment null key does not include a particular record in the index if the value of any key segment of that record matches the null value.

NOTE:  In previous releases, the Btrieve documentation referred to the Any Segment Null element at the Manual Key element.

Any segment null keys have all the attributes of a null key with one exception: in an any segment null key, Btrieve excludes from the index those records in which every byte in any segment of a key contains the null value.

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

To create an any segment null key or key segment, specify anyseg; otherwise, specify n or omit the nullkey keyword from your description file.

All Segments Null

Format: nullkey=allsegs|n

Range: Not applicable

The All Segments Null element specifies whether the key you are defining has a null value. You can include the All Segment Null element in a description file for an indexing operation. However, to maintain consistent formats for the description files, the indexing operation disregards any null value you specify.

NOTE:  In previous releases, the Btrieve documentation referred to the All Segments Null element as the Null Key element.

If you specify the All Segment Null key attribute, Btrieve excludes from the index those records in which all the bytes in all segments of a key contain a null value.

Specify allsegs if you want to define a null value for this key. Otherwise, specify n or omit the nullkey keyword.

Null Key Value

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 nullkey=n, the description file does not require the Null Key Value element.

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.

When you assign an attribute to a key, all segments of that key share the same attributes. However, the key type can be different for each segment in the key. The sort order, either ascending or descending, can also differ for each segment.

A Btrieve file limits the maximum number of key segments rather than the maximum number of keys. The maximum number of key segments allowed depends on the page size. (Note that you can define more key segments than there are keys defined for the file.)

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 ACS, 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 ACSs, you must specify this element for each key that uses an alternate collating sequence.

You can specify only one ACS per key, and each segment of the key should have an alternate= and name= pair, or a countryid= and codepage= pair.

To use an ACS 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 23. Alternate Collating Sequence File Format

Offset	Length	Description
0	1	Signature byte. This byte should always contain the value ACh.
1	8	An 8-byte name that uniquely identifies the alternate collating sequence to Btrieve.
9	256	A 256-byte table containing the sort value for every character. Store the value for each sort character at the offset corresponding to the character's representation in the ASCII collating sequence. For example, to sort the character A as something other than 41h, store the new sort value at offset 41h in the table.

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.