4.6.41 The PERFORM Statement

The PERFORM statement is used to transfer control explicitly to one or more procedures and to return control implicitly whenever execution of the specified procedure is complete.

The PERFORM statement is also used to control execution of one or more imperative statements which are in the scope of that PERFORM statement.

See also the section The EXIT Statement earlier in this chapter.

General Formats

Format 1

Format 2

Format 3

Format 4

Directives

1. In addition to Compiler directives which provide flagging and modify the reserved word list, the following directive may impact either the syntax or semantics described in this section.
   • PERFORM-TYPE - controls the handling of overlapping PERFORM ranges.

Syntax Rules

All Formats

1. If procedure-name-1 is omitted, imperative-statement-1 and the END-PERFORM phrase must be specified; if procedure-name-1 is specified, imperative-statement-1 and the END-PERFORM phrase must not be specified.

   When imperative-statement-1 is specified, the END-PERFORM phrase is optional.

   Procedure-name-1 and imperative-statement-1 may both be omitted.

2. The words THROUGH and THRU are equivalent.

3. Where procedure-name-1 and procedure-name-2 are both specified and either is the name of a procedure in the declaratives portion of the Procedure Division, both must be procedure-names in the same declarative section.

Formats 2 and 4

4. Each identifier represents a numeric elementary item described in the Data Division. In Format 2, identifier-1 must be described as a numeric integer.

5. Floating-point data items and literals can be used anywhere a numeric data item or literal can be specified. They can not be used where an integer is required.

Formats 3 and 4

6. If neither the TEST BEFORE nor the TEST AFTER phrase is specified, the TEST BEFORE phrase is assumed.

7. Condition-1, condition-2, ... , can be any conditional expression. (See the section Conditional Expressions earlier in this chapter.)

Format 4

8. In Format 4, if procedure-name-1 is omitted, the AFTER phrase must not be specified.

9. Each literal represents a numeric literal.

10. If an index-name is specified in the VARYING or AFTER phrase, then:
    1. The identifier in the associated FROM and BY phrases must reference an integer data item.

    2. The literal in the associated FROM phrase must be a positive integer.

    3. The literal in the associated BY phrase must be a nonzero integer.

11. If an index-name is specified in the FROM phrase, then:
    1. The identifier in the associated VARYING or AFTER phrase must reference an integer data item.

    2. The identifier in the associated BY phrase must reference an integer data item.

    3. The literal in the associated BY phrase must be an integer.

12. The literal in the BY phrase must not be zero.

13. Two AFTER phrases are permitted in Format 4 of the PERFORM statement.

    Six AFTER phrases are permitted in Format 4 of the PERFORM statement.

    This limit is raised to fifteen.

General Rules

All Formats

1. When procedure-name-1 is specified, the PERFORM statement is referred to as an out-of-line PERFORM statement;

   when procedure-name-1 is omitted, the PERFORM statement is referred to as an in-line PERFORM statement.

2. The statements contained within the range of procedure-name-1 (through procedure-name-2 if specified) for an out-of-line PERFORM statement

   or contained in the PERFORM statement itself for an in-line PERFORM statement

   are referred to as the specified set of statements.

3. The END-PERFORM phrase delimits the scope of the in-line PERFORM statement. (See the section Explicit And Implicit Scope Terminators in the chapter Concepts of the COBOL Language.)

4. An in-line PERFORM statement functions according to the following general rules for an otherwise identical out-of-line PERFORM statement, with the exception that the statements contained within the in-line PERFORM statement are executed in place of the statements contained within the range of procedure-name-1 (through procedure-name-2 if specified). Unless specifically qualified by the word in-line or out-of-line, all the general rules which apply to the out-of-line PERFORM statement also apply to the in-line PERFORM statement.

5. When the PERFORM statement is executed, control is transferred to the first statement of the specified set of statements (except as indicated in General Rules 8b, 8c and 8d). This transfer of control occurs only once for each execution of a PERFORM statement. For those cases where a transfer of control to the specified set of statements does take place, an implicit transfer of control to the end of the PERFORM statement is established as follows:
   1. If procedure-name-1 is a paragraph-name and procedure-name-2 is not specified, the return is after the last statement of procedure-name-1.

   2. If procedure-name-1 is a section-name and procedure-name-2 is not specified, the return is after the last statement of the last paragraph in procedure-name-1.

   3. If procedure-name-2 is specified and it is a paragraph-name, the return is after the last statement of the paragraph.

   4. If procedure-name-2 is specified and it is a section-name, the return is after the last statement of the last paragraph in the section.

   5. If an in-line PERFORM statement is specified, an execution of the PERFORM statement is completed after the last statement contained within it has been executed.

   6. An EXIT PERFORM statement can be used to exit an in-line perform before executing all statements within the in-line perform.

6. There is no necessary relationship between procedure-name-1 and procedure-name-2 except that a consecutive sequence of operations is to be executed beginning at the procedure named procedure-name-1 and ending with the execution of the procedure named procedure-name-2. In particular, GO and PERFORM statements can occur between procedure-name-1 and the end of procedure-name-2. If there are two or more logical paths to the return point, then procedure-name-2 can be the name of a paragraph consisting of the EXIT statement, to which all of these paths must lead.

7. If control passes to the specified set of statements by means other than a PERFORM statement, control will pass through the last statement of the set to the next executable statement as if no PERFORM statement referenced the set.

8. The PERFORM statements operate as follows:

   1. Format 1 is the basic PERFORM statement. The specified set of statements referenced by this type of PERFORM statement is executed once and then control passes to the end of the PERFORM statement.

   2. Format 2 is the PERFORM ... TIMES. The specified set of statements is performed the number of times specified by integer-1 or by the initial value of the data item referenced by identifier-1 for that execution. If at the time of the execution of a PERFORM statement, the value of the data item referenced by identifier-1 is equal to zero or is negative, control passes to the end of the PERFORM statement. Following the execution of the specified set of statements the specified number of times, control is transferred to the end of the PERFORM statement.

      During execution of the PERFORM statement, reference to identifier-1 cannot alter the number of times the specified set of statements is to be executed from that which was indicated by the initial value of the data item referenced by identifier-1.

      Integer-1 must be zero or positive, but it may be signed.

   3. Format 3 is the PERFORM ... UNTIL. The specified set of statements is performed until the condition specified by the UNTIL phrase is true. When the condition is true, control is transferred to the end of the PERFORM statement. If the condition is true when the PERFORM statement is entered,

      and the TEST BEFORE phrase is specified or implied,

      no transfer to procedure-name-1 takes place, and control is passed to the end of the PERFORM statement.

      If the TEST AFTER phrase is specified, the PERFORM statement functions as if the TEST BEFORE phrase were specified except that the condition is tested after the specified set of statements has been executed. Any subscripting or reference modification associated with the operands specified in condition-1 is evaluated each time the condition is tested.

      When UNTIL EXIT is specified, the specified set of statements is performed repeatedly until some statement in the set causes this repetition to end. In the case of an out-of-line PERFORM, the only statements that will cause this termination are statements such as EXIT PROGRAM and STOP RUN. In the case of an in-line PERFORM, the repetition can also be terminated by the EXIT PERFORM statement and the GO TO statement.

   4. Format 4 is the PERFORM ... VARYING. This variation of the PERFORM statement is used to augment the values referenced by one or more identifiers or index-names in an orderly fashion during the execution of a PERFORM statement. In the following discussion, every reference to identifier as the object of the VARYING, AFTER, and FROM (current value) phrases also refers to index-names.

      If index-name-1 is specified, the value of identifier-3, index-name- 2, or literal-1 at the beginning of the execution of the PERFORM statement must correspond to an occurrence number of an element in the table associated with index-name-1. If index-name-3 is specified, the value of identifier-6, index-name-4, or literal-3 at the beginning of the execution of the PERFORM statement must correspond to an occurrence number of an element in the table associated with index-name-3.

      Subsequent augmentation, as described below, of index-name-1 or index-name-3 must not result in the associated index being set to a value outside the range of the table associated with index-name-1 or index-name-3; except that, at the completion of the PERFORM statement, the index associated with index-name-1 can contain a value that is outside the range of the associated table by one increment or decrement value.

      If identifier-2 or identifier-5 is subscripted, the subscripts are evaluated each time the content of the data item referenced by the identifier is set or augmented. If identifier-3, identifier-4, identifier-6, or identifier-7 is subscripted, the subscripts are evaluated each time the content of the data item referenced by the identifier is used in a setting or augmenting operation. Any subscripting or reference modification associated with the operands specified in condition-1 or condition-2 is evaluated each time the condition is tested.

      Representations of the actions of several types of Format 4 PERFORM statements are given on the following pages.

      1. If the TEST BEFORE phrase is specified or implied:

         When the data item referenced by one identifier is varied, the content of the data item referenced by identifier-2 is set to literal-1 or the current value of the data item referenced by identifier-3 at the point of initial execution of the PERFORM statement; then, if the condition of the UNTIL phrase is false, the specified set of statements is executed once. The value of the data item referenced by identifier-2 is augmented by the specified increment or decrement value (literal-2 or the value of the data item referenced by identifier-4) and condition-1 is evaluated again. The cycle continues until this condition is true, at which point control is transferred to the end of the PERFORM statement. If condition-1 is true at the beginning of execution of the PERFORM statement, control is transferred to the end of the PERFORM statement.

         

         Figure 4-1: The VARYING Option of a PERFORM Statement with the TEST BEFORE Phrase Having One Condition

         When the data items referenced by two identifiers are varied, the content of the data item referenced by identifier-2 is set to literal-1 or the current value of the data item referenced by identifier-3 and then the content of the data item referenced by identifier-5 is set to literal-3 or the current value of the data item referenced by identifier-6.

         After the contents of the data items referenced by the identifiers have been set, condition-1 is evaluated; if true, control is transferred to the end of the PERFORM statement; if false, condition-2 is evaluated. If condition-2 is false, the specified set of statements is executed once, then the content of the data item referenced by identifier-5 is augmented by literal-4 or the content of the data item referenced by identifier-7 and condition-2 is evaluated again.

         

         Figure 4-2: The VARYING Option of a PERFORM Statement with the TEST BEFORE Phrase Having Two Conditions

         This cycle of evaluation and augmentation continues until this condition is true. When condition-2 is true, the content of the data item referenced by identifier-2 is augmented by literal-2 or the content of the data item referenced by identifier-4, the content of the data item referenced by identifier-5 is set to literal-3 or the current value of the data item referenced by identifier-6, and condition-1 is reevaluated. The PERFORM statement is completed if condition-1 is true; if not, the cycle continues until condition-1 is true.

         At the termination of the PERFORM statement, the data item referenced by identifier-5 contains literal-3 or the current value of the data item referenced by identifier-6. The data item referenced by identifier-2 contains a value that exceeds the last used setting by one increment or decrement value, unless condition-1 was true when the PERFORM statement was entered, in which case the data item referenced by identifier-2 contains literal-1 or the current value of the data item referenced by identifier-3.

      2. If the TEST AFTER phrase is specified:

         When the data item referenced by one identifier is varied, the content of the data item referenced by identifier-2 is set to literal-1 or the current value of the data item referenced by identifier-3 at the point of execution of the PERFORM statement; then the specified set of statements is executed once and condition-1 of the UNTIL phrase is tested. If the condition is false, the value of the data item referenced by identifier-2 is augmented by the specified increment or decrement value (literal-2 or the value of the data item referenced by identifier-4) and the specified set of statements is executed again. The cycle continues until condition-1 is tested and found to be true, at which point control is transferred to the end of the PERFORM statement.

         When the data items referenced by two identifiers are varied, the content of the data item referenced by identifier-2 is set to literal-1 or the current value of the data item referenced by identifier-3; then the current value of the data item referenced by identifier-5 is set to literal-3 or the current value of the data item referenced by identifier-6; and the specified set of statements is then executed. Condition-2 is then evaluated; if false, the content of the data item referenced by identifier-5 is augmented by literal-4 or the content of the data item referenced by identifier-7 and the specified set of statements is again executed. The cycle continues until condition-2 is again evaluated and found to be true, at which time condition-1 is evaluated. If false, the content of the data item referenced by identifier-2 is augmented by literal-2 or the content of data item referenced by identifier-4, the content of the data item referenced by identifier-5 is set to literal-3 or the current value of the data item referenced by identifier-6 and the specified set of statements is again executed. This cycle continues until condition-1 is again evaluated and found to be true, at which time control is transferred to the end of the PERFORM statement.

         

         Figure 4-3: The VARYING Option of a PERFORM Statement with the TEST AFTER Phrase Having One Condition

         After completion of the PERFORM statement, each data item varied by an AFTER or VARYING phrase contains the same value it contained at the end of the most recent execution of the specified set of statements. See Figure 4-4.

         

         Figure 4-4: The VARYING Option of a PERFORM Statement with a TEST AFTER Phrase Having Two Conditions

         During the execution of the specified set of statements associated with the PERFORM statement, any change to the VARYING variable (the data item referenced by identifier-2 and index-name-1), the BY variable (the data item referenced by identifier-4), the AFTER variable (the data item referenced by identifier-5 and index-name-3), or the FROM variable (the data item referenced by identifier-3 and index-name-2) will be taken into consideration and will affect the operation of the PERFORM statement.

         When the data items referenced by two identifiers are varied, the data item referenced by identifier-5 goes through a complete cycle (FROM, BY, UNTIL) each time the content of the data item referenced by identifier-2 is varied. When the contents of three or more data items referenced by identifiers are varied, the mechanism is the same as for two identifiers except that the data item being varied by each AFTER phrase goes through a complete cycle each time the data item being varied by the preceding AFTER phrase is augmented.

9. The range of a PERFORM statement consists logically of all those statements that are executed as a result of executing the PERFORM statement through execution of the explicit transfer of control to the end of the PERFORM statement. The range includes all statements that are executed as the result of a transfer of control by CALL, EXIT, GO TO and PERFORM statements in the range of the PERFORM statement, as well as all statements in declarative procedures that are executed as a result of the execution of statements in the range of the PERFORM statement. The statements in the range of a PERFORM statement need not appear consecutively in the source program.

10. Statements executed as the result of a transfer of control caused by executing an EXIT PROGRAM statement are not considered to be part of the range of the PERFORM statement when:
    1. the EXIT PROGRAM statement is specified in the same program in which the PERFORM statement is specified, and

    2. the EXIT PROGRAM statement is within the range of the PERFORM statement.

11. If the range of a PERFORM statement includes another PERFORM statement, the sequence of procedures associated with the included PERFORM should itself either be totally included in, or totally excluded from, the logical sequence referred to by the first PERFORM. Thus, an active PERFORM statement, whose execution point begins within the range of another active PERFORM statement should not allow control to pass to the exit of the other active PERFORM statement; furthermore, two or more such active PERFORM statements should not have a common exit.

    These restrictions are not enforced. PERFORM statements can be freely nested, and recursion (a PERFORM statement performing a procedure containing it) is allowed. Only the exit point of the innermost PERFORM statement currently being executed is recognized. These rules can be changed by use of the PERFORM-TYPE Compiler directive.

    See the following illustrations for examples of legal PERFORM constructs.

    

12. A PERFORM statement that appears in a section that is not in an independent segment can have within its range, in addition to any declarative sections whose execution is caused within that range, one of the following:
    1. Sections and/or paragraphs wholly contained in one or more non-independent segments.

    2. Sections and/or paragraphs wholly contained in a single independent segment.

    These restrictions do not apply.

13. A PERFORM statement that appears in an independent segment can have within its range, in addition to any declarative sections whose execution is caused within that range, only one of the following:
    1. Sections and/or paragraphs wholly contained in one or more non-independent segments.

    2. Sections and/or paragraphs wholly contained in the same independent segment as that PERFORM statement.

    These restrictions do not apply.

Format 4

14. The data items referenced by identifier-4 and identifier-7 must not have a zero value.

15. If an index-name is specified in the VARYING or AFTER phrase, and an identifier is specified in the associated FROM phrase, the data item referenced by the identifier must have a positive value.

4.6.42 The READ Statement

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.

General Formats

Format 1 (Record Sequential Files)

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 Compiler directives which provide flagging and modify the reserved word list, the following directive may impact either the syntax or semantics described in this section.
   • 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.
   • 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.

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

   This rule is not enforced.

Formats 1, 3, 4 and 5 (Record Sequential, Relative and Indexed Files)

4. The WITH LOCK phrase can be included only when single records are being locked manually in a shareable file.

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

   phrases must be specified for files in dynamic access mode when records are to be retrieved sequentially.

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.

   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.

   The redefinition may have a different length from the record key.

10. Data-name can be qualified.

11. 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 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:
   1. 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.)

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

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

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

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

      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:
   1. The standard ending reel/unit label procedure.

   2. A reel/unit swap.

   3. The standard beginning reel/unit label procedure.

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

13. For files opened for I/O:
    1. With LOCK MODE AUTOMATIC, unless the WITH NO LOCK phrase is specified, each record is locked as it is read.

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

    3. 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. 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:
    1. The file position indicator is set and the I/O status associated with file-name-1 is updated.

    2. 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.)

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

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

    The NOT AT END phrase is only executed following successful completion of the operation.

19. 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,

    the next Format 3 READ statement, if any, executed for that file must be a READ NEXT statement, if AT END occurred because no previous logical record existed. Otherwise

    the AT END condition must be followed by:

    1. A successful CLOSE statement followed by the execution of a successful OPEN statement for that file.

    2. A successful START statement for that file.

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

22. The record to be made available by the READ statement is determined as follows:
    1. 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

       existing record within the established key of reference, and that record is then made available.

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

       existing record in the file.

       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.

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

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

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

4.6.43 The RELEASE Statement

The RELEASE statement transfers records to the initial phase of a SORT operation.

General Format

Syntax Rules

1. A RELEASE statement can only be used within the range of an input procedure associated with a SORT statement for a file whose sort-merge file description entry contains record-name. (See the section The SORT Statement in this chapter.)

2. Record-name must be the name of a logical record in the associated sort-merge file description entry and can be qualified.

3. If identifier is a function-identifier, it must reference an alphanumeric function. When identifier is not a function-identifier,

   record-name and identifier must not reference the same storage area.

4. Record-name can be defined as a floating-point item.

5. Identifier can be a floating-point item.

General Rules

1. The execution of a RELEASE statement causes the record named by record-name to be released to the initial phase of a sort operation.

2. If the FROM phrase is used, the contents of the identifier data area are moved to record-name, then the contents of record-name are released to the sort file. Moving records takes place according to the rules specified for the MOVE statement without the CORRESPONDING phrase. The information in the record area is no longer available, but the information in the data area associated with identifier is available.

3. After the execution of the RELEASE statement, the logical record is no longer available in the record area unless the associated sort-merge file is named in a SAME RECORD AREA clause. The logical record is also available to the program as a record of other files referenced in the same SAME RECORD AREA clause as the associated sort-merge file, as well as to the file associated with record-name. When control passes from the input procedure, the file consists of all those records which were placed in it by the execution of RELEASE statements.

4.6.44 The RETURN Statement

The RETURN statement obtains either sorted records from the final phase of a SORT operation or merged records during a MERGE operation.

General Format

Syntax Rules

1. File-name must be described by a sort-merge file description entry in the Data Division.

2. A RETURN statement can only be used within the range of an output procedure associated with a SORT or MERGE statement for file-name.

3. 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 and the record area associated with file-name must not be the same storage area.

4. Identifier-1 can be a floating-point item.

General Rules

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

2. The execution of the RETURN statement causes the next existing record in the file referenced by file-name, as determined by the keys listed in the SORT or MERGE statement, to be made available in the record area associated with file-name. If no next logical record exists in the file referenced by file-name, the at end condition exists and control is transferred to imperative-statement-1 of the AT END phrase. Execution continues according to the rules for each statement specified in imperative-statement-1. If a procedure branching or conditional statement which causes explicit transfer of control is executed, control is transferred according to the rules for that statement. Otherwise, upon completion of the execution of imperative-statement-1, control is transferred to the end of the RETURN statement

   and the NOT AT END phrase if specified is ignored.

   When the at end condition occurs, execution of the RETURN statement is unsuccessful and the contents of the record area associated with file-name are undefined. After the execution of imperative-statement-1 in the AT END phrase, no RETURN statement can be executed as part of the current output procedure.

3. If an at end condition does not occur during the execution of a RETURN statement, then after the record is made available and after executing any implicit move resulting from the presence of an INTO phrase, control is transferred to imperative-statement-2, if specified. Otherwise, control is transferred to the end of the RETURN statement.

4. The END-RETURN phrase delimits the scope of the RETURN statement.

5. The INTO phrase can be specified in a RETURN statement:
   1. If only one record description is subordinate to the sort-merge file description entry, or:

   2. If all record-names associated with file-name and the data item referenced by identifier describe a group item or an elementary alphanumeric-item.

6. The result of the execution of a RETURN statement with the INTO phrase is equivalent to the application of the following rules in the order specified:

   1. The execution of the same RETURN statement without the INTO phrase.

   2. The current record is moved from the record area to the area specified by identifier according to the rules for the MOVE statement without the CORRESPONDING phrase. The size of the current record is determined by rules specified for the RECORD clause. If the file description entry contains a RECORD IS VARYING clause, the implied move is a group move. The implied MOVE 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. The record is available in both the record area and the data item referenced by identifier-1.