PreviousMicrosoft COBOL V2.2 Source Compatibility Introduction to Conversion Series 3Next"

Chapter 3: Rebuild

This chapter describes how you invoke Rebuild, and lists the error messages you may receive when running Rebuild.

The physical file formats used by this COBOL system for COBOL sequential, relative and indexed data files are incompatible with the formats used in Microsoft COBOL Version 1 and Version 2.2.

Rebuild, the file management utility, has a facility which converts files in Microsoft COBOL V1 and V2.2 formats for use with this COBOL. (You can find details of the other facilities offered by Rebuild in your Programmer's Guide to File Handling.)

We recommend that you make a backup copy of the file being converted before using Rebuild. Rebuild takes every precaution to prevent the source files being corrupted, but it can happen if the command line is incorrectly specified.

3.1 Invoking Rebuild

To invoke Rebuild, you enter:

rebuild in-file, out-file /s.. [options]

where the parameters are:

in-file The name of the file to be converted
out-file The name of the file to contain the result. This must be different from in-file
/s Defines the format of the input file and must be specified
options Can be any of the following parameters:
/o Defines the organization of the input file and output files
/r Defines the record lengths and recording mode of the input file and output files
/k Defines the key structure of the output file
/i Causes Rebuild to display information
/v Causes Rebuild to display a running record count.

You can place these parameters anywhere in the command. They are free-format with spaces allowed between fields. See your Programmer's Guide to File Handling for details of the options.

You can add further options to some of the parameters; these determine how the parametter is interpreted at run time. You can specify parameters in two ways on the command line:


Note: Parameters are shown with the / character for Windows, but you should use a hyphen (-) character on UNIX systems. So, for example, the /s option should be entered as the -s option on UNIX systems.


The following sections describe these options and which parameters you can specify with them.

3.1.1 The /s Option

The /s option is used for the conversion process to define the format of the input file. You must specify this option. The allowed parameters are ms1 and ms2, where:

The output file will always be in the format used by this system.

3.1.2 The /o Option

The /o option defines the organization of the file to be converted. If the option is omitted, indexed is assumed. The organization is identified by a single letter parameter, where:

The output file is always the same organization as the input file, but is in a format suitable for use with this COBOL system.

3.1.3 The /r Option

The /r option defines the record lengths and recording mode of the input and output files. When you specify this option you should also specify a parameter which defines the record structure of the output file, where:

In the case of variable length formats, if you specify the minimum and maximum lengths as the same value, a variable format file will be created with fixed length records.

To access files created using the v parameter, you should include the RECORDING MODE V clause in the File Description (FD) of the accessing program. RECORDING MODE F is the default. Alternatively, if you convert every file with a v parameter, you do not need to alter your source programs. Instead you must submit your programs to this COBOL system with the RECMODE"V" system directive set, which will make the default recording mode variable for every FD.

If the recording mode of a file does not match the one you specified (or the default) in the FD, an error status will be given when the file is opened.

You may omit the lengths for converting Microsoft COBOL files with fixed length records and Microsoft COBOL Version 1 relative files, but not Microsoft COBOL Version 2.2 relative files. When you omit the record length, it will be taken as the length of the first record in the file.

For relative files, the lengths you give must be exact. If not, the records are not correctly transferred, but no warning is given. For sequential and indexed files, if you give a fixed length which is smaller than the maximum record size of the input file, an error will occur. If the fixed length you give is larger than the maximum record size, or the input file has variable records, and the fixed length is the same as the maximum, all the records will be written at the length specified, padded with ASCII spaces.

Consider the following example settings of this /r option:

/r:f Indicates that the output file is a fixed format file, with all records the same length as the first record in the input file
/r:f235 Indicates that the output file is a fixed format file, with records of 235 characters in length
/r:v Indicates that the output file is a variable format file, with all records the same length as the first record in the input file
/r:v76-76 Indicates that the output file is a variable format file, with all records of 76 characters in length
/r:v23-678 Indicates that the output file is a variable format file, with all records between 23 and 678 characters in length

3.1.4 The /k Option

The /k option defines the key structure for an indexed file. You use this option to convert Microsoft COBOL Version 1 files whose key information file (.KEY) is missing. Microsoft COBOL Version 2.2 indexed files contain the key information in the data part of the file. Thus, this option is not needed even if .KEY is missing.

The parameters for this option define the keys. The definitions of two or more keys are separated by a colon ( : ). You can define each key as a number of parts (split key), each part being separated by a comma ( , ). You define the key part by a start character position and length, separated by a plus (+) or L.

For alternate keys (those other than the first defined), an additional parameter, the character d, should terminate the definition if they are defined as "WITH DUPLICATES".

For example:

/k:1+20 Defines a single key, starting at character position 1, length 20 characters
/k:5+5:20+1d:40+2,43+10 Defines three keys, the third being split, and the second allowing duplicates. The first key, the record key, starts at character position 5, length 5; the second key, an alternate key allowing duplicates, starts at 20, length 1; and the third key, a split alternate key, has two parts, the first starting at 40, length 2, the second at 43, length 10. The first character position in a record is position 1.

3.1.5 The /i Option

If you specify the /i option, Rebuild displays information about the input and output files, including record lengths, file type and, for indexed files, key structure.

It is not possible to obtain information about a file without actually invoking a conversion.

Examples

The command line:

rebuild oldfile,new/s:ms2/i

causes the following information for the conversion of the fixed length file oldfile to be displayed:

 Conversion successful - records read = 0055 
 Input file : OLDFILE 
     Record length - 41 
 Output file : NEW 
         Organization - Indexed 
         Recording mode - Fixed 
         Record length - 41 
         Keys description : 
             Start char Length 
         Key -0 
              1+          6 

and the command line:

rebuild oldfile,new/s:ms2/r:v40-100/i

causes the following information for the conversion of the variable length file oldfile to be displayed:

 Conversion successful - records read = 0055 
 Input file : OLDFILE 
     Largest record length  -        100 
     Smallest record length -         45 
     Average record length  -         75 
 Output file : NEW 
     Organization - Indexed 
     Recording mode - Variable 
     Maximum record length -    40 
     Minimum record length -   100 
     Keys description : 
         Start char   Length 
     Key -  0         1+         6 
     Key -  1 with duplicates 
                        10+          5
                        20+          3

3.1.6 The /v Option

If you specify the /v option, Rebuild displays a record count on the screen which it increments as it processes the file. This is useful if you wish to see how Rebuild is progressing. You must not use the /v option if you are redirecting the output. This option is intended for interactive use only.

3.1.7 Examples

rebuild oldms001.dat, ms001.dat /s:ms1 /o:i/r:f120 /k:1+20
rebuild oldms001.dat, ms001.dat /s:ms1 /k:1+20

These commands convert a Microsoft COBOL Version 1 indexed file, with fixed length records of 120 characters, and a single key of 20 characters starting at position 1, where the .KEY file is missing. If the .KEY file is present, the /k option is not needed.

rebuild oldms001.dat, ms001.dat /s:ms2 /o:i/r:f120
rebuild oldms001.dat, ms001.dat /s:ms2

These commands convert a Microsoft COBOL Version 2.2 indexed file, with fixed length records of 120 characters. The key information is extracted from the start of the data file. Thus, this conversion can take place even if the .KEY index file is missing or corrupt.

rebuild oldrt549.seq,rt549.seq /s:ms2 /o:s/r:v5-1000 /i

This command converts a Microsoft COBOL Version 2.2 sequential file, with variable length records of between 5 and 1000 characters.

3.2 Parameter Files

At any point on the Rebuild command line, you can specify an @ character followed by the name of a parameter file. This indicates that parameters are to be taken from the named file. The contents of the parameter file are treated as if they were part of the command line, replacing @file-name.


Note: The @ character is a special character on UNIX, and should be escaped using the "\" character. Parameter files should therefore be specified using \@filename.


The parameter file is an ASCII text file which can contain any of the options described in the section Invoking Rebuild earlier in this chapter.

You can specify the parameters in free format, with spaces being non-significant (line ends are treated as spaces). The file must not be bigger than 1024 bytes. You may include comments in the file by preceding them with an asterisk (*). Anything following the asterisk is treated as a comment, up to the end of the line.

The following is an example of how you can specify a parameter file on the Rebuild command line:

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

where:

ms001.par is an ASCII text file containing the following line:

/s:ms1 /o:i /r:v100-200 /k:1+20,25+5:40+12:60+3,85+10d 

or the following lines (which are equivalent to the line above):

 *          Works master file - conversion parameters

  /s:ms1                   * Microsoft v1 indexed file 
  /o:i 
  /r:v   100 - 200         * Variable length records 
  /k: 
           1 +  20   ,     * prime key - first part 
          25 +   5   :     *           - 2nd part

          40 +  12   :     * 1st alternate key 
          60 +   3   ,     * 2nd alternate key (with duplicates) 
                           *             - first part 
          85 +  10 d       *             - second part

If a parameter in a parameter file is in error, a suitable message is displayed on the command line.

3.3 System Parameters

You can specify special system parameters immediately following Rebuild on the command line. These system parameters are present for use during development, testing and support of Rebuild. Each parameter consists of two slashes followed by a letter followed by a space:


Note: The // characters used with these options should be replaced by hyphens on UNIX systems; for example, //q should be --q on UNIX.


3.4 Warning Messages

Depending on the operation you select, some command line options are unnecessary. In these cases, the incorrect usage is indicated, but the option is ignored and processing continues.

The option may be correct, but omission of other information sometimes causes Rebuild to select the wrong process. If this is the case, correct the command line and rerun. Below are the warning messages you may receive if you specify incorrect information on the command line:

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

3.4.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 is detected. The program sets the return code to a value other than zero to indicate the type of error that has occurred; 9 indicates that you have made an error when entering information on the command line; 2 indicates that an error has been detected on an output file; 1 indicates that an error has been detected on an input file. This code can be tested in a batch stream using the IF ERRORLEVEL command (see your Operating System documentation for further details of this command).

The most likely cause of an error is that you have specified parameters to Rebuild that do not correctly represent the input file. In most cases it is difficult for Rebuild to determine that such a mistake has been made, since most data files carry insufficient information to make them easy to identify. Consequently, the error presented by Rebuild may not obviously identify the cause.

3.4.2 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
MS2X specified for non-indexed file
Must have key definition (/k option) with MS2X
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

3.4.3 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
records processed -

3.4.4 Conversion Errors

Error on input file - attempt to read past eof

Note: This error is likely to occur if you try to convert a Microsoft COBOL Version 1 sequential or relative file with a /s:ms2 option.

The output file is closed, and should be useable, if not complete.


***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 BTRIEVE indexed file
Error on input file - file is not a C-ISAM indexed file
Error on input file - file is not a LII indexed file
***Error on input file - file is not a MF indexed file
***Error on input file - file is not a 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

3.5 Supplementary Information

       Input file : OLDFILE 
         Largest record length  -   293 
         Smallest record length -   253 
         Average record length  -   546
       Output file : NEW 
         Organization - Indexed 
         Recording mode - Fixed 
         Maximum record length  -   253 
         Minimum record length  -   253 
         Keys description : 
           Start char   Length 
         Key -     0 
                   1+         9

The second record was bigger than the first, so Rebuild failed after reading it. Rerun Rebuild adding a /r option using this largest record length, as follows:

rebuild oldfile,new/s:ms2/r:f293/i

This gives:

***Error on input file - record size > specified -
  records read = 0005 
       Input file : OLDFILE 
         Largest record length  -   353 
         Smallest record length -   253 
         Average record length  -   339
       Output file : NEW 
         Organization - Indexed 
         Recording mode - Fixed 
         Maximum record length -    293 
         Minimum record length -    293 
         Keys description : 
           Start char   Length 
         Key -     0 
                   1+         9 

The sixth record is bigger than the maximum given, so you need to repeat the procedure with the new largest record length, as follows:

rebuild oldfile,new/s:ms2/r:f353/i

This gives a successful conversion:

       Conversion successful - records read = 0049
       Input file : OLDFILE 
         Largest record length  -   353 
         Smallest record length -   119 
         Average record length  -   261
       Output file : NEW 
         Organization - Indexed 
         Recording mode - Fixed 
         Maximum record length -    353 
         Minimum record length -    353 
         Keys description : 
           Start char   Length 
         Key -     0 
                   1+         9 


Copyright © 1999 MERANT International Limited. All rights reserved.
This document and the proprietary marks and names used herein are protected by international law.

PreviousMicrosoft COBOL V2.2 Source Compatibility Introduction to Conversion Series 3Next"