HP OpenVMS Systems Documentation

HP COBOL
Reference Manual

Function

For sequential access files, the READ statement makes the next logical record available. For random access files, READ makes a specified record available.

file-name

is the name of a file described in the Data Division. It cannot be a sort or merge file.

dest-item

is the identifier of a data item that receives the record accessed by the READ statement.

stment

is an imperative statement executed when the relevant condition (at end or invalid key) occurs.

stment2

is an imperative statement executed when the relevant condition (not at end or not invalid key) occurs.

key-data

is the data-name of a data item specified as a record key for file-name or the segmented-key name specified as a record key for file-name. It can be qualified.

Syntax Rules

1. Format 1 must be used for a sequential access mode file.
2. There must be a NEXT phrase for dynamic access mode files to retrieve records sequentially.
3. READ file-name PRIOR and READ file-name PREVIOUS are equivalent syntax.
4. Format 2 can be used for random or dynamic access mode files to retrieve records randomly.
5. The KEY phrase can be used only for indexed files.
6. To use the REGARDLESS or ALLOWING options the program must specify these entries:
   • APPLY LOCK-HOLDING clause of the I-O-CONTROL paragraph
   • ALLOWING option of the OPEN statement
7. There must be an INVALID KEY or AT END phrase when there is no applicable USE AFTER EXCEPTION procedure for the file.
8. The storage area associated with dest-item and the record area associated with file-name cannot be the same storage area.
9. On Alpha and I64 systems, the WITH [NO] LOCK phrase is X/Open standard syntax. It is invalid to specify both X/Open standard and Hewlett-Packard standard (LOCK-HOLDING, ALLOWING, OR REGARDLESS) file-sharing syntax for the same file connector. Hence, the WITH [NO] LOCK phrase cannot be used with the ALLOWING or REGARDLESS phrase. <>

General Rules

1. The file must be open in the INPUT or I-O mode when the READ statement executes.
2. For sequential access mode files, the NEXT phrase is optional. It has no effect on READ statement execution.
3. READ PRIOR can only be used with an INDEXED file whose organization is INDEXED and whose access mode is DYNAMIC. The file must be opened for INPUT or I-O.
4. Executing a Format 1 READ statement can cause the following to occur:
   • The record pointed to by the File Position Indicator becomes available in the file's record area.
   • For sequential and relative files, the File Position Indicator points to the file's next existing record.
   • For indexed files, the File Position Indicator points to the next existing record established by the file's Key of Reference.
   • If the file has no next record, the File Position Indicator indicates that no next logical record exists.
5. The READ statement updates the value of the FILE STATUS data item for the file.
6. A record is available before any statement executes after the READ.
7. More than one record description can describe a file's logical records. The records then share the same record area in storage. Sharing a record area is equivalent to implicit redefinition.
   READ statement execution does not change the contents of data items in the record area beyond the range of the current data record. The contents of those items are undefined.
8. A Format 1 READ statement can recognize the end of reel/unit during its execution. If it has not reached the logical end of the file, the READ statement performs a reel/unit swap. The Current Volume Pointer points to the file's next reel/unit.
9. During execution of a Format 2 READ statement, the File Position Indicator can indicate that an optional file is not present. The invalid key condition then exists, and READ statement execution is unsuccessful.
10. When a Format 1 READ statement executes, the File Position Indicator can indicate that:
    • There is no next logical record.
    • No valid next record has been established.
    • An optional file is not present.
    • The number of significant digits in the relative record number is larger than the relative key data items.
    
    When the READ statement detects the no valid next record condition, the READ is unsuccessful.

    
    When the READ statement detects one of the above conditions, not including the no valid next record condition:

    • It updates the FILE STATUS data item for the file to indicate the at end condition.
    • If the READ statement has an AT END phrase, control transfers to stment. No USE AFTER EXCEPTION procedure for the file executes.
    • If there is no AT END phrase, a USE AFTER EXCEPTION procedure must be associated with the file. Control transfers to that procedure. Control returns from the USE AFTER EXCEPTION procedure to the next executable statement after the end of the READ statement.
    
    When the at end condition occurs, execution of the READ statement is unsuccessful.
11. After the unsuccessful execution of a READ statement, the contents of the file's record area are undefined. If an optional file is not present, the File Position Indicator is unchanged; otherwise, it indicates that no valid next record has been established. For indexed files, the Key of Reference is undefined.
12. READ PRIOR retrieves a record from an Indexed file which logically precedes the one which was made current by the previous file access operation, if such a logically previous record exists.
13. For a relative or indexed file in dynamic access mode, a Format 1 READ statement with the NEXT phrase retrieves the file's next logical record. For an indexed file, when the Key of Reference has ascending sort order, the next logical record is the next record with a key value equal to or greater than the previous key value. When the Key of Reference has descending sort order, the next logical record is the next record with a key value equal to or less than the previous key value.
14. For a relative file, a Format 1 READ statement updates the contents of the file's RELATIVE KEY data item. The data item contains the relative record number of the available record.
15. For a relative file, a Format 2 READ statement sets the File Position Indicator to the record whose relative record number is in the file's RELATIVE KEY data item. Execution then continues as specified in General Rule 3.
    If the record is not in the file, the invalid key condition exists, and READ statement execution is unsuccessful.
16. When your program sequentially accesses an indexed file for records with duplicate record key values in the Key of Reference, those records are made available to your program in the same order in which they were created. The duplicate values can be created by execution of WRITE or REWRITE statements.
17. For an indexed file, a Format 2 READ statement with the KEY phrase establishes key-name as the Key of Reference for the retrieval. For a dynamic access mode file, the same Key of Reference applies to later retrievals by Format 1 READ statement executions for the file. The Key of Reference continues in effect until a new Key of Reference is established.
18. For an indexed file, a Format 2 READ statement without the KEY phrase establishes the prime record key as the Key of Reference for the retrieval. For a dynamic access mode file, the same Key of Reference applies to later retrievals by Format 1 READ statement executions for the file. The Key of Reference continues in effect until a new Key of Reference is established.
19. For an indexed file, a Format 2 READ statement compares the value in the Key of Reference with the value in the corresponding data item in the file's records. The comparison continues until the READ statement finds the first record with an equal value. The READ statement sets File Position Indicator to the record. Execution then continues as specified in General Rule 3.
    If the READ statement cannot identify a record with an equal value, the invalid key condition exists. READ statement execution is then unsuccessful.
20. The Format 2 READ verb can use the KEY IS syntax to establish the key field within the file record which is the Key of Reference. An immediately subsequent READ PRIOR will follow the order of the Key of Reference to access the logically previous record in the file according to that Key of Reference. If the KEY IS syntax is not used, the Key of Reference is understood to be the file's primary key field.
21. When a successful READ PRIOR has occurred and the Key of Reference has ascending order, the record retrieved can have the same key value or a smaller key value than the preceding record for the Key of Reference. If the Key of Reference has descending order, the record retrieved can have the same key value or a higher key value for the Key of Reference. The retrieved record can have the same key value if duplicate values for the Key of Reference exist on the file.
22. When a READ PRIOR has been executed and a logically previous record does not exist, a File Status value of 10 indicating END-OF-FILE is returned. A READ PRIOR which is done immediately after Opening the file will produce the END-OF-FILE status.
23. If the number of character positions in the record being read is less than the minimum size specified by the record description entries for the file, the record area to the right of the last valid character read is undefined.
    If the number of character positions in the record being read is greater than the maximum size specified by the record description entries for the file, the record is truncated on the right to the maximum size.
    In both cases, the READ operation is successful and the I-O status is set to indicate a record length conflict has occurred.
24. The REGARDLESS and ALLOWING options can be used only in a Hewlett-Packard standard manual record-locking environment. To create a manual record-locking environment, an access stream must specify the APPLY LOCK-HOLDING clause of the I-O-CONTROL paragraph.
25. On Tru64 UNIX and OpenVMS, the REGARDLESS option enables an access stream to read a record regardless of any record locks held by other concurrent access streams. READ REGARDLESS holds no lock on the record read.
    This statement generates a soft record lock condition if the record is locked by another access stream. This condition results in a File Status value of 90 and invokes an applicable USE procedure, if any. Execution of the READ REGARDLESS statement is considered successful and program execution resumes at the next statement following the READ REGARDLESS statement.<>
    However, on Tru64 UNIX systems, the soft lock condition (file status 90) is not recognized for indexed files. A READ REGARDLESS statement for a record locked by another process performs the requested read operation on the record and returns a file status of 00. <>
26. The ALLOWING UPDATERS and WITH NO LOCK options permit other concurrent access streams in a manual record-locking environment to simultaneously READ, DELETE, START, and REWRITE the current record. These options hold no locks on the current record.
27. The ALLOWING READERS option permits other concurrent access streams in a Hewlett-Packard standard, manual record-locking environment to simultaneously read the current record. This option holds a read-lock on each such record read. No access stream can update the current record until it is unlocked.
    On Tru64 UNIX systems, for indexed files, the ALLOWING READERS phrase has some limitations, which are described in the HP COBOL User Manual (see the section on indicating access allowed to other streams in the chapter on sharing files). <>
28. The ALLOWING NO OTHERS or WITH LOCK option locks the record read by the current access stream. No other concurrent access stream can access this record until it is unlocked. Only this access stream can update this record. This option applies to files opened in I-O mode. See general rule 29.
29. For files opened for input, a READ statement does not acquire a record lock, regardless of the locking syntax specified. This applies to X/Open standard and Hewlett-Packard standard locking.
30. If there is an applicable USE AFTER EXCEPTION procedure, it executes whenever an input condition occurs that would result in a nonzero value in the first character of a FILE STATUS data item. However, it does not execute if: (a) the condition is invalid key, and there is an INVALID KEY phrase or (b) the condition is at end, and there is an AT END phrase.
31. If no exception condition exists, the record is made available in the record area. Control is transferred to the end of the READ statement; however, if stment2 is specified, stment2 executes before control is transferred to the end of the READ statement.