RETURN DB-KEY

Database Access Commands › Navigational DML › RETURN DB-KEY

RETURN DB-KEY

Purpose

Retrieves an index entry without retrieving the associated record.

Note: This command applies only to CA IDMS system-owned indexed records.

Syntax

►►─── RETURN DB-KEY into db-key-variable FROM index-set-name ─────────────────►

 ►─┬─ CURRENCY ─────────────────┬────┬────────────────────┬─── . ─────────────►◄
   ├─ FIRST currency ───────────┤    └─ error-expression ─┘
   ├─ LAST currency ────────────┤
   ├─ NEXT currency ────────────┤
   ├─ PRIOR currency ───────────┤
   └─ USING index-key-variable ─┘

Parameters

RETURN DB-KEY into

Clause introducing the return of the database key, to the record associated with the specified index entry, to the location identified by db-key-variable.

db-key-variable

A numeric variable data field in the dialog's record buffers that can hold a binary fullword value.

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

FROM index-set-name

Specifies the index set associated with the index entry being retrieved.

Note: Index-set-name must be known to the dialog's subschema.

CURRENCY

Retrieves the entry that is current of index.

FIRST currency

Retrieves the first entry in the index.

LAST currency

Retrieves the last entry in the index.

NEXT currency

Retrieves the entry following the current of index.

PRIOR currency

Retrieves the entry preceding the current of index.

USING index-key-variable

Retrieves the first index entry whose symbolic key matches the contents of index-key-variable.

Index-key-variable is the name of a variable data field that is not more than 256 bytes in length.

error-expression

Specifies the status codes that are returned to the dialog.

Usage

The RETURN DB-KEY command is used as follows:

The value of the symbolic key in the index entry is returned to the symbolic key field for the associated record in the dialog's record buffer.
The database key that points to the record associated with the index entry is returned to a specified field in the dialog's record buffers.
The record referenced in the RETURN DB-KEY command must be referenced in a prior DML call in the dialog's run unit.

Considerations

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

Status code	Meaning
0000	The request was executed successfully
1707	The end of the index was reached. Currency is set on the index owner. The DBMS returns the owner's db-key When 1707 is returned for an SPF index, currency remains on the last entry of the index. No db-key is returned.
1725	Index currency was not established with an OBTAIN command
1726	The index entry cannot be found
1729	A run-unit deadlock condition occurred. DBMS aborted and rolled back the run unit. All resources associated with the task are released

Further Considerations

After successful execution of a RETURN DB-KEY command, the retrieved index entry is current of index.
If an end-of-set condition is encountered, currency is set to the last or first entry in the index, based on whether next or prior currency has been requested.
If a specified entry cannot be found, currency is set between the two entries that are higher and lower than the specified value.
If the specified value is higher or lower than all index entries, currency is set after or before the highest or lowest entry in the index.

More information:

Error Handling