Enterprise COBOL for z/OS, V4.2, Language Reference

PERFORM statement

The PERFORM statement transfers control explicitly to one or more procedures and implicitly returns control to the next executable statement after execution of the specified procedures is completed.

The PERFORM statement is:

An out-of-line PERFORM statement
When procedure-name-1 is specified.
An in-line PERFORM statement
When procedure-name-1 is omitted.

An in-line PERFORM must be delimited by the END-PERFORM phrase.

The in-line and out-of-line formats cannot be combined. For example, if procedure-name-1 is specified, imperative statements and the END-PERFORM phrase must not be specified.

The PERFORM statement formats are:

Basic PERFORM statement

The procedures referenced in the basic PERFORM statement are executed once, and control then passes to the next executable statement following the PERFORM statement.

Note: A PERFORM statement must not cause itself to be executed. A recursive PERFORM statement can cause unpredictable results.

Read syntax diagramSkip visual syntax diagram
Format 1: Basic PERFORM statement

>>-PERFORM------------------------------------------------------>

>--+-procedure-name-1--+-------------------------------+-+-----><
   |                   '-+-THROUGH-+--procedure-name-2-' |   
   |                     '-THRU----'                     |   
   '-+------------------------+--END-PERFORM-------------'   
     '-imperative-statement-1-'                              

procedure-name-1 , procedure-name-2
Must name a section or paragraph in the procedure division.

When both procedure-name-1 and procedure-name-2 are specified, if either is a procedure-name in a declarative procedure, both must be procedure-names in the same declarative procedure.

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

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

imperative-statement-1
The statements to be executed for an in-line PERFORM

An in-line PERFORM statement functions according to the same general rules as an otherwise identical out-of-line PERFORM statement, except that statements contained within the in-line PERFORM 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 the word out-of-line, all the rules that apply to the out-of-line PERFORM statement also apply to the in-line PERFORM.

Whenever an out-of-line PERFORM statement is executed, control is transferred to the first statement of the procedure named procedure-name-1. Control is always returned to the statement following the PERFORM statement. The point from which this control is returned is determined as follows:

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

The only necessary relationship between procedure-name-1 and procedure-name-2 is that a consecutive sequence of operations is executed, beginning at the procedure named by procedure-name-1 and ending with the execution of the procedure named by procedure-name-2.

PERFORM statements can be specified within the performed procedure. If there are two or more logical paths to the return point, then procedure-name-2 can name a paragraph that consists only of an EXIT statement; all the paths to the return point must then lead to this paragraph.

When the performed procedures include another PERFORM statement, the sequence of procedures associated with the embedded PERFORM statement must be totally included in or totally excluded from the performed procedures of the first PERFORM statement. That is, an active PERFORM statement whose execution point begins within the range of performed procedures of another active PERFORM statement must not allow control to pass through the exit point of the other active PERFORM statement. However, two or more active PERFORM statements can have a common exit.

The following figure illustrates valid sequences of execution for PERFORM statements.

This figure shows valid PERFORM statement execution sequences.
Link to detail.

When control passes to the sequence of procedures by means other than a PERFORM statement, control passes through the exit point to the next executable statement, as if no PERFORM statement referred to these procedures.

END-PERFORM

Delimits the scope of the in-line PERFORM statement. Execution of an in-line PERFORM is completed after the last statement contained within it has been executed.

PERFORM with TIMES phrase

The procedures referred to in the TIMES phrase of the PERFORM statement are executed the number of times specified by the value in identifier-1 or integer-1, up to a maximum of 999,999,999 times. Control then passes to the next executable statement following the PERFORM statement.

Read syntax diagramSkip visual syntax diagram
Format 2: PERFORM statement with TIMES phrase

>>-PERFORM------------------------------------------------------>

>--+-procedure-name-1--+-------------------------------+--+-identifier-1-+--TIMES-+-><
   |                   '-+-THROUGH-+--procedure-name-2-'  '-integer-1----'        |   
   |                     '-THRU----'                                              |   
   '-+-identifier-1-+--TIMES--+------------------------+--END-PERFORM-------------'   
     '-integer-1----'         '-imperative-statement-1-'                              

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

identifier-1
Must name an integer item. identifier-1 cannot be a windowed date field.

If identifier-1 is zero or a negative number at the time the PERFORM statement is initiated, control passes to the statement following the PERFORM statement.

After the PERFORM statement has been initiated, any change to identifier-1 has no effect in varying the number of times the procedures are initiated.

integer-1
Can be a positive signed integer.

PERFORM with UNTIL phrase

In the UNTIL phrase format, the procedures referred to are performed until the condition specified by the UNTIL phrase is true. Control is then passed to the next executable statement following the PERFORM statement.

Read syntax diagramSkip visual syntax diagram
Format 3: PERFORM statement with UNTIL phrase

>>-PERFORM------------------------------------------------------>

>--+-procedure-name-1--+-------------------------------+--| phrase 1 |-+-><
   |                   '-+-THROUGH-+--procedure-name-2-'               |   
   |                     '-THRU----'                                   |   
   '-| phrase 1 |--+------------------------+--END-PERFORM-------------'   
                   '-imperative-statement-1-'                              

phrase 1

|--+----------------------------+--UNTIL--condition-1-----------|
   '-+------+--TEST--+-BEFORE-+-'                       
     '-WITH-'        '-AFTER--'                         

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

condition-1
Can be any condition described under Conditional expressions. If the condition is true at the time the PERFORM statement is initiated, the specified procedures are not executed.

Any subscripting associated with the operands specified in condition-1 is evaluated each time the condition is tested.

If the TEST BEFORE phrase is specified or assumed, the condition is tested before any statements are executed (corresponds to DO WHILE).

If the TEST AFTER phrase is specified, the statements to be performed are executed at least once before the condition is tested (corresponds to DO UNTIL).

In either case, if the condition is true, control is transferred to the next executable statement following the end of the PERFORM statement. If neither the TEST BEFORE nor the TEST AFTER phrase is specified, the TEST BEFORE phrase is assumed.

PERFORM with VARYING phrase

The VARYING phrase increases or decreases the value of one or more identifiers or index-names, according to certain rules. (See Varying phrase rules.)

The format-4 VARYING phrase PERFORM statement can serially search an entire seven-dimensional table.

Read syntax diagramSkip visual syntax diagram
Format 4: PERFORM statement with VARYING phrase

>>-PERFORM------------------------------------------------------>

>--+-procedure-name-1--+-------------------------------+--| phrase 1 |--| phrase 2 |-+-><
   |                   '-+-THROUGH-+--procedure-name-2-'                             |   
   |                     '-THRU----'                                                 |   
   '-| phrase 1 |--+------------------------+--END-PERFORM---------------------------'   
                   '-imperative-statement-1-'                                            

phrase 1

|--+----------------------------+--VARYING--+-identifier-2-+---->
   '-+------+--TEST--+-BEFORE-+-'           '-index-name-1-'   
     '-WITH-'        '-AFTER--'                                

>--FROM--+-identifier-3-+--BY--+-identifier-4-+--UNTIL---------->
         +-index-name-2-+      '-literal-2----'          
         '-literal-1----'                                

>--condition-1--------------------------------------------------|

phrase 2

   .---------------------------------------------------------------.   
   V                                                               |   
|----AFTER--+-identifier-5-+--FROM--+-identifier-6-+--| phrase 3 |-+--|
            '-index-name-3-'        +-index-name-4-+                   
                                    '-literal-3----'                   

phrase 3

|--BY--+-identifier-7-+--UNTIL--condition-2---------------------|
       '-literal-4----'                       

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

identifier-2 through identifier-7
Must name a numeric elementary item. These identifiers cannot be windowed date fields.
literal-1 through literal-4
Must represent a numeric literal.
condition-1, condition-2
Can be any condition described under Conditional expressions. If the condition is true at the time the PERFORM statement is initiated, the specified procedures are not executed.

After the conditions specified in the UNTIL phrase are satisfied, control is passed to the next executable statement following the PERFORM statement.

If any of the operands specified in condition-1 or condition-2 is subscripted, reference modified, or is a function-identifier, the subscript, reference-modifier, or function is evaluated each time the condition is tested.

Floating-point data items and literals can be used anywhere a numeric data item or literal can be specified.

When TEST BEFORE is indicated, all specified conditions are tested before the first execution, and the statements to be performed are executed, if at all, only when all specified tests fail. When TEST AFTER is indicated, the statements to be performed are executed at least once, before any condition is tested.

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

Varying identifiers

The way in which operands are increased or decreased depends on the number of variables specified. In the following discussion, every reference to identifier-n refers equally to index-name-n (except when identifier-n is the object of the BY phrase).

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 an augmenting operation.

The following figure illustrates the logic of the PERFORM statement when an identifier is varied with TEST BEFORE.

This figure illustrates a PERFORM statement, varying one identifier with TEST BEFORE.
Link to detail.

The following figure illustrates the logic of the PERFORM statement when an identifier is varied with TEST AFTER.

This figure illustrates a PERFORM statement, varying one identifier with TEST AFTER.
Link to detail.

Varying two identifiers

PERFORM PROCEDURE-NAME-1 THROUGH PROCEDURE-NAME-2
      VARYING IDENTIFIER-2 FROM IDENTIFIER-3
            BY IDENTIFIER-4 UNTIL CONDITION-1
         AFTER IDENTIFIER-5 FROM IDENTIFIER-6
            BY IDENTIFIER-7 UNTIL CONDITION-2
  1. identifier-2 and identifier-5 are set to their initial values, identifier-3 and identifier-6, respectively.
  2. condition-1 is evaluated as follows:
    1. If it is false, steps 3 through 7 are executed.
    2. If it is true, control passes directly to the statement following the PERFORM statement.
  3. condition-2 is evaluated as follows:
    1. If it is false, steps 4 through 6 are executed.
    2. If it is true, identifier-2 is augmented by identifier-4, identifier-5 is set to the current value of identifier-6, and step 2 is repeated.
  4. procedure-name-1 and procedure-name-2 are executed once (if specified).
  5. identifier-5 is augmented by identifier-7.
  6. Steps 3 through 5 are repeated until condition-2 is true.
  7. Steps 2 through 6 are repeated until condition-1 is true.

At the end of PERFORM statement execution:

  • identifier-5 contains the current value of identifier-6.
  • identifier-2 has a value that exceeds the last-used setting by the increment or decrement value (unless condition-1 was true at the beginning of PERFORM statement execution, in which case, identifier-2 contains the current value of identifier-3).

The following figure illustrates the logic of the PERFORM statement when two identifiers are varied with TEST BEFORE.

This figure illustrates PERFORM varying two identifiers with TEST BEFORE, as described in text above for varying two identifiers.

The following figure illustrates the logic of the PERFORM statement when two identifiers are varied with TEST AFTER.

This figure illustrates a PERFORM statement, varying two identifiers with TEST AFTER.
Link to detail.

Varying three identifiers

PERFORM PROCEDURE-NAME-1 THROUGH PROCEDURE-NAME-2
      VARYING IDENTIFIER-2 FROM IDENTIFIER-3
            BY IDENTIFIER-4 UNTIL CONDITION-1
          AFTER IDENTIFIER-5 FROM IDENTIFIER-6
            BY IDENTIFIER-7 UNTIL CONDITION-2
          AFTER IDENTIFIER-8 FROM IDENTIFIER-9
            BY IDENTIFIER-10 UNTIL CONDITION-3

The actions are the same as those for two identifiers, except that identifier-8 goes through the complete cycle each time that identifier-5 is augmented by identifier-7, which, in turn, goes through a complete cycle each time that identifier-2 is varied.

At the end of PERFORM statement execution:

  • identifier-5 and identifier-8 contain the current values of identifier-6 and identifier-9, respectively.
  • identifier-2 has a value exceeding its last-used setting by one increment/decrement value (unless condition-1 was true at the beginning of PERFORM statement execution, in which case identifier-2 contains the current value of identifier-3).

Varying more than three identifiers

You can produce analogous PERFORM statement actions to the example above with the addition of up to four AFTER phrases.

Varying phrase rules

No matter how many variables are specified, the following rules apply:

  • In the VARYING or AFTER phrases, when an index-name is specified:
    • The index-name is initialized and incremented or decremented according to the rules under INDEX phrase. (See also SET statement.)
    • In the associated FROM phrase, an identifier must be described as an integer and have a positive value; a literal must be a positive integer.
    • In the associated BY phrase, an identifier must be described as an integer; a literal must be a nonzero integer.
  • In the FROM phrase, when an index-name is specified:
    • In the associated VARYING or AFTER phrase, an identifier must be described as an integer. It is initialized as described in the SET statement.
    • In the associated BY phrase, an identifier must be described as an integer and have a nonzero value; a literal must be a nonzero integer.
  • In the BY phrase, identifiers and literals must have nonzero values.
  • Changing the values of identifiers or index-names in the VARYING, FROM, and BY phrases during execution changes the number of times the procedures are executed.


Rate this page

[ Index | Table of contents ]