The @FIND/@OBTAIN DBKEY statement accesses a record occurrence directly by using a database key that has been stored previously by the program. You can use the DML @ACCEPT verb (see @ACCEPT DBKEY FROM CURRENCY and @ACCEPT DBKEY RELATIVE TO CURRENCY) or an Assembler assignment statement to save a db-key. In this manner, you can directly access any record in the program's subschema regardless of its location mode.
Additionally, the DML @ACCEPT PGINFO verb (see @ACCEPT PGINFO, @ACCEPT DBKEY FROM CURRENCY, and @ACCEPT DBKEY RELATIVE TO CURRENCY) can be used to save page information that can be used to directly access the record from a specific page group when the Mixed Page Binds Allowed feature is used.
For more information about the Mixed Page Group Binds Allowed feature, see the Database Administration Guide.
Note: Native VSAM users—This statement is not valid for accessing data records in a native VSAM key-sequenced data set (KSDS).
Currency
Currency is not used to determine the location of the record specified in the @FIND/@OBTAIN DBKEY statement; the record is identified by its db-key and, optionally, by its record name.
Following successful execution of an @FIND/@OBTAIN DBKEY statement, the accessed record becomes the current record of run unit, its area, its record type, and all sets in which it currently participates as member or owner. The RECNAME field of the IDMS communications block is updated with the name of the accessed record.
Syntax
►►─┬─ @FIND ───┬─────────────────────────────────────────────────────────────► └─ @OBTAIN ─┘ ►─┬──────────────────────────┬──────────────────────────────────────────────► └─ ,KEEP= ─┬─ SHARED ────┬─┘ └─ EXCLUSIVE ─┘ ►─┬─ DBKEY=db-key ─┬───────────────────┬─┬──────────────────────────────────►◄ │ └─ ,PGINFO=pg-info ─┘ │ └─┬───────────────────┬─ DBKEY=db-key ─┘ └─ REC=record-name ─┘
Parameters
Accesses a record directly by using a db-key value contained in program variable storage.
Identifies the location in program variable storage that contains a db-key previously saved by the program. If a record name is specified, db-key must contain the db-key of an occurrence of the named record type. If a record name is not specified, db-key can contain the db-key of an occurrence of any record type in the subschema. Db-key must identify a binary fullword synchronized field; it can be a register or a user-defined variable.
Places a shared or exclusive lock on the accessed record:
Places a shared lock on the specified record.
Places an exclusive lock on the specified record.
Specifies page information that is used to determine the area with which the db-key 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.
Pg-info, a four-byte field that is made up of two halfword fields, identifies the location in variable storage that contains the page information previously saved by the program.
Page information is returned in the PGINFO field in the subschema control area if the subschema includes areas in mixed page groups. Page information can also be returned using the @ACCEPT PGINFO, @ACCEPT DBKEY FROM CURRENCY, and @ACCEPT DBKEY RELATIVE TO CURRENCY statements.
Optionally identifies the record type of the requested record. Record-name must identify a record that is included in the subschema; it can be a register, a user-defined variable, or a user-supplied variable enclosed in quotes.
Example
The following @FIND statement locates an occurrence of the EMPLOYEE record whose db-key matches the value of a field in program variable storage called SAVEDKEY.
The located record becomes current of run unit, current of the EMPLOYEE record type, current of the DEPT-EMPLOYEE, OFFICE-EMPLOYEE, and all other sets in which it currently participates as member or owner, and current of the ORDER-REGION area.
@FIND DBKEY=SAVEDKEY,REC='EMPLOYEE'
Status codes
After completion of the @FIND/@OBTAIN DBKEY function, the ERRSTAT field in the IDMS communication block indicates the outcome of the operation. The following is a list of the acceptable status codes for this function and their corresponding meaning:
This request has been serviced successfully.
The area in which the named record participates has not been readied.
The db-key is inconsistent with the area in which the record is stored. The db-key has not been initialized properly, or the record name is incorrect.
The requested record is not in the subschema. The program has probably invoked the wrong subschema.
The subschema specifies an access restriction that prohibits retrieval of the named record.
The specified record cannot be found.
A database file will not open properly.
When the KEEP parameter is specified as part of an @FIND/@OBTAIN statement, a major code of 06 will be returned if an error occurs during the KEEP processing (see @KEEP later in this chapter). The major code of 03 states that an error has occurred in the @FIND/@OBTAIN processing.
|
Copyright © 2014 CA.
All rights reserved.
|
|