CREATE VSAM CURSOR - connect_cdc_sqdata - Latest

Purpose

The CREATE VSAM CURSOR statement defines an SQData cursor over an existing VSAM datastore. You can then process the cursor with OPEN, FETCH, CLOSE, or FOREACH.

VSAM cursors are commonly used to look up reference data from a key-indexed VSAM file, validate source values, or retrieve related data as part of primary CDC processing.

Category

Cursor Statements

Syntax

CREATE VSAM CURSOR AS <cursor_name>
        ON <datastore_name>
        DESCRIBED BY <result_record>
        [USING <key_record>]
        ;
        
        CREATE VSAM CURSOR AS <cursor_name>
        ON <datastore_name>
        USING <key_record>
        ;

Parameters

Usage notes

Use ON to identify the VSAM datastore associated with the cursor. At least one of DESCRIBED BY or USING must also be present.

In practice, a VSAM cursor relies on three related constructs:

• A VSAM datastore and its associated data descriptions.
• A key record for USING to locate matching VSAM rows, and a result record for DESCRIBED BY to receive the fetched data.
• Execution through OPEN(), FETCH(), CLOSE(), or FOREACH().

This topic documents only the CREATE VSAM CURSOR statement itself. The VSAM datastore named by ON, along with any result or key records referenced by DESCRIBED BY and USING, must already be defined elsewhere in the SQData script.

Use DESCRIBED BY when the cursor should populate a record with the fetched row. Use USING when key values are required to locate the VSAM entry to be opened and fetched.

For best results:

• The USING record should match the key fields needed to locate the correct VSAM entry.
• The DESCRIBED BY record should match the layout and types of the VSAM data returned by the fetch.

The alias defined by AS may appear before or after the cursor options.

Return values

When a VSAM cursor reaches end-of-file or no matching row is found, FETCH() returns the normalized SQData value '100'.

Example

CREATE VSAM CURSOR AS SQDATA_VSAM_CURSOR
        ON SQDATA_VSAM_SOURCE
        DESCRIBED BY SQDATA_VSAM_ROW
        USING SQDATA_VSAM_KEY
        ;