Library > Products > Pervasive PSQL > Pervasive PSQL v9 SP2 (9.5) > Advanced Operations Guide > Converting Data Files > Rebuild Utility Tasks

PreviousAdvanced Operations Guide (v9 SP2 (9.5) revision 1) Next

Rebuild Utility Tasks

Chapter contents

The following Rebuild tasks are available:

GUI Tasks

To start the GUI Rebuild utility

There are two ways to start the GUI Rebuild utility:

To obtain help for the Rebuild utility

You can access this help file by clicking Help in any dialog box.

To select data and dictionary files for rebuilding

  1. After you click Next at the Rebuild welcome screen, the Select Files dialog box appears (Figure 14-4.)
    2. Figure 14-4 Select Files Dialog Box



  2. 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. Click OK when you have finished adding files to rebuild.

    3. 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 and continue with Step 3.

To specify rebuild options

  1. Before you rebuild the file(s), you may want to specify settings. The Settings dialog box displays as illustrated in Figure 14-5.
    2. Figure 14-5 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 Rebuild Options Screen .

    When you are ready, see To start the rebuild process .

To start the rebuild process

  1. Click Next to begin the rebuild process, which converts all of the listed data and dictionary files.

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

    Figure 14-6 Start Rebuild Dialog Box



  2. Click Finish when you have finished converting files.
  3. To display the results, click View Log File The REBUILD.LOG file is displayed as illustrated in Figure 14-7.
    4. Figure 14-7 Rebuild Log Display



    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.

CLI Tasks

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

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. For a discussion of optimal page size for disk storage, 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.
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. On NetWare, the default file name is brebuild.log. The default location is the current working directory on Windows and Linux. On NetWare, the default location is SYS:\SYSTEM.
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 c:\pvsw\demodata\class.mkd
The following example rebuilds a file to the 9.5 format:

rbldcli -f95 c:\pvsw\demodata\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 sys:\mydir\*.* <end>
-c -p1024 dta:\dir\*.* <end>
-m0 -k0 sys:\ssql\*.* <end>

To run Rebuild on Linux

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

    2. 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 (Server edition).

  2. Change directory to /usr/local/psql/bin directory.
  3. Type one of the following commands at the prompt:
    4. 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 NetWare

  1. Run RCONSOLE from a workstation, or go to the server's console.
  2. Type one of the following commands at the prompt:
    3. LOAD BREBUILD [-parameter ...] file 
or 
LOAD BREBUILD @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. 

LOAD BREBUILD -c -p4096 -bsys:\newfiles 
sys:\oldfiles\*.mkd

To run the Rebuild on Windows

  1. Open a command prompt on the machine where Pervasive PSQL is installed.
  2. Optionally, change directory to PVSW\BIN. (This is not required if PVSW\BIN is in the Path system variable.)
  3. Type one of the following commands at the prompt:
    4. 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 an ASCII log file. See Log File .

Chapter contents
Book contents

Prev topic: Rebuild Utility GUI Reference
Next topic: Description Files