PreviousSorting Files File Handling Library RoutinesNext

Chapter 9: Rebuild

9.1 Overview

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 option(s) specified on the Rebuild command line.


Caution:


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

9.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. To create or edit such a file, use vi.

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

Within the Rebuild parameter file:

In the following example:

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

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

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


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


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

9.3 Rebuild Command Line

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

On UNIX systems, Rebuild options must be preceded by a hyphen (-) character rather than a slash (/) character.

The following options are available:

-c Specifies file compression
-d Skips corrupt data records
-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
-n Displays information about a file (no other processing is performed)
-o Specifies the organization of the input and output files
-q Specifies a quick rebuild
-r Defines the record structure of the input file and output files
-s Specifies the format of the input file
-t Specifies the format of the output file
-v Displays a record count which is incremented as the file is processed
-x Specifies the order in which data is written when reorganizing an indexed file

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.


9.3.1 Rebuild Options

Various options are available with Rebuild; some of these are followed by parameters providing further information. The option letter can be separated from its parameters by an optional colon (:). Options can be placed anywhere within the command, and are free-format with spaces allowed between fields.


-c

Specifies file compression. Data compression can only be specified for an output file. Key compression can be specified for an output file or the rebuild of an existing file. The -c option operates in a similar manner to the Compiler directives DATACOMPRESS and KEYCOMPRESS.

The data in C-ISAM and Level 2 files cannot be compressed.

Parameters
dn Data compression

For data compression, n must be in the range 0 through 255 where 0 denotes no compression, values of 1 through 127 are reserved, and 128 through 255 are for user-defined compression routines.

in Key compression

For key compression, n must be in the range 0 through 7 where 1 denotes compression of duplicates, 2 denotes compression of leading characters, 4 denotes compression of trailing spaces and any combination of these can be specified by adding together the appropriate values. Zero denotes no key compression.

Examples
-c:d1i6 Specifies data compression routine 1, and index compression of leading characters and trailing spaces.
-c:i1 Specifies key compression of duplicates only.

-d

Specifies that Rebuild should continue from the beginning of the next record if it finds that the data part of a record in an indexed file is corrupt.

This option should not be used when reorganizing from IDXFORMAT "8" files.

Default

If the -d option is not set, Rebuild returns file status error 9/018 when it encounters a corrupted record.


-e

Specifies that, when rebuilding a corrupt file, or a file with a new key structure (-k option used), and a record with an illegal duplicate key is encountered, Rebuild reports the duplicate and continues to process the remaining records. (The record with the duplicate key is not written.)

If the -e option is not specified, illegal duplicate keys cause Rebuild to terminate with an "Error on output file - status 22" error.


-f

Validates an indexed file. A non-zero value is returned by Rebuild if the file is corrupt.


Caution: The key offset for this option starts at 1. Key offsets for other options start at 0.


When using this option with files that are not C-ISAM, IDXFORMAT "3" and IDXFORMAT "4" formats, the additional parameters are not required and will be ignored.

Parameters
c Specifies the validation performed. You can select any combination of these checks by adding the appropriate numbers together. (The more checks you perform, the longer the validation takes.)
1 Checks the data file structure and counts the number of records.
2 Checks the structure of the free space list (FSL).
4 Checks that the FSL entries actually exist in the data file.
8 Checks the index file structure.
16 Checks that index file key entries correctly locate data file records.
32 Checks that index file key values match those of the data file records.
63 All of above (default).
d Specifies the message level. These values are cumulative, so if you select level 4, you will receive messages at levels 1, 2 and 3 as well.
0 Displays nothing.
1 Displays error messages only.
2 Displays messages showing which options you have selected.
3 Displays information about the file including key definition, record lengths, data compression, and the version of the file handler which created and updated the file.
4 Displays the different types of record present in the file:
1 IDXFORMAT"4" information record.
2 Deleted record.
3 System record.
4 Data record.
5 Data record which has been reduced in size by a rewrite.
6 Data record which has been increased in size by a rewrite and therefore cannot fit into the original record area. Instead, this record points to another record area which contains the record.
7 Record pointed to by type 6 record.
8 Record which has been reduced in size pointed to by type 6 record.
5 Displays statistics about each key structure including information about how much space is being saved by key compression
Examples
rebuild test.dat -f:c9

Checks the structure of the data file (1) and the structure of the index file (8).

rebuild test.dat -f:c63d5

Performs full integrity check on a file, displaying all possible information.


-I

Displays information about the input and output files, including record lengths, file type and key structure. If you only want to see the information and do not want to perform any other operation, use the -n option instead.


-k

Defines the key structure for an indexed file.

The key structure is used to rebuild the index of an indexed file when the index part is missing or corrupt.

When converting non-indexed files to indexed files, this option is required to specify the key information for the new output file. It is also possible, using Rebuild with the -k option, to replace the key structure of an existing indexed file with an alternative structure.

Each key is defined by its starting character position within the record (the first character position in a record is 1) and its length in characters. The starting position and length must be separated by a plus sign (+) or the letter L.

The definition of one key is separated from the definition of the next key by a colon (:). Each key can be defined as a number of parts (split key), each part being separated by a comma (,).

Alternate keys (those other than the first defined) can be terminated by the parameter d, indicating WITH DUPLICATES.

Sparse keys can be specified by the parameter s, indicating sparse. The s parameter must be followed by the sparse character itself. If the sparse character is non-printable, or a lower or upper case 'h', the s parameter must be followed by hvalue, where value is the hexadecimal ASCII value of the sparse character.

Different key compression values can be specified for each key by using the c parameter, indicating compression. The c parameter must be followed by a key compression value between 0 and 7.

Examples
-k:1+20

This example defines a single key, starting at character position 1 and 20 characters in length.

-k:5+5:20+1d:40+2,43+10

This example defines three keys. The first key, the primary key, starts at character position 5 and is 5 characters in length; the second key, an alternate key allowing duplicates, starts at character position 20 and is 1 character in length; the third key, a split alternate key, has two parts, the first starting at character position 40 and 2 characters in length and the second starting at character position 43 and 10 characters in length.

-k:1+5:20+10dsZ

This example defines two keys. The first key, the primary key, starts at character position 1 and is 5 characters in length; the second key, an alternate, sparse key allowing duplicates, starts at character position 20 and is 10 characters in length, the sparse character is Z.

-k:1+5:20+10dsh0

This example defines two keys. The first key, the primary key, starts at character position 1 and is 5 characters in length. The second key, an alternate, sparse key allowing duplicates, starts at character position 20 and is 10 characters in length; the sparse character is the null character.

-k:1+10:11+20dc3

This example defines two keys. The first key, the primary, starts at character position 1 and is 10 characters in length. The second key, an alternate compressed key allowing duplicates, starts at character position 11 and is 20 characters in length. The types of key compression being used are compression of duplicates (1) and compression of leading characters (2).


-n

The -n option displays the same information about the file as the -I option, but without doing any other processing.


-o

The -o option specifies the organization of a file that you are converting both from and to.

Parameters: Format 1
-o:s
-o:r
-o:i
sequential
relative
indexed

By default, the output file has the same organization as the input file, but in a format suitable for this COBOL system. However, you can create indexed files from sequential and relative files by adding the letter i after the s or r. To create an index for such a file, you must specify the key structure with the -k option.

Default: Format 1

If the -o option is omitted the organization of the file to be converted is assumed to be indexed.

Example: Format 1
-o:ri -k:1+2:3+10d  

This example converts a relative file into an indexed file with the key structure specified by the -k option.

Parameters: Format 2
-o:infile-org,outfile-org

This format enables you to convert from any one file organization to another.

infile-org and outfile-org can be any of the following:

lseq line sequential
seq sequential
rel relative
ind indexed

Using this syntax you can convert a line sequential file to an indexed file, or a striped file to a variable sequential file, and so on.

Examples: Format 2
rebuild in-file, out-file -o:lseq,ind -t:mf -k:1+10 -r:v20-30

Converts a line sequential file to an indexed file with the key structure specified by the -k option, the file format specified with the -t option and the recording mode and record lengths specified with the -r option. The key information must be wholly contained within the minimum record length.

rebuild in-file, out-file -o:ind,seq -r:v20-30

Converts an indexed file to a variable length sequential file with the recording mode and record lengths specified by the -r option.


-q

Specifies a quick rebuild.

With this option the performance of Rebuild is improved. However, you cannot use the -v option with the -q option; if you do, Rebuild displays no messages until it has finished. You cannot use this option with IDXFORMAT"8" files.


-r

The -r option defines the record lengths and recording mode of a file. Usually, this information is obtained by Rebuild from the input file and transferred directly to the output file. When converting from files that do not contain any header information to another file format, this information is required so that Rebuild knows what record lengths it is dealing with.

Examples
-r:f record-length 

Specifies a fixed length record format with records of record-length, for example, -r:f100.

-r:v min-record-length max-record-length

Specifies a variable length format with the maximum and minimum record lengths separated by a hyphen; for example, -r:v100-200.


-s

Specifies the format of the input file.

Parameters
-s:c-isam
-s:lii
-s:mf
-s:mf4
-s:mf8
C-ISAM format.
LEVEL II V2.5 COBOL format.
Format used by this COBOL system.
IDXFORMAT"4" format.
IDXFORMAT"8" format.

Note: You do not need to specify -s:C-ISAM, as Rebuild automatically recognizes C-ISAM files.


By default the output file is in the same format as the input file but this option can be used in conjunction with the -t option to convert a C-ISAM or LEVEL II V2.5 COBOL to the indexed file format used by this COBOL system.


-t

Specifies the index format of the output file and can be used in conjunction with the -s option to convert from one file format to another while reorganizing the file at the same time.

Parameters
-t:c-isam
-t:lii
-t:mf
-t:mf4
-t:mf8
C-ISAM format.
LEVEL II V2.5 COBOL format.
Format used by this COBOL system.
IDXFORMAT"4" format.
IDXFORMAT"8" format.

-v

Causes Rebuild to display a record count which it increments as it processes the file. This is useful if you want to keep track of how Rebuild is progressing.


Warning: Do not use the -v option if you are redirecting the output.


-x

Defines the key-of-reference. The key-of-reference defines the order in which data is written when an indexed file is reorganized.

Parameters
n The number of the key to be used where the primary key is 0 and the alternate keys are numbered, starting at 1, in the order they are specified in the SELECT statement in the creating program.
Default

If no -x option is specified, the primary key (key 0) is assumed.

Example
-x:2 

Data is written in the order specified by the second alternate key for the file.


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


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

9.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. It also allows you to convert to and from any file organization.

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

9.7 Validating an Indexed File

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

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

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

With C-ISAM, IDXFORMAT "3" and IDXFORMAT "4" file formats, a number of validation checks are performed by Rebuild and you can choose to perform all of them, or just a subset of them. Of course, the more checks you perform, the longer the validation process takes. With other file formats the additional parameters are not required.

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

rebuild test.dat -f:c63d5

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

9.9 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 following sections.

9.9.1 Error Messages

When an error is encountered, the command line is displayed, followed by an error message. For command line errors, a caret (^) is displayed under the point in the command line where the error occurred.

9.9.1.1 Command Line Errors

***Invalid parameter combination
-k option is required for conversion to indexed file
Data compression out of range
Data compression specified more than once
Input file same as output file
Index compression out of range
Index compression specified more than once
Invalid command - -n not allowed with Microsoft format file
Invalid command - must specify output file for conversion
Invalid command line
Invalid compression choice - must be 'd' or 'i'
Invalid format
Invalid key length - cannot be zero
Invalid key specification - key not contained in record
Invalid key start - cannot be zero
Invalid key structure - '+' expected
Invalid option
Invalid organization
Invalid organization - 'i' or nothing expected
Invalid organization - must be indexed for index rebuild
Invalid organization - must be indexed for reorganization
Invalid record length - cannot be zero
Invalid record lengths - maximum must not be less than minimum
Invalid record parameter - '-' expected
Invalid record type - 'F' or 'V' expected
Invalid source format
No output file specified for -t to refer to
No output file specified for data compression
Number expected
Output file was not specified for indexed output
Parameter file not found

9.9.1.2 Rebuild Errors

***Error on input file - bad file structure
***Error on input file - Communications failure
***Error on input file - Disk input output error
***Error on input file - disk space exhausted
***Error on input file - duplicate key - record not written:
***Error on input file - file is not a C-ISAM indexed file
***Error on input file - file is not an LII indexed file
***Error on input file - file is not an MF indexed file
***Error on input file - file is not an MF4 indexed file
***Error on input file - file is not a variable relative file
***Error on input file - file is not a variable sequential file
***Error on input file - File locked
***Error on input file - file must be indexed for rebuild
***Error on input file - file must be indexed for reorganization
***Error on input file - file not found
***Error on input file - illegal filename specified
***Error on input file - invalid -x: key-of-reference
***Error on input file - no record size information
***Error on input file - not MF indexed or variable format
***Error on input file - record size > specified
***Error on input file - status xx ***Error on input file - status 9/yyy
***Error on output file - record length < min or > max
***Error on output file - status xx ***Error on output file - status 9/yyy

9.9.2 Information Messages

The following information messages are output when Rebuild is processing a file.

Converting file
Rebuild aborted
Rebuild successful
Rebuilding file
Rebuilding index
Records processed
Reorganization successful
Reorganizing file

9.9.3 Warning Messages

Depending on the operation selected, some command line options are unnecessary. In such cases, the unnecessary option is indicated but ignored and processing continues. Note that the option may be correct, but omission of other information may have caused Rebuild to select the wrong process. If this is the case, correct the command line and re-run.

** WARNING ** - Option ignored - -k option not needed for a reorganization
*** WARNING *** - Option ignored - -k option not needed with -n
*** WARNING *** - Option ignored - -r option not needed for a reorganization
*** WARNING *** - Option ignored - -x option not needed for index rebuild

9.10 Rebuild Examples

The section provides examples of using Rebuild.

rebuild badms001.dat,ms001.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 badms001.dat,ms001.dat -x:3 

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

rebuild ms001.dat 

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

rebuild ms001.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:ri -k:1+2:3+10d -c:i7 

Generates an index, with key compression, for a 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 © 2000 MERANT International Limited. All rights reserved.
This document and the proprietary marks and names used herein are protected by international law.

PreviousSorting Files File Handling Library RoutinesNext