Creating and Modifying Data Files

This section includes detailed information on creating and modifying data files using the following BUTIL commands: CLONE, CLROWNER, CREATE, DROP, INDEX, SETOWNER, and SINDEX. This section also includes information about removing unused space in a Btrieve data file, which is discussed in Compacting Btrieve Data Files .

CLONE

The CLONE command creates a new, empty file with the same file specifications as an existing file (including any supplemental indexes, but excluding the owner name). The new data file includes all the defined key characteristics (such as key position, key length, or duplicate key values) contained in the existing file.

The CLONE command ignores all MicroKernel configuration options that affect file statistics (such as System Data ) except file version. The CLONE command creates a new file using the database engine file version you specify with the Create File Version option.

Format

BUTIL -CLONE outputFile sourceFile [/O<owner | *>] [/
pagecompresson | /pagecompressoff] [/
recordcompresson | /recordcompressoff] [/UIDuname /
PWDpword [/DBdbname]] [/S]

Remarks

Btrieve 6.0 and later allows a maximum of 23 key segments in a data file with a page size of 1,024 bytes. Therefore, the CLONE command sets the page size in the new data file to 2,048 bytes if the existing data file contains 24 key segments and has a page size of 1,024 bytes. This occurs if the existing data file has a format earlier than 6.0 and the database engine was not loaded with the Create File Version option (page 4-27) set to 5.x or 6.x.

If you are cloning a pre-7.x file, ensure that the database engine is configured to create the file format version that you want the new file to be. For example, if you want to clone a 6.15 file in 9.5 format, ensure that the MicroKernel File Format Version option is set to 9.5.

---

Note
If your source file is in 8.x format or later and it does not contain system data, your output file will not contain system data, regardless of the database engine configuration. To add system data to an existing file, refer to Getting Started With Pervasive PSQL.

---

If you are trying to recover from receiving Status Code 30 (The file specified is not a MicroKernel file) and you suspect that the header page of the source file might be damaged, try creating the new MicroKernel file using the CREATE command with a description file.

Example

The following command creates the NEWCRS.MKD file by cloning the COURSE.MKD file.

butil -clone newcrs.mkd course.mkd 

CLROWNER

The CLROWNER command clears the owner name of a MicroKernel file.

Format

BUTIL -CLROWNER sourceFile </O<owner | *> [/UIDuname /
PWDpword [/DBdbname]]

Example

The following command clears the owner name for the TUITION.MKD file. The owner name for the file is Sandy.

butil -clrowner tuition.mkd /OSandy 

CREATE

The CREATE command generates an empty MicroKernel file using the characteristics you specify in a description file. Before you can use the CREATE command, you must create a description file to specify the new key characteristics. For more information, see Appendix A Description Files.

Format

BUTIL -CREATE outputFile descriptionFile [< Y | N >] [/UIDuname /
PWDpword [/DBdbname]]

Example

The following command creates a file named COURSE.MKD using the description provided in the CREATE.DES description file.

butil -create course.mkd create.des 

Sample Description File for the CREATE Command

The sample description file shown in Figure 13-17 creates a MicroKernel formatted file. The file is specified to have a page size of 512 bytes and 2 keys. The fixed-length portion of each record in the file is set to 98 bytes. The file specifies variable-length records with no blank truncation, record compression, and variable-tail allocation tables (VATs). The free space threshold is set to 20 percent. Allocation is set to 100 pages. The MicroKernel preallocates 100 pages, or 51,200 bytes, when it creates the file.

Key 0 is a segmented key with two duplicatable, nonmodifiable string segments and a null value of 20 hexadecimal (space) specified for both segments. Key 0 uses the collating sequence upper.alt.

Key 1 is a numeric, nonsegmented key that does not allow duplicates but permits modification. It is sorted in descending order.

DROP

The DROP command removes an index from a file and adjusts the key numbers of any remaining indexes, subtracting 1 from each subsequent key number. If you do not want to renumber the keys, you can add 128 to the key number you specify to be dropped. This renumbering feature is available only for 6.0 and later files.

Format

BUTIL -DROP sourceFile < keyNumber | SYSKEY > 
[/O<owner | *>] [/UIDuname /PWDpword [/DBdbname]]

Examples

In both of the following examples, COURSE.MKD has three keys. The original keys in the file are numbered 0, 1, and 2.

In the first example, the BUTIL -DROP command drops key number 1 from the COURSE.MKD file and renumbers the remaining key numbers as 0 and 1.

butil -drop course.mkd 1 

In the following example, the BUTIL -DROP command drops key number 1, but does not renumber the keys. The key numbers remain 0 and 2.

butil -drop course.mkd 129  

INDEX

The INDEX command builds an external index file for an existing MicroKernel file, based on a field not previously specified as a key in the existing file. Before you can use the INDEX command, you must create a description file to specify the new key characteristics. For more information about description files, see Appendix A Description Files.

The records in the new file consist of the following:

Format

BUTIL -INDEX sourceFile indexFile descriptionFile [/O<owner | *>] 
[/O<owner | *>] [/UIDuname /PWDpword [/DBdbname]]

Remarks

The INDEX command creates the external index file and then displays the number of records that were indexed. To retrieve the data file's records using the external index file, use the SAVE command.

Sample Description File for the INDEX Command

The description file shown in the following illustration defines a new key with one segment. The key begins at byte 30 of the record and is 10 bytes long. It enables duplicates, is modifiable, is a STRING type, and uses no alternate collating sequence.

Example

The following command creates an external index file called NEWCRS.IDX using a data file called COURSE.MKD. The COURSE.MKD file does not require an owner name. The description file containing the definition for the new key is called NEWCRS.DES.

butil -index course.mkd newcrs.idx newcrs.des 

SETOWNER

The SETOWNER command sets an owner name for a MicroKernel file.

Format

BUTIL -SETOWNER sourceFile /O<owner | *> level [/O<owner | *>] 
[/UIDuname /PWDpword [/DBdbname]]

Example

The following example creates an owner for the COURSE.MKD file. The owner name is Sandy, and the restriction level is 1.

butil -setowner course.mkd /OSandy 1  

SINDEX

The SINDEX command creates an additional index for an existing MicroKernel file. By default, the key number of the new index is one higher than the previous highest key number for the data file, or you can instruct the database engine to use a specific key number. An exception is if a DROP command previously removed an index without renumbering the remaining keys, thus producing an unused key number; in this case, the new index receives the first unused number.

You can instruct the database engine to use a specific key number for the new index with the key number option. The key number you specify must be a valid key number that is not yet used in the file. If you specify an invalid key number, you receive Status Code 6.

If you do not use the SYSKEY option with this command, you must create a description file that defines key specifications for the index before you can use the SINDEX command. For more information about description files, see Appendix A Description Files.

Format

BUTIL -SINDEX sourceFile <descriptionFile | SYSKEY> [keyNumber] 
[/O<owner | *>] [/O<owner | *>] [/UIDuname /PWDpword [/
DBdbname]]

Examples

The following example adds an index to the COURSE.MKD file. The name of the description file is NEWIDX.DES.

butil -sindex course.mkd newidx.des  

The following example adds the system-defined key to the COURSE.MKD file. The system-defined key was dropped.

butil -sindex course.mkd syskey 

Compacting Btrieve Data Files

You can use several commands in the BUTIL (CLONE, RECOVER, and LOAD, respectively) to remove unused space in a data file to decrease its size.

To compact a Btrieve data file