|Microsoft COBOL V2.2 Source Compatibility||Introduction to Conversion Series 3|
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.
To invoke Rebuild, you enter:
rebuild in-file, out-file /s.. [options]
where the parameters are:
||The name of the file to be converted|
||The name of the file to contain the result. This must
be different from
||Defines the format of the input file and must be specified|
||Can be any of the following parameters:|
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.
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.
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.
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|
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".
|/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.|
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.
The command line:
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:
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
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.
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.
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
Note: The @ character is a special character on UNIX, and should
be escaped using the "\" character. Parameter files should
therefore be specified using
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
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.
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.
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:
/n(information only) option was specified.
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.
/noption 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.
/noption, or convert the Microsoft format file to the indexed file format used by this system and enter the command line again.
/koption is incorrect.
/ooption is incorrect.
i(indexed). See the section The /o Option earlier in this chapter for details.
/ooption is incorrect.
rare the letter i (when converting to an indexed file) or a '/' (when another option is specified).
/soption is incorrect.
/soption and the correct parameter. See the section The /s Option earlier in this chapter for details.
/koption to enable Rebuild to set up the keys for this file.
The following information messages are output when Rebuild is processing a file:
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.
/s:btrvwas not recognized as a Btrieve indexed file. The return code is set to 1.
/s:c-isamwas not recognized as a C-ISAM indexed file. The return code is set to 1.
/s:liiwas not recognized as a LEVEL II V2.5 COBOL indexed file. The return code is set to 1.
/s:mfwas not recognized as an
mfindexed file. The return code is set to 1.
/s:mf4was not recognized as an
mf4indexed file. The return code is set to 1.
/o:ris not recognized as a variable relative file. The return code is set to 1.
/o:swas 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.
/roption without specifying record lengths.
/roption. See the section The /r Option earlier in this chapter for details.
/roption do not match those in the file.
/roption and try the operation again.
The status xx is an ANSI'85 file status. If the first byte is a 9, 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.
The status xx is an ANSI'85 file status. If the first byte is a 9, the status yyy is a COBOL run time error number. The return code is set to 2.
rebuild olds001.dat,ms001.dat /s:ms1 /k:1+20 /i > rebuild.prt rebuild oldrt549.seq,rt549.seq /s:ms2 /o:s /r:v5-1000 /i >> rebuild.prt rebuild badms001.dat,ms001.dat @ms001.par >> rebuild.prt
causes the information for all three conversions to be placed in the text file, rebuild.prt, one after the other. You can view this later using a text editor or the "type" command.
If this occurs, use the /i option when converting the file to display the key structure in the file, compare this with the key structure defined in the program, and either change the program to match the file, or use Rebuild again on the converted file to rebuild the index, specifying the full key description required for the file using the /k option. (See your Programmer's Guide to File Handling for a description of this use of Rebuild.)
For example, the first pass:
***Error on input file - record size > specified - records read = 0001
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:
***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:
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.
|Microsoft COBOL V2.2 Source Compatibility||Introduction to Conversion Series 3|