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 77

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).

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 | *>]] [/UIDuname /PWDpword [/DBdbname]]


sourceFile	The fully qualified name of the data file from which to transfer records. When you run BUTIL for Windows platforms, 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 platforms, 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.
/UID<name> /UIDuname	Specifies the name of the user authorized to access a database with security enabled.
/PWD<word> /PWDpword	Specifies the password for the user who is identified by uname. Pword must be supplied if uname is specified.
/DB<name> /DBdbname	Specifies the name of the database on which security is enabled. If omitted, the default database is assumed.

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 database engine 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 database engine 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 (see Importing and Exporting ASCII File Format). You can create the data file using either the Create or the Clone command.

Format

butil -load unformattedFile outputFile [/O<owner |*>] [/UIDuname /PWDpword [/DBdbname]]


unformattedFile	The fully qualified name of the ASCII file containing the records to load into a data file. For Windows platforms, 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 platforms, 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.
/UID<name> /UIDuname	Specifies the name of the user authorized to access a database with security enabled.
/PWD<word> /PWDpword	Specifies the password for the user who is identified by uname. Pword must be supplied if uname is specified.
/DB<name> /DBdbname	Specifies the name of the database on which security is enabled. If omitted, the default database is assumed.

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 |*>]
[/Q] [/J] [/I] [/UIDuname /PWDpword [/DBdbname]]


sourceFile	The fully qualified name of the data file from which to recover data. When you run BUTIL for Windows platforms, 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.
/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 database engine 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 database engine 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.
/UID<name> /UIDuname	Specifies the name of the user authorized to access a database with security enabled.
/PWD<word> /PWDpword	Specifies the password for the user who is identified by uname. Pword must be supplied if uname is specified.
/DB<name> /DBdbname	Specifies the name of the database on which security is enabled. If omitted, the default database is assumed.

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 and Exporting ASCII File Format 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.

Format

butil -save sourceFile unformattedFile [Y indexFile | N <keyNumber | -1>] [/O<owner1 | *> [/O<owner2 | *>]] [/Q] [/J] [/I] [/UIDuname /PWDpword [/DBdbname]]


sourceFile	The fully qualified name of the data file containing the records to save. When you run BUTIL for Windows platforms, 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.
/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 database engine 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 database engine 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.
/UID<name> /UIDuname	Specifies the name of the user authorized to access a database with security enabled.
/PWD<word> /PWDpword	Specifies the password for the user who is identified by uname. Pword must be supplied if uname is specified.
/DB<name> /DBdbname	Specifies the name of the database on which security is enabled. If omitted, the default database is assumed.

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