Procedure Definition Language Statements › FOR Statement (Sequential Files) › FOR NEW Statement (Sequential Files)

FOR NEW Statement (Sequential Files)

The FOR NEW statement adds new records to the end of a sequential file using a dataview for that file. The FOR NEW statement is not iterative. To repeat processing of a FOR NEW, you must include it in a looping construct.

This statement has the following format:

[<<label>>]
FOR [THE] NEW dataview‑name
     statements

    [ WHEN ERROR     ]
    [     statements ]
ENFOR

<<label>>

An optional 1‑ to 15‑character name of the FOR NEW construct. You can use it to refer to the construct in the QUIT statement.

FOR [THE] NEW

Specifies the action to take to add each new record.

FOR NEW initializes the values in the record defined by the specified dataview. If initial values were specified for the field in the dataview definition, they are used. Otherwise, the fields are initialized to zeros (for numeric fields) and blanks (for alphanumeric fields).

Note for the DBA: Fields in the underlying record that are not defined in the modeled dataview are initialized to spaces, without regard to the intended data type of the field. Therefore, it is recommended that dataviews used in FOR NEW span the entire record.

You can add the reserved word, THE, for readability.

dataview‑name

The name of the dataview for which a new record is added. The dataview must be updateable.

statements

PDL statements. Typically, the statements in the scope of the FOR NEW construct are those that place values into the newly created record.

WHEN ERROR (Optional)

Specifies statements to execute when a dataview error is encountered in the scope of the FOR construct. If 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 terminates the FOR construct. If FOR constructs are nested, the most recent unterminated FOR construct is terminated. You can reference any recently added field in the dataview record after ENDFOR unless a QUIT statement is used.

The file is opened when the FOR NEW statement executes. The record is actually inserted at the ENDFOR.

A QUIT in the logical scope of a FOR NEW aborts the creation of the record, that is, creates an empty sequential file.

PROCESS NEXT has no meaning in the FOR NEW.

Dataview fields cannot be referenced before execution of the FOR statement for the dataview.

The first time a FOR NEW is executed, the file is opened for output and the disposition parameter takes control to determine where the record is added. In a z/OS environment, DISP=MOD, the new record is added to the end of the file. If DISP=OLD, the existing records are purged and the new record is added to the beginning of the file. Subsequent records are added to the end of the file in both cases. See the following examples.

Online, if one or more users are writing to the file, new records are interleaved. If a sequential file is written online under CICS, you cannot read it in batch until CICS closes it.

Example

FOR THE NEW INVEN_ITEM
      MOVE TRANS_INFO TO INVEN_ITEM BY NAME
ENDFOR

The following table illustrates the differences in the processing of a sequential file when the disposition parameter is set to OLD or MOD in z/OS.