Chapter 10: Rebuild


Rebuild is a file management utility invoked from the command prompt which enables you to:

The operation performed on a file by Rebuild depends on the options specified on the Rebuild command line.


Command Line

The 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.

Option Files

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

If you use a file to supply Rebuild command line options, the file must be an ASCII text file.

Within the Rebuild options file:

In the following example:

rebuild infile.dat, outfile.dat @conv.par

conv.par is an ASCII text file containing Rebuild options.

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.

Warning: When you are redirecting output, do not use the -v option.

Rebuild Options

The processing performed by Rebuild is defined by the option(s) specified on the command line.

The following options are available:

-c Specifies file compression
-d Reconstructs an index from the data area of an indexed file
-e Reports illegal duplicate keys and continues processing
-f Validates indexed files
-i Displays information about the files being processed
-k Defines the key structure for an indexed file
-m Reserved for future use
-n Displays information about a file (no other processing is performed)
-o Specifies the organization of the input and output files
-p Rebuilds IDXFORMAT "8" file in place
-q Reserved for future use
-r Defines the record structure of the input and output files
-s Specifies the format of the input file
-t Specifies the format of the output file
-u Attempts to recover a file for which the last update operation was not completed
-v Displays a record count which is incremented as the file is processed
-y Forces Rebuild to ignore file size discrepancies
-x Specifies the order in which data is written when reorganizing an indexed file
-z Instructs Rebuild to use a Fileshare server for file access
--q Suppresses display of the Rebuild banner
--v Displays the version number of Rebuild

Options can be placed in any order on the command line, except that options beginning with a double hyphen (--) must be placed before options beginning with a single hyphen (-). Options are free-format; spaces are required between options.

A colon (:) is required before parameters of the -f or -v options. For other options, a colon before parameters is optional. Do not insert spaces between the parameters of options.

For detailed information on the options, see the topic Overview of Rebuild command line options

Reorganizing Indexed Files

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

rebuild in-file,out-file [-c]  [-d] [-i]
    [-k] [-n] [-p] [-s] [-v] [-x] 

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 reorganize 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.

A third reason is to rebuild a duplicate key chain. A duplicate key has a duplicate occurrence value appended to it to make it unique. When a new duplicate key is added, the occurrence value of the last added key is incremented by one and used for the newly added key. If keys are deleted, no change is made to the occurrence values of the remaining keys. Therefore, you can reach the maximum number of duplicate values, even if some of those keys have already been deleted. In these circumstances it is a good idea to reorganize the file. For more information on duplicate keys, see the section Duplicate Keys in the chapter File Organizations.

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.

Rebuilding a Corrupt Indexed File

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

rebuild in-file[,out-file] [-c] [-d] [-e]
    [-i] [-k] [-n] [-p] [-s] [-v]

The out-file parameter is optional, but recommended, because if you do not specify it, and the Rebuild operation fails, you will lose your original file.

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 file can grow in size. One reason is that information held in the original index about free space in the data file is lost, which means that the free space cannot be reused. Another reason is that if you specify the -d option, index records are created individually as with normal I/O operations, leading to index nodes that are only partially filled. 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 creates a new index file, by reading the data file, infile.dat:

rebuild infile.dat

In the following example Rebuild reads the input file to get the key information, and creates a new indexed file, by working through the data in physical order, skipping over duplicate records:

rebuild infile.dat, outfile.dat -d -e

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

Converting a File

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

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

Rebuild enables you to convert files from one file organization and format to another.

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

Validating an Indexed File

The format of the command line for validating an indexed file is:

rebuild in-file -f 

Rebuild can perform a number of validation checks and you can request all of them, or just a subset of them. Of course, the more checks you request, the longer the validation process takes.

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

rebuild test.dat -f

Rebuild through Fileshare

You can use Rebuild on files that reside on Fileshare servers, but only with a limited range of Rebuild options. The format of the command line for using Rebuild through Fileshare is:

rebuild in-file[,out-file] -z:server-name {/l|/n}


server-name The name of a Fileshare server. All occurrences of server-name must refer to the same Fileshare server.

You can also specify a Fileshare server without using the -z Rebuild option. The format of the command line for this is:

rebuild $$server-name/in-file [$$server-name/out-file] {/l|/n}

Callable Rebuild

You can call Rebuild from 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.

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.
4File is corrupt.
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 options. 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 options 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

Rebuild Messages

Rebuild may output error, information or warning messages when rebuilding, converting or reorganizing an indexed file. For more information see the topic Error Messages

Rebuild Examples

The section provides examples of using Rebuild.

rebuild infile.dat,outfile.dat -i

Reorganizes the file. The data is written in the order of the prime record key, and processing information displayed when the reorganization is complete.

rebuild infile.dat,outfile.dat -x:3 

Reorganizes the file. The data is written in the order of the third alternate key.

rebuild infile.dat

Rebuilds the indexed file (assuming that the index (.idx) file is still present, and the key information held therein is not corrupt).

rebuild infile.dat -k:1+20 -i 

Rebuilds the indexed file. The index (.idx) file does not need to exist, and is ignored if it does. It will be completely recreated using the key definition specified (which need not correspond to the key definition used when the file was created). Processing information will be displayed when the rebuild is complete.

With C-ISAM and Level 2 files that do not have index files, use the -r and -s options to specify the record information and file format.

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

Converts a C-ISAM format index file into the format used by this system and compresses the data part of the file.

rebuild infile.dat,outfile.dat --o:rel,ind -k:1+2:3+10d -c:i7 -r:f10 

Generates an index, with key compression, for a fixed-length relative file.

rebuild infile.dat,outfile.dat -s:lii -t:lii 

Reorganizes a LEVEL II V2.5 COBOL format file and retains the LII structure on the output file. It is possible to combine -s and -t with other formats in a similar manner.

set data=/tmp.dat rebuild data -i

Reorganizes and displays information about the file /tmp.dat.

Copyright © 2009 Micro Focus (IP) Ltd. All rights reserved.