The FOR NEW statement inserts a single record into a VSAM file using a dataview defined for the 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
[WHERE $RRN = value]
statements
[WHEN DUPLICATE]
[ statements]
[WHEN ERROR ]
[ statements]
ENDFOR
An optional 1‑ to 15‑character name of the FOR NEW construct. You can use it to refer to the construct in a QUIT statement.
Specifies the action to take to insert or add each new record. You can add the reserved word, THE, for readability.
FOR NEW initializes the field values in the new record if the program did not initialize them previously. 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).
The name of the dataview that defines the new record inserted. The dataview must be updateable.
Specifies the relative record number of the new record in an RRDS VSAM data set. The operator must be the equal sign (=). This statement is required for RRDS files, but cannot be used for ESDS files or KSDS files.
PDL statements. Typically, the statements in the scope of the FOR NEW construct are those that place values into the newly created record.
Used only for KSDS and RRDS data sets.) The WHEN DUPLICATE clause contains statements that execute when any key value of a record to add matches the key value of a record existing in the file and the index is defined as unique. For RRDS files, the record is a duplicate when the relative record number matches the relative record number of a record in the file.
If the WHEN DUPLICATE clause is omitted and the index is defined as unique, a run‑time error occurs and control passes to the WHEN ERROR statement if a duplicate record is encountered. If the WHEN ERROR is not coded, control passes to the error procedure.
If the WHEN DUPLICATE clause is included and the index is not defined as unique, the WHEN DUPLICATE clause is ignored. The WHEN DUPLICATE clause is also ignored when it is specified for an ESDS file.
Note: Although the file is not updated when a duplicate record is found (the duplicate record is not added), the WHEN DUPLICATE clause does not affect the execution of the statements that precede it. The statements in the WHEN DUPLICATE clause execute when the duplication is detected at the ENDFOR. At that point, all other statements in the scope of the FOR were already executed. If the FOR construct includes statements that increment counters or set messages, you can correct those values in the WHEN DUPLICATE processing. However, you cannot continue executing the FOR construct.
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.
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 field in the dataview record just added after ENDFOR unless a QUIT statement is used.
A QUIT or PROCESS NEXT in the logical scope of a FOR NEW abandons the creation of the record. Further reference to fields in the dataview outside of the FOR is invalid.
Insertion of a new record into the file occurs at the ENDFOR.
You cannot delete a record in the dataview specified in the FOR NEW construct in the logical scope of the FOR NEW construct.
Examples
In this example, the FOR NEW construct is included in a LOOP construct to process multiple records. Notice that a WHEN DUPLICATE clause is specified to correct the NEW‑COUNT total when the duplicate record was not added.
LOOP UNTIL TRANSCODE = 'Q'
TRANSMIT INVEN‑PNL
FOR THE NEW INVEN‑ITEM
MOVE INVEN‑PNL TO INVEN‑ITEM BY NAME
SET NEW‑COUNT = NEW‑COUNT + 1
WHEN DUPLICATE
SET NEW‑COUNT = NEW‑COUNT ‑ 1
ENDFOR
ENDLOOP
In this example, the $RRN function determines the location of the new record. First, the file is read in descending order to determine the relative record number of the last existing record. Then the new records are added, starting with the next relative record number.
FOR FIRST PAYROLL ORDERED BY DESCENDING
SET NEXT‑REC = $RRN(PAYROLL) + 1
WHEN NONE
SET NEXT‑REC = 1
ENDFOR
LOOP UNTIL DONE
FOR NEW PAYROLL
WHERE $RRN = NEXT‑REC
DO NEW‑SETUP
SET NEXT‑REC = $RRN(PAYROLL) + 1
MOVE NEW‑PAY TO PAYROLL BY NAME
ENDFOR
ENDLOOP
CA Ideal supports VSAM file access through the FOR construct. As for any other data access method, you want to ensure the integrity of VSAM files in the event of system failures, disk problems, and so on. Following is a description of backout and recovery for VSAM files that CA Ideal accesses.
In non‑CICS environments, the CA Ideal PDL CHECKPOINT statement results in a CLOSE (Type=T) operation in z/OS and a TCLOSE operation in VSE. The ROLLBACK statement has no effect.
When VSAM is invoked under CICS, CICS command level functions are actually used to access VSAM files. CICS provides the facilities that ensure the integrity of VSAM files. If these facilities are installed and enabled for VSAM files accessed in a CA Ideal program, the Procedure Definition statements CHECKPOINT and BACKOUT function as expected for VSAM files: A CHECKPOINT results in a CICS SYNCPOINT and a BACKOUT statement results in a SYNCPOINT ROLLBACK.
In addition, if CICS VSAM files are accessed along with CA Datacom/DB and DB2, the CICS SYNCPOINT and SYNCPOINT ROLLBACK facilities help synchronize VSAM files with the other databases (each of which has its own recovery facilities).
|
Copyright © 2015 CA Technologies.
All rights reserved.
|
|