| Previous | Contents | Index |
You must define at least one main key, called the primary key, for an indexed file. You may also optionally define from 1 to 254 additional keys called alternate keys. Each alternate key represents an additional data item in each record of the file. You can also use the key value in any of these alternate keys as a means of identifying the record for retrieval.
You define primary and alternate key values in the Record Description entry. Primary and alternate key values need not be unique if you specify the WITH DUPLICATES phrase in the file description entry (FD). When duplicate key values are present, you can retrieve the first record written in the logical sort order of the records with the same key value and any subsequent records using the READ NEXT phrase. The logical sort order controls the order of sequential processing of the record. (For more information about retrieving records with duplicate key values, see the information about the READ statement in the Compaq COBOL Reference Manual.)
When you open a file, you must specify the same number and type of keys that were specified when the file was created. (This situation is subject to modification by the check duplicate keys and relax key checking options, as well as a duplicate key specification on an FD.) If the number or type of keys does not match, the system will issue a run-time diagnostic when you try to open the file.
As your program writes records into an indexed file, the I/O system locates the values contained in the primary and alternate keys. The I/O system builds these values into a tree-structured table or index, which consists of a series of entries. Each entry contains a key value copied from a record. With each key value is a pointer to the location in the file of the record from which the value was copied.
Figure 6-5 shows the general structure of an indexed file defined with a primary key only.
Figure 6-5 Indexed File Organization
For a more detailed explanation of indexed file structure on OpenVMS Alpha systems, see the Guide to OpenVMS File Applications. <>
For information about specifying file organization in your program, see
Section 6.2.2.
6.1.2 Record Format
Compaq COBOL provides four record format types: fixed, variable, print-control, and stream. Table 6-2 shows the record format availability.
| Sequential | Line Sequential |
Relative |
Indexed |
||
|---|---|---|---|---|---|
| Disk | Tape | ||||
| Fixed length | yes | yes | no | yes | yes |
| Variable length | yes | yes | no | yes | yes |
| Print control | yes | no | no | no | no |
| Stream | no | no | yes | no | no |
The compiler determines the record format from the information that you specify as follows:
If a file has more than one record description, the different record descriptions automatically share the same record area in memory. The I/O system does not clear this area before it executes the READ statement. Therefore, if the record read by the latest READ statement does not fill the entire record area, the area not overlaid by the incoming record remains unchanged.
The record format type that was specified when the file was created must be used for all subsequent accesses to the file.
In Example 6-1, a file contains a company's stock inventory information (part number, supplier, quantity, price). Within this file, the information is divided into records. All information for a single piece of stock constitutes a single record.
| Example 6-1 Sample Record Description |
|---|
01 PART-RECORD.
02 PART-NUMBER PIC 9999.
02 PART-SUPPLIER PIC X(20).
02 PART-QUANTITY PIC 99999.
02 PART-PRICE PIC S9(5)V99.
|
Each record in the stock file is itself divided into discrete pieces of information referred to as elementary items (02 level items). You give each elementary item a specific location in the record, give it a name, and define its size and type. The part number is an elementary item in the part record, as are supplier, quantity, and price. In this example PART-RECORD contains four elementary items: PART-NUMBER, PART-SUPPLIER, PART-QUANTITY, and PART-PRICE.
Files with a fixed-length record format contain the same size records. The compiler generates the fixed-length format when either of the following conditions is true:
The compiler does not generate fixed-length format when any of the following conditions exist:
Fixed-length record size is determined by either the largest record description or the record size specified by the RECORD CONTAINS clause, whichever is larger. Example 6-2 shows how fixed-length record size is determined.
| Example 6-2 Determining Fixed-Length Record Size |
|---|
FD FIXED-FILE
RECORD CONTAINS 100 CHARACTERS.
01 FIXED-REC PIC X(75).
|
For the file, FIXED-FILE, the RECORD CONTAINS clause specifies a record size larger than the record description; therefore, the record size is 100 characters.
In Example 6-2, the following warning message is generated when the file FIXED-FILE is used:
"Record contains value is greater than length of longest record." |
If the multiple record descriptions are associated with the file, the size of the largest record description is used as the size. In Example 6-3, for the file REC-FILE, the FIXED-REC2 record specifies the largest record size; therefore, the record size is 90 characters.
| Example 6-3 Determining Fixed-Length Record Size for Files with Multiple Record Descriptions |
|---|
FD REC-FILE
RECORD CONTAINS 80 CHARACTERS.
01 FIXED-REC1 PIC X(75).
01 FIXED-REC2 PIC X(90).
|
When the file REC-FILE is used, the following warning message is generated:
"Longest record is longer than RECORD CONTAINS value - longest record size used." |
Files with a variable-length record format can contain records of different length. The compiler generates the variable-length attribute for a file when the file description contains a RECORD VARYING clause or a RECORD CONTAINS TO clause.
Each record is written to the file with a 32-bit integer that specifies the size of the record. This integer is not counted in the size of the record.
Examples 6-4, 6-5, and 6-6 show you the three ways you can create a variable-length record file.
In Example 6-4, the DEPENDING ON phrase sets the OUT-REC record length. The IN-TYPE data field determines the OUT-LENGTH field's contents.
| Example 6-4 Creating Variable-Length Records with the DEPENDING ON Phrase |
|---|
FILE SECTION.
FD INFILE.
01 IN-REC.
03 IN-TYPE PIC X.
03 REST-OF-REC PIC X(499).
FD OUTFILE
RECORD VARYING FROM 200 TO 500 CHARACTERS
DEPENDING ON OUT-LENGTH.
01 OUT-REC PIC X(500).
WORKING-STORAGE SECTION.
01 OUT-LENGTH PIC 999 COMP VALUE ZEROES.
|
Example 6-5 shows how to create variable-length records using the RECORD VARYING phrase.
| Example 6-5 Creating Variable-Length Records with the RECORD VARYING Phrase |
|---|
FILE SECTION.
FD OUTFILE
RECORD VARYING FROM 200 TO 500 CHARACTERS.
01 OUT-REC-1 PIC X(200).
01 OUT-REC-2 PIC X(500).
|
Example 6-6 creates variable-length records by using the OCCURS clause with the DEPENDING ON phrase in the record description. Compaq COBOL determines record length by adding the sum of the variable record's fixed portion to the size of the table described by the number of table occurrences at execution time.
In this example, the variable record's fixed portion size is 113 characters. (This is the sum of P-PART-NUM, P-PART-INFO, and P-BIN-INDEX.) If P-BIN-INDEX contains a 7 at execution time, P-BIN-NUMBER will be 35 characters long. Therefore, PARTS-REC's length will be 148 characters; the fixed portion's length is 113 characters, and the table entry's length at execution time is 35 characters.
| Example 6-6 Creating Variable-Length Records and Using the OCCURS Clause with the DEPENDING ON Phrase |
|---|
.
.
.
FILE SECTION.
FD PARTS-MASTER
RECORD VARYING 118 TO 163 CHARACTERS.
01 PARTS-REC.
03 P-PART-NUM PIC X(10).
03 P-PART-INFO PIC X(100).
03 P-BIN-INDEX PIC 999.
03 P-BIN-NUMBER PIC X(5)
OCCURS 1 TO 10 TIMES DEPENDING ON P-BIN-INDEX.
.
.
.
|
If you describe a record with both the RECORD VARYING...DEPENDING ON phrase on data-name-1 and the OCCURS clause with the DEPENDING ON phrase on data-name-2, Compaq COBOL specifies record length as the value of data-name-1.
If you have multiple record-length descriptions for a file and omit either the RECORD VARYING clause or the RECORD CONTAINS TO clause, all records written to the file will have a fixed length equal to the length of the longest record described for the file, as in Example 6-7.
| Example 6-7 Defining Fixed-Length Records with Multiple Record Descriptions |
|---|
.
.
.
FD PARTS-MASTER.
01 PARTS-REC-1 PIC X(200).
01 PARTS-REC-2 PIC X(300).
01 PARTS-REC-3 PIC X(400).
01 PARTS-REC-4 PIC X(500).
.
.
.
PROCEDURE DIVISION.
.
.
.
100-WRITE-REC-1.
MOVE IN-REC TO PARTS-REC-1.
WRITE PARTS-REC-1.
GO TO ...
200-WRITE-REC-2.
MOVE IN-REC TO PARTS-REC-2.
WRITE PARTS-REC-2.
GO TO ...
.
.
.
|
Writing PARTS-REC-1, PARTS-REC-2, PARTS-REC-3 or PARTS-REC-4 produces records equal in length to the longest record, PARTS-REC-4. Note that this is not variable-length I/O.
On OpenVMS, Compaq COBOL places explicit form-control bytes directly into the file. A Compaq COBOL program trying to read a print-control file can read it successfully as a variable file (since the I/O system strips the VFC header). <>
Print-control files contain record-advancing information with each record. These files are intended for eventual printing, but are created on disk by your Compaq COBOL program. The compiler generates print-control records when you use the WRITE AFTER ADVANCING, the LINAGE, or the APPLY PRINT-CONTROL clause, or if you create a Report Writer file or use ASSIGN TO PRINTER (on Tru64 UNIX and Windows NT systems).
On OpenVMS, in any of the preceding cases, if you compile /NOVFC, the compiler does not generate print-control records, but generates stream files instead. <>
On OpenVMS Alpha systems, you must use the /NOFEED option on the DCL PRINT command to print a print-control file. <>
Stream files contain records of different length, delimited by a record terminator.
The compiler generates a stream record formatted file when you use the ORGANIZATION IS LINE SEQUENTIAL clause in the File-Control Division. This record format is useful for files created by text editors.
On OpenVMS, a stream file will also be generated under certain
situations if you compiled /NOVFC. See the section in this book that
describes print-control records for more information.
6.1.3 File Design
The difficulty of design is proportional to the complexity of the file organization. Before you create your sequential, relative, or indexed file applications, you should design your files based on these design considerations:
On OpenVMS, for more information about file design, see Chapter 15.
For OpenVMS Alpha systems you can also refer to the Guide to OpenVMS File Applications.
<> Chapter 15 contains instructions on optimizing the file
design for indexed files. With indexed files, in particular, if you
accept all the file defaults instead of carefully designing your file,
your application may run more slowly than you expect.
6.2 Identifying Files and Records from Within Your Compaq COBOL Program
Before your program can perform I/O on a file, your program must identify the file to the operating system and specify the file's organization and access modes. A program must follow these steps whenever creating a new file or processing an existing file.
You use a file description entry to define a file's logical structure and associate the file with a file name that is unique within the program. The program uses this file name in the following COBOL statements:
The program uses the record name for the WRITE and REWRITE statements.
6.2.1 Defining a File Connector
You must establish a link between the file connector your program uses and the file specification that the I/O system uses. You create this link and define a file connector by using the SELECT statement with the ASSIGN clause and optionally specifying the VALUE OF ID clause or by using logical names or environment variables.
A file connector is a Compaq COBOL data structure that contains information about a file. The file connector links a file name and its associated record area to a physical file.
Defining a File Connector with SELECT and ASSIGN
Your program must include a SELECT statement, including an ASSIGN clause, for every file description entry (FD) it contains. The file name you specify in the SELECT statement must match the file name in the file description entry.
In the ASSIGN clause, you specify a nonnumeric literal or data name that associates the file name with a file specification. This value must be a complete file specification.
Example 6-8 and Example 6-9 show the relationships between the SELECT statement, the ASSIGN clause, and the FD entry.
In Example 6-8, because the file name specified in the FD entry is DAT-FILE, all I/O statements in the program referring to that file or to its associated record must use the file name DAT-FILE or the record name DAT-RECORD. The I/O system uses the ASSIGN clause to interpret DAT-FILE as REPORT.DAT on OpenVMS Alpha systems, and REPORT on Tru64 UNIX and Windows NT systems. The default directory will be used on OpenVMS Alpha systems, and the current working directory will be used on Tru64 UNIX and Windows NT systems.
| Example 6-8 Defining a Disk File |
|---|
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT DAT-FILE
ASSIGN TO "REPORT".
.
.
.
DATA DIVISION.
FILE SECTION.
FD DAT-FILE.
01 DAT-RECORD PIC X(100).
.
.
.
|
On OpenVMS Alpha systems, if no file type is supplied, Compaq COBOL supplies the default file extension DAT. On Tru64 UNIX and Windows NT systems, the extensions dat and idx (and lck, on Windows NT systems) are appended, but only in the case of indexed files. |
The I/O statements in Example 6-9 refer to MYFILE-PRO, which the ASSIGN clause identifies to the operating system as MARCH.311. Additionally, the operating system looks for the file in the current directory on the magnetic tape mounted on MTA0: on an OpenVMS Alpha system.
| Example 6-9 Defining a Magnetic Tape File (OpenVMS) |
|---|
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT MYFILE-PRO
ASSIGN TO "MTA0:MARCH.311"
.
.
.
DATA DIVISION.
FILE SECTION.
FD MYFILE-PRO.
01 DAT-RECORD PIC X(100).
.
.
.
PROCEDURE DIVISION.
A000-BEGIN.
OPEN INPUT MYFILE-PRO.
.
.
.
READ MYFILE-PRO AT END DISPLAY "end".
.
.
.
CLOSE MYFILE-PRO. <>
|
Example 6-10 achieves the same result as Example 6-9, but on Tru64 UNIX. The I/O statements in Example 6-10 refer to MYFILE-PRO, which the ASSIGN clause identifies to the operating system as a magnetic tape file. The file is named in the Data Division VALUE OF ID clause as MARCH.311.
| Example 6-10 Defining a Magnetic Tape File (Tru64 UNIX) |
|---|
ENVIRONMENT DIVISION
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT MYFILE-PRO
ASSIGN TO REEL.
.
.
.
DATA DIVISION.
FILE SECTION.
FD MYFILE-PRO VALUE OF ID "MARCH.311".
01 DAT-RECORD PIC X(100).
.
.
.
PROCEDURE DIVISION.
A000-BEGIN.
OPEN INPUT MYFILE-PRO.
.
.
.
READ MYFILE-PRO AT END DISPLAY "end".
.
.
.
CLOSE MYFILE-PRO.
|
For each OPEN verb referring to a file assigned to magnetic tape, the user is prompted to assign the file to a magnetic tape device. These device names are in the form /dev/rmt0(a,l,m,h) ... /dev/rmt31(a,l,m,h) and correspond to special files on the system that refer to mass storage tape devices. For more information on tape devices see the mtio(7) Tru64 UNIX manual page.
As an alternative to prompting, each file assigned to a magnetic tape can have its associated tape device defined through a shell environment variable. The name of this environment variable is the concatenation of COBOL_TAPE_ and the base of the file name used in the COBOL program. The value of this environment variable is the name of the desired tape device. The environment variable needed in Example 6-10 to assign the MARCH.311 file to tape device /dev/rmt0a is:
% setenv COBOL_TAPE_MARCH /dev/rmt0a <> |
Establishing File Names with ASSIGN and VALUE OF ID
If the file specification is subject to change, you can use a partial file specification in the ASSIGN clause and complete it by using the optional VALUE OF ID clause of the FD entry. In the VALUE OF ID clause, you can specify a nonnumeric literal or an alphanumeric WORKING-STORAGE item to supplement the file specification.
VALUE OF ID can complete a file name specified in ASSIGN TO:
ASSIGN TO "filename" VALUE OF ID ".ext" |
In the above example, OPEN would create a file with the name "filename.ext".
VALUE OF ID can override a file name specified in ASSIGN TO:
ASSIGN TO "oldname" VALUE OF "newname" |
VALUE OF ID can be a directory/device specification and ASSIGN TO can provide the file name, as in the following example:
ASSIGN TO "filename.dat"
VALUE OF ID "/usr/"
or
ASSIGN TO "filename"
VALUE OF ID "DISK:[DIRECTORY]"
|
On OpenVMS, with this code OPEN would create a file with the name DISK:[DIRECTORY]FILENAME.DAT. <>
On Tru64 UNIX, with this code OPEN would create a file with the name "/usr/filename.dat". <>
Establishing Device and File Independence with Logical Names
On OpenVMS, logical names let you write programs that are device and file independent and provide a brief way to refer to frequently used files.
You can assign logical names with the ASSIGN command. When you assign a logical name, the logical name and its equivalence name (the name of the actual file or device) are placed in one of three logical name tables; the choice depends on whether they are assigned for the current process, on the group level, or on a systemwide basis. See the OpenVMS DCL Dictionary for more information on DCL and a description of logical name tables.
| Previous | Next | Contents | Index |