*I#Berkeley DB: Db::get[P

Db::get





#include <db_cxx.h>

int<Db::get(DbTxn *txnid, Dbt *key, Dbt *data, u_int32_t flags);





Description



CThe Db::get method retrieves key/data pairs from the database. TheaddressCand length of the data associated with the specified key are4returned in the structure referenced by data.

@In the presence of duplicate key values, Db::get will return theHfirst data item for the designated key. Duplicates are sorted by insertGorder except where this order has been overridden by cursor operations.ERetrieval of duplicates requires the use of cursor operations.BSee Dbc::get for details.

;If the file is being accessed under transaction protection,<the txnid parameter is a transaction ID returned fromQDbTxnMgr::begin, otherwise, NULL.

CThe flags parameter must be set to 0 or one of the followingvalues:

X

DB_GET_BOTH
Retrieve the key/data pair only if both the key and data match the arguments.U

DB_SET_RECNO
Retrieve the specified numbered key/data pair from a database.EUpon return, both the key and data items will have beenFfilled in, not just the data item as is done for all other uses of theDb::get method.

1The data field of the specified keyimust be a pointer to a logical record number (i.e.,a db_recno_t).9This record number determines the record to be retrieved.

IFor DB_SET_RECNO to be specified, the underlying database must be of type<btree and it must have been created with the DB_RECNUM flag.



RIn addition, the following value may be set by logically OR'ing it into theflags parameter:

T

DB_RMW
Acquire write locks instead of read locks when doing the retrieval.BSetting this flag may decrease the likelihood of deadlock during aFread-modify-write cycle by immediately acquiring the write lock duringFthe read part of the cycle so that another thread of control acquiringGa read lock for the same item, in its own read-modify-write cycle, willnot result in deadlock.


IIf the database is a recno database and the requested key exists, but wasEnever explicitly created by the application or was later deleted, theDDb::get method returns DB_KEYEMPTY. Otherwise, if the requested keyAis not in the database, the Db::get function returns DB_NOTFOUND.Otherwise, the Db::get>method either returns errno or throws an exception that:encapsulates an errno on failure, and 0 on success.



Errors

NIf a fatal error occurs in Berkeley DB, the Db::get method may fail and eitherIreturn DB_RUNRECOVERY or throw an exception encapsulating DB_RUNRECOVERY,Gat which point all subsequent database calls will also fail in the sameFway. Methods marked as returning errno will, by default, throwHan exception that encapsulates the error information. The default error\behavior can be changed, see DbException.

The Db::get&method may fail and throw an exceptionKfor any of the errors specified for the following Berkeley DB and C library functions:6Db::cursor,DBcursor->c_close(3),2Dbc::get, fflush(3), fprintf(3), vfprintf(3),and vsnprintf(3).

In addition, the Db::get&method may fail and throw an exceptionor return errnofor the following conditions:

(

EAGAIN
A lock was unavailable.


B

EINVAL
An invalid flag value or parameter was specified.

pThe DB_THREAD flag was specified to the Db::open method and neither the¨DB_DBT_MALLOC or DB_DBT_USERMEM flags were set in the/Dbt.

#A record number of 0 was specified.





Class

,Db



See Also

4Db::close,6Db::cursor,0Db::del,.Db::fd,Db::get,HDb::get_byteswapped,:Db::get_type,2Db::join,2Db::open,0Db::put,1Db::statand2Db::sync.
˙˙