Importing and Exporting Data

Pervasive logo

Advanced Operations Guide

Importing and Exporting Data

This section provides detailed information on importing and exporting data using the following BUTIL commands: COPY, LOAD, RECOVER, and SAVE.

Table 14-9 Commands to Import and Export Data

Command

Description

COPY

Copies the contents of one data file to another.

LOAD

Loads the contents of a sequential file into a data file.

RECOVER

Reads data sequentially from a data file and writes the results to a sequential file.

SAVE

Reads data along a key path and writes the results to a sequential file.

COPY

The COPY command copies the contents of one MicroKernel file to another. COPY retrieves each record in the input data file and inserts it into the output data file. The record size must be the same in both files. After copying the records, COPY displays the total number of records inserted into the new data file.

Note
COPY performs in a single step the same function as a RECOVER command followed by a LOAD command.

Using the COPY command, you can create a data file that contains data from an old file, but has new key characteristics.

To copy a MicroKernel data file

Use the CREATE command to create an empty data file with the desired key characteristics (key position, key length, or duplicate key values).
or

Use CLONE to create an empty data file using the characteristics of an existing file.

Use the COPY command to copy the contents of the existing data file into the newly created data file.

Format
BUTIL -COPY sourceFile outputFile [/O< owner1 | *> 
[/O<owner2 | *>]] [/S]


  
  
     sourceFile 
     The fully qualified name of the data file from which to transfer records. 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. 
  
  
     outputFile 
     The fully qualified name of the data file into which to insert records. The output data file can contain data or be empty. 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. 
  
  
     /Oowner1 
     The owner name of the source data file, if required. If only the output data file requires an owner name, specify /O followed by a blank for owner1 (as illustrated in the example).
  
  
     /Oowner2 
     The owner name of the output 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.
  




 
Example

The following command copies the records in COURSE.MKD to NEWCRS.MKD. The COURSE.MKD input file does not require an owner name, but the NEWCRS.MKD output file uses the owner name Pam.
butil -copy course.mkd newcrs.mkd /O /OPam  
If you omit the first /O from this example, the utility assumes that the owner name Pam belongs to the input data file, not the output data file.

LOAD

The LOAD command inserts records from an input ASCII file into a file. The input ASCII file can be a single file or an extended file (the base file plus several extension files). LOAD performs no conversion on the data in the input ASCII file. After the utility transfers the records to the data file, it displays the total number of records loaded.

Note
The LOAD command opens the output file in Accelerated mode; during a LOAD operation, the MicroKernel does not log the file. If you are using archival logging, back up your data files again after using the LOAD command.

Extended files: If the utility finds the next extension file, it continues the load process. Do not delete any extension file created earlier by the SAVE and RECOVER commands. If the file has three extensions and the user deletes the second one, LOAD stops loading records after processing the first extension file.

If SAVE or RECOVER created three extension files and a fourth one exists from a previous SAVE or RECOVER, LOAD reads the records from the fourth extension and inserts them into the MicroKernel file. If a fourth file exists, then you need to delete it before starting the LOAD process.

Before running the LOAD command, you must create the input ASCII file and the data file. You can create the input ASCII file using a standard text editor or an application; the input ASCII file must have the required file format (as explained in Importing Records From an ASCII File ). You can create the data file using either the CREATE or the CLONE command.

Format
BUTIL -LOAD unformattedFile outputFile [/O<owner |*>] [/S]


  
  
     unformattedFile 
     The fully qualified name of the ASCII file containing the records to load into a data file. For Windows NT, you do not need to specify the name of the path if the data file resides in the same directory as your current directory.
  
  
     outputFile 
     The fully qualified name of the data file into which to insert the records. 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 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.
  




 
Example

The following example loads sequential records from the COURSE.TXT file into the COURSE.MKD file. The owner name of the COURSE.MKD file is Sandy.
butil -load course.txt course.mkd /OSandy  
RECOVER

The RECOVER command extracts data from a MicroKernel file and places it in an ASCII file that has the same format as the input ASCII file that the LOAD command uses. This is often useful for extracting some or all of the data from a damaged MicroKernel file. The RECOVER command may be able to retrieve many, if not all, of the file's records. You can then use the LOAD command to insert the recovered records into a new, undamaged MicroKernel file.

Note
The Maintenance utility performs no conversion on the data in the records. Therefore, if you use a text editor to modify an output file containing binary data, be aware that some text editors may change the binary data, causing the results to be unpredictable.

Format
BUTIL -RECOVER sourceFile unformattedFile [/O<owner |*>] [/S] 
[/Q] [/J] [/I]


  
  
     sourceFile 
     The fully qualified name of the data file from which to recover data. 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.
  
  
     unformattedFile 
     The fully qualified name of the ASCII file where the utility should store the recovered records.
  
  
     /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.
  
  
     /Q 
     Indicates whether to replace an existing unformatted file. By default, the Maintenance utility overwrites the existing files. If you specify this option and a file with the same name exists, the utility returns an error message.

The utility also checks whether the MicroKernel file to be recovered is extended. If the file is extended, the utility checks for files with the same name as the potential unformatted extension file. If one of those files exists, the utility returns an error message.
  
  
     /J 
     Indicates BACKWARD reading of the file. If you specify this option, the utility recovers data from the MicroKernel file using STEP LAST and PREVIOUS operations. The default is forward reading, using STEP FIRST and NEXT operations.
  
  
     /I 
     Indicates FORWARD reading of the file. Although the default is forward reading, you can use this option to indicate FORWARD and BACKWARD reading. This means that if you specify both /I and /J, respectively, the utility reads the file forward until it fails. Then it starts at the end of the file and reads backwards until it reaches the record that failed previously or encounters another failure.

If you specify /J first, the utility reads backwards and then reads forward.
  




  
For each record in the source file, if the RECOVER command receives a variable page error (Status Code 54), it places all the data it can obtain from the current record in the unformatted file and continues the recovery process.

The utility produces the following messages:

informs you about the name of the last extension file created
checks if the next extension file exists, and if so, tells you to delete it
if you move the extended unformatted files to a different location, you are prompted to move the base file and all of its extension files

Example

The following example extracts records from the COURSE.MKD file and writes them into the COURSE.TXT file.
butil -recover course.mkd course.txt 
SAVE

The SAVE command retrieves records from a MicroKernel file using a specified index path and places them in an ASCII file that is compatible with the required format for the LOAD command. You can then edit the ASCII file and use the LOAD command to store the edited data in another data file. (See Importing Records From an ASCII File for more information about the ASCII file format.)

SAVE generates a single record in the output ASCII file for each record in the input data file. Upon completion, SAVE displays the total number of records saved.

Note
The Maintenance utility performs no conversion on the data in the records. Therefore, if you use a text editor to modify an output file containing binary data, be aware that some text editors may change the binary data, causing the results to be unpredictable.

Format
BUTIL -SAVE sourceFile unformattedFile [Y indexFile | N <keyNumber | -1>] [/O<owner1 | *> [/O<owner2 | *>]] [/S] [/Q] [/J] [/I]


  
  
     sourceFile 
     The fully qualified name of the data file containing the records to save. 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.
  
  
     unformattedFile 
     The fully qualified name of the ASCII file where you want the utility to store the records.
  
  
     indexFile 
     The fully qualified name of an external index file by which to save records if you do not want to save records using the default of the lowest key number.
  
  
     keyNumber 
     The key number (other than 0) by which to save records if you do not want to save records using the default of the lowest key number.
  
  
     -1
     The specification for saving the records in physical order using the Btrieve Step operations.
  
  
     /Oowner1 
     The owner name for the source file, if required. If only the index file requires an owner name, specify /O followed by a blank for owner1.
  
  
     /Oowner2 
     The owner name for the index 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.
  
  
     /Q 
     Indicates whether to replace an existing unformatted file. By default, the Maintenance utility overwrites the existing files. If you specify this option and a file with the same name exists, the utility returns an error message.

The utility also checks whether the MicroKernel file to be saved is extended. If the file is extended, the utility checks for files with the same name as the potential unformatted extension files. If one of those files exists, the utility returns an error message.
  
  
     /J 
     Indicates BACKWARD reading of the file. If you specify this option, the utility recovers data from the MicroKernel file using GET LAST and PREVIOUS operations. The default is forward reading, using GET FIRST and NEXT operations.
  
  
     /I 
     Indicates FORWARD reading of the file. Although the default is forward reading, you can use this option to indicate FORWARD and BACKWARD reading. This means that if you specify both /I and /J, respectively, the utility reads the file forward until it fails. Then it starts at the end of the file and reads backwards until it reaches the record that failed previously or encounters another failure.

If you specify /J first, the utility reads backwards and then reads forward.
  




 
The utility produces the following messages:

informs you about the name of the last extension file created
checks if the next extension file exists, and if so, tells you to delete it
if you move the extended unformatted files to a different location, you are prompted to move the base file and all of its extension files

Examples

The following two examples illustrate how to use the SAVE command to retrieve records from a data file.

This example uses a NEWCRS.IDX external index file to retrieve records from the COURSE.MKD file and store them in an unformatted text file called COURSE.TXT:
butil save course.mkd course.txt newcrs.idx  
The following example retrieves records from the COURSE.MKD file using key number 3 and stores them in an unformatted text file called COURSE.TXT:
butil -save course.mkd course.txt n 3  

*Table 14-9 Commands to Import and Export Data*
Command	Description
COPY	Copies the contents of one data file to another.
LOAD	Loads the contents of a sequential file into a data file.
RECOVER	Reads data sequentially from a data file and writes the results to a sequential file.
SAVE	Reads data along a key path and writes the results to a sequential file.

`sourceFile`	The fully qualified name of the data file from which to transfer records. 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.
`outputFile`	The fully qualified name of the data file into which to insert records. The output data file can contain data or be empty. 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`owner1`	The owner name of the source data file, if required. If only the output data file requires an owner name, specify /O followed by a blank for owner1 (as illustrated in the example).
/O`owner2`	The owner name of the output 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.

`unformattedFile`	The fully qualified name of the ASCII file containing the records to load into a data file. For Windows NT, you do not need to specify the name of the path if the data file resides in the same directory as your current directory.
`outputFile`	The fully qualified name of the data file into which to insert the records. 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 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 from which to recover data. 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.
`unformattedFile`	The fully qualified name of the ASCII file where the utility should store the recovered records.
/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.
/Q	Indicates whether to replace an existing unformatted file. By default, the Maintenance utility overwrites the existing files. If you specify this option and a file with the same name exists, the utility returns an error message. The utility also checks whether the MicroKernel file to be recovered is extended. If the file is extended, the utility checks for files with the same name as the potential unformatted extension file. If one of those files exists, the utility returns an error message.
/J	Indicates BACKWARD reading of the file. If you specify this option, the utility recovers data from the MicroKernel file using STEP LAST and PREVIOUS operations. The default is forward reading, using STEP FIRST and NEXT operations.
/I	Indicates FORWARD reading of the file. Although the default is forward reading, you can use this option to indicate FORWARD and BACKWARD reading. This means that if you specify both /I and /J, respectively, the utility reads the file forward until it fails. Then it starts at the end of the file and reads backwards until it reaches the record that failed previously or encounters another failure. If you specify /J first, the utility reads backwards and then reads forward.

`sourceFile`	The fully qualified name of the data file containing the records to save. 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.
`unformattedFile`	The fully qualified name of the ASCII file where you want the utility to store the records.
`indexFile`	The fully qualified name of an external index file by which to save records if you do not want to save records using the default of the lowest key number.
`keyNumber`	The key number (other than 0) by which to save records if you do not want to save records using the default of the lowest key number.
-1	The specification for saving the records in physical order using the Btrieve Step operations.
/O`owner1`	The owner name for the source file, if required. If only the index file requires an owner name, specify /O followed by a blank for owner1.
/O`owner2`	The owner name for the index 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.
/Q	Indicates whether to replace an existing unformatted file. By default, the Maintenance utility overwrites the existing files. If you specify this option and a file with the same name exists, the utility returns an error message. The utility also checks whether the MicroKernel file to be saved is extended. If the file is extended, the utility checks for files with the same name as the potential unformatted extension files. If one of those files exists, the utility returns an error message.
/J	Indicates BACKWARD reading of the file. If you specify this option, the utility recovers data from the MicroKernel file using GET LAST and PREVIOUS operations. The default is forward reading, using GET FIRST and NEXT operations.
/I	Indicates FORWARD reading of the file. Although the default is forward reading, you can use this option to indicate FORWARD and BACKWARD reading. This means that if you specify both /I and /J, respectively, the utility reads the file forward until it fails. Then it starts at the end of the file and reads backwards until it reaches the record that failed previously or encounters another failure. If you specify /J first, the utility reads backwards and then reads forward.

Prev
Btrieve Command-Line Maintenance Utility (BUTIL)

Contents
Up
Check for Revisions

Next
Creating and Modifying Data Files