Description Files
 
Description Files
Using Description Files to Store Btrieve File Information
A description file is an ASCII text file that contains descriptions of file and key specifications that the Maintenance tool can use to create data files and indexes. Some users employ description files as a vehicle for archiving information about the data files they have created. Description files are not the same as DDFs, or Data Dictionary Files, used by the Relational Engine.
Description files contain one or more elements. An element consists of a keyword, followed by an equal sign (=), followed by a value (with no space). Each element in a description file corresponds to a particular characteristic of a data file or key specification.
Note Before using description files, you should be familiar with Btrieve fundamentals. For information about these topics, see PSQL Programmer's Guide.
This appendix discusses the following topics:
• Rules for Description Files
• Description File Examples
• Description File Elements
Rules for Description Files
Use the following rules when creating a description file.
•Enter elements in either uppercase or lowercase.
•Separate elements from each other with a separator (blank space, tab, or carriage return/line feed), as in the following example:
record=4000
key=24
•Specify the description file elements in the proper order. Table 77 presents the elements in the appropriate order.
•Address all element dependencies. For example, if you specify nullkey=allsegs in your description file, you must also specify a value for the value= element.
•Define as many keys as you specify with the Key Count element. For example, if you specify key=12, you must define 12 keys in the description file.
•For a key that consists of multiple segments, you must define the following elements for each key segment:
•Key Position
•Key Length
•Duplicate Key Values
•Modifiable Key Values
•Key Type
The Descending Sort Order element is optional for each segment.
•If any key in the file uses an ACS, you must specify an ACS file name or an ISR table name. You can include this information as either the last element of the key (applies to current key only) or the last element in the description file (applies to entire data file).
•You can specify only one ACS per key, and you must provide an ACS file name or ISR table name. Different keys in the same file can use different types of collating sequences. For example, Key 0 can use an ACS file name, and Key 1 can use an ISR table name.
•Different segments of the same key cannot have different collating sequences.
•If you specify an ACS at the end of a description file, it is used as the default ACS. That is, if you specify alternate=y for a given key but do not include an ACS file name or ISR table name for that key, the database engine uses the ACS file name or ISR table name specified at the end of the file.
•If you are creating a new key and you specify alternate=y but you omit the ACS file name or ISR table name, the database engine does not create the key.
•If a Description File element is optional, you can omit it.
•Make sure the description file contains no text formatting characters. Some word processors embed formatting characters in a text file.
Description File Examples
The sample description files shown in this section describe a data file. This data file has a page size of 512 bytes and 2 keys. The fixed-length portion of the record is 98 bytes long. The file allows variable-length records but does not use blank truncation.
The file uses record compression, allows for Variable-tail Allocation Tables (VATs), and has the free space threshold set to 20 percent. The MicroKernel engine preallocates 100 pages, or 51,200 bytes, when it creates the file. The file has two keys: Key 0 and Key 1. Key 0 is a segmented key with two segments.
In Figure 40, both keys use the same ACS file name (upper.alt). In Figure 41, Key 0 and Key 1 use different ACS file names (lower.alt and upper.alt, respectively). In Figure 42, the file has no keys except the system-defined key used for logging.
Figure 40 Sample Description File Using Alternate Collating Sequence File Name
Figure 41 Sample Description File Using Alternate Collating Sequence File Name on a Key Segment
Figure 42 Sample Description File Using System-Defined Key for Logging
Description File Elements
Description file elements must appear in a particular order. Table 77 lists the description file elements in the appropriate order. For each element, the table specifies the required format and the range of acceptable values.
•An asterisk (*) indicates that the element is optional.
•A pound sign (#) indicates that it is not applicable in the current MicroKernel version but is retained for backward compatibility with previous MicroKernel versions.
•A percent sign (%) indicates that the element is applicable only to the current MicroKernel version.
Table 77 Summary of Description File Elements
Element
Keyword and Format
Range
Comments
File Specification Information
 
 
 
Comment Block*
/*. . . . . . . . . . . . */
5120 bytes
None.
Record Length
record=nnnn
4  – page size limits
None.
Variable-Length Records
variable=<y|n>
N/A
Not applicable to key-only files.
Reserved Duplicate Pointer*
dupkey=<nnn>
0 – 119
Applicable only to files for which you plan to add linked-duplicatable keys.
Blank Truncation*
truncate=<y|n>
N/A
Not applicable for files that use record compression.
Record Compression*
compress=<y | n>
N/A
Not applicable to key-only files. See also Record and Page Compression.
Key Count
key=nnn
0  – 119
Specify 0 to create a data-only file.
If key count is 0, then Include Data and Use System Data cannot be set to no.
Page Size
page=nnnn
512 – 4096 bytes for file versions prior to 9.0 (a multiple of 512 bytes up to 4096)
512, 1024, 1536, 2048, 2560, 3072, 3584, 4096, or 8192 bytes for file version 9.0.
1024, 2048, 4096, 8192, or 16384 bytes for file versions 9.5.
4096, 8192, or 16384 bytes for file versions 13.0.
 
Page Preallocation*
allocation=nnnnn
1 –  65535
None.
Replace Existing File*#
replace=<y|n>
N/A
None.
Include Data*
data=<y|n>
N/A
Specify n to create a key-only file. Cannot create a key-only file that both allows duplicates and uses a system-defined key.
Free Space Threshold*
fthreshold=<5|10|20|30>
N/A
Applicable only for files that have variable-length records. The default is 5.
Variable-Tail Allocation Tables (VATs)
huge=<y|n> #
vats=<y|n>
N/A
Applicable only for files that have variable-length records.
Balanced Index*
balance=<y|n>
N/A
None.
Use Key Number *
usekeynum=<y|n>
N/A
Used with the Key Number element.
1Use System Data*%
sysdataonrecord=
<n|loggable>
N/A
If no element specified, MicroKernel configuration is used. If creating a key-only file, MicroKernel configuration is used and this element is ignored. Also, you cannot create a key-only file that both allows duplicates and uses a system-defined key.
Page Compression*
pagecompress=<y | n>
N/A
Key Specification Information
 
 
 
Key Number *
keynum=nnn
0 – 118
Must be unique to the file, specified in ascending order, and valid for the file’s Page Size. Applicable only when creating a file.
Key Position
position=nnnn
1 – record length
Cannot exceed the Record Length.
Key Length
length=nnn
key type limit
Cannot exceed the limit dictated by the Key Type. For binary keys, the key length must be an even number. The total of the Key Position and Key Length cannot exceed the file’s Record Length.
Duplicate Key Values
duplicates=<y|n>
N/A
Cannot create a key-only file that allows duplicates and uses a system-defined key.
Modifiable Key Values
modifiable=<y|n>
N/A
None.
Key Type
type=
validMKDEKeyType
N/A
Can enter the entire word (as in float) or just the first three letters (as in flo).
Descending Sort Order*
descending=<y|n>
N/A
None.
Alternate Collating Sequence
alternate=<y|n>
N/A
Applicable only for case sensitive STRING, LSTRING, WSTRING, WZSTRING, or ZSTRING keys. When creating an additional index for an existing file, if you want the index to use an ACS other than the first one in the data file, use with caseinsensitive=y.
Case-Insensitive Key*
caseinsensitive=<y|n>
N/A
Applicable only for STRING, LSTRING, or ZSTRING keys that do not use an ACS.
Repeating Duplicates*
repeatdup=<y|n>
N/A
If creating a key-only file, use repeating duplicates. If using this element, you must use duplicates=y.
Null Segments*
nullkey=<allsegs | n | anyseg |>
N/A
None.
Null Key Value
value=nn
1-byte hex
Used with the Null Segments element.
Segmented Key
segment=<y|n>
N/A
None.
Alternate Collating Sequence
name=sequenceFile or isr=table name (%)
valid path or values valid to operating system or -1
Used with the Alternate Collating Sequence element.
1When the database engine adds a system key, the resulting records may be too large to fit in the file’s existing page size. In such cases, the database engine automatically increases the page size to the next accommodating size.