butil

---

Description

The Pervasive.SQL Maintenance Utility, or butil, is a command line utility that performs command file and data manipulations on a MKDE file.

The maintenance utility performs the following file and data manipulations:

• Starts and stops continuous operations for use in performing server backups.
• Recovers changes made to a file between the time of the last backup and a system failure.
• Imports and exports ASCII, unformatted, and SDF sequential data.
• Copies data between data files.
• Returns MKDE version information.

Continuous operation is an MKDE feature that enables you to back up files while they are in use by Pervasive.SQL-based applications. Two maintenance commands, startbu and endbu, begin and end continuous operation on a file or set of files.

Synopsis

butil 
-clone outputFile sourceFile [/Oowner] [/UIDuid /PWDpwd [/DBname]] 
-clrowner sourceFile [/Oowner] [/UIDuid /PWDpwd [/DBname]] 
@commandFile [commandOutputFile] 
-copy sourceFile outputFile [/Oowner1] [/Oowner2] [/UIDuid /PWDpwd [/DBname]] 
-create sourceFile descriptionFile [Y | N] [/UIDuid /PWDpwd [/DBname]] 
-drop sourceFile <keyNumber | SYSKEY> [/Oowner] [/UIDuid /PWDpwd [/DBname]] 
-endbu </A | sourceFile | @listFile> [/UIDuid /PWDpwd [/DBname]] 
-index sourceFile indexFile descriptionFile [/Oowner] [/UIDuid /PWDpwd [/DBname]] 
-load unformattedFile outputFile [/Oowner] [/UIDuid /PWDpwd [/DBname]] 
-recover sourceFile unformattedFile [/Oowner] [/UIDuid /PWDpwd [/DBname]] 
-rollfwd sourceFile unformattedFile [/Oowner] [/UIDuid /PWDpwd [/DBname]] 
-save sourceFile unformattedFile  
[Y indexFile | N <keyNumber | -1>][/Oowner]  
[/UIDuid /PWDpwd [/DBname]] 

-setowner sourceFile owner level [/UIDuid /PWDpwd [/DBname]] 
-sindex sourceFile <descriptionFile | SYSKEY> 
	[keyNumber][/Oowner] [/UIDuid /PWDpwd [/DBname]] 
-startbu <sourceFile | @listFile> [/UIDuid /PWDpwd [/DBname]] 
-stat sourceFile [/Oowner] [/UIDuid /PWDpwd [/DBname]] 
-ver 

Options

---

Note
Maintenance Utility command options are not case sensitive unless the option is a filename.

---

If you run butil without specifying a command option or with an invalid command option, a usage message is printed. The usage message indicates that there is an optional /S command line argument to butil. This argument, which is used to suppress screen-at-a-time printing on NetWare, is ignored under Linux.

Commands

-clone outputFile sourceFile [/Oowner] 

The clone command creates a new, empty Pervasive.SQL formatted 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 of the defined key characteristics (such as key position, key length, or duplicate key values) contained in the existing file. Unless specified, the new data file will not have an owner name.

-clrowner sourceFile [/Oowner] 

The clrowner command clears the owner name of a Pervasive.SQL data file.

@commandFile [commandOutputFile] 

The Maintenance Utility allows you to specify the butil command options in a commandFile that can be specified to butil. An <end> keyword must be placed after each command option in the file.

The following is an example command file:

create xface.btr xface.dsc
<end>

stat xface.btr
<end>

-copy sourceFile outputFile [/Oowner1] [/Oowner2] 

The copy command copies the contents of one Pervasive.SQL formatted file to another. Copy retrieves each record in the source 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 output data file.

Copy performs the same function as recover and load in a single step.

-create sourceFile descriptionFile [Y | N] 

The create command generates an empty Pervasive.SQL formatted data file using the characteristics specified in the description file. If the path name is the name of an existing Pervasive.SQL formatted file, this command creates a new, empty Pervasive.SQL formatted file in place of the existing Pervasive.SQL formatted file. Any data that was stored in the existing file is lost and cannot be recovered.

Y|N indicates whether to replace an existing file. If you specify N but a Pervasive.SQL formatted file with the same name exists, the utility returns an error message and does not create a new file. The default is Y.

-drop sourceFile <keyNumber | SYSKEY> [/Oowner] 

The drop command removes an index from a Pervasive.SQL formatted data 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.

-endbu </A | sourceFile | @listFile> 

The endbu command ends continuous operation on a data file or set of data files previously defined for backup. Execute this command after you have issued the startbu command and your backup utility has finished running. To back up data files using continuous operation, first issue the butil - startbu command, followed by the data file or set of data files. Next, run your backup program. Then, stop continuous operation by using the butil - endbu command. All the files must be located on the server where you are running butil. You cannot specify a mapped drive using the endbu command.

/A stops continuous operation of all the files defined for the backup.

-index sourceFile indexFile descriptionFile [/Oowner] 

The index command builds an external index file for an existing Pervasive.SQL formatted 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. The records in the new file consist of the following:

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

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

-load unformattedFile outputFile [/Oowner] 

The load command inserts records from an unformatted input sequential file into a Pervasive.SQL formatted file. It performs no conversion on the data in the input sequential file. After the utility transfers the records to the data file, it displays the total number of records loaded.

Before running the load command, you must create the input sequential file and the data file. You can create the input sequential file using a standard text editor or an application; the input sequential file must have the required file format (as explained below). You can create the data file using either butil -create or butil -clone.

Records in the input sequential file must be in the following format:

• The first field must be a left-adjusted integer (in ASCII) that provides the length of the record. This field does not include the end-of-line markers. For files with fixed length records, the length you specify should equal the record length of the data file. For files with variable length records, the length you specify must be at least as long as the minimum fixed length of the data file.
• A separator (either a comma or a blank) must follow the length field.
• The record data follows the separator. The length of the data must be the exact number of bytes specified by the length field.
• An end-of-line marker must terminate each line. The end-of-line marker is not included in the length value at the beginning of the line.

-recover sourceFile unformattedFile [/Oowner] 

The recover command extracts data from a Pervasive.SQL formatted file and places it in a sequential file that has the same format as the input sequential file used by the load command. This command is often useful for extracting some or all of the data from a damaged Pervasive.SQL formatted 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 Pervasive.SQL formatted file.

-rollfwd sourceFile [ /Ldumpfile /Wdumpfile 
/Tdatalength /Ekeylength /H /V /A /Oowner] 

The rollfwd command recovers changes made to a data file between the time of the last backup and a system failure. The MKDE stores the changes in a log.

If a system failure occurs, you can restore the backup copy of your data file and then use the rollfwd command, which applies all changes stored in the log to your backup copy.

-save sourceFile unformattedFile 
[Y indexFile | N <keyNumber | -1>] [/Oowner] 

The save command retrieves records from a Pervasive.SQL formatted data file using the specified index path and places them in a sequential file that is compatible with the required format for the load command. Save generates a single record in the output sequential file for each record in the input data file. Upon completion, save displays the total number of records saved.

The Maintenance Utility performs no conversion of 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.

indexFile is used if you do not want to save records by using the default of the lowest key number.

keyNumber is used if you do not want to save records using the default of the lowest key number.

-1 is the specification for saving the records in physical order using the Pervasive.SQL Step operations.

-setowner sourceFile owner level 

The setowner command creates an owner for a Pervasive.SQL formatted file and assigns an access restriction level to that owner. For more information about owner names, see Advanced Operations Guide.

-sindex sourceFile <descriptionFile | SYSKEY > [keyNumber] [/Oowner] 

The sindex command creates an additional index for an existing Pervasive.SQL formatted file. The key number of the new index is one higher than the previous highest key number of the data file. 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.

Before you can use the sindex command, you must create a description file to key specifications for the index.

keyNumber is used when you do not want to save records using the default of the lowest key number.

-startbu <sourceFile | @listFile> 

The startbu command places a file or set of files into continuous operation for backup purposes. To back up files using continuous operation, first issue the butil -startbu command, followed by the data file or set of data files. All the files must be located on the server where you are running butil. You cannot specify a mapped drive using the startbu command.

Next, run your backup program. Then issue the butil -endbu command to stop continuous operation.

When you place a data file into continuous operation mode, the MKDE creates a temporary file with the same name as the data file, but with a .^^^ extension. Therefore, do not create multiple data files with the same names but different extensions. For example, do not use a naming scheme such as INVOICE.HDR and INVOICE.DET for your Pervasive.SQL data files.

-stat sourceFile [/Oowner] 

The stat command reports the defined characteristics of a data file and statistics about the file's contents.

-ver 

The ver command returns the version number of the MKDE loaded at the server.

Variables

descriptionFile
is the path name of a description file containing the description of the index you wish to use. Is an ASCII text file containing information the Maintenance Utility needs to perform create and index operations. Description files are made up of one or more elements, where each element consists of a keyword followed by an equal sign (=) and a value (with no space separator). Please refer to the Advanced Operations Guide for details of description files.

indexFile
is the path_name of the index file in which the MKDE stores the external index.

keyNumber
is the key number (other than 0) of the index specified.

level
is 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 any 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).

listFile
is the name of the text file containing the pathnames of files to be included in either the endbu or startbu operations. These pathnames must be separated by a space or end-of-line marker.

outputFile
is the path name of the data file into which you want to insert records. The output file can be empty or have existing data.

owner
is the owner of any specified files, if any. Can be used more than once in a command line when more than one file is specified. For example, copy sourceFile outputFile [/Oowner1][/Oowner2]. The MKDE enables you to restrict access to a file by specifying an owner name. Since owner names are optional, the files you use with this utility may or may not require an owner name. Owner names are case sensitive.

sourceFile
is the path_name of an existing data file, except when using the create command, which creates an empty data file. Generally refers to a Pervasive.SQL file.

unformattedFile
is the pathname of an ASCII sequential file.

Examples

• The following command creates a Pervasive.SQL formatted file named patients.btr using the description provided in the BUILD.dsc description file.

% butil -create patients.btr BUILD.dsc

• The following command copies the records in patients.btr to newpats.btr. The patients.btr input file does not require an owner name, but the newpats.btr output file uses the owner name Pam.

% butil -copy patients.btr newpats.btr /O /OPam

• The following command creates the newapp.btr file by cloning the patients.btr file.

% butil -clone newapp.btr patients.btr

• The following command clears the owner name for the newpats.btr. The owner name for the file newpats.btr is Pam.

% butil -clrowner patients.btr /OPam

• The following command sets the owner name for the newpats.btr to Ron with a restriction level of 1.

% butil -setowner patients.btr /ORon 1

• The following command creates an external index file called newpats.idx using a data file called patients.btr. The patients.btr file does not require an owner name. The description file containing the definition for the new key is called NEWidx.dsc

% butil -index patients.btr newpats.idx NEWidx.dsc

The description file shown below 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 sequences.

position=30 length=10 duplicates=y modifiable=y
type=string alternate=n segment=n

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

• The first example uses the newpats.idx external index file to retrieve records from the patients.btr data file and store them in an unformatted text file called patients.sav.

% butil -save patients.btr patients/.sav Y newpats.idx

• The next example retrieves records from the patients.btr file using key number 3 and stores them in an unformatted text file called patients.sav.

% butil -save patients.btr patients/.sav N 3

• The following example loads sequential records from patients.adr file into the patients.btr file. The owner name of the patients.btr file is Sandy.

% butil -load patientsa.adr patients.btr /OSandy

• The following example adds an index to the patients.btr file. The name of the description file is suppidx.dsc. The owner name of the patients.btr is Ron.

% butil -sindex patients.btr suppidx.dsc /ORon

See Also

syslogd(1)

API Programmer's Reference - describes the Pervasive.SQL API

$PVSW_ROOT/doc/readme.html - contains useful configuration information and release notes ($PVSW_ROOT denotes the directory where Pervasive.SQL for Linux is installed - by default it is /usr/local/psql)