| Sorting Files | File Handling Library Routines | |
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:
Failure to do this can lead to unpredictable results.
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.
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.
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.
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. |
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.
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.
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.
| 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. |
-c:d1i6 |
Specifies data compression routine 1, and index compression of leading characters and trailing spaces. |
-c:i1 |
Specifies key compression of duplicates only. |
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.
If the -d option is not set, Rebuild returns file status error 9/018 when it encounters a corrupted record.
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.
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.
| 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.)
|
||||||||||||||||||||||||||||
| 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.
|
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.
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.
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.
-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).
The -n option displays the same information about the file as the -I option, but without doing any other processing.
The -o option specifies the organization of a file that you are converting both from and to.
-o:s-o:r-o:i |
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.
If the -o option is omitted the organization of the file to be converted is assumed to be indexed.
-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.
-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.
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.
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.
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.
-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.
Specifies the format of the input file.
-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.
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.
-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. |
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.
Defines the key-of-reference. The key-of-reference defines the order in which data is written when an indexed file is reorganized.
| 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. |
If no -x option is specified, the primary key (key 0) is assumed.
-x:2
Data is written in the order specified by the second alternate key for the file.
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.
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.
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
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
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
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.
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.
-c:[dn][dn]-c:[dn][in] -c[in][in].-c:[dn][in].-n option for a Microsoft format
file which you cannot do unless the Microsoft format file has been
converted into the indexed file format used by this system.-n
option, or convert the Microsoft format file to the indexed file format
used by this system and then re-enter the command.d or i parameters. -k option is incorrect.-o option is incorrect.-o
option are:
s
Sequential
r
Relative
i
Indexed
-o option is incorrect.i, s
or r are the letter i (when converting to an indexed file)
or a hyphen (-) (when another option is specified).-r:Vminreclen-maxreclenf (fixed) or
v (variable).-s option is incorrect.-t option.-s:c-isam was not recognized as a
C-ISAM indexed file. The return code is set to 1.-s:lii was not recognized as a
LEVEL II V2.5 COBOL indexed file. The return code is set to 1.-s:mf was not recognized as an
mf indexed file. The return code is set to 1.mf indexed
file.-s:mf4 was not recognized as an
mf4 indexed file. The return code is set to 1.mf4 indexed
file.-o:r is not recognized as a
variable relative file. The return code is set to 1.-o:s was not recognized as a
variable sequential file. The return code is set to 1.-x)
exceeds the number of keys for the given file. The return code is set to
1.-r option without specifying
record lengths.-r option. See the description of the -r option earlier in
this chapter for details.-r option do not
match those in the file.-r option and try the operation again.The status xx is an ANSI'85 file status. If the first byte is a 9, then the status yyy is a COBOL run-time error number. The output file is closed, and should be usable, if not complete. The return code is set to 1.
-r option.The status xx is an ANSI'85 file status. If the first byte is a 9, then the status yyy is a COBOL run-time error number. The return code is set to 2.
The following information messages are output when Rebuild is processing a file.
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.
-n (information only) option was specified. 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.
| Sorting Files | File Handling Library Routines | |