Data Manipulation Language Statements › ACCEPT DBKEY RELATIVE TO CURRENCY

ACCEPT DBKEY RELATIVE TO CURRENCY

The ACCEPT DBKEY RELATIVE TO CURRENCY statement moves a selected db-key and optionally its page information to a specified location in program variable storage. The db-key moved to variable storage can be the db-key of the next, prior, or owner record relative to the current record of set.

This version of the ACCEPT statement allows you to save the db-key of a record within a set without actually having to access the record. By using a FIND/OBTAIN DBKEY statement, you can directly access records whose db-keys you save using the ACCEPT DBKEY RELATIVE TO CURRENCY statement.

Note: You must establish set currency before using this statement. If no set currency is established, the DBMS returns 0000 to the ERROR_STATUS field and -1 to the db-key field.

Currency

ACCEPT DBKEY RELATIVE TO CURRENCY does not update any currencies.

Syntax

►►─── ACCEPT CURRENCY SET (set name) ─┬─ NEXT ──┬─ INTO (db-key-field) ──────►
                                      ├─ PRIOR ─┤
                                      └─ OWNER ─┘

 ►────────────────────────┬──────────────────────────────────────┬─ ; ───────►◄
                          └ PAGE INFO INTO (page-info-location)──┘            

Parameters

SET (set-name)

Identifies the record whose db-key will be moved into the location specified by db-key, described below. Set-name must be a set included in the subschema.

When a record declared as an optional or manual member of a set is accessed, it does not become current of set unless it is connected to an occurrence of the set. If the record is not connected to an occurrence of the set, an attempt to access the owner record will locate instead the owner of the current record of set. In such cases, use the OWNER option to determine whether the retrieved record is actually a set member before executing the ACCEPT DBKEY RELATIVE TO CURRENCY statement. You can do this with the IF statement, described later in this chapter.

NEXT

Saves the db-key of the next record relative to the record current of the specified set. You cannot request NEXT currency unless the specified set has prior pointers. Prior pointers ensure that the next pointer in the prefix of the current record does not point to a logically deleted record.

No indication of an end-of-set condition is possible for the NEXT or PRIOR options. A retrieval command must be issued to determine whether the next or prior record in the set occurrence is the owner record.

Native VSAM users: You cannot request NEXT currency for sets defined for native VSAM records.

PRIOR

Saves the db-key of the prior record relative to the record current of the specified set. You cannot request PRIOR currency unless the specified set has prior pointers.

No indication of an end-of-set condition is possible for the NEXT or PRIOR options. A retrieval command must be issued to determine whether the next or prior record in the set occurrence is the owner record.

Native VSAM users: You cannot request PRIOR currency for sets defined for native VSAM records.

OWNER

Saves the db-key of the owner of the record current of the specified set. A request for OWNER CURRENCY cannot be executed unless the specified set has owner pointers. However, if the current record of the named set is the owner record occurrence, a request for OWNER currency returns the db-key of the record itself. This will happen even if the set does not have owner pointers.

Native VSAM users: You cannot request OWNER currency for sets defined for native VSAM records.

INTO (db-key-field)

Identifies the location in variable storage that will contain the db-key of the requested record. Db-key must be a FIXED BINARY(31) field.

INTO (page-info-location)

Specifies the name of the four-byte field that can be defined either as a group field or as a fullword field (PIC S9(8) COMP). Identifies the location in variable storage that contains page information for the specified record type. Upon successful completion of this statement, the first two bytes of the field contain the page group number and the last two bytes contain a db-key radix that can be used for interpreting dbkeys.

Example

The following statements access the EMP_EXPERTISE set and save the db-key of the owner record of the SKILL_EXPERTISE set:

EMP_ID_0415 = '0119';
FIND CALC RECORD (EMPLOYEE);
FIND FIRST SET (EMP_EXPERTISE);
ACCEPT CURRENCY SET (SKILL_EXPERTISE) OWNER
   INTO (SAVE_DBKEY);

Status Codes

Upon completion of the ACCEPT DBKEY RELATIVE TO CURRENCY function, the ERROR_STATUS field in the IDMS DB communications block indicates the outcome of the operation: