Copyright: Copyright © 1982-2001 Pervasive Software Inc. All Rights Reserved


Introduction

The Rebuild Utility can convert MicroKernel data files as shown in the table below.

Original File Format	Converted File Format	Reason for Conversion
pre-v6.0	v7.x	Take advantage of v7.x features and improve general performance.
v6.x	v7.x	Take advantage of v7.x features and improve general performance.
v7.x	v7.x	Original file does not have a system key.
pre-v6.0	v6.x	Take advantage of v6.x features and improve general performance. Use this option only if you are still running the v7.x engine with other v6.x engines.
The file format that results from the conversion depends on the value you set for the MicroKernel’s Create File Version configuration option, which you specify using the Setup Utility. For example, if you set the Create File Version to 7.x and you run the Rebuild Utility on v6.x files, the utility converts the files to v7.x format.

Before you run the Rebuild Utility, back up all the data files you plan to convert. Having backup copies ensures against data loss if a power interruption occurs while you are running the utility.

To ensure that your backup is successful, perform any one of the following operations:

Close all data files before running the backup utility.

Use continuous operations.

Use a backup utility that opens the files in exclusive write mode so that other processes cannot write to the files. Ensure that the backup utility has exclusive rights to the files.

Once you have backed up your files, from the Options menu select Settings to configure the settings that determine how the file will be rebuilt. Then choose Select Files to add all the files you would like to rebuild. After you have made these selections, you are ready to begin the rebuild process. From the Run menu choose Start Rebuild and click the Start button. When the process completes, select View Status File from the Run menu.


About

The About dialog box displays various product information, including the name, version and copyright of the Rebuild Utility.

OK


Displays a Browse dialog box that lets you select the files you want to rebuild.


Closes the dialog box without saving any changes.


Closes the dialog box.


Continue On Error

Determines whether the Rebuild Utility continues if it encounters an error during the rebuild process. If you select Yes, the utility continues with the next file even if an error occurs. The utility notifies you of non-MicroKernel data files or other errors but continues rebuilding data files. If you select No, the utility halts the rebuild if it encounters an error.


Deletes the currently selected file from the Selected Files list.


Deleting Files
To delete selected files

Highlight the file and click Delete.

Tip

You will have a chance to view the list of files again from the Start Rebuild dialog box prior to starting the rebuild process.


Displays help for this dialog box.


Closes the About dialog box.


Saves the set of files in the Selected Files list.


Saves the selected settings.


Output Directory

Specifies an alternate location for the rebuilt files. (The default location is the current directory of the original file being rebuilt.) You must specify a directory that already exists. This option lets you rebuild large files on a different volume or on a different server. The MicroKernel and its communications components must be loaded on the server that contains the rebuilt files. Do not use wildcard characters in the path.

If the Output Directory location is different than the original file’s location, the original file is not deleted during the rebuild. If the output directory is the same as the original file, the original file will be deleted upon completion of the rebuild.

Click the Browse... button to locate the output directory using the Directory Browse dialog box.


Page Size

Specifies the page size (in bytes) of the new files. Choose either EXISTING, 512, 1024, 2048, 3072, or 4096. If you select EXISTING, the utility uses the existing page size. The utility changes the page size if the original size does not work.

For example, assume you have a v5.x file with a page size of 1024 and 24 keys. Since Btrieve v6.0 and later supports only 23 keys for a page size of 1024, the utility automatically selects a new page size for the file and writes an informative message to the status file.


Save Settings On Exit

Saves the configuration settings on the Settings dialog box when you close the Rebuild Utility.


Select Files

Use this option to select files you want to rebuild or to delete files previously selected for rebuild. Click on the following dialog buttons for an explanation of their function.

Add...

Delete

OK

Cancel

Help


Selecting Files
To select files to rebuild

1 Click the Add... button.

2 Use the Browse dialog box to locate the files you want to rebuild.

Tip

You will have a chance to view this list of files again from the Start Rebuild dialog box prior to starting the rebuild process.


Settings

The Settings dialog box contains configuration parameters for the utility. Click on the dialog box components for a detailed explanation.

Output Directory

Key Number

Status File Path

Page Size

Continue On Error

Save Settings On Exit

Choose System Data and Key

OK

Cancel

Help


Start Rebuild

This dialog box lists the files to be rebuilt which were selected in the Select Files dialog box. Ensure that you have made all the selections in the Settings dialog box prior to invoking the rebuild process.

By default, the Rebuild Utility creates temporary files in the same directory in which the conversion takes place. You therefore need enough disk space in that directory (while the Rebuild Utility is running) to accommodate both the original file and the new file. You can specify a different directory for storing these files using the Output Directory option in the Settings dialog box.

The Rebuild Utility deletes the original file after rebuilding it if the file is being rebuilt in the same directory. If the new file is in a different directory the original file is not deleted. Normally, the Rebuild Utility automatically deletes temporary files when the conversion is complete. However, if a power failure or other serious interruption occurs, the Rebuild Utility may not delete the temporary files. If this occurs, look for filenames such as _T-xxxxx.TMP and delete them.

You should view the Status File after the rebuild completes.

Start

Close

Help

Tip

If there are no files to rebuild, the Start button is disabled.


Selecting this button will begin the rebuilding of the files in the Files to Rebuild list. To select files to rebuild, go to the Select Files dialog box.


Status File Path

Specifies a location for the rebuild log file. (The default location is the current working directory.)

Click the Browse... button to specify the log directory using the Browse dialog box.


Choose System Data and Key

Specifies whether the file is rebuilt with System Data or System and Key Data. The MicroKernel cannot perform logging for a file without system data when no user-defined unique key exists.


View Status File

The Rebuild Utility writes to the status file for every file it attempts to rebuild. The rebuild settings are listed for every file. If you disabled the Continue on Error setting the status file contains the information up to the point of the error. The status file can be used as a reference in the future. The status file informs you if the rebuild was successful. If the rebuild was not successful, the status file contains error messages explaining why the rebuild failed. The path for the status file is specified in the Settings dialog box.


Key Number

Specifies the key by which the utility reads when rebuilding a file. If you specify NONE for this option, the utility clones the files, drops the indexes, copies the records into the new files, and rebuilds the indexes. Because this method is faster and creates smaller files than specifying a key number, use it whenever possible.

This method may create a new file in which the records are in a different physical order than in the original file.

If you specify a key number, the utility clones and copies the files without dropping and replacing indexes. While this method is slower than specifying NONE, it is available in case you do not want to rebuild your indexes.