Rebuild Utility Tasks

Chapter contents

The following Rebuild tasks are available:

GUI Rebuild: GUI Tasks

Command-line Rebuild: CLI Tasks

GUI Tasks

To start the GUI Rebuild utility

To obtain help for the Rebuild utility

To rebuild a file or files

To start the GUI Rebuild utility

Click Tools then Rebuild from the Pervasive PSQL Control Center menu or start the utility from the Pervasive group on the Start menu.

To obtain help for the Rebuild utility

You can access the documentation by clicking Help on the graphical user interface.

To rebuild a file or files

After you click Next at the Rebuild welcome screen, the Select Files screen appears.

Click Add and select the data or dictionary file you want to rebuild. You can select more than one file to rebuild at a time.

Figure 14-4 Select Files 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.

Click Next after you have added the desired file or files.

Specify the rebuild options. See Rebuild Options Screen .

Click Next to begin the rebuild process.

The utility reports the processing information. When the rebuild process completes, the success or failure of it displays and View Log File is enabled.

Figure 14-5 Rebuild Process

To display the results, click View Log File. The contents of the log file display in the default text editor for the operating system.

The Rebuild utility writes to the log file for every file it attempts to convert. If you disabled the Continue on Error setting, the log 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.

Click Finish when you have finished rebuilding files and viewing the log file.

CLI Tasks

The Rebuild command-line utility is named rbldcli.exe on Windows and rbldcli on Linux. The following command line Rebuild utility tasks are available.

To run Rebuild on Linux

To run Rebuild on Windows

To see your progress while rebuilding files

To learn about the command line parameters for the CLI Rebuild utility, see the following section.

Command Line Parameters

The parameter option specifies the parameter(s) used with the utility. You may use the parameters in any order. Precede each parameter with a hyphen (-). Do not place a space after the hyphen or after the single-letter parameter and the parameter value.

Note
On Linux platforms only, the parameters are case sensitive.

Parameter is defined as follows:


-c	Instructs Rebuild to continue with the next data or dictionary file if an error occurs. The utility notifies you of non-MicroKernel data files or errors with MicroKernel files, but continues rebuilding data files. The errors are written to the log file. See Log File . Tip: This parameter is particularly useful if you specify wildcard characters (.) for a mixed set of files. Mixed set means a combination of MicroKernel files and non-MicroKernel files. Rebuild reports an error for each non-MicroKernel file (or any errors on MicroKernel files), but continues processing.
-d	If you specify -d, Rebuild converts pre-6.0 supplemental indexes (which allow duplicates) to 6.x, 7.x, or 8.x indexes with linked-duplicatable keys. If you omit this parameter, Rebuild preserves the indexes as repeating-duplicatable keys. If you access your data files only through the transactional interface and your files have a relatively large number of duplicate keys, you can use the -d parameter to enhance the performance of the Get Next and Get Previous operations.
-m<0 \| 2>	The "m" parameter stands for "method." Rebuild selects a processing method whether you specify this parameter or not. If you omit this parameter, Rebuild does the following: uses -m2 as the default method if sufficient available memory exists uses an alternative method,-m0, if the amount of available memory is not sufficient. See Amount of Memory for how the amount of memory affects the method chosen.
0	Clones and copies the data or dictionary file without dropping and replacing indexes. This method is slower than the -m2 method. It is available in case you do not want to rebuild your indexes. A file built with the -m0 creates a file where each key page is about 55% to 65% full. The file is more optimized for writing and less for reading. If you can afford the extra rebuild time, which can be considerable depending on the situation, you might want to rebuild a file optimized for writing. See also Optimizing the Rebuild Process .
2	Clones the data or dictionary file, drops the indexes, copies the records into the new file, and rebuilds the indexes. This method is faster and creates smaller files than the -m0 method. The -m2 method may create a new file in which the records are in a different physical order than in the original file. A file built with the -m2 method has key pages that are 100% full. This allows the file to be optimized for reading.
-p<D \| P \| bytes>	Optimizes page size for disk storage or processing, or specifies a specific page size to use for the rebuilt file. If you omit this parameter, Rebuild uses the page size from the source file. If the source page size does not work for the current database engine, Rebuild changes the page size and displays an informative message explaining the change. (For example, older file formats, such as 5.x, supported a page size of 1024 with 24 keys. File format 8.x supports only 23 keys for a page size of 1024, so Rebuild would select a different page size if building an 8.x file.) The database engine may ignore the page size specified and automatically upgrade the page size. For example, for the 9.5 file format, the odd page sizes such as 1536 and 3072 are not supported. The database engine automatically upgrades to the next valid page size because the next valid page size is more efficient. For older file formats, the database engine may upgrade the page size based on other conditions. See also Index Page Size .
D	Optimizes page size for disk storage. See Choosing a Page Size in Pervasive PSQL Programmer's Guide, which is part of the Pervasive PSQL Software Developer's Kit (SDK).
P	Optimizes for processing (that is, for your application accessing its data). For -pP, Rebuild uses a default page size of 4096 bytes. See Optimizing the Rebuild Process
bytes	Specifies the page size (in bytes) for the new file. For file versions prior to 9.0, the valid values are 512, 1024, 1536, 2048, 2560, 3072, 3584, and 4096. For file version 9.0, the values are the same with the addition of 8192. For file version 9.5 or newer, the valid values are 1024, 2048, 4096, 8192, and 16384.
-bdirectoryname	Specifies an alternate location for the rebuilt file (which may also be a location on a different server). The default location is the directory where the data file is located. You must specify a location that already exists. Rebuild does not create a directory for you. The directory also must be on a machine that is running the Pervasive PSQL database engine. You may use either a fully qualified path or a relative path. Do not use wildcard characters in directoryname. On your local server, the MicroKernel Database Engine and the Message Router must be loaded. On a remote server, the MicroKernel Database Engine and communications components must be loaded. If you omit this parameter, the rebuilt file replaces the original data file. A copy of the original file is not retained. If you specify this parameter, the rebuilt file is placed in the specified location and the original file is retained. An exception to this is if the specified location already contains data files with the same names. Rebuild fails if the alternate location you specify contains files with the same names as the source files. For example, suppose you want to rebuild mydata.mkd, which is in a directory named folder1. You want to place the rebuilt file into a directory named folder2. If mydata.mkd also exists in folder2 (perhaps unknown to you), Rebuild fails and informs you to check the log file. Note: Ensure that you have create file permission for the location you specify (or for the location of the source file if you omit the parameter).
-knumber	Specifies the key number that Rebuild reads from the source file and uses to sort the rebuilt file. If you omit this parameter, Rebuild reads the source file in physical order and creates the rebuilt file in physical order. See also Optimizing the Rebuild Process .
-s[D \| K]	Retains in the rebuilt file the existing system data and key from the source file. If you omit this parameter, Rebuilt does not include the system data and key in the rebuilt file. See also System Data .
D	Rebuilds the file to include system data. The system data is not indexed. See also System Data .
K	Rebuilds the file to include system data and key. The system data is indexed. See also System Data .
-lfile	Specifies a file name, and optionally a path location, for the Rebuild log file. The default file name is rbldcli.log on Windows and Linux. The default location is the current working directory on Windows and Linux. The following conditions apply: The path location must already exist. Rebuild does not create the path location. If you specify a path location without a file name, Rebuild ignores this parameter and uses the default file name and location. If you specify a file name without a path location, Rebuild uses the default location. You must have read and write file permission for the location you specify. Rebuild uses the default location if it cannot create the log file because of file permission. See also Log File .
-f<6 \| 7 \| 8 \| 9>	Specifies a file format for the rebuilt data or dictionary file. File formats supported are versions 6.x, 7.x, 8.x, and 9.x. The following example rebuilds a file to the 9.0 format: rbldcli -f9 file_path\class.mkd The following example rebuilds a file to the 9.5 format: rbldcli -f95 file_path\class.mkd If you omit this parameter, Rebuild uses the value set for the MicroKernel's "Create File Version" configuration option. See Create File Version . Note1: If you specify a file format newer than the version supported by the current database engine, Rebuild uses the highest supported file format of that engine. Rebuild reports no error or message for this. Note2: Rebuild does not convert data types in indexes. If you rebuild a file to an older file format for use with an older database engine, ensure that the engine supports the data types used. You must manually adjust data types as required by your application and by the database engine. Example1. Your data file contains index fields that use the WZSTRING data type. If you rebuild the data file to a 6.x file format, the WZSTRING data type is not converted. You would be unable to use the data file with a Btrieve 6.15 engine. That engine does not support the WZSTRING data type. Example 2. Your data file contains true NULLs. You rebuild the data file to a 7.x file format. The true NULLs are not converted. You would be unable to use the data file with the Pervasive PSQL 7 engine. That engine does not support true NULLs.
-uiduname	Specifies the name of the user authorized to access a database with security enabled.
-pwdpword	Specifies the password for the user who is identified by uname. Pword must be supplied if uname is specified.
-dbdbname	Specifies the name of the database on which security is enabled.

File and @command_file are defined as follows:


file	Specifies the data and dictionary file(s) to convert. If the source file is not in the current working directory, include the location, either as a fully qualified path or as a relative path. You may use the asterisk () wildcard character in the file name to specify multiple files. Note*: If the original file contains an owner name, Rebuild applies the owner name and level to the rebuilt file.
@command_file	Specifies a command file for Rebuild to execute. You may include multiple entries in one command file. Each entry in the command file contains the command line parameters (if any) and the set of files to convert, followed by <end> or [end]. When specifying the files to convert, use full directory names. You may use the asterisk () wildcard character in the file names. The following is an example of a Rebuild command file: `-c d:\mydir\.* <end> -c -p1024 e:\dir\. <end> -m0 -k0 d:\ssql\. <end>`

To run Rebuild on Linux

Ensure that the account under which you are logged in has permission to run Pervasive PSQL utilities.

By default, you must be logged in as user psql to run utilities. User psql has no password and can be accessed only through the root account by using the su command. To use utilities from accounts other than psql, you must first make modifications to your .bash_profile. See Pervasive PSQL Account Management on Linux in Getting Started With Pervasive PSQL.

Change directory to /usr/local/psql/bin directory.

Type one of the following commands at the prompt:

rbldcli [-parameter ...] file 
or 
rbldcli @command_file

Parameter, file, and @command_file are defined in Command Line Parameters .

Example Usage

The following example continues on error, sets a page size of 4096 bytes, and places the rebuilt files in a different directory on the server.

rbldcli -c -p4096 -b/usr/local/psql/tmp /usr/local/
psql/data/DEMODATA/*.mkd

To run Rebuild on Windows

Open a command prompt on the machine where Pervasive PSQL is installed.

Optionally, change to the \bin directory where you installed the Program Files. (This is not required if the location is in the Path system variable.)

Type one of the following commands at the prompt:

rbldcli [-parameter ...] file 
or 
rbldcli @command_file

Parameter, file, and @command_file are defined in Command Line Parameters .

Example Usage

The following example continues on error, sets a page size of 4096 bytes, and places the rebuilt files in a different directory on the server.

rbldcli -c -p4096 -bc:\dbtemp c:\datafiles\*.mkd

To see your progress while rebuilding files

Rebuild reports on the screen the number of records processed per file, incrementing 50 records at a time. In addition, Rebuild writes information to a text log file. See Log File .