Btrieve Command-Line Maintenance Utility (BUTIL)

---

Use this utility if you prefer a command-line interface or if you want to start or stop continuous operation. The Btrieve Maintenance utility is also available in a command-line format that runs on the server (as an NLM on NetWare or from a DOS command prompt on Windows NT) or locally on DOS, and Win32 clients. You can execute Maintenance utility commands from the command line or through a command file you create. Before you perform commands in the Btrieve Maintenance utility, also referred to as BUTIL, it is important you understand some concepts and elements addressed in the Commands.

The Btrieve Command-Line Maintenance utility performs the following common file and data manipulations:

• Importing and Exporting Data
• Creating and Modifying Data Files
• Viewing Data File Statistics
• Displaying Btrieve Interface Module Version
• Unloading the Btrieve Interface and Requester (DOS only)
• Performing Continuous Operations

Return Codes

When BUTIL finishes executing, it returns an exit code or DOS "errorlevel" return code to the operating system. The return codes are as follows:

 
Table 14-6 BUTIL.EXE Return Codes

Code	Meaning
SUCCESS_E = 0	Requested operation succeeded.
PARTIAL_E = 1	Requested operation completed, but with errors.
INCOMPLETE_E = 2	Requested operation did not complete.
USAGE_E = 3	Syntax error in input, display usage screen and exit.

Commands

Table 14-7 lists the commands that you can use with the Command-line Maintenance Utility.

 
Table 14-7 Command-Line Maintenance Utility Commands  

Command	Description
CLONE	Creates a new, empty data file using an existing file's specifications.
CLROWNER	Clears the owner name of a data file.
COPY	Copies the contents of one data file to another.
CREATE	Creates a data file.
DROP	Drops an index.
ENDBU	Ends continuous operation on data files defined for backup in Win32 and NLM versions only.
INDEX	Creates an external index file.
LOAD	Loads the contents of an unformatted file into a data file.
RECOVER	Reads data sequentially from a data file and writes the results to an unformatted file. (The DOS version does not support ROLLFWD.) Use this command if you have a damaged file.
ROLLFWD	Recovers changes made to a data file between the time of the last backup and a system failure.
SAVE	Reads data along a key path and writes the results to a sequential file.
SETOWNER	Assigns an owner name to a data file.
SINDEX	Creates an index.
STARTBU	Starts continuous operation on files defined for backup in Win32 and NLM versions only.
STAT	Reports statistics about file attributes and current sizes of data files.
STOP (DOS only)	Unloads the Btrieve Interface and requester.
VER	Displays the version of the MicroKernel Database Engine and Btrieve Interface Module that is loaded at the server.

Viewing Command Usage Syntax

To view a summary of each command usage, enter the following command at the file server:

butil  

---

Note
Unless otherwise shown, all command syntax is lowercase on UNIX platforms. Windows-based platforms are case insensitive. NetWare can be configured to be case sensitive or insensitive, but for purposes of discussion, this section assumes case insensitive.

---

The utility displays usage syntax for each command as illustrated in
Table .

 
Table 14-8 Maintenance Utility Command Syntax on NetWare

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

BUTIL -CLROWNER sourceFile /O<owner | *> [/S]

BUTIL @commandFile [commandOutputFile]

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

BUTIL -CREATE outputFile descriptionFile [< Y | N >] [/S]

BUTIL -DROP sourceFile < keyNumber | SYSKEY > [/O<owner | *>] [/S]

BUTIL -ENDBU < /A | sourceFile | @listFile > [/S]

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

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

BUTIL -RECOVER sourceFile unformattedFile [/O<owner |*>] [/S]

BUTIL -ROLLFWD <sourceFile | volume | drive | @listFile> [</L[dumpFile] | /W[dumpFile]> [/T<dataLength>] [/E<keyLength>] [/H] [/V] [/O<ownerList | owner> | *]] [/A] [/S]

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

BUTIL -SETOWNER sourceFile /O<owner | *> level [/S]

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

BUTIL -STARTBU <sourceFile | @listFile> [/S]

BUTIL -STAT <sourceFile> [/O<owner | *>] [/S]

BUTIL -VER [/S]

---

Note
The /S option applies only to the NetWare version of the command-line utility. Also, on NetWare you always have to specify the full path of the file name such as sys:\pvsw\demodata\tuition.mkd.

---

Command Format

The format for the Maintenance utility command line is as follows:

BUTIL [-command [parameter ...]] | @commandFile


  

  

    
 
-command
    
 
A Maintenance utility command, such as COPY. You must precede the command with a dash (-), and you must enter a space before the dash. Table 14-7 lists the commands.
  
  

    
 
parameter
    
 
Information that the command may require. Discussions of the individual commands provide details when applicable.
  
  

    
 
@commandFile
    
 
Fully qualified file name of a command file.
  




 

Command Files

You can use a command file to do the following:

• Execute a command that is too long to fit on the command line.
• Execute a command that you use often (by entering the command once in the command file and then executing the command file as often as you want).
• Execute a command and write the output to a file, using the following command format:

  BUTIL @commandFile [commandOutputFile]  
  

For each command executed, the resulting output file shows the command followed by its results. All messages appear on the server console screen, as well.

• Execute multiple commands sequentially.

Command files contain the same information as that required on the command line.

Rules for Command Files

Observe the following rules when creating a Maintenance utility command file:

• You cannot split a single parameter across two lines.

You must end each command with <end> or [end]. You must also end each command with an <end> when trying to execute multiple commands. The <end> or [end] must be lowercase.

Command File Example

The following is an example command file, COPYCRS.CMD. The file calls the BUTIL - CLONE command to create the NEWCRS.MKD file by cloning the COURSE.MKD file, and the -CREATE command to create the NEWFILE.DTA file by using the description provided in the NEWFILES.DES description file.

-clone newcrs.mkd course.mkd <end> 
-create newfile.dta newfiles.des <end> 

The following command uses the COPYPATS.CMD file and writes the output to the COPYPATS.OUT file:

butil @copypats.cmd copypats.out 

Description Files

Description files are ASCII text files that contain descriptions of file and key specifications that the Maintenance utility can use to create data files and indexes. Some users employ description files as a vehicle for archiving information about the data files they have created. For more information about the description file format, see Appendix ADescription Files.

Extended File Support

The size of the MicroKernel data file can be larger than the operating system file size limit. When you export data from an extended MicroKernel file to an unformatted file, the size of the unformatted file can exceed the MicroKernel file size limit because of the differences in the physical format.

When you are exporting large files, the Interactive Maintenance utility detects that the unformatted file has exceeded the operating system file size limit (2 GB) and starts creating extension files. This process is transparent. Extension files and the original unformatted file must reside on the same volume. The extension file uses a naming scheme in which the file names are similar to the base file name. In contrast to native MKDE extension files which use a caret "^" to indicate extension file status, the unformatted extension files use a tilde "~" to avoid overwriting any existing extended MKDE files with the same base file name. The first export extension file is the same base file name with ".~01" extension. The second extension file is ".~02," and so on. These extensions are appended in hexadecimal format.

While the naming convention supports up to 255 extension files, the current maximum number of extension files is 32, thus supporting files as large as 64 GB.

To SAVE or RECOVER huge files to unformatted files, see the respective command. Also, when you import data from an unformatted file, the utility detects if the file has extensions and loads the data from the extension file.

Owner Names

The MicroKernel allows you to restrict access to files by specifying an owner name. Because owner names are optional, the files you use with the utility may or may not require an owner name. If the file requires an owner name, you must specify it using the /O option. You can specify one of the following:

• Single owner name.
• List of up to eight owner names. Separate the owner names with commas.
• Asterisk (*). The utility prompts you for the owner name. With the ROLLFWD command, the utility prompts you for a list of owner names separated by commas.

Owner names are case-sensitive. If you enter owner names on the command line, the utility discards leading blanks. If you specify an asterisk, the utility does not discard leading blanks.

Redirecting Error Messages

Be sure that you specify a fully qualified file name (including a drive letter or UNC path) when redirecting error messages.

To redirect error messages to a file on a Windows NT or UNIX server

• Use the following command format.

  BUTIL -command commandParameters > filePath 
  

To redirect error messages to a file on a NetWare server

• Use the following command format.

  LOAD BUTIL -command commandParameters (CLIB_OPT)
  />filepath 
  

ASCII File Format

See Importing Records From an ASCII File in the Interactive Maintenance utility section.

Rules for Specifying File Names on Different Platforms

When you run BUTIL on a Windows-based platform or a UNIX-based platform, you do not need to specify the name of the path if the data file resides in the same directory as your current directory.