Database Access Commands › Navigational DML › FIND/OBTAIN DB-KEY

FIND/OBTAIN DB-KEY

Purpose

Accesses a record occurrence directly by using a database key that is stored in a field in a dialog's record buffers.

Any record in a dialog's subschema can be accessed in this manner, regardless of its location mode.

Syntax

►►─┬─ FIND ───┬─┬────────────────────────┬───────────────────────────────────►
   └─ OBTAIN ─┘ └─ KEEP ─┬─────────────┬─┘
                         └─ EXCLUSIVE ─┘

 ►─┬─ DB-KEY ─┬──────┬─ db-key-variable ─┬──────────────────────┬─┬──────────►
   │          ├─ IS ─┤                   └─ page-specification ─┘ │
   │          └─ = ──┘                                            │
   └─┬───────────────┬─ DB-KEY ─┬──────┬─ db-key-variable ────────┘
     └─ record name ─┘          ├─ IS ─┤
                                └─ = ──┘

 ►─┬────────────────────┬────────────────────────────────────────────────────►◄
   └─ error-expression ─┘

Expansion of page-specification

►►─┬───────────────────────────────────────────┬────────────────────────►◄
   └─ PAGE-INFO ─┬──────┬─ page-info-variable ─┘
                 ├─ IS ─┤
                 └─ = ──┘

Expansion of page-specification

►►─┬───────────────────────────────────────────┬────────────────────────►◄
   └─ PAGE-INFO ─┬──────┬─ page-info-variable ─┘
                 ├─ IS ─┤
                 └─ = ──┘

Parameters

KEEP

Places a shared lock on the object record.

EXCLUSIVE

Places an exclusive lock on the object record.

record-name

Specifies the name of the record to be accessed using the database key value contained in db-key-variable.

If specified, record-name must be known to the dialog's subschema.

DB-KEY IS db-key-variable

Specifies the binary fullword in the dialog's record buffers that contains a previously saved database key. If record-name is specified, db-key-variable must contain the database key of an occurrence of the named record type. If record-name is not specified, db-key-variable can contain the database key of an occurrence of any record type in the dialog's subschema.

Db-key-variable is a PIC S9(8) COMP SYNC.

IS or = are optional keywords and have no effect on processing.

PAGE-INFO

Specifies page information that is used to determine the area with which the dbkey is associated. If not specified, the page information associated with the record that is current of rununit is used.

Note: Page information is only used if the subschema includes areas that have mixed page groups; otherwise, it is ignored.

page-info-variable

A four-byte field that may be defined either as a group field or as a fullword field (PIC S9(8) COMP). Identifies the location in variable storage that contains the page information previously saved by the program.

Page information is returned in the PAGE-INFO field in the subschema control area if the subschema includes areas in mixed page groups. Page information may also be returned using an ACCEPT PAGE-INFO statement.

error-expression

Specifies the status codes that are returned to the dialog.

Usage

Considerations

If autostatus is not in use, a dialog's error-status field indicates the outcome of a FIND/OBTAIN DB-KEY command:

Further Considerations

• FIND/OBTAIN DB-KEY cannot be used to access data records in a native VSAM KSDS.
• After successful execution of a FIND/OBTAIN DB-KEY command, the accessed record is current of the run unit, its record type, its area, and all sets in which it currently participates as member or owner.

Example

The following example illustrates the use of the FIND DB-KEY command to locate an occurrence of the ITEM record whose database key matches the value in a field called SAVED-KEY:

FIND ITEM DB-KEY IS SAVED-KEY.

More information:

Error Handling