[an error occurred while processing this directive]

HP OpenVMS Systems Documentation

HP COBOL
User Manual

Contents

Index

6.4 Reading Files

Reading sequential, line sequential, relative, and indexed files includes the following tasks:

Opening the file
Executing a READ or START statement

Sections 6.4.1, 6.4.2, and 6.4.3 describe the specific tasks involved in reading sequential, line sequential, relative, and indexed files.

6.4.1 Reading a Sequential or Line Sequential (Alpha, I64) File

Reading a sequential or (on Alpha and I64 only) line sequential file involves the following:

Opening the file for INPUT or I/O for sequential files, or INPUT for line sequential files (I/O is not permitted for line sequential files)
Executing a READ statement

Each READ statement reads a single logical record and makes its contents available to the program in the record area. There are two ways of reading records:

READ file-name INTO destination-area
READ file-name

Statements (1) and (2) in the following example are logically equivalent:

FILE SECTION.
FD  STOCK-FILE.
01  STOCK-RECORD     PIC X(80).
WORKING-STORAGE SECTION.
01  STOCK-WORK       PIC X(80).

-------------(1)---------------    -------------(2)---------------
READ STOCK-FILE INTO STOCK-WORK.   READ STOCK-FILE.
                                   MOVE STOCK-RECORD TO STOCK-WORK.

When you omit the INTO phrase, you process the records directly in the record area or buffer (for example, STOCK-RECORD). The record is also available in the record area if you use the INTO phrase.

In a READ INTO clause, if the destination area is shorter than the length of the record area being read, the record is truncated on the right and a warning is issued; if longer, the destination area is filled on the right with blanks.

If the data in the record being read is shorter than the length of the record (for example, a variable-length record), the contents of the record beyond that data are undefined.

Generally speaking, if the recordtype is fixed, the prolog and epilog are zero. The exceptions to this are: for relative files there is a 1 byte record status flag prolog; for sequential files there is a 1 byte epilog if the record length is odd.

Example 6-28 reads a sequential file and displays its contents on the terminal.

Example 6-28 Reading a Sequential File

IDENTIFICATION DIVISION.
PROGRAM-ID. SEQ02.
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
    SELECT TRANS-FILE ASSIGN TO "TRANS".
DATA DIVISION.
FILE SECTION.
FD  TRANS-FILE.
01  TRANSACTION-RECORD    PIC X(25).
PROCEDURE DIVISION.
A000-BEGIN.
    OPEN INPUT TRANS-FILE.
    PERFORM A100-READ-TRANS-FILE
       UNTIL TRANSACTION-RECORD = "END".
    CLOSE TRANS-FILE.
    STOP RUN.
A100-READ-TRANS-FILE.
    READ TRANS-FILE
       AT END MOVE "END" TO TRANSACTION-RECORD.
    IF TRANSACTION-RECORD NOT = "END"
       DISPLAY TRANSACTION-RECORD.

6.4.2 Reading a Relative File

Your program can read a relative file sequentially, randomly, or dynamically. The following three sections describe the specific tasks involved in reading a relative file sequentially, randomly, and dynamically.

Reading a Relative File Sequentially

Reading relative records sequentially involves the following:

Specifying ORGANIZATION IS RELATIVE in the Environment Division SELECT clause
Specifying ACCESS MODE IS SEQUENTIAL (or DYNAMIC) in the Environment Division SELECT clause (and using the READ NEXT phrase)
Opening the file for INPUT or I-O
Reading records as you would a sequential file, or using a START statement

The READ statement makes the next logical record of an open file available to the program. The system reads the file sequentially from either cell 1 or wherever you START the file, up to cell n. It skips the empty cells and retrieves only valid records. Each READ statement updates the contents of the file's RELATIVE KEY data item, if specified. The data item contains the relative number of the available record. When the at end condition occurs, execution of the READ statement is unsuccessful (see Chapter 7).

Sequential processing need not begin at the first record of a relative file. The START statement specifies the next record to be read and positions the file position indicator for subsequent I/O operations.

Example 6-29 reads a relative file sequentially, displaying every record on the terminal.

Example 6-29 Reading a Relative File Sequentially

IDENTIFICATION DIVISION.
PROGRAM-ID. REL04.
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
    SELECT FLAVORS ASSIGN TO "BRAND"
                   ORGANIZATION IS RELATIVE
                   ACCESS MODE IS SEQUENTIAL
                   RELATIVE KEY IS KETCHUP-MASTER-KEY.
DATA DIVISION.
FILE SECTION.
FD  FLAVORS.
01  KETCHUP-MASTER           PIC X(50).
WORKING-STORAGE SECTION.
01  KETCHUP-MASTER-KEY       PIC 99.
01  END-OF-FILE              PIC X.
PROCEDURE DIVISION.
A000-BEGIN.
    OPEN INPUT FLAVORS.
    PERFORM A010-DISPLAY-RECORDS UNTIL END-OF-FILE = "Y".
A005-EOJ.
    DISPLAY "END OF JOB".
    CLOSE FLAVORS.
    STOP RUN.
A010-DISPLAY-RECORDS.
    READ FLAVORS AT END MOVE "Y" TO END-OF-FILE.
    IF END-OF-FILE NOT = "Y" DISPLAY KETCHUP-MASTER.

Reading a Relative File Randomly

Reading relative records randomly involves the following:

Specifying ORGANIZATION IS RELATIVE in the Environment Division SELECT clause
Specifying ACCESS MODE IS RANDOM (or DYNAMIC) in the Environment Division SELECT clause
Opening the file for INPUT or I-O
Moving the relative record number value to the RELATIVE KEY data name
Reading the record from the cell identified by the relative record number

The READ statement selects a specific record from an open file and makes it available to the program. The value of the relative key identifies the specific record. The system reads the record identified by the RELATIVE KEY data name clause. If the cell does not contain a valid record, the invalid key condition occurs, and the READ operation fails (see Chapter 7).

Example 6-30 reads a relative file randomly, displaying every record on the terminal.

Example 6-30 Reading a Relative File Randomly

IDENTIFICATION DIVISION.
PROGRAM-ID. REL05.
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
    SELECT FLAVORS ASSIGN TO "BRAND"
                   ORGANIZATION IS RELATIVE
                   ACCESS MODE IS RANDOM
                   RELATIVE KEY IS KETCHUP-MASTER-KEY.
DATA DIVISION.
FILE SECTION.
FD  FLAVORS.
01  KETCHUP-MASTER           PIC X(50).

WORKING-STORAGE SECTION.
01  KETCHUP-MASTER-KEY       PIC 99 VALUE 99.
PROCEDURE DIVISION.
A000-BEGIN.
    OPEN INPUT FLAVORS.
    PERFORM A100-DISPLAY-RECORD UNTIL KETCHUP-MASTER-KEY = 00.
    DISPLAY "END OF JOB".
    CLOSE FLAVORS.
    STOP RUN.
A100-DISPLAY-RECORD.
    DISPLAY "TO DISPLAY A RECORD ENTER ITS RECORD NUMBER (0 to END)".
    ACCEPT KETCHUP-MASTER-KEY WITH CONVERSION.
    IF KETCHUP-MASTER-KEY > 00
       READ FLAVORS
        INVALID KEY DISPLAY "BAD KEY"
                        CLOSE FLAVORS
                        STOP RUN
       END-READ
       DISPLAY KETCHUP-MASTER.

Reading a Relative File Dynamically

The READ statement has two formats so that it can select the next logical record (sequential access) or select a specific record (random access) and make it available to the program. In dynamic mode, the program can switch from random access I/O statements to sequential access I/O statements in any order, without closing and reopening files. However, you must use the READ NEXT statement to sequentially read a relative file open in dynamic mode.

Sequential processing need not begin at the first record of a relative file. The START statement repositions the file position indicator for subsequent I/O operations.

A sequential read of a dynamic file is indicated by the NEXT phrase of the READ statement. A READ NEXT statement should follow the START statement since the READ NEXT statement reads the next record indicated by the current record pointer. Subsequent READ NEXT statements sequentially retrieve records until another START statement or random READ statement executes.

Example 6-31 processes a relative file containing 10 records. If the previous program examples in this chapter have been run, each record has a unique even number from 2 to 20 as its key. The program positions the record pointer (using the START statement) to the cell corresponding to the value in INPUT-RECORD-KEY. The program's READ...NEXT statement retrieves the remaining valid records in the file for display on the terminal.

Example 6-31 Reading a Relative File Dynamically

IDENTIFICATION DIVISION.
PROGRAM-ID. REL06.
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
    SELECT FLAVORS ASSIGN TO "BRAND"
                   ORGANIZATION IS RELATIVE
                   ACCESS MODE IS DYNAMIC
                   RELATIVE KEY IS KETCHUP-MASTER-KEY.
DATA DIVISION.
FILE SECTION.
FD  FLAVORS.
01  KETCHUP-MASTER           PIC X(50).
WORKING-STORAGE SECTION.
01  KETCHUP-MASTER-KEY       PIC 99.
01  END-OF-FILE              PIC X   VALUE "N".
PROCEDURE DIVISION.
A000-BEGIN.
    OPEN I-O FLAVORS.
    DISPLAY "Enter number".
    ACCEPT KETCHUP-MASTER-KEY.
    START FLAVORS KEY = KETCHUP-MASTER-KEY
          INVALID KEY DISPLAY "Bad START statement"
          GO TO A005-END-OF-JOB.
    PERFORM A010-DISPLAY-RECORDS UNTIL END-OF-FILE = "Y".
A005-END-OF-JOB.
    DISPLAY "END OF JOB".
    CLOSE FLAVORS.
    STOP RUN.
A010-DISPLAY-RECORDS.
    READ FLAVORS NEXT RECORD AT END MOVE "Y" TO END-OF-FILE.
    IF END-OF-FILE NOT = "Y" DISPLAY KETCHUP-MASTER.