File Information Editor

---

This section provides general information about the File Information Editor with which you can create new files based on file and key specifications you construct. Because this Editor allows you to load information based on an existing file, it is also useful for viewing file and key specifications on existing data files. You can also create a new file based on the file and key specifications of an existing file (similar to CLONE in the command-line Maintenance utility ).

You open the File Information Editor by clicking Options4Show Information Editor.

 
Figure 14-2 File Information Editor

File Information Editor Dialog Elements

At the top of the Editor, the following buttons appear:

Load Information	Loads information based on an existing file. When you load information, you are not editing the existing file. Instead, you are loading a copy of the information about that file.
Create File	Creates a new file based on current information in the dialog box.
Set to Defaults	Sets the controls to default values.
Description Comments	If you are creating a description file, allows you to enter notes about the file.
Show 6.x Attributes	Displays controls specific to 6.x and later files, which are unavailable when you load information based on a pre-6.0 file. (This button is unavailable unless you load information based on a pre-6.x file.)
Help	Displays help for the File Information Editor dialog box.

The Data File Info box, also at the top of the File Information Editor, contains the following controls:

Owner Name	Provides a text box you can use to specify the owner name, if applicable, for an existing file.
Version	Earliest version of the MicroKernel that can read all the attributes of the file. For example, if you created a file using the 6.15 MicroKernel but did not use any attributes specific to 6.15, the Maintenance utility displays 6.0 as the version number. See File Version Notes for additional information about file format versions.
Total Records	Total number of records in the file.

The File Specification box is in the middle of the File Information Editor. Table 14-1 describes the controls in this box.

 
Table 14-1 File Specification Controls  

Control	Description	Range	Default
Record Length	Specifies the logical data record length (in bytes) of the fixed-length records in a file.	4-4,088	100
Page Size	Specifies the physical page size (in bytes) for the file. Must be a multiple of 512 bytes.	512-4,096	4,096
# Keys	Indicates the number of distinct keys (as opposed to key segments) currently defined in the Editor. Reflects the number of keys in the Key list.	0-119	0
# Segments	Indicates the number of key segments currently defined in the Editor. Reflects the number of segments in the Segment list.	0-119	0
Available Linked Keys	Specifies how many 8-byte place holders you want to reserve for future linked-duplicatable keys. If you are loading information based on an existing data file, this value reflects the number of place holders currently available in that file. (The number of originally reserved place holders is not stored in the file.)	0-119	3
Key-Only	Indicates whether the file is key-only. Not applicable if you turn Data Compression on, if you turn Variable Records on, or if you define more than one key for the file.	On or Off	Off
Balanced Indexing	Specifies that the file uses the balanced indexing method of managing key pages.	On or Off	Off
Pre-allocation	Specifies that the file uses preallocated pages.	On or Off	Off
# Pages	Specifies the number of pages you want preallocated when you create the file. Applicable only if Pre-allocation is turned on. If you are loading information based on an existing data file, this value reflects the number of unused, preallocated pages left in that file. (The number of originally preallocated pages is not stored in the file.)	1-65,535	0
Data Compression	Specifies that the file uses data compression. Not applicable for key-only files or files that use blank truncation.	On or Off	Off
Variable Records	Specifies that the file can contain variable-length records.	On or Off	Off
Blank Truncation	Specifies whether the file uses blank truncation on variable records to conserve disk space. Applicable only if Variable Records is turned on.	On or Off	Off
Include VATs	Specifies whether the file supports Variable-tail Allocation Tables for faster access to data in very long records. Applicable only if Variable Records is turned on.	On or Off	Off
% Free Space	Specifies the amount of unused space a file's variable pages must have available before the MicroKernel creates a new variable page. Applicable only if Data Compression or Variable Records are turned on.	5, 10, 20, or 30	5

At the bottom middle of the dialog box, the Key list shows the key numbers defined in a file. (For 6.x and later files, these key numbers do not have to be consecutive; they can have gaps between them.) The Maintenance utility displays the highlighted key's specifications in the Key box at the bottom left of the dialog box.

Also at the bottom middle of the dialog box, the Segment list shows the key segment numbers defined for the key highlighted in the Key list. The Maintenance utility displays the highlighted segment's specifications in the Segment box at the bottom right of the dialog box.

In addition, the following buttons appear under the Key and Segment lists:

Insert	Defines a new key or segment.
Delete	Removes the highlighted key or segment specification.
Compress	Renumbers the keys consecutively. You can use this button to remove gaps that result from deleting a key specification.

---

Note
Because these buttons control key specifications for a file you want to create, you cannot use them to operate on keys in an existing file. If you want to create or drop an index on an existing file, refer to Index Tasks .

---

At the bottom left in the dialog box is the Key group box. Table 14-2 describes the controls in this area. These controls are specific to the designated key (that is, the key highlighted in the Key list), not just to the current key segment. When you change the setting for one of these controls, the change affects all segments of the specified key.

 
Table 14-2 Key Specification Controls 

Control	Description	Default
Duplicates	Specifies that the key can have duplicate values.	On
Modifiable	Specifies that the key value can be modified after creation. Allowing modification of key values does not affect performance. Key pages are only updated if the actual key value changes, not if non-key fields in a particular record are changed.	On
Repeating Duplicates	Specifies that the MicroKernel uses the repeating-duplicatable method of storing duplicate key values.	Off
Sparse Key (Null Key)	A sparse key contains fewer key values than the number of record in the file. To specify which key values are excluded from the index, see the next two controls. Applicable only to keys that contain nullable segments.	Off
All Segments (Null)	Specifies that if all key segments in the record contain a null value, the MicroKernel does not include that record in the index. Applicable only if Sparse Key (Null Key) is turned on. Equivalent to key flag 0x0008. Whether a segment is evaluated as null is determined solely by the null indicator segment for that field; the contents of the field are not evaluated.	Off
Any Segment (Manual)	Specifies that if one or more key segments contains a null value, the MicroKernel does not include that record in the index. Applicable only if Sparse Key (Null Key) is turned on. Equivalent to key flag 0x0200. Whether a segment is evaluated as null is determined solely by the null indicator segment for that field; the contents of the field are not evaluated.	Off
ACS Information	Allows you to specify an alternate collating sequence (ACS) for the key. Applicable only if the Use ACS check box is selected for a segment of the key.	Off
Unique Values	Indicates the number of unique key values in the file. Applicable only if you are loading information based on an existing data file.	N/A

At the bottom right in the dialog box is the Key Segment group box. Table 14-3 describes the controls in this area. These controls are specific to the designated key segment (that is, the segment highlighted in the Segment list),

 
Table 14-3 Key Segment Specification Controls  

Control	Description	Default
Data Type	Specifies a data type for the key segment. The NULL data type indicates that the index is one byte Null indicator segment. It must be in a multi-segment key and it must precede another key segment that is not a NULL type. The number used in the Btrieve API for this key type is 255.	String
Position	Specifies by number the relative starting position of the beginning of this key segment in the record. The value cannot exceed the record length.	1
Length	Specifies the length (in bytes) of the key segment. This value cannot exceed the limit dictated by the data type for the segment. The total of key position and key length cannot exceed the record length.	10
Null Value	Specifies the null character value (in hexadecimal) for the key segment. Applicable only if the Null Key check box is selected for the key.	Binary zero
Case Insensitive	Specifies whether the segment is sensitive to case. Applicable only for STRING, LSTRING, and ZSTRING data types or for keys that do not use an ACS.	On
Descending	Specifies that the MicroKernel sort the key segment values in descending order (that is, from highest to lowest).	Off
Use ACS	Specifies that the segment uses the alternate collating sequence defined for the key. Applicable only for string, lstring and zstring data types that are case sensitive.	Off
Null Value Discrete Ordering	NULL Value Discrete Ordering is used for the null indicator segment (NIS) to determine whether the MKDE should treat the NIS as a boolean value, where any non-zero value is considered NULL, or as a one byte integer, where zero is considered non-null and all other values are considered different types of null. In this case they are sorted as discrete values. The Btrieve API uses the NO_CASE flag, 0x0400, to indicate discrete ordering should be performed, because that flag was previously unused for integer values.	Off

Information Editor Tasks

You perform the following tasks with the File Information Editor:

• Load information from an existing data file
• Create a new file
• Compact a Btrieve file
• Show or hide 6.x data
• Specify a key's alternate collating sequence

Loading Information from an Existing Data File

When you load information from an existing file, you are not editing the existing file. Instead, you are loading a copy of the information about that file. Generally, you want to load a data file before performing other tasks with the File Information Editor, but this is not mandatory.

To load information from an existing data file into the File Information Editor

1. Click Load Information at the top of the File Information Editor. The Select File dialog box appears (Figure 14-3).

    
   Figure 14-3 Select File Dialog Box

2. Specify the name and path of the file for which you want to load information. (By default, data files have the .mkd extension.)

   The Maintenance utility first attempts to open the specified file as a data file. If the file requires an owner name, the utility prompts you for one. (Because owner names are optional, the file you open may not require an owner name.) If the specified file is not a data file, the utility then attempts to open the file as a description file.

Creating a New File

You can create a new file based on the current information in the File Information Editor or on new information you provide.

To create a new file based on the current information in the File Information Editor

1. Click Create File at the top of the File Information Editor dialog box. The Create File dialog box (Figure 14-4) appears.

    
   Figure 14-4 Create File Dialog Box

2. Specify the controls in the Create File dialog box, which are described in Table 14-4.

    
   Table 14-4 Create File Dialog Controls

   Control	Description	Default
   File Name	Specifies a name and path for the file. By default, data files have the .mkd extension.	N/A
   File Type	Specifies the type of file to create. If you are creating a description file, you can use the Index Only option, which creates a description file you can use with the BUTIL utility to add an index to an existing data file. (For more information, refer to Creating Indexes .)	MicroKernel-compatible
   System Data	Determines whether the utility includes system data in the file. If you choose Use Engine Setting, the utility uses the setting for the System Data configuration option described . If you choose No System Data, the utility does not create system data, regardless of the engine configuration. If you choose Force System Data, the utility creates system data, regardless of the engine configuration. This is applicable only if the file type is MicroKernel-compatible.	Use Engine Setting

Adding Comments to a Description File

The comments are written to the top of the description file when you create the description file. For example, the comment, "This is my file," appears at the top of the description files as /* This is my file */. If you add additional comments after creating the description file, you need to create the file again to include the additional comments.

To add comments to a description file

1. Click Description Comments. The Description File Comments dialog box (Figure 14-5) appears.

    
   Figure 14-5 Description File Comments Dialog Box

2. Enter a block of comments up to 5,120 characters long.
3. Click OK when you are finished entering comments.

Compacting Btrieve Data Files

You can compact a Btrieve data file to remove unused space in it, which typically decreases the file's size. You can also perform this procedure using the command-line Maintenance utility .

To compact a Btrieve file

1. Click Load Information in the File Information Editor and select the file you want to compact.
2. Click Create File, give the file a new name (which creates a clone) in the Create File dialog box, and click OK.
3. From the Data menu on the main window, select Save. In the Save Data dialog box, enter the name of the original file in the From MicroKernel File box and then specify a name for the output file (for example, <original file>.out) in the To Sequential File box.
4. Click Execute. The Save Data dialog box displays the results of the save. Click Close.
5. From the Data menu, select Load. In the Load Data dialog box, enter the name of the sequential data file you just saved in the From Sequential File box. Then enter the name of the clone file you created in Step 2 in the To MicroKernel File box.
6. Click Execute. The Loading Data dialog box displays the results of the load. Click Close.

   You can now compare the size of the original file to the clone file to verify the reduction in size.

Showing and Hiding 6.x Data

When you load a pre-6.0 file, all the controls in the File Information Editor that are specific to 6.x and later are unavailable unless you click the Show 6.x Data button. For example, one feature that is specific to 6.x and later is the use of variable-tail allocation tables, or VATs.

This button is useful for users working in environments that use both pre-6.0 and 6.x and later MicroKernels. By hiding the 6.x-specific controls, you can avoid unintentionally creating a 6.x file. (Pre-6.0 MicroKernels cannot access 6.x files.)

To display the 6.x-specific controls

• Click Show 6.x Data.

The Show 6.x Data button is unavailable unless you are working with pre-6.0 files.

Specifying a Key's Alternate Collating Sequence

You can use an alternate collating sequence (ACS) to sort string keys (types STRING, LSTRING, and ZSTRING) differently from the standard ASCII collating sequence. By using one or more ACSs, you can sort keys as follows:

• By your own user-defined sorting order, which may require a sorting sequence that mixes alphanumeric characters (A-Z, a-z, and 0-9) with non-alphanumeric characters (such as #).
• By an international sorting rule (ISR) that accommodates language-specific collations, including multi-byte collating elements, diacritics, and character expansions and contractions.

Files can have a different ACS for each key in the file, but only one ACS per key. Therefore, if the key is segmented, each segment must use either the key's specified ACS or no ACS at all. For a file in which a key has an ACS designated for some segments but not for others, Btrieve sorts only the segments that specify the ACS.

The ISR tables are provided with Pervasive.SQL and are based on ISO-standard locale tables. ISR tables are stored in the COLLATE.CFG file, which is a Pervasive.SQL system file. This means that multiple data files can share a single ISR.

To specify a key's alternate collating sequence

1. Click ACS Information.

   The Maintenance utility displays the Specify ACS Information dialog box (Figure 14-6).

    
   Figure 14-6 Specify ACS Information Dialog Box

2. You can specify either a country ID and code page, an ACS file name, or an International Sorting Rule (ISR) as follows:

 
Table 14-5 ACS Information Controls

Control	Description	Default
ACS Country/Code
Country ID	An Intel-format number that identifies your country. Refer to your operating system's documentation for specific information.	-1
Code Page	An Intel-format number that identifies the code page you want to use. Refer to your operating system's documentation for specific information.	-1
ACS File	Specifies the fully qualified file name of the alternate collating sequence file.	N/A
International Sorting Rule	When you click this radio button you can specify a specific ISR table for sorting international data. Pervasive.SQL provides a set of pre-generated ISR tables, which are listed in the Pervasive.SQL Programmer's Guide.

3. When you specify a country ID and code page ID, the MicroKernel stores the locale-specific collating sequence in the data file. Moreover, the MicroKernel can insert new key values correctly, even if the locale changes.
4. When you specify an ACS file name for a data file, the MicroKernel copies the contents of the ACS file into the data file. (That is, the data file does not contain the file name of the ACS file.) The ACS identifies itself using an eight-digit name (such as UPPER). Subsequently, when you view the ACS information for a data file, the Maintenance utility displays this eight-digit name, not the file name of the original ACS.
5. When you specify an ACS file name for a description file, the Maintenance utility copies the actual path and file name of the ACS file into the description file. Subsequently, when you view the ACS information for a description file, the Maintenance utility attempts to locate the specified ACS file.

   To specify an ACS that sorts string values using an ISO-defined, language-specific collating sequence, you must specify an ISR table name. The Table Name field is limited to 16 characters. For more information on ISRs, refer to the Pervasive.SQL Programmer's Guide, available with the Pervasive.SQL Software Developer's Kit (SDK).