Compaq COBOL
Reference Manual

Technical Notes

• OPEN statement execution can result in these FILE STATUS data item values:

  File Status	Meaning
  00	Open is successful.
  05	Optional file not present.
  07	No rewind on non-reel device.
  35	File not found.
  37	An open in I-O mode is attempted for a nonmass storage file, or an open is attempted for nonmass storage file that was declared as a relative or indexed file.
  38	An open is attempted on a file closed with lock.
  39	A mismatch exists between the current program's description of an index key and the existent file's description of the key, or (for OpenVMS Alpha systems) there is a conflict of maximum record size or record type.
  41	File is already open
  91	Open is unsuccessful; file locked by another access stream.
  95	No file space on device.
  30	All other permanent errors.

  
  You must use the I-O-CONTROL statement APPLY PREALLOCATION with a value greater than 0 (the default is 0) to enable the detection of "device full" (file status 95) with the OPEN statement.
• Attempts to specify both X/Open standard and Compaq standard file-sharing syntax for the same file connector are invalid. When the compiler cannot detect such attempts because they occur in different compilation units, the run-time system detects and reports the violations (file status 30). This holds for explicit and implicit usage.

Additional References

• LOCK MODE clause in the Section 4.2.1, FILE_CONTROL paragraph in Chapter 4
• Section 4.2.10, I_O_CONTROL paragraph in Chapter 4
• Section 6.8.6, CLOSE statement
• Section 6.8.42, USE statement

Function

The PERFORM statement executes one or more intra-program procedures. It returns control to the end of the PERFORM statement when all procedures have completed execution.

first-proc

is a procedure-name that identifies a paragraph or section in the Procedure Division. The set of statements in first-proc is the first (or only) set of statements in the PERFORM range.

end-proc

is a procedure-name that identifies a paragraph or section in the Procedure Division. The set of statements in end-proc is the last set of statements in the PERFORM range.

stment

is an imperative statement.

repeat-count

is a numeric integer literal or the identifier of a numeric integer elementary item. It controls how many times the statement set (or sets) executes.

cond

can be any conditional expression.

var

is an index-name or the identifier of a numeric integer elementary data item. Its value is changed by increm each time all statements in the PERFORM range execute.

init

is a numeric literal, index-name, or the identifier of a numeric elementary data item. It specifies the value of var before any statement in the PERFORM range executes.

increm

is a nonzero numeric literal or the identifier of a numeric elementary data item. It systematically changes the value of var each time the program executes all statements in the PERFORM range.

Syntax Rules

All Formats

1. If there is no first-proc, the PERFORM statement must contain stment and the END-PERFORM phrase. If there is a first-proc, the statement cannot have the END-PERFORM phrase.
2. If either first-proc or end-proc is placed in the Declaratives part of the Procedure Division, both must also be placed in the same DECLARATIVES section.
3. The words THRU and THROUGH are equivalent and interchangeable.

Formats 3 and 4

4. If there is no TEST BEFORE or TEST AFTER phrase, TEST BEFORE is the default.

Format 4

5. If there is no first-proc, there can be no AFTER phrase.
6. If var is an index-name:
   • init must be an integer data item or a positive integer literal
   • increm must be an integer data item or a nonzero integer literal
7. If init is an index-name:
   • var must be an integer data item
   • increm must be an integer data item or a positive integer literal

General Rules

All Formats

1. When first-proc appears, the statement is an out-of-line PERFORM statement. Otherwise, it is an in-line PERFORM statement.
2. The statements in the range of first-proc to end-proc for an out-of-line PERFORM are the statement set. For an in-line PERFORM, the statement set is contained within the scope of the PERFORM...END-PERFORM syntax.
3. Unless restricted to in-line or out-of-line statements, all General Rules apply to both types of PERFORM statements. An in-line PERFORM statement operates according to the general rules for an out-of-line PERFORM, except for periods, which are not allowed within the body of the PERFORM. The statements in the in-line PERFORM execute in place of the statements in the range of first-proc to end-proc.
4. When the PERFORM statement executes, control transfers to the first statement of first-proc. However, for Format 2, 3, or 4 PERFORM statements, transfer of control depends on evaluation of the specified condition.
   Transfer of control occurs only once for each PERFORM statement executed. When transfer of control does occur, after the statement set executes, control implicitly transfers back to the to the end of the perform statement as follows:
   • If first-proc is a paragraph-name and there is no end-proc, the return is after the last statement of first-proc.
   • If first-proc is a section-name and there is no end-proc, the return is after the last statement of the last paragraph of first-proc.
   • If end-proc is a paragraph-name, the return is after the last statement of end-proc.
   • If end-proc is a section-name, the return is after the last statement of the last paragraph of end-proc.
   • If the statement is an in-line PERFORM, execution ends after the last statement of the statement set.
5. first-proc and end-proc need not be related except that first-proc is the beginning and end-proc is the last in a consecutive series of operations.
   GO TO and PERFORM statements can occur between first-proc and end-proc. If there are two or more logical paths to the return point, end-proc can be a paragraph, consisting of the EXIT statement, to which all these paths must lead.
6. If a statement other than a PERFORM statement, transfers control to the statement set, at the end of the statement set, control transfers through the last statement of the set to the next executable statement following the set as if no PERFORM statement referenced the set.
7. The range of a PERFORM statement consists of all statements executed as a result of executing the PERFORM. It continues through execution of the implicit control transfer to the end of the PERFORM statement.
8. The range of the PERFORM statement additionally includes all statements executed as a result of a CALL, EXIT, GO TO, or PERFORM statement. The range the PERFORM statement also includes all statements in the Declaratives Section that can be executed if control is transferred from statements in the range of the PERFORM statement.
9. Statements executed as the result of a control transfer caused by an EXIT PROGRAM statement are not part of the range when:
   • The EXIT PROGRAM statement is specified in the same program as the PERFORM statement, and
   • The EXIT PROGRAM statement is within the range of the PERFORM statement.
10. A PERFORM statement in a fixed ⁶ segment can have only one of the following in its range:
    • Sections and paragraphs completely contained in one or more nonindependent segments
    • Sections and paragraphs completely contained in one independent segment
    
    However, the PERFORM statement range also includes any Declarative procedures activated during its execution.
11. A PERFORM statement in an independent ¹ segment can have only one of the following in its range:
    • Sections and paragraphs completely contained in one or more nonindependent segments
    • Sections and paragraphs completely contained in the same independent segment as the PERFORM statement itself
    
    However, the PERFORM statement range also includes any Declarative procedures activated during its execution.
12. first-proc and end-proc cannot name sections or paragraphs in any other program in the executable image. Statements in other programs are in a PERFORM statement's range only if the range includes a CALL statement.
13. A PERFORM statement range can contain another PERFORM statement. In that case, the included PERFORM statement's sequence of procedures must be either totally included in, or excluded from, the logical sequence of the first PERFORM statement.
    For example:
    • An active PERFORM statement whose execution point is in the range of another active PERFORM statement must not allow control to pass to the exit of the other active PERFORM.
    • Two or more active PERFORM statements cannot have a common exit.
    
    Use the check compiler option with the perform keyword to verify at run time that there is no recursive activation of a PERFORM.
    Figure 6-2 shows valid and invalid nested PERFORM statements.
14. Undocumented results might occur when end-proc precedes first-proc or when first-proc and end-proc are not in the same program segment.

Figure 6-2 Valid and Invalid Nested PERFORM Statements

Format 1

15. Format 1 is the basic PERFORM statement. The statement sets in the PERFORM range execute once. Control then passes to the end of the PERFORM statement.

Format 2

16. The statement sets execute the number of times specified by repeat-count. If the value of repeat-count is zero or negative when the PERFORM statement executes, control passes to the end of the PERFORM statement.
    During PERFORM statement execution, changing the value of repeat-count does not change the number of times the statement sets execute.

Format 3

17. The statement sets execute until cond is true. Control then transfers to the end of the PERFORM statement.
18. If cond is true when the PERFORM statement executes:
    • If there is a TEST BEFORE phrase or one is implied, there is no transfer to first-proc; control passes to the end of the PERFORM statement.
    • If there is a TEST AFTER phrase, the PERFORM statement tests cond after the statement set executes.

Format 4

19. The Format 4 PERFORM statement systematically changes the value of var during its execution.
20. If var is an index-name, its value, when the PERFORM statement execution begins, must equal the occurrence number of an element in its table.
21. If init is an index-name, var must equal the occurrence number of an element in the table associated with init. As the value of the var index changes during PERFORM execution, it cannot contain a value outside the range of its table. However, when the PERFORM statement ends, the var index can contain a value outside the range of the table by one increment or decrement value.
22. increm must not be zero.
23. init must be positive when var is an index-name and init is an identifier.
24. If there is a TEST BEFORE phrase (or one is implied), and one var is varied (see Figure 6-3):
    • var is set to the value of init when the PERFORM statement begins to execute.
    • If cond is false, the statement set executes once. The value of var changes by the increment or decrement value (increm), and cond is evaluated again. This cycle continues until cond is true. Control then transfers to the end of the PERFORM statement.
    • If cond is true when the PERFORM statement begins executing, control transfers to the end of the PERFORM statement.

    Figure 6-3 PERFORM ... VARYING with the TEST BEFORE Phrase and One Condition

    ---

    
25. If there is a TEST BEFORE phrase (or one is implied), and the PERFORM statement has two vars (see Figure 6-4):
    • The first and second vars are set to the value of the first and second init when the PERFORM statement begins to execute.
    • If the first cond is true, control transfers to the end of the PERFORM statement.
    • If the second cond is false, the statement set executes once. The second var changes by the value of increm, and the second cond is evaluated again. This cycle continues until the second cond is true.
    • When the second cond is true, the value of the first var changes by the value of the first increm, and the second var is set to the value of the second init. The first cond is reevaluated. The PERFORM statement ends if the first cond is true. Otherwise, the cycle continues until cond is true.

    Figure 6-4 PERFORM ... VARYING with the TEST BEFORE Phrase and Two Conditions

    ---

    
26. At the end of a PERFORM statement with the TEST BEFORE phrase:
    • The value of the first var exceeds the last-used value by one increment or decrement value. However, if cond was true when the PERFORM statement began, var contains the current value of init.
    • The value of each other var equals the current value of its associated init.
27. If there is a TEST AFTER phrase and one var is varied (see Figure 6-5):
    • var is set to the value of init when the PERFORM statement starts to execute.
    • The statement set executes once. Then, cond is evaluated. If it is false, the value of var changes by the increment or decrement value (increm), and the statement set executes again. This cycle continues until cond is true. Control then transfers to the end of the PERFORM statement.

    Figure 6-5 PERFORM ... VARYING with the TEST AFTER Phrase and One Condition

    ---

    

28. If there is a TEST AFTER phrase, and two vars are varied (see Figure 6-6):
    • The first and second vars are set to the value of the first and second init when the PERFORM statement starts to execute.
    • The statement set executes. The second cond is then evaluated. If it is false, the second var changes by the value of increm, and the statement set executes again. This cycle continues until the second cond is true.
    • When the second cond is true, the first cond is evaluated. If it is false, the value of the first var changes by the value of the first increm, the second var is set to the value of the second init, and the statement set executes again. The PERFORM statement ends if the first cond is true. Otherwise, the cycle continues until cond is true.

    Figure 6-6 PERFORM ... VARYING with the TEST AFTER Phrase and Two Conditions

    ---

    
29. At the end of a PERFORM statement with the TEST AFTER phrase, the value of each var is the same as at the end of the most recent statement set execution.
30. During execution of the sets of statements in the range, any change to var, increm, or init affects PERFORM statement operation.
31. When there is more than one var, var in each AFTER phrase goes through a complete cycle each time var in the preceding AFTER (or VARYING) phrase is varied.

Additional References

• Section 6.1.4, Scope of Statements
• Section 6.5, Conditional Expressions
• Section 6.8.32, SET statement
• Online help, check compiler option

Examples

In the examples' results, s represents a space. The examples assume these Data Division and Procedure Division entries:

DATA DIVISION. WORKING-STORAGE SECTION. 01 ITEMA VALUE "ABCDEFGHIJ". 03 CHARA OCCURS 10 TIMES PIC X. 01 ITEMB VALUE SPACES. 03 CHARB OCCURS 10 TIMES PIC X. 01 ITEMC PIC 99 VALUE 1. 01 ITEMD PIC 99 VALUE 7. 01 ITEME PIC 99 VALUE 4. 01 ITEMF VALUE SPACES. 03 ITEMG OCCURS 4 TIMES. 05 ITEMH OCCURS 5 TIMES. 07 ITEMI PIC 99. PROCEDURE DIVISION. . . . PROC-A. MOVE CHARA (ITEMC) TO CHARB (ITEMC). PROC-B. MOVE CHARA (ITEMC) TO CHARB (10). PROC-C. ADD 2 TO ITEMC. PROC-D. MULTIPLY ITEMC BY ITEMD GIVING ITEMI (ITEMC, ITEMD).

1. Performing one procedure (Format 1):

   PERFORM PROC-A.

   
   ITEMB = Asssssssss

2. Performing a range of procedures (Format 1):

   PERFORM PROC-A THRU PROC-B.

   
   ITEMB = AssssssssA

3. Performing a range of procedures (Format 2):

   PERFORM PROC-A THRU PROC-C 3 TIMES.

   
   ITEMB = AsCsEssssE
   ITEMC = 07

4. Performing a range of procedures (Format 4):

   PERFORM PROC-A THRU PROC-B VARYING ITEMC FROM 1 BY 1 UNTIL ITEMC > 5.

   
   ITEMB = ABCDEssssE
   ITEMC = 06

5. Testing the UNTIL condition after execution (Format 4):

   PERFORM PROC-A THRU PROC-B TEST AFTER VARYING ITEMC FROM 1 BY 1 UNTIL ITEMC > 5.

   
   ITEMB = ABCDEFsssF
   ITEMC = 06

6. Performing a range of procedures varying a data item by a negative amount (Format 4):

   PERFORM PROC-A THRU PROC-B VARYING ITEMC FROM ITEMD BY -1 UNTIL ITEMC < ITEME.

   
   ITEMB = sssDEFGssD
   ITEMC = 03

7. In-line PERFORM (Format 4):

   PERFORM VARYING ITEMC FROM 1 BY 2 UNTIL ITEMC > 7 MOVE CHARA (ITEMC) TO CHARB (ITEMC) MOVE CHARA (ITEMC) TO CHARB (ITEMC + 3) END-PERFORM.

   
   ITEMB = AsCAECGEsG

8. Varying two data items (Format 4):

   PERFORM PROC-D VARYING ITEMC FROM 1 BY 1 UNTIL ITEMC > 4 AFTER ITEMD FROM 1 BY 1 UNTIL ITEMD > 5.

   
   ITEMG (1) = 01s02s03s04s05s
   ITEMG (2) = 02s04s06s08s10s
   ITEMG (3) = 03s06s09s12s15s
   ITEMG (4) = 04s08s12s16s20s

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, the WITH [NO] LOCK phrase is X/Open standard syntax. It is invalid to specify both X/Open standard and Compaq 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 Compaq 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 Compaq 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 Compaq 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 Compaq 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.