Btrieve Command-Line Maintenance Utility (butil)


–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 76 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 <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 Description Files.

Extended File Support

The size of the database engine 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 database engine 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 MicroKernel Engine extension files which use a caret “^” to indicate extension file status, the unformatted extension files use a tilde “~” to avoid overwriting any existing extended MicroKernel Engine 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 64, thus supporting files as large as 128 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.

A short owner name can be up to 8 bytes. A long owner name can be up to 24 bytes. Once a long owner name is specified, the data file cannot be read by a database engine prior to PSQL v10.10. Also, a data file with a long owner name cannot be rebuilt to a file format prior to 9.5 unless the owner name is first removed. An owner name, long or short, with less than the maximum allowed bytes is padded with spaces to the maximum length (8 or 24 bytes).

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