Compaq COBOL
Reference Manual
Previous Contents Index

Technical Notes

Additional References

6.8.25 PERFORM

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

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

Format 4

  1. If there is no first-proc, there can be no AFTER phrase.
  2. If var is an index-name:
  3. If init is an index-name:

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:
  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:
  10. A PERFORM statement in a fixed 6 segment can have only one of the following in its range:
    However, the PERFORM statement range also includes any Declarative procedures activated during its execution.
  11. A PERFORM statement in an independent 1 segment can have only one of the following in its range:
    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:
    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

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

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

  1. The statement sets execute until cond is true. Control then transfers to the end of the PERFORM statement.
  2. If cond is true when the PERFORM statement executes:

Format 4

  1. The Format 4 PERFORM statement systematically changes the value of var during its execution.
  2. 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.
  3. 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.
  4. increm must not be zero.
  5. init must be positive when var is an index-name and init is an identifier.
  6. If there is a TEST BEFORE phrase (or one is implied), and one var is varied (see Figure 6-3):

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

  7. If there is a TEST BEFORE phrase (or one is implied), and the PERFORM statement has two vars (see Figure 6-4):

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

  8. At the end of a PERFORM statement with the TEST BEFORE phrase:
  9. If there is a TEST AFTER phrase and one var is varied (see Figure 6-5):

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

  10. If there is a TEST AFTER phrase, and two vars are varied (see Figure 6-6):

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

  11. 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.
  12. During execution of the sets of statements in the range, any change to var, increm, or init affects PERFORM statement operation.
  13. 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

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

6.8.26 READ

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


    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.<>
    On Windows NT, the REGARDLESS option for sequential and relative files is not supported. If a locked record is encountered, a hard-lock condition exists (file status 92).<>
    However, on Tru64 UNIX and Windows NT ) 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.
    However, on Windows NT systems there are no read-locks available. The READERS option puts a lock on the record, and no other access stream can access the record. <>
    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.

Note

6 Segmentation is described in Section 6.7. Compaq COBOL supports segmentation for compatibility with existing applications only. Compaq recommends that you do not use segmentation in new applications.

Previous Next Contents Index