PERFORM Statement (COBOL)

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

The PERFORM statement is used to process each element of an array.

See also the section The EXIT Statement.

General Formats for Format 1 (Out-of-Line PERFORM)

General Formats for Format 2 (Inline PERFORM)

Syntax for General Formats for Format 2 (Inine PERFORM) for the PERFORM statement

General Formats for Format 3

Directives

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

Syntax Rules for All Formats

Each identifier represents a numeric elementary item described in the Data Division. identifier-1 must be described as a numeric integer.
Floating-point data items and literals can be used anywhere a numeric data item or literal can be specified. They cannot be used where an integer is required.
If the TEST phrase is specified, the EXIT phrase must not be specified.
If neither the TEST BEFORE nor the TEST AFTER phrase is specified, the TEST BEFORE phrase is assumed.
condition-1, condition-2, condition-3, and condition-4 can be any conditional expression. (See the section Conditional Expressions in the chapter Procedure Division)
Each literal represents a numeric literal.
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.
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.
The literal in the BY phrase must not be zero.
Two AFTER phrases are permitted in the PERFORM statement.
Six AFTER phrases are permitted in the PERFORM statement.

This limit is raised to fifteen.

Syntax Rules for Format 1

The words THROUGH and THRU are equivalent.
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.

Syntax Rules for Format 3

Identifier-9 must either be a .NET or a Java array or an instance of a collection class, i.e. a class that implements the System.IEnumerable interface (.NET) or the java.lang.Iterable interface (JVM). Examples of such collection classes are the List and Dictionary classes.
It must be possible to perform a casting operation from the element type of identifier-9 to the type of identifier-8.

General Rules for Format 1

The statements contained within the range of procedure-name-1 (through procedure-name-2 if specified) are referred to as the specified set of statements.
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, 8d and 8e). 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 topic.
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.
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.

General Rules for Format 2

The statements contained in the PERFORM statement itself are referred to as the specified set of statements.
The END-PERFORM phrase delimits the scope of the in-line PERFORM statement. (See the topic Explicit and Implicit Scope Terminators in the chapter Concepts of the COBOL Language.)
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.
When the PERFORM statement is executed, control is transferred to the first statement of the specified set of statements (except as indicated in the General Rules 2b, 2c, 2d and 2e). 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. An EXIT PERFORM statement can be used to exit an in-line perform before executing all statements within the in-line perform.

General Rules for Formats 1 and 2

If control passes to the specified set of statements by means other than a PERFORM statement, control passes through the last statement of the set to the next executable statement as if no PERFORM statement referenced the set.
The PERFORM statements operate as follows:
1. In 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. If you use the PERFORM ... TIMES form, 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. If you use the PERFORM ... UNTIL form, 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-2 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. If you use the PERFORM ... VARYING form, 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-2 or condition-4 is evaluated each time the condition is tested.
  
  Representations of the actions of several types of 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-2 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-2 is true at the beginning of execution of the PERFORM statement, control is transferred to the end of the PERFORM statement. See the diagram below.
    
    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. See the diagram of The VARYING Option of a PERFORM Statement with the TEST BEFORE Phrase Having Two Conditions below.
    
    After the contents of the data items referenced by the identifiers have been set, condition-2 is evaluated; if true, control is transferred to the end of the PERFORM statement; if false, condition-4 is evaluated. If condition-4 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-4 is evaluated again.
    
    This cycle of evaluation and augmentation continues until this condition is true. When condition-4 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-2 is reevaluated. The PERFORM statement is completed if condition-2 is true; if not, the cycle continues until condition-2 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-2 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.
    
    Figure 1.
  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-2 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-2 is tested and found to be true, at which point control is transferred to the end of the PERFORM statement. See the diagram below.
    
    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-4 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-4 is again evaluated and found to be true, at which time condition-2 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-2 is again evaluated and found to be true, at which time control is transferred to the end of the PERFORM statement. See the diagram The VARYING Option of a PERFORM Statement with a TEST AFTER Phrase Having Two Conditions below.
    
    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.
    
    Figure 2. 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) is taken into consideration and affects 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.
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 element.
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 both of the following conditions apply:
1. The EXIT PROGRAM statement is specified in the same program in which the PERFORM statement is specified
2. The EXIT PROGRAM statement is within the range of the PERFORM statement.
The data items referenced by identifier-4 and identifier-7 must not have a zero value.
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.

The PERFORM Statement