PreviousSorting Files File Conversion UtilitiesNext

Chapter 10: Rebuild

10.1 Overview

Rebuild is a file management utility invoked from the NetExpress Command Prompt which enables you to:

The operation performed on a file by Rebuild depends on the option(s) specified on the Rebuild command line.


Caution:


10.2 Command Line

The general format of the Rebuild command line is:

rebuild in-file [,out-file] [options]

Both in-file and out-file must include the filename extension. The filename of out-file must not be the same as in-file. You can use environment variables in place of in-file or out-file to implement filename mapping.

The options specified on the command line define the operation to be carried out by Rebuild.

10.2.1 Parameter Files

On the Rebuild command line an at character (@) followed by a filename indicates that the named file contains Rebuild command line parameters.

If you use a file to supply Rebuild command line parameters, the file must be an ASCII text file (you can use Notepad to create or edit such a file).

The Rebuild parameter file must be no larger than 1024 bytes.

Within the Rebuild parameter file, spaces are non-significant, line ends are treated as spaces and any text between an asterisk (*) and the line end is treated as a comment.

In the following example:

rebuild badms001.dat, ms001.dat @ms001.par

ms001.par is an ASCII text file containing Rebuild parameters.

10.2.2 Redirection of Information

All information displayed by the Rebuild utility can be redirected to a text file using standard operating system redirection:

> Creates a new file.
>> Extends an existing file

For example:

rebuild oldms001.dat,ms001.dat /k:1+20<N>/i >> rebuild.prt

redirects the output from Rebuild to the existing file rebuild.prt.


Note: You must not use the /v option when you are redirecting output.


10.2.3 System Parameters

The following system parameters can be specified on the command line:

//q prevents banners being displayed.
//v displays the version number of the Rebuild program itself.

10.3 Rebuild Options

The processing performed by Rebuild is defined by the option(s) specified on the command line. The following options are available:

Options can be placed in any order on the command line.

Options can be separated from their parameters by an optional colon (:).


Note: To ensure that Rebuild does not use default values which conflict with your file(s), you should always make the Rebuild command as explicit as possible.


Full details of the Rebuild options and how to specify them are given in the online help file. Look under Rebuild in the help file index.

10.4 Reorganizing Indexed Files

The format of the command line for reorganizing a file is:

rebuild in-file,out-file [/c] [/d {/k}] [/x] [/I] [/v]

As indexed files are updated by adding, deleting and altering records, the index and data structures become disjointed, making processing less efficient. In addition, space left by deleted records is not always reused, making the file bigger than it needs to be.

After a large number of changes have been made, it is worth reorganizing an indexed file to rebuild the data and indices in an ordered sequential fashion and to reclaim any free space. This will ensure optimum performance and data integrity.

There are other reasons why you may want to rebuild a file. For example, if a file is processed sequentially, the access time to process the file increases over time, as the records start to become out of sequence due to updates. In this situation, you can reduce access time by reorganizing the file.

For example:

rebuild infile.dat,outfile.dat

causes Rebuild to read the data file (infile.dat) using the index file (infile.idx) and then create the output file (outfile.dat). The deleted records in infile.dat are not written to the output file.


Note: You cannot use the same filename for the input file and the output file.


10.5 Rebuilding a Corrupt Indexed File

The format of the command line for rebuilding an index is:

rebuild in-file [/c] [/k] [/I] [/v] [/e] [/f] [/q]

There are a number of reasons why an indexed file becomes corrupt, for example:

When a COBOL program attempts to open a corrupt indexed file, the run-time system detects that the file is corrupt and returns an extended file status code.

Rebuild can recover corrupt indexed files for you:


Note: When you use Rebuild to generate a new index file from an existing data file, the information held in the original index about free space in the data file is lost. This means that the free space in the data file cannot be reused and the file may be bigger than is necessary. To overcome this problem, you should reorganize the file after you have rebuilt the index.


In the following example Rebuild reads the .idx file to get the key information, and a new index file is created, by reading the data file, infile.dat, sequentially:

rebuild infile.dat

If the index file is not present, you must supply information about the key structure using the /k option.

10.5.1 Fix File Index

You can rebuild the index of a corrupt indexed file by selecting Data Tools and then Fix File Index from the NetExpress Tools menu.


Note: Fix File does not support IDXFORMAT 8 files. To build the index of a file of IDXFORMAT 8 format, use Rebuild from the command line.


The following is displayed:



Figure 10-1: Fix File Index

Enter (or select, using the Browse button), the name of the corrupt indexed file.

If the file header information is available, you can recreate the index file by pressing the Fix File Index button.

If the file header information is unavailable, a message is displayed. As Fix File cannot derive this information from the file header, you must select a file format and define the file keys. In order to do this, click on the Advanced Options button. The following is displayed:



Figure 10-2: Advanced Options

From this dialog you can specify the file format (this must be the same as in the original file, before it became corrupt). You can also specify that if a record with a duplicate key is encountered, Fix File reports the duplicate and continues to process the remaining records (the record with the duplicate key is not written). To specify the key information, click on the Define Keys button:



Figure 10-3: Key Information

(If the header was read sucessfully, all the key information for the file is displayed here.)

To create a key, click on Insert Key to add the first key. The tree structure is expanded and focus switches to the offset field. For each key you need to supply the Key Options, Key Compression and Key Component infomation.

The key length cannot be greater than 1016 bytes or the maximum record length. The key offset cannot be greater than the minimum record length or 63488 bytes, whichever is smaller.

If the key has more than one component (key components are shown as child items in the tree structure), you can insert another component using either the Insert Component Before or Insert Component After button. Note that a component must be selected for these buttons to be visible.

If the file has more than one key defined, you can insert another key using either the Insert Key Before or Insert Key After button. Note that a key must be selected for these buttons to be visible.

10.6 Converting a File

The format of the command line for converting a file is:

rebuild in-file,out-file [/s] [/o] [/r] [/t] [/k] [/c] [/I] [/v]

Rebuild enables you to convert LEVEL II V2.5 COBOL files to indexed files in the format used by this COBOL system.

Only indexed files in the format used by this system can be rebuilt by Rebuild. This means that you should use Rebuild to convert your files into this format so that they can be rebuilt in the event of corruption.

In the following example Rebuild converts a C-ISAM file into the format used by this system and compresses the data part of the file:

rebuild infile.dat,outfile.dat /s:c-isam /c:d1 /t:mf

10.7 Validating an Indexed File

The format of the command line for validating a file is:

rebuild in-file /f[c] [d]

You can use Rebuild to validate the structure of an indexed file.

A number of validation checks are performed by Rebuild and you can choose to perform all of them, or just a sub-set. Of course, the more checks you perform, the longer the validation process takes.

In the following example Rebuild performs a full integrity check on the file:

rebuild test.dat /f:c63d5

10.8 Callable Rebuild

You can call Rebuild from within your COBOL program as follows:

call "CALLRB" using commands status

where the parameters are:

commands A PIC X(600) item containing the Rebuild command line. This item must be 600 bytes in length because Rebuild scans the command line backwards from offset 599.
status A PIC XX COMP X item containing the returned file status. This item shows the result of the call to Rebuild.

When called from within a program, Rebuild does not display any of its usual messages unless the /v option is used, in which case a running total of the records that are being processed is displayed.

If an error occurs or the rebuild is unsuccessful, RETURN-CODE contains a non-zero value and status contains the returned file status. You should always check RETURN-CODE and status after a call to Rebuild.

The possible values of RETURN-CODE are shown below.

Value
Description
0 Rebuild executed successfully.
1 An error occurred on the input file such as file not found or invalid file format - check status-parameter.
2 An error occurred on the output file - check status-parameter.
9 The parameter list contained an error such as an invalid option or an invalid combination of options.

If an error occurs, execute Rebuild from the command line on the same file with a set of identical parameters. The screen output should give a more precise indication as to the cause of the error.


Note: If you are using the /f option (validate an indexed file), then any non-zero RETURN-CODE indicates that the file is corrupt. Again, execute Rebuild from the command line on the same file with a set of identical parameters to obtain more precise information.


The following example shows Rebuild being called from within a COBOL program.

        01 parameters   pic x(600).
        01 status       pic xx comp-x.
        .
        .
        .
        move "infile.dat,outfile.dat /s:lii /c:d1" to parameters
        call "CALLRB" using parameters,status
        end-call

10.9 Creating Your Own Rebuild

The Rebuild utility supplied with this COBOL system, rebuild.exe, is a large file because it contains modules for every job that it can do. However, these modules are also supplied separately so that you can create your own, customised, version of Rebuild. The lists below show which objects you must link in to create your own version of rebuild.exe or a program which calls Rebuild, and those which are optional.

10.9.1 Mandatory Objects

REBUILD Main rebuild module (for a customised rebuild.exe)

or

CALLRB Main callable rebuild module (for your own program).

and

RBLDMAIN Command line processing
RBLDSUB Processes files and calls file handlers
EXTERNL Rebuild uses external data item
mFFH Micro Focus File Handler
FHRSUB Essential for creating your own Rebuild

10.9.2 Optional Objects

MSCVSUB Needed to convert MS format files to Micro Focus
CDFH Needed when /d option is used
XFHNAME Needed if filename mapping is required
CBLDC001 Needed if data compression is used (DATACOMPRESS"1")
CBLDC003 Needed if data compression is used (DATACOMPRESS"3")
FHREDIR Needed to rebuild a file through fileshare.
FHRDRPWD Needed by FHREDIR
FHXSCOMP Needed by FHREDIR
IDXCHECK Needed to validate indexed files.

10.10 Error Messages

Rebuild may output error, information or warning messages when rebuilding, converting or reorganizing an indexed file.

A list of Rebuild error messages is given in the online help file. Look under "Rebuild" in the help file index.


Note: The Fix File Index tool displays file status codes rather than error messages.


10.11 Rebuild Examples

The online help file contains a number of Rebuild examples. Look under Rebuild in the help file index.


Copyright © 1998 Micro Focus Limited. All rights reserved.
This document and the proprietary marks and names used herein are protected by international law.
PreviousSorting Files File Conversion UtilitiesNext