Converting MicroKernel Data Files

---

NOT UPDATED FOR NEW REBUILD - SEE ADVANCED OPS

The Rebuild utility is a tool that can convert older Btrieve data files to the current Pervasive.SQL format. While the current engines remain compatible with the older files, there are several reasons for converting the files including support for nullable columns and performance improvements.

 
Table 20-1    Rebuild Utility Conversions

Original File Format	Converted File Format	Reason for Conversion
8.x	8.x	Remove deleted record space from a file, change the page size, or add system data.
Pre-8.x	8.x	Take advantage of write (insert, update, delete) performance improvements offered by Turbo Write Accelerator.
Pre-7.x	7.x	Take advantage of 7.x features and improve general performance.
7.x	7.x	Original file does not have a system key.
Pre-6.0	6.x	Take advantage of 6.x features and improve general performance. Use this option only if you are still running the 7.x engine with other 6.x engines.

The Rebuild utility comes in two forms with Pervasive.SQL V8: a 32-bit GUI version for Windows, and a command-line version that runs as an NLM on NetWare.

The file format that results from the conversion depends on either the value you set with the command-line parameter or with the GUI utility. When you use the command-line utility and do not specify a file versoin, the value used is taken from the MicroKernel's Create File Version configuration option. For example, if the Create File Version value is 8.x then running the Rebuild utility on version 7.x files will result in the rebuilt files being converted to version 8.x format.

If you have more than one server engine available, you may wish to use each of your available server engines to rebuild a portion of the total number of files that must be converted. During your scheduled down time for the upgrade, you may find it helpful to copy large files out to the computers where the other server engines are, and then copy the files back when you are finished converting. That way you can share the burden of converting among a number of CPUs.

You can use the Continue on Error option in combination with a *.* file list to convert all the data files in a directory, even if other types of files exist in the directory. The other types of files generate an error when the Rebuild utility attempts to open them. If you have the Continue on Error option set, the utility ignores each of these errors and skips to the next file.

If you have files in the same directory that are already in the version 8 format, they are also rebuilt, and the physical order of the records in these files may be changed depending on the rebuild options you select. You cannot convert from a more recent format back to an earlier format. For example, you cannot convert a version 8 data file to version 6.x format.

There is currently no facility to perform a recursive or multi-directory conversion without building a list of all the individual directories or individual files that you wish to convert.

Before running 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 the utility is running.

---

Note
Large files, such as 3 or 4 GB, may take several hours to convert.

---

To ensure that the backup is successful, perform one or more 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.

---

Note
You cannot run the Rebuild utility on a file that is in continuous operation mode.

---

Running the GUI Rebuild Utility

There are two ways to start the GUI Rebuild utility:

• On a Windows machine, select Tools, then Rebuild from the Pervasive Control Center menu.
• From the Windows Start menu, select Programs, then Pervasive.SQL V8, then Other Utilities, then Rebuild.

The main window displays as illustrated in Figure 20-1.

 
Figure 20-1    Rebuild Utility Main Window

Getting Help

You can access a Help file from either the Help menu or by clicking Help in any dialog box.

Converting a Data File

   To convert a data file:

1. Choose Select Files from the Options menu. The Select Files dialog box appears (Figure 20-2.)

    
   Figure 20-2    Select Files Dialog Box

   

2. Click Add and select the file you want to rebuild. You can select more than one file to rebuild at a time. Click OK when you have finished adding files to rebuild.

   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.

3. Before you rebuild the file(s), you may want to specify settings. Choose Settings from the Options menu. The Settings dialog box displays as illustrated in Figure 20-3.

    
   Figure 20-3    Settings Dialog Box

   

   You can change the configuration options for the Rebuild utility before you rebuild your selected file or files. These options are defined in Table 20-2.

    
   Table 20-2    Controls in the Settings Dialog Box 

   Control	Description
   Output Directory	Specifies an alternate location for the rebuilt files. (The default location is the current directory.) You must specify a directory that already exists. This option lets you rebuild large files 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 is deleted upon completion of the rebuild.
   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.
   Status File Path	Specifies a location for the rebuild log file. (The default location is the current working directory.) Do not use wildcard characters in the path.
   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 1,024 and 24 keys. Because Btrieve 6.0 and later supports only 23 keys for a page size of 1,024, the utility automatically selects a new page size for the file and writes an informative message to the status file.
   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. This option is useful if you have specified wildcard characters for the rebuilt files.
   Save Settings Upon Exit	Saves the current values in this dialog box for use in subsequent Rebuild sessions.
   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.

4. After you specify the settings, you need to start the file conversion process. Select Start Rebuild from the Run menu. The Start Rebuild dialog box displays as indicated in Figure 20-4.

    
   Figure 20-4    Start Rebuild Dialog Box

   

5. Click Start to begin the rebuild process, which converts all of the listed files.

   When the process completes, a message dialog box informs of the success or failure of the conversion and prompts you to view the results.

6. Click Close when you have finished converting files.
7. To display the results, select View Status File from the Run menu. The REBUILD.LOG file is displayed as illustrated in Figure 20-5.

    
   Figure 20-5    Start Rebuild Dialog Box

   

The Rebuild utility writes to the status file for every file it attempts to convert. The log file (REBUILD.LOG by default) is an ASCII text file that is placed by default in the directory in which you run the Rebuild utility from.

You can examine the log file by selecting the View Status File command from the Run menu. 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. If the rebuild was not successful, the status file contains error messages explaining why the rebuild failed.