HP 3000 Manuals HP 3000 Manuals
READ Statement The READ statement makes a record of a file available to your program. Syntax READ has three formats depending on the type of organization of the file from which a record is made available.Parameters file-name-1 name of the file to be read. identifier-1 data item described in the WORKING-STORAGE or FILE SECTION. imperative- one or more imperative statements, executed when an statement-1 INVALID KEY or AT END condition occurs. imperative- one or more imperative statements, executed when a NOT statement-2 INVALID KEY or NOT AT END condition occurs. data-name-1 name of a data item, as specified by either the RECORD KEY or ALTERNATE RECORD KEY clause, of the associated file. It may be qualified. Description The following rules apply to any of the formats of the READ statement. Each format is described separately following these common rules. When a READ statement is executed for a file, the file must be open in the INPUT or I-O mode. The execution of a READ statement causes the FILE-STATUS data item (if specified) of the file being read to be updated. Refer to Chapter 6 , under "FILE STATUS Clause", for valid status keys.[REV BEG] For more information on handling I/O errors, see "Input-Output Error Handling Procedures" .[REV END] When the logical records of a file are described with more than one record description, these records automatically share the same storage area. This is equivalent to an implicit redefinition of the area. Those character positions of the current data record not filled in by the READ statement contain data items that are undefined at completion of the execution of the READ statement. If the INTO phrase is specified, the input file must not contain logical records whose sizes vary according to their record descriptions. Also, the storage area associated with identifier-1, and the record area associated with the file being read must be distinct from one another. That is, these areas must not be the same storage areas. When the INTO phrase is used, the record being read is placed into the input record area of the file, and the data item contained in the input record area is copied into the storage area of identifier-1 according to the rules of the MOVE statement (without the CORRESPONDING phrase). This implied MOVE does not occur if the execution of the READ statement is unsuccessful. Any subscripting or indexing associated with identifier-1 is evaluated after the input record has been read, and immediately before it is moved into the storage area of identifier-1. If no exception exists, control is transferred to the end of the READ statement, or to imperative-statement-2, if specified. READ Statement - Format 1 A format 1 READ statement may be used for sequential, relative, random, or indexed files. The READ statement must be used for relative or indexed files whose access mode is sequential (see the SELECT clause). It must also be used, including the NEXT phrase, when the access mode for a relative or indexed file is dynamic and records of the file are being accessed sequentially and to read records sequentially from a random access file.
NOTE The NEXT phrase is optional for files whose access mode is sequential.
For a sequential, relative, or indexed file being accessed sequentially, the record to be made available by a format 1 READ statement is determined as follows: * The record pointed to by the file position indicator is made available provided that the file position indicator was positioned by a SEEK, START, or OPEN statement, and the record is still accessible through the path indicated by the file position indicator. If the record is no longer available, the file position indicator is updated to point to the next existing record (within the established key of reference for indexed files) and that record is then made available. _________________________________________________________________ NOTE A record may not be available because it was never written (for random access files), it was deleted (for relative files), or because an alternate record key has been changed (for indexed files). _________________________________________________________________ * 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 (with the established key of reference for indexed files) and that record is made available. A format 1 READ statement for a random access file, or for a relative or indexed file whose access mode is dynamic, uses the NEXT phrase to position the file position indicator to the next logical record of the file. The record made available is then determined as for files opened in sequential access mode. If no next logical record exists for the file and a READ statement attempts to execute for that file, the READ statement is unsuccessful and an AT END condition occurs. The steps taken by the program in such a situation are essentially the same as for a sequential file. That is, 1. The value of any FILE STATUS data item specified for the file is changed to indicate an AT END condition. 2. If an AT END phrase is specified in the READ statement, control is transferred to the imperative statement following the AT END keywords and any USE procedure specified for the file is ignored. If no AT END phrase is specified in the READ statement, a USE procedure must be specified either implicitly or explicitly for the file, and that procedure is executed. If no USE procedure is defined for the file, the AT END phrase must be used in the READ statement. Following the unsuccessful execution of any READ statement, the contents of the associated record area and the position of the file position indicator are undefined. For indexed files, the key of reference is also undefined. When the AT END condition exists, a format 1 READ statement for the file must not be executed without first executing one of the following: * A successful CLOSE statement followed by a successful OPEN statement for that file; * A successful START for that file (if it is relative or indexed); * A successful format 2 READ statement for a relative or random access file, or a format 3 READ statement for an indexed file. In the case of unlabeled magnetic tapes, the AT END condition indicates an EOF mark was read. Subsequent READ statements cause reading of the next file on the tape. Since this may cause reading off the end of the tape, the exact number of files on the tape must be known. If the end of a labeled magnetic tape reel is found during the execution of a READ statement, and the logical end of the file is not encountered, a reel swap is performed, and the first record of the new reel is made available. Execution of a format 1 READ statement may be unsuccessful for one of three reasons: * The position of the file position indicator is undefined; * No next logical record exists in the file (that is, the end-of-file has been encountered). * The OPTIONAL phrase was used in the SELECT statement for the file, and the file was not present at the time the file was opened. If the RELATIVE KEY phrase is specified in the SELECT clause for a relative file, successful execution of a format 1 READ statement updates the contents of the RELATIVE KEY data item so that it contains the relative record number of the record made available. For a random access file, the ACTUAL KEY data item is updated to contain the relative record number of the record just read. For an indexed file being sequentially accessed, records having the same duplicate value in an alternate record key being used for the key of reference are made available in the same order in which they are released by WRITE statements, or by execution of REWRITE statements that create duplicate values. READ Statement - Format 2 Format 2 of the READ statement can be used for relative files whose access mode is random, or whose access mode is dynamic when records are to be retrieved randomly. It can also be used for random access files. When a format 2 READ statement is executed for a relative file, the current record pointer is set to the record whose relative record number is contained in the data item named in the RELATIVE KEY phrase for the file (see the SELECT clause). This record is then made available. If the file does not contain such a record, an INVALID KEY condition exists, and the READ statement is unsuccessful. When an INVALID KEY condition exists, two actions are performed. First, the data item specified by the FILE STATUS clause, if used, is updated to reflect the condition. Next, if there is a USE procedure for the file, and an INVALID KEY condition exists but the INVALID KEY phrase was not specified in the READ statement, the procedure named in the USE statement is executed. If there is no USE procedure specified for the file, the INVALID KEY phrase must be used in the READ statement; when an INVALID KEY condition exists, control is passed to imperative-statement-1 in the INVALID KEY phrase. When a format 2 READ statement is executed for a random access file, it is equivalent to executing a SEEK statement for the file, followed by the READ statement. The contents of the data name specified in the ACTUAL KEY clause of the SELECT statement are used to set the file position indicator to the record to be read. The record is then made available unless an INVALID KEY condition exists. An INVALID KEY condition exists for a random access file if the contents of the ACTUAL KEY data item do not point to a record within the file. When this occurs, the imperative statement in the INVALID KEY phrase is executed. READ Statement - Format 3 Format 3 of the READ statement is used for indexed files whose access mode is random, or is dynamic and records are to be retrieved randomly. If the KEY phrase is specified, data-name-1, as specified by either the RECORD KEY or ALTERNATE RECORD KEY clause, is established as the key of reference for this retrieval. Also, if the access mode of the file is dynamic, this key of reference is used for retrievals by any subsequent executions of format 1 READ statements for the file until a different key of reference is established for the file. If the KEY phrase is not specified, the prime record key, as specified by the RECORD KEY clause of the SELECT statement, is established as the key of reference for retrieval. It acts in the same manner as an alternate key when format 2 READ statements are subsequently issued. Execution of a format 3 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. The records used in the comparison are selected according to the ascending values of their keys, and not by the order in which the records were written (called "chronological order"). The comparison continues either until the first record having the same value is found, or until no such value is found. If a value is found that matches the key of reference, the file position indicator is positioned to the record containing the matched value and that record is made available to your program. If the comparison fails, an INVALID KEY condition exists and execution of the READ statement is unsuccessful. When an INVALID KEY condition occurs and no INVALID KEY phrase is specified, a USE procedure must be specified, and is executed. When an INVALID KEY condition occurs and the INVALID KEY phrase is specified, control is transferred to the imperative statement appearing in the INVALID KEY phrase; any USE procedure that was specified for the file is ignored.
![[]](../../pic3k/M011820/FFN1043c50.gif)