READ Statement COBOL

For sequential access, the READ statement makes available the next or previous logical record from a file.For random access, the READ statement makes available a specified record from a mass storage file.

Format 1:Read Sequential Access

Read Sequential Access

Format 2:Read Random Access

Read Random Access

The file referenced by file-name-1 must be open in the INPUT or I–O mode at the time this statement is executed.

In a Format 1 READ statement, the NEXT phrase causes the next logical record to be retrieved from the file, and the PREVIOUS phrase causes the previous logical record to be retrieved.The PREVIOUS phrase may not be specified for a sequential organization file.

For a file in which sequential access mode is specified, a Format 1 READ statement must be used.If both the NEXT phrase and the PREVIOUS phrase are omitted from a Format 1 READ statement for a file in sequential access mode, the default is NEXT.

For a file in which dynamic access mode is specified and records are to be retrieved sequentially using Format 1 READ statements, either the NEXT phrase or the PREVIOUS phrase must be specified.

Format 2 is used for files in random access mode or for files in dynamic access mode when records are to be retrieved randomly.

The INVALID KEY phrase or the AT END phrase must be specified if no applicable USE procedure is specified for file-name-1.

The KEY phrase may be specified only when the organization of file-name-1 is indexed. When the KEY phrase is present, data-name-1 or split-key-name-1 must be the name of one of the record keys associated with file-name-1. data-name-1 or split-key-name-1 may be qualified.

The setting of the file position indicator at the start of the execution of a Format 1 READ statement is used in determining the record to be made available according to the following rules.Comparisons for records in sequential files relate to the record number. Comparisons for records in relative files relate to the relative key number.Comparisons for records in indexed files relate to the value of the current key of reference, and the comparisons of key values are made according to the collating sequence of the file.

  1. If the file position indicator indicates that no valid next record has been established, execution of the READ statement is unsuccessful.
  2. If the file position indicator indicates that an optional input file is not present, execution proceeds as described below for the case when no next record exists.
  3. If the file position indicator was established by a previous OPEN or START statement, and
    • PREVIOUS was not specified, the first existing record in the file whose record number or key value is greater than or equal to the file position indicator is selected.
    • PREVIOUS was specified, the first existing record in the file whose record number or key value is less than or equal to the file position indicator is selected.
  4. If the file position indicator was established by a previous READ statement, and the file is a sequential or relative file, or an indexed file whose current key of reference does not allow duplicates, and
    • PREVIOUS was not specified, the first existing record in the file whose record number or key value is greater than the file position indicator is selected.
    • PREVIOUS was specified, the first existing record in the file whose record number or key value is less than the file position indicator is selected.
  5. For indexed files, if the file position indicator was established by a previous READ statement, and the current key of reference does allow duplicates, and
    • PREVIOUS was not specified, the first record in the file whose key value is either equal to the file position indicator and whose logical position within the set of duplicates is immediately after the record that was made available by that previous READ statement, or whose key value is greater than the file position indicator, is selected.
    • PREVIOUS was specified, the first record in the file whose key value is either equal to the file position indicator and whose logical position within the set of duplicates is immediately before the record that was made available by that previous READ statement, or whose key value is less than the file position indicator, is selected.

If a record is found that satisfies these requirements, and there is no record lock conflict for that record, it is made available in the record area for the file.

If no record is found that satisfies these requirements, the file position indicator is set to indicate that no next record exists, and execution proceeds as described below for the case when no next record exists.

If a record is made available, the file position indicator is updated as follows:

  • For sequential files, the file position indicator is set to the record number of the record made available.
  • For relative files, the file position indicator is set to the relative record number of the record made available.If the RELATIVE KEY clause is specified for file-name-1 and the number of significant digits in the relative record number of the selected record is larger than the size of the relative key data item, the file position indicator is set to indicate this condition and execution proceeds as described below for the case when no next record exists.
  • For indexed files, the file position indicator is set to the value of the current key of reference of the record made available.

The execution of the READ statement causes the value of the file status data item, if any, associated with file-name-1 to be updated.

When the logical records of a file are described with more than one record description, they share the same storage area; this is equivalent to an implicit redefinition of the area. If the number of character positions in the record that is read is less than the minimum size specified by the record description entries for file-name-1, the portion of the record area that is to the right of the last valid character read is undefined.If the number of character positions in the record that is read is greater than the maximum size specified by the record description entries for file-name-1, the record is truncated on the right to the maximum size.In either case, the READ statement is successful and an I–O status value is set indicating that a record length conflict has occurred.

For a Format 1 READ statement, if the file position indicator indicates that no next (or previous) logical record exists, or that an optional input file is not present, the NOT AT END phrase, if specified, is ignored, and the following operations occur in the order specified:

  1. An I–O status value is derived from the setting of the file position indicator and stored into the file status data item for the file, if there is one.
  2. If the AT END phrase is specified in the Format 1 READ statement, control is transferred to the imperative statement in the AT END phrase.Any USE procedure associated with file-name-1 is not executed.
  3. If the AT END phrase is not specified, the applicable USE procedure, if there is one, is executed.Upon return from the USE procedure, control is transferred to the end of the READ statement.If there is no applicable USE procedure, an error message is produced and the run unit is terminated.The runtime can be configured, as described for the DEFAULT-USE-PROCEDURE keyword of the COMPILER- OPTIONS record in Chapter Configuration, of the RM/COBOL User’s Guide, to assume that a default empty USE procedure is applicable, thus causing execution to continue at the next executable statement after the READ statement.

If the at end condition occurs, execution of the Format 1 READ statement is unsuccessful.Following the unsuccessful execution of the READ statement, the contents of the associated record area are undefined and the file position indicator is set to indicate that no valid next record has been established.A further Format 1 READ statement for that file must not be executed without first executing one of the following:

  • A successful CLOSE statement followed by the execution of a successful OPEN statement for that file
  • A successful START statement for that file
  • A successful Format 2 READ statement for that file

If an at end condition does not occur during the execution of a Format 1 READ statement, the AT END phrase and its associated imperative statement are ignored, if specified, and the following actions occur:

  • The file position indicator is set and the I–O status value associated with the file- is updated and stored into the file status data item for the file, if there is one name
  • If an exception condition other than at end exists, control is transferred according to rules of the USE procedure applicable to the file-name.
  • 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 NOT AT END phrase.In the latter case, execution continues according to the rules for each statement specified in imperative-statement-2.If a procedure branching or conditional statement that 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.

For relative files if the RELATIVE KEY phrase is specified, the execution of a Format 1 READ statement updates the contents of the relative key data item such that it contains the relative record number of the record made available.

For relative files the execution of a Format 2 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.

For an indexed file being sequentially accessed using the NEXT phrase (specified either implicitly or explicitly) in a Format 1 READ statement, 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 that create such duplicate values.If the file is being sequentially accessed using the PREVIOUS phrase in a Format 1 READ statement, the records with duplicate keys are made available in reverse of the order that they are released or made duplicate.

In single record locking modes, any record lock held by the run unit for file-name-1 is released upon execution of the READ statement.The successful execution of the READ statement may obtain a record lock on the accessed record as described in the discussion of the LOCK phrase.

In multiple record locking modes any record locks held by the run unit for file-name-1 are not released upon execution of the READ statement.

KEY Phrase

KEY Phrase

For an indexed file if the KEY phrase is specified in a Format 2 READ statement, data-name-1 or split-key-name-1 is established as the key of reference for this retrieval. If the dynamic access mode is specified, this key of reference is also 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 in a Format 2 READ statement, the prime record key is established as the key of reference for this retrieval.

If the dynamic access mode is specified, this key of reference is also 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.

For indexed files, the execution of a Format 2 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.

For relative files, the KEY phrase cannot be specified.

LOCK Phrase

WITH [NO ] LOCK

The LOCK phrase may be specified to control record locking for a shared input-output file.If the file is not a shared input-output file, the LOCK phrase is ignored and the execution of the READ statement does not attempt to obtain a lock on the record accessed.For a file open in the INPUT mode, the execution of the READ statement never attempts to obtain a lock on the record accessed.

In manual record locking modes, the READ statement only attempts to lock the record accessed when the LOCK phrase, without the NO option, is specified.If the record accessed by the READ statement is to be subsequently rewritten or deleted, the LOCK phrase, without the NO option, should be specified in a READ statement executed in manual record locking modes.For a READ statement that is executed in manual record locking modes, the NO LOCK phrase is redundant.

In automatic record locking modes, the READ statement automatically attempts to lock the record accessed except when the NO LOCK phrase is specified.Specifying NO LOCK will reduce file contention in a shared file environment when the record accessed by the READ statement is not to be subsequently rewritten or deleted.In automatic record locking modes, the LOCK phrase, without the NO option, is redundant.

When a READ statement attempts to obtain a record lock and the record accessed is already locked by another concurrently executing run unit, the subsequent action depends on the form of the program:

  • If the program declares both a file status data item for file-name-1 and an applicable USE procedure for file-name-1, the READ statement completes unsuccessfully with an I–O status value that indicates a locked record conflict and the USE procedure is performed.The status of the file position indicator in this case is described in the RM/COBOL User’s Guide.
  • If the conditions in the above paragraph are not satisfied, the runtime system waits for the other run unit to unlock the record before completing the READ statement execution for this run unit.

If the record is already locked by this run unit through another COBOL file-name that refers to the same physical file, the READ statement will not wait but will complete unsuccessfully regardless of whether both a file status data item and applicable USE procedure are defined in the program. If the record is already locked by this run unit through file-name-1, the READ statement completes successfully and the lock status of the accessed record is not changed.

When a READ statement does not attempt to obtain a lock on the record accessed, the lock status of the record is not significant.The current contents of the record are obtained at the time of the execution of the READ statement without indication of its locked or unlocked status. See “ Record Locking” for additional information on record locking.

INTO Phrase

INTOidentifier-1

If the INTO phrase is specified, the record being read is moved from the record area to the area specified by identifier-1 according to the rules specified for the MOVE statement without the CORRESPONDING phrase.The size of the current record is determined by rules specified in the RECORD clause.If the file description entry contains a RECORD IS VARYING clause, the implied move is a group move. The implied move does not occur if the execution of the READ statement was unsuccessful.Any subscripting associated with identifier-1 is evaluated after the record has been read and immediately before it is moved to the data item.

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-1.

The INTO phrase must not be used when the input file contains logical records of various sizes as indicated by their record descriptions.The storage area associated with identifier-1 and the record area associated with file-name-1 must not be the same storage area.

INVALID KEY and NOT INVALID KEY Phrases

INVALID KEY imperative -statement-1

NOT INVALID KEY imperative -statement-2

The causes of the invalid key condition for a READ statement execution have been indicated in the preceding text.See the discussions of relative organization input-output and indexed organization input-output, for additional information on the invalid key condition and the use of the INVALID KEY clause.

READ Statement Examples



Face Book Twitter Google Plus Instagram Youtube Linkedin Myspace Pinterest Soundcloud Wikipedia

All rights reserved © 2018 Wisdom IT Services India Pvt. Ltd DMCA.com Protection Status

COBOL Topics