Procedure Definition Language Statements › FOR Statement (Sequential Files) › FOR EACH/FIRST/ANY Statement (Sequential Files)

FOR EACH/FIRST/ANY Statement (Sequential Files)

The FOR EACH, FOR FIRST, and FOR ANY statements process a set of records (or process a single record) from a sequential file. All of the statements in the logical scope of the FOR apply to each selected records from the sequential file defined in the specified dataview.

This statement has the following format:

[<<label>>]
    [EACH            ]
FOR [ALL             ] dataview_name
    [[THE] FIRST [n] ]
    [ANY n           ]
           [WHERE where condition]
                  statements
           [WHEN NONE     ]
           [    statements]
           [WHEN ERROR    ]
           [    statements]
ENDFOR

<<label>>

An optional 1‑ to 15‑character name of the FOR construct. This label refers to the construct in QUIT and PROCESS NEXT statements and as the operand of certain functions such as $COUNT.

EACH|ALL

Indicate that the statements in the scope of the FOR construct apply to every record that satisfies the where condition. You can use the reserved words EACH and ALL interchangeably.

[THE] FIRST [n]

Specifies that the statements in the scope of the FOR construct apply to the first n records that satisfy the where condition. The value specified for n can be an identifier of a numeric field or a numeric literal that specifies the number of records to process. The default is FIRST 1. You can add the reserved word THE for readability.

ANY n

Specifies that the statements in the scope of the FOR construct apply to any n records that satisfy the where condition. The value specified for n can be an identifier of a numeric field or a numeric literal that specifies the number of records to process. N is required for the FOR ANY clause.

For sequential dataviews, ANY n is equivalent to FIRST n.

dataview‑name

The name of the dataview processed.

• WHERE clause(Optional)

  Specifies that the statements in the scope of the FOR construct apply to those records that satisfy the condition.

  where‑condition

  A condition with the following qualifications:

  • If the condition is a condition name, it must be from the dataview referenced.
  • The left‑hand operand of each relational‑expression must be the identifier of a field or alpha‑group in the dataview referenced.
  • If the left‑hand operand is an alphanumeric field, the right‑hand operand must be an alphanumeric expression.
  • If the left‑hand operand is a numeric field, the right‑hand operand can be a numeric expression, an alphanumeric expression, or a non‑alpha group that is not a panel group or dynamic matching parameter. When the right‑hand operand is not a numeric expression, a warning is issued when the program is compiled and, if the right‑hand operand cannot be converted to numeric, a runtime error occurs.
  • The left‑hand operand of a relational‑expression in a where condition need not be qualified as to dataview name since it refers implicitly to the dataview in the FOR clause. However, reserved words used as operands must always be qualified.
  • The right‑hand operand of a relational‑expression can be any arithmetic or alphanumeric expression, but cannot reference any fields in the dataview named in the FOR clause.
  • Simple conditions cannot be Boolean functions or flags.
  • Any subscripts used in the where condition must not be numeric fields in the dataview referenced.

statements

PDL statements. The group of statements in the logical scope of a FOR construct can reference any field in the record processed by the FOR.

WHEN NONE

An optional postscript that specifies that, when none of the records meets the where condition, the statements following the WHEN NONE execute.

WHEN ERROR (Optional)

Specifies statements to be executed when a dataview error is encountered in the scope of the FOR construct. If the WHEN ERROR is not specified, errors are processed by the user‑defined or default error procedure.

The statements specified following a WHEN ERROR clause can access $ERROR functions and should resolve the error with either a PROCESS NEXT or DO ERROR statement. If processing falls through to the ENDFOR, the $ERROR functions are no longer available.

Note: Only dataview errors are handled by the WHEN ERROR clause. System and internal errors are handled by the user‑specified or default error procedure.

ENDFOR

A reserved word that marks the end of the FOR construct. If FOR statements are nested, the most recent unterminated FOR construct is terminated by the first occurrence of ENDFOR. Each FOR in a nested FOR construct must have a corresponding ENDFOR.

You cannot read sequential files online under CICS.

You cannot modify sequential files in the scope of a FOR EACH construct, even if the dataview is marked updateable. Sequential files are updated by writing records to a new file.

The keyword QUIT in the logical scope of a FOR EACH abandons processing of the set of records. The next statement executed is the statement after the ENDFOR. When FOR and LOOP constructs are nested, you can abandon any construct by referencing the optional label in a QUIT statement. See the QUIT statement in this chapter.

You can reference fields processed by each iteration of the FOR construct in PDL statements. The identifier is the name of the field defined in the dataview or the field name with the dataview name as qualifier. For example, you can compare field ACCT_NO in dataview ACCT to the field ACCT_NO in panel PNL1:

IF ACCT.ACCT_NO EQ PNL1.ACCT_NO ...

You cannot make such references before the FOR executes.

Sometimes it is convenient to first process a dataview record and then refer to its fields rather than to code the actions in the FOR. For example, you can delegate finding the appropriate record to a lower level procedure.

You can nest any of the FOR constructs as long as each FOR construct refers to a different dataview. Do not nest a FOR construct for a given dataview in another FOR construct for the same dataview.