HP 3000 Manuals HP 3000 Manuals
General Formats (Continued) The READ Statement Function. For sequential access, the READ statement makes available the next or previous (MF only) logical record from a file. For random access, the READ statement makes available a specified record from a mass storage file. General Formats. Format 1 (Record Sequential Files) .For MF only: Format 2 (Line Sequential Files).Format 3 (Relative And Indexed Files).Format 4 (Relative Files).Format 5 (Indexed Files) .Directives and Run-time Switches. 1. In addition to flagging and reserved words directives, the following directive may impact either the syntax or semantics described in this section. See your COBOL System Reference for details. * RETRYLOCK - causes the COBOL system to retry to read a locked record. 2. The following run-time switches may impact the semantics described in this section. See your COBOL System Reference for details. * B, B1 - causes the record pointer to be updated past any locked record encountered when executing a READ NEXT statement. * N - controls the interpretation of null characters before control characters when reading line sequential records. * T - controls the interpretation of tab characters when reading line sequential records. Syntax Rules. All Formats (All Files). 1. The INTO phrase must not be used when the input file contains logical records of various sizes as indicated by their record descriptions. This restriction has been removed (ANS85 only). The storage area associated with identifier and the storage area which is the record area associated with file-name must not be the same storage area. 2. For OSVS, VSC2 and MF only: Identifier can be a floating-point data item . 3. The INVALID KEY phrase or the AT END phrase must be specified if no applicable USE procedure is specified for file-name. For OSVS, VSC2 and MF only: This rule is not enforced. Formats 1, 3, 4 and 5 (Record Sequential, Relative and Indexed Files). 4. For MF only: The WITH LOCK phrase can be included only when single records are being locked manually in a shareable file. 5. For MF only: The WITH NO LOCK phrase is only allowed when records are being locked manually or automatically in a shareable file. Format 3 (Relative and Indexed Files). 6. The NEXT or PREVIOUS (MF only) phrases must be specified for files in dynamic access mode when records are to be retrieved sequentially. For MF only: Formats 3, 4 and 5 (Relative And Indexed Files). 7. The WITH KEPT LOCK phrase can be included only when multiple records are being locked manually in a shareable file. Formats 4 and 5 (Relative And Indexed Files). 8. Format 4 or 5 is used for files in random access mode or for files in dynamic access mode when records are to be retrieved randomly. Format 5 (Indexed Files). 9. Data-name must be the name of a data item specified as a record key associated with file-name. For MF and OSVS only: Data-name may also be a redefinition of a data-item specified as a record key associated with a file-name, provided the data-name has the same length as that data-item. For OSVS only: The redefinition may have a different length from the record key. 10. Data-name can be qualified. 11. For MF only: Split-key-name is a concatenation of one or more data items specified as a record key associated with file-name. General Rules. All Formats (All Files). 1. The associated file must be open in the INPUT or I/O mode at the time the statement is executed. (See the section The OPEN Statement earlier in this chapter.) 2. The execution of the READ statement causes the value of the FILE STATUS data item, if any, associated with file-name to be updated. (See the section I/O Status earlier in this chapter.) 3. When the logical records of a file are described by more than one record description, these records automatically share the same storage area; this is equivalent to an implicit redefinition of the area. The contents of any data items which lie beyond the range of the current data record are undefined at the completion of the execution of the READ statement. 4. If the INTO phrase is specified, the record being read is moved from the record area to the area specified by identifier according to the rules specified for the MOVE statement without the CORRESPONDING phrase. The implied MOVE does not occur if execution of the READ statement was unsuccessful. Any subscripting or indexing associated with identifier is evaluated after the record has been read and immediately before it is moved to the data item. 5. When the INTO phrase is used, the record being read is available in both the input record area and the data area associated with identifier. 6. If the file position indicator indicates that no next logical record exists, or that an optional input file is not present, the following occurs in the order specified: a. A value, derived from the setting of the file position indicator, is placed into the I/O status associated with file-name-1 to indicate the at end condition. (See the section I/O Status in this chapter.) b. If the AT END phrase is specified in the statement causing the condition, control is transferred to AT END imperative-statement-1. Any USE AFTER EXCEPTION procedure associated with the file connector referenced by file-name-1 is not executed. Execution then continues according to the rules for each statement specifed in imperative-statement-1. If a procedure branching or conditional statement that causes explicit transfer of control is executed, control is transferred in accordance with the rules of that statement; otherwise, upon completion of the execution of imperative-statement-1, control is transferred to the end of the READ statement and the NOT AT END phrase, if specified, is ignored. c. If the AT END phrase is not specified, a USE AFTER STANDARD EXCEPTION procedure must be associated with this file-name-1, and that procedure is executed. Return from that procedure is to the next executable statement following the end of the READ statement. For ANS85 only: When the AT END condition occurs, the execution of the READ statement is unsuccessful. 7. Following the unsuccessful execution of any READ statement, the contents of the associated record area are undefined and the file position indicator is set to indicate that no next record has been established. Format 1 (Record Sequential Files). 8. The record to be made available by the READ statement is determined as follows: a. For ANS85 only: If the file position indicator was positioned by the execution of the OPEN statement, the record pointed to by the file position indicator is made available. b. For ANS85 only: If the file position indicator was positioned by the execution of a previous READ statement, the file position indicator is updated to point to the next existing record in the file, and that record is made available. For MF only: However if the previous statement was a READ, and if that READ returned a locked record status, the file position indicator is left unchanged. The record pointed to by the file position indicator is made available. 9. If the end of a reel or unit is recognized during the execution of a READ statement, and end-of-file has not been reached, the following procedures are executed: a. The standard ending reel/unit label procedure. b. A reel/unit swap. c. The standard beginning reel/unit label procedure. d. The first data record of the new reel/unit is made available. 10. If a file described with the OPTIONAL clause is not present at the time the file is opened, then at the time of execution of the first READ statement for the file, the AT END condition occurs and execution of the READ statement is unsuccessful. The standard end of file procedures are not performed. (See sections The FILE-CONTROL Paragraph, The OPEN Statement, and The USE Statement in this chapter.) Execution of the program then proceeds as in General Rule 13. 11. For MF only: For files opened for INPUT, the READ, READ WITH LOCK or READ WITH KEPT LOCK statements do not acquire a record lock. 12. Two or more run units can share a sequential output file by opening it EXTEND with AUTOMATIC or MANUAL record locking. Records that are appended to the file are in unspecified order (MF). 13. For MF only: For files opened for I/O: a. With LOCK MODE AUTOMATIC, unless the WITH NO LOCK phrase is specified each record is locked as it is read. b. With LOCK MODE MANUAL, a simple READ statement does not acquire a lock on the record - the READ WITH LOCK statement must be used to acquire a record lock. The WITH NO LOCK phrase, if specified, is documentary. c. The use of multiple or single record locking determines when the record lock is released. (See section The FILE-CONTROL Paragraph in this chapter.) 14. For MF only: If an end-of-file status occurs on a READ statement in a file opened for I/O or INPUT by one run unit and opened EXTEND by another run unit, the run unit that attempted the READ must close the file. This run unit has no access to the appended records because the status remains end-of-file. Formats 1, 2 and 3 (Sequential, Relative and Indexed Files) . 15. If an AT END condition does not occur during the execution of a READ statement, the AT END phrase, if specified, is ignored and the following actions occur: a. The file position indicator is set and the I/O status associated with file-name-1 is updated. b. If an exception condition which is not an at end condition exists, control is transferred according to the rules of the USE statement following the execution of any USE AFTER EXCEPTION procedure applicable to file-name-1. (See the section The USE Statement in this chapter.) c. If no exception condition exists, the record is made available in the record area and any implicit move resulting from the presence of an INTO phrase is executed. Control is transferred to the end of the READ statement or to imperative-statement-2, if specified. In the latter case, execution continues according to the rules for each statement specified in imperative-statement-2. If a control branching or conditional statement which causes explicit transfer of control is executed, control is transferred in accordance with the rules for that statement; otherwise, upon completion of the execution of imperative-statement-2, control is transferred to the end of the READ statement. 16. If when a READ statement with the NEXT option is executed, no next logical record exists in the file, the AT END condition occurs, and the execution of the READ statement is considered unsuccessful. See the section I/O Status earlier in this chapter. 17. For sequential files or (ANS85 only) files in sequential access mode, the NEXT phrase is optional and has no effect on the execution of the READ statement. Format 3 (Relative and Indexed Files). 18. For MF only: Following a READ which encounters a locked record status, the file position indicator points at the locked record. A subsequent READ NEXT or READ PREVIOUS will retrieve the same record again. For ANS85 only: The NOT AT END phrase is only executed following successful completion of the operation. 19. For MF only: If when a READ statement with the PREVIOUS option is executed no previous logical record exists in the file, the AT END condition occurs, and the execution of the READ statement is considered unsuccessful. 20. When the AT END condition has been recognized, For MF only: the next Format 3 READ statement, if any, executed for that file must be a READ NEXT statement, if AT END occurred because noprevious logical record existed. Otherwise the AT END condition must be followed by: a. A successful CLOSE statement followed by the execution of a successful OPEN statement for that file. b. A successful START statement for that file. c. A successful Format 4 (or Format 5 for indexed files) READ statement for that file. 21. For a file for which dynamic access mode is specified, a READ statement with the NEXT phrase specified causes the next logical record to be retrieved from the file as described in General Rule 8 (MF only). 22. The record to be made available by the READ statement is determined as follows: a. For MF only: If the file position indicator was positioned by the execution of an OPEN statement, and the PREVIOUS option is specified, the AT END condition occurs. Otherwise if the file position indicator was positioned by the execution of the START or OPEN statement and the record is still accessible through the path indicated by the file position indicator, the record pointed to by the file position indicator is made available. If the record is no longer accessible, which can have been caused for a relative file by deletion of the record, or for an indexed file by a change in an alternate key, the file position indicator is updated to point to the next or, if the PREVIOUS option is specified, the previous (MF only) existing record within the established key of reference, and that record is then made available. b. If the file position indicator was positioned by the execution of a previous READ statement, the file position indicator is updated to point to the next or, if the PREVIOUS option is specified, the previous (MF only) existing record in the file. For MF only: However, if the previous statement was a READ, and if that READ returned a locked record status, the file position indicator is left unchanged. The record pointed to by the file position indicator is made available. For MF only: Formats 1, 3, 4 and 5 (Sequential, Relative. and Indexed Files) 23. If the lock mode is MANUAL with single record locking and the referenced file is opened I/O, the run unit acquires a record lock on the record only if the WITH LOCK phrase is specified. A simple READ statement does not acquire a record lock. To read past a locked record the file position indicator should be updated using the START statement. This, however, cannot be used on alternate keys which allow duplicates. 24. If the lock mode is MANUAL with multiple record locking and the referenced file is opened I/O, the run unit acquires a lock on the record only if the WITH KEPT LOCK phrase is specified. A simple READ statement does not acquire a record lock. To read past a locked record the file position indicator should be updated using the START statement. This, however, cannot be used on alternate keys which allow duplicates. 25. The WITH WAIT phrase ensures that a lock is acquired on the record, waiting if necessary. Format 3 (Relative Files). 26. If the RELATIVE KEY phrase is specified for the file, the execution of a READ statement updates the contents of the RELATIVE KEY data item so that it contains the relative record number of the record made available. Format 4 (Relative Files). 27. The execution of a READ statement sets the file position indicator to, and makes available, the record whose relative record number is contained in the data item named in the RELATIVE KEY phrase for the file. If the file does not contain such a record, the INVALID KEY condition exists and execution of the READ statement is unsuccessful. (See section The INVALID KEY Condition in this chapter.) For MF only: Formats 3 and 5 (Relative and Indexed Files). 28. The IGNORE LOCK phrase causes the READ to proceed as if the record were not locked. Format 3 (Indexed Files). 29. For an indexed file being sequentially accessed, records having the same duplicate value in an alternate record key which is the key of reference are made available in the same order in which they are released by execution of WRITE statements, or by execution of REWRITE statements which create such duplicate values. Format 5 (Indexed Files). 30. If the KEY phrase is not specified the prime record key is established as the key of reference for this retrieval. If dynamic access mode is specified, this key of reference is also used forretrievals by any subsequent executions of Format 3 READ statements for the file. 31. If the KEY phrase is specified, data-name-1 or split-key-name (MF only) is established as the key of reference for this retrieval. If dynamic access mode is specified, this key of reference is also used for retrievals by any subsequent executions of Format 3 READ statements for the file until a different key of reference is established for the file. 32. Execution of a Format 5 READ statement causes the value of the key of reference to be compared with the value contained in the corresponding data item of the stored records in the file, until the first record having an equal value is found. The file position indicator is positioned to this record which is then made available. If no record can be so identified, the INVALID KEY condition exists and execution of the READ statement is unsuccessful. (See the section The INVALID KEY Condition in this chapter.)
![[]](../../pic3k/M015064/FFN2573c50.gif)
![[]](../../pic3k/M015064/FFN2583c50.gif)
![[]](../../pic3k/M015064/FFN2593c50.gif)
![[]](../../pic3k/M015064/FFN2603c50.gif)
![[]](../../pic3k/M015064/FFN2613c50.gif)