Creating and Modifying Data Files

Pervasive logo

Advanced Operations Guide

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 .

Table 14-10 Commands to Create and Modify Data Files

Command

Description

CLONE

Creates a new, empty data file using an existing file's specifications.

CLROWNER

Clears the owner name of a data file.

CREATE

Creates a data file.

DROP

Drops an index.

INDEX

Creates an external index file.

SETOWNER

Assigns an owner name to a data file.

SINDEX

Creates an index.

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 MicroKernel file version you specify with the Create File Version option.

Format
BUTIL -CLONE outputFile sourceFile [/O<owner | *>] [/S]


  
  
     outputFile 
     The fully qualified file name to use for the new, empty data file. When you run BUTIL for Windows NT/95/98, you do not need to specify the name of the path if the data file resides in the same directory as your current directory.
  
  
     sourceFile 
     The fully qualified file name of the existing data file to replicate.When you run BUTIL for Windows NT/95/98, you do not need to specify the name of the path if the data file resides in the same directory as your current directory.
  
  
     /Oowner 
     The owner name, if any, for the source data file. The new data file does not have an owner name. See Owner Names   for more information.
  
  
     /S (NetWare only)
     By default, the Maintenance utility stops at each full screen of output and waits for a keystroke before continuing. With the /S option, the utility continuously scrolls output on the screen. You cannot use /S on the command line if you specify a command file, but you can specify /S with a command inside a command file.
  




 
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 MicroKernel was not loaded with the Create File Version option set to 5.x or 6.x.

If you are cloning a pre-7.x file, ensure that the MicroKernel 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 8.x format, ensure that the MicroKernel File Format Version option is set to 8.x.

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

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 | *> [/S]


  
  
     sourceFile 
     The fully qualified file name of the data file. When you run BUTIL for Windows NT/95/98, you do not need to specify the name of the path if the data file resides in the same directory as your current directory.
  
  
     /Oowner 
     The owner name to clear. See Owner Names  for more information.
  
  
     /S (NetWare only) 
     By default, the Maintenance utility stops at each full screen of output and waits for a keystroke before continuing. With the /S option, the utility continuously scrolls output on the screen. You cannot use /S on the command line if you specify a command file, but you can specify /S with a command inside a command file.
  




 
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 >] [/S]


  
  
     outputFile 
     The fully qualified file name of the MicroKernel file to create. If the file name is the name of an existing MicroKernel file, this command creates a new, empty file in place of the existing file. Any data that was stored in the existing file is lost and cannot be recovered. When you run BUTIL for Windows NT/95/98, you do not need to specify the name of the path if the data file resides in the same directory as your current directory. 
  
  
     descriptionFile 
     The fully qualified name of the description file containing the specifications for the new MicroKernel file.
  
  
     Y|N 
     Indicates whether to replace an existing file. If you specify N but a MicroKernel file with the same name exists, the utility returns an error message. The default is Y.
  
  
     /S (NetWare only) 
     By default, the Maintenance utility stops at each full screen of output and waits for a keystroke before continuing. With the /S option, the utility continuously scrolls output on the screen. You cannot use /S on the command line if you specify a command file, but you can specify /S with a command inside a command file.
  




 
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 14-16 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, data 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.

Figure 14-16 Sample Description File for the CREATE Command

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 | *>] [/S]


  
  
     sourceFile 
     The fully qualified name of the file from which you are dropping the index. When you run BUTIL for Windows NT/95/98, you do not need to specify the name of the path if the data file resides in the same directory as your current directory. 
  
  
     keyNumber 
     The number of the key to remove. To preserve the original key numbers, add a 128 bias to the key number you specify.
  
  
     SYSKEY 
     Instructs the utility to drop the system-defined log key (also called system data). Dropping the system-defined log key does not delete values from the records; the MicroKernel still assigns unique system-defined log key values to newly inserted records. 
  
  
     

     However, the MicroKernel cannot perform logging for a file from which the system-defined log key is dropped, if no user-defined unique keys exist. For this reason, you should use this option only if you suspect that the system-defined log key is corrupt and you intend to re-add it.

The SINDEX command allows you to re-use the system-defined log key once you have dropped it.
  
  
     /Oowner 
     The owner name for the file, if required.
  
  
     /S (NetWare only)
     By default, the Maintenance utility stops at each full screen of output and waits for a keystroke before continuing. With the /S option, the utility continuously scrolls output on the screen. You cannot use /S on the command line if you specify a command file, but you can specify 
/S with a command inside a command file.
  




 
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:

The 4byte address of each record in the existing data file.
The new key value on which to sort.

Note
If the key length you specify in the description file is 10 bytes, the record length of the external index file is 14 bytes (10 plus the 4byte address).

Format
BUTIL -INDEX sourceFile indexFile descriptionFile [ /O<owner | *>] 
[/S]


  
  
     sourceFile 
     The fully qualified name of the existing file for which to build an external index. When you run BUTIL for Windows NT/95/98, you do not need to specify the name of the path if the data file resides in the same directory as your current directory. 
  
  
     indexFile 
     The fully qualified name of the index file in which the MicroKernel should store the external index.
  
  
     descriptionFile 
     The fully qualified name of the description file you have created containing the new key definition. The description file should contain a definition for each segment of the new key.
  
  
     /Oowner 
     The owner name for the data file, if required.
  
  
     /S (NetWare only) 
     By default, the Maintenance utility stops at each full screen of output and waits for a keystroke before continuing. With the /S option, the utility continuously scrolls output on the screen. You cannot use /S on the command line if you specify a command file, but you can specify /S with a command inside a command file.
  




 
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.

Figure 14-17 Sample Description File for INDEX Command

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 [/S]


  
  
     sourceFile 
     The fully qualified name of the data file. When you run BUTIL for Windows NT/95/98, you do not need to specify the name of the path if the data file resides in the same directory as your current directory.
  
  
     /Oowner 
    
 The owner name to be set



  
  
     level 
    
 The type of access restriction for the data file. The possible values for this parameter are as follows



  
  
     

     0: Requires an owner name for any access mode (no data encryption)
  
  
     

     1: Permits read access without an owner name (no data encryption)
  
  
     

     2: Requires an owner name for any access mode (with data encryption)
  
  
     

     3: Permits read access without an owner name (with data encryption)
  
  
     /S (NetWare only)
     By default, the Maintenance utility stops at each full screen of output and waits for a keystroke before continuing. With the /S option, the utility continuously scrolls output on the screen. You cannot use /S on the command line if you specify a command file, but you can specify /S with a command inside a command file.
  




 
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 MicroKernel 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 MicroKernel 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 | *>] [/S]


  
  
     sourceFile 
     The fully qualified name of the existing file for which to build an external index. When you run BUTIL for Windows NT/95/98, you do not need to specify the name of the path if the data file resides in the same directory as your current directory. 
  
  
     descriptionFile 
     The fully qualified name of the description file you have created containing the new key definition. The description file should contain a definition for each segment of the new key.
  
  
     SYSKEY 
     Instructs the utility to re-add the system key on a file in which the system key was dropped.
  
  
     /Oowner 
     The owner name for the data file, if required.
  
  
     /S (NetWare only) 
     By default, the Maintenance utility stops at each full screen of output and waits for a keystroke before continuing. With the /S option, the utility continuously scrolls output on the screen. You cannot use /S on the command line if you specify a command file, but you can specify /S with a command inside a command file.
  




 
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

Rename your data file and then use the CLONE option to create a blank data file using the original file name.
Use RECOVER to save the data from the clone file to an unformatted text file in sequential order.
Use LOAD to load the recovered data into the clone.
Every record containing data will load into the newly created data file without blank records.

Note
You can also perform this operation in the Btrieve Interactive Maintenance utility.

*Table 14-10 Commands to Create and Modify Data Files*
Command	Description
CLONE	Creates a new, empty data file using an existing file's specifications.
CLROWNER	Clears the owner name of a data file.
CREATE	Creates a data file.
DROP	Drops an index.
INDEX	Creates an external index file.
SETOWNER	Assigns an owner name to a data file.
SINDEX	Creates an index.

`outputFile`	The fully qualified file name to use for the new, empty data file. When you run BUTIL for Windows NT/95/98, you do not need to specify the name of the path if the data file resides in the same directory as your current directory.
`sourceFile`	The fully qualified file name of the existing data file to replicate.When you run BUTIL for Windows NT/95/98, you do not need to specify the name of the path if the data file resides in the same directory as your current directory.
/O`owner`	The owner name, if any, for the source data file. The new data file does not have an owner name. See Owner Names for more information.
/S (NetWare only)	By default, the Maintenance utility stops at each full screen of output and waits for a keystroke before continuing. With the /S option, the utility continuously scrolls output on the screen. You cannot use /S on the command line if you specify a command file, but you can specify /S with a command inside a command file.

`sourceFile`	The fully qualified file name of the data file. When you run BUTIL for Windows NT/95/98, you do not need to specify the name of the path if the data file resides in the same directory as your current directory.
/O`owner`	The owner name to clear. See Owner Names for more information.
/S (NetWare only)	By default, the Maintenance utility stops at each full screen of output and waits for a keystroke before continuing. With the /S option, the utility continuously scrolls output on the screen. You cannot use /S on the command line if you specify a command file, but you can specify /S with a command inside a command file.

`outputFile`	The fully qualified file name of the MicroKernel file to create. If the file name is the name of an existing MicroKernel file, this command creates a new, empty file in place of the existing file. Any data that was stored in the existing file is lost and cannot be recovered. When you run BUTIL for Windows NT/95/98, you do not need to specify the name of the path if the data file resides in the same directory as your current directory.
`descriptionFile`	The fully qualified name of the description file containing the specifications for the new MicroKernel file.
Y\|N	Indicates whether to replace an existing file. If you specify N but a MicroKernel file with the same name exists, the utility returns an error message. The default is Y.
/S (NetWare only)	By default, the Maintenance utility stops at each full screen of output and waits for a keystroke before continuing. With the /S option, the utility continuously scrolls output on the screen. You cannot use /S on the command line if you specify a command file, but you can specify /S with a command inside a command file.

`sourceFile`	The fully qualified name of the file from which you are dropping the index. When you run BUTIL for Windows NT/95/98, you do not need to specify the name of the path if the data file resides in the same directory as your current directory.
`keyNumber`	The number of the key to remove. To preserve the original key numbers, add a 128 bias to the key number you specify.
SYSKEY	Instructs the utility to drop the system-defined log key (also called system data). Dropping the system-defined log key does not delete values from the records; the MicroKernel still assigns unique system-defined log key values to newly inserted records.
	However, the MicroKernel cannot perform logging for a file from which the system-defined log key is dropped, if no user-defined unique keys exist. For this reason, you should use this option only if you suspect that the system-defined log key is corrupt and you intend to re-add it. The SINDEX command allows you to re-use the system-defined log key once you have dropped it.
/O`owner`	The owner name for the file, if required.
/S (NetWare only)	By default, the Maintenance utility stops at each full screen of output and waits for a keystroke before continuing. With the /S option, the utility continuously scrolls output on the screen. You cannot use /S on the command line if you specify a command file, but you can specify /S with a command inside a command file.

`sourceFile`	The fully qualified name of the existing file for which to build an external index. When you run BUTIL for Windows NT/95/98, you do not need to specify the name of the path if the data file resides in the same directory as your current directory.
`indexFile`	The fully qualified name of the index file in which the MicroKernel should store the external index.
`descriptionFile`	The fully qualified name of the description file you have created containing the new key definition. The description file should contain a definition for each segment of the new key.
/O`owner`	The owner name for the data file, if required.
/S (NetWare only)	By default, the Maintenance utility stops at each full screen of output and waits for a keystroke before continuing. With the /S option, the utility continuously scrolls output on the screen. You cannot use /S on the command line if you specify a command file, but you can specify /S with a command inside a command file.

`sourceFile`	The fully qualified name of the data file. When you run BUTIL for Windows NT/95/98, you do not need to specify the name of the path if the data file resides in the same directory as your current directory.
/O`owner`	The owner name to be set
`level`	The type of access restriction for the data file. The possible values for this parameter are as follows
	0: Requires an owner name for any access mode (no data encryption)
	1: Permits read access without an owner name (no data encryption)
	2: Requires an owner name for any access mode (with data encryption)
	3: Permits read access without an owner name (with data encryption)
/S (NetWare only)	By default, the Maintenance utility stops at each full screen of output and waits for a keystroke before continuing. With the /S option, the utility continuously scrolls output on the screen. You cannot use /S on the command line if you specify a command file, but you can specify /S with a command inside a command file.

`sourceFile`	The fully qualified name of the existing file for which to build an external index. When you run BUTIL for Windows NT/95/98, you do not need to specify the name of the path if the data file resides in the same directory as your current directory.
`descriptionFile`	The fully qualified name of the description file you have created containing the new key definition. The description file should contain a definition for each segment of the new key.
SYSKEY	Instructs the utility to re-add the system key on a file in which the system key was dropped.
/O`owner`	The owner name for the data file, if required.
/S (NetWare only)	By default, the Maintenance utility stops at each full screen of output and waits for a keystroke before continuing. With the /S option, the utility continuously scrolls output on the screen. You cannot use /S on the command line if you specify a command file, but you can specify /S with a command inside a command file.

Prev
Importing and Exporting Data

Contents
Up
Check for Revisions

Next
Viewing Data File Statistics