RRDS native VSAM file RRN and dbkeys in IDMS

Products

• IDMS

Issue/Introduction

When storing a new record into an RRDS native VSAM file in IDMS, the DIRECT-DBKEY field in SUBSCHEMA-CTRL must be primed before issuing the STORE. This is documented at Use of Native VSAM Data Sets.

This article describes what that value must be and how it is used.

Environment

Release: All supported releases.

Cause

Every record in an RRDS VSAM file has a relative record number (RRN), ideally numbered sequentially 1, 2, 3 ... etc. When an RRDS VSAM file is defined to IDMS as a native VSAM file, an IDMS style dbkey is required. IDMS uses a one-to-one arithmetic transformation to map the RRN to a dbkey value.

Resolution

A native VSAM file is not an IDMS database so it has no real dbkey. IDMS generates one for each record based on the RRN. The formula is this:

Take the low page of the area page range as specified in the DMCL, multiply it by the "dbkey radix factor", and add the RRN. The resulting value is used as the four-byte binary dbkey for the record for all traditional IDMS processing such as locking, journaling, the value returned in the DBKEY field in SUBSCHEMA-CTRL, and also the first four bytes of any related ROWID columns if the record is used in an SQL context.

Note: the dbkey radix factor is the MAXIMUM RECORDS PER PAGE value on the segment definition rounded up to the next even power of 2. For example, if it is 63, then the value used in the multiplication will be 64.

When an RRDS record is being STOREd in an IDMS program, the DIRECT-DBKEY field in SUBSCHEMA-CTRL must be primed to the value of the new record's RRN - not the dbkey. If the provided RRN results in an invalid dbkey for the record's area, the STORE returns an error-status 1202. If there already is a record with the provided RRN, it returns a 1205.

If no application specific requirement is in place for deriving the DIRECT-DBKEY, one suggestion would be to take the dbkey of the last record in the area, subtract the dbkey of the first record in the area (treating them both as four-byte binary integers) and add 2. This will generate the next available RRN after the record that is currently last in the area. However it will have no impact on any gaps in the RRN sequencing in the file that may exist.