Description Files
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 Zen Programmer’s Guide.
This appendix discusses the following topics:
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. The table under Description File Elements 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 this figure, both keys use the same ACS file name (upper.alt).
In the next figure, Key 0 and Key 1 use different ACS file names (lower.alt and upper.alt, respectively).
In this third figure, the file has no keys except the system-defined key used for logging.
Description File Elements
Description file elements must appear in a particular order. The following table 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.
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. |
1Use System Data v2* | sysdata2=<n|y> | N/A | Add system data v2 to the file. Not for use with a key-only file. Requires a 13.0 format file. |
Page Compression* | pagecompress=<y|n> | N/A | See also Record and Page Compression. |
File Version* | version=0x<HH> | N/A | If no element is specified, the system default file version is used. If the element is specified, use hexadecimal digits as in these examples: • 0x90 for version 9.0 • 0x95 for version 9.5 • 0xD0 for version 13.0 |
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 system data, 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. | |||
Last modified date: 10/31/2023