207 lines
11 KiB
HTML
207 lines
11 KiB
HTML
<!--$Id: db_get.html 63573 2008-05-23 21:43:21Z trent.nelson $-->
|
|
<!--Copyright (c) 1997,2008 Oracle. All rights reserved.-->
|
|
<!--See the file LICENSE for redistribution information.-->
|
|
<html>
|
|
<head>
|
|
<title>Berkeley DB: DB->get</title>
|
|
<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit.">
|
|
<meta name="keywords" content="embedded,database,programmatic,toolkit,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,Java,C,C++">
|
|
</head>
|
|
<body bgcolor=white>
|
|
<table width="100%"><tr valign=top>
|
|
<td>
|
|
<b>DB->get</b>
|
|
</td>
|
|
<td align=right>
|
|
<a href="../api_c/api_core.html"><img src="../images/api.gif" alt="API"></a>
|
|
<a href="../ref/toc.html"><img src="../images/ref.gif" alt="Ref"></a></td>
|
|
</tr></table>
|
|
<hr size=1 noshade>
|
|
<tt>
|
|
<b><pre>
|
|
#include <db.h>
|
|
<p>
|
|
int
|
|
DB->get(DB *db,
|
|
DB_TXN *txnid, DBT *key, DBT *data, u_int32_t flags);
|
|
<p>
|
|
int
|
|
DB->pget(DB *db,
|
|
DB_TXN *txnid, DBT *key, DBT *pkey, DBT *data, u_int32_t flags);
|
|
</pre></b>
|
|
<hr size=1 noshade>
|
|
<b>Description: DB->get</b>
|
|
<p>The DB->get method retrieves key/data pairs from the database. The
|
|
address and length of the data associated with the specified <b>key</b>
|
|
are returned in the structure to which <b>data</b> refers.</p>
|
|
<p>In the presence of duplicate key values, DB->get will return the
|
|
first data item for the designated key. Duplicates are sorted by insert
|
|
order, except where this order has been overridden by cursor operations.
|
|
<b>Retrieval of duplicates requires the use of cursor operations.</b>
|
|
See <a href="../api_c/dbc_get.html">DBcursor->get</a> for details.</p>
|
|
<p>When called on a database that has been made into a secondary index
|
|
using the <a href="../api_c/db_associate.html">DB->associate</a> method, the DB->get and
|
|
DB->pget methods return the key from the secondary index and the data
|
|
item from the primary database. In addition, the DB->pget method
|
|
returns the key from the primary database. In databases that are not
|
|
secondary indices, the DB->pget method will always fail.</p>
|
|
<p>The DB->get method will return <a href="../ref/program/errorret.html#DB_NOTFOUND">DB_NOTFOUND</a> if the specified key is not in the database.
|
|
The DB->get method will return <a href="../ref/program/errorret.html#DB_KEYEMPTY">DB_KEYEMPTY</a> if the database is a Queue or Recno database and
|
|
the specified key exists, but was never explicitly created by the
|
|
application or was later deleted.
|
|
Unless otherwise specified, the DB->get method
|
|
returns a non-zero error value on failure
|
|
and 0 on success.
|
|
</p>
|
|
<b>Parameters</b> <br>
|
|
<b>data</b><ul compact><li>The data <a href="../api_c/dbt_class.html">DBT</a> operated on.</ul>
|
|
<b>flags</b><ul compact><li>The <b>flags</b> parameter must be set to 0 or
|
|
one of the following values:
|
|
<br>
|
|
<b><a name="DB_CONSUME">DB_CONSUME</a></b><ul compact><li>Return the record number and data from the available record closest to
|
|
the head of the queue, and delete the record. The record number will
|
|
be returned in <b>key</b>, as described in <a href="../api_c/dbt_class.html">DBT</a>. The data will
|
|
be returned in the <b>data</b> parameter. A record is available if it
|
|
is not deleted and is not currently locked. The underlying database
|
|
must be of type Queue for DB_CONSUME to be specified.</ul>
|
|
<b><a name="DB_CONSUME_WAIT">DB_CONSUME_WAIT</a></b><ul compact><li>The DB_CONSUME_WAIT flag is the same as the DB_CONSUME
|
|
flag, except that if the Queue database is empty, the thread of control
|
|
will wait until there is data in the queue before returning. The
|
|
underlying database must be of type Queue for DB_CONSUME_WAIT
|
|
to be specified.
|
|
<p>If lock or transaction timeouts have been specified, the DB->get method
|
|
with the DB_CONSUME_WAIT flag
|
|
may return <a href="../ref/program/errorret.html#DB_LOCK_NOTGRANTED">DB_LOCK_NOTGRANTED</a>.
|
|
This failure, by itself, does not require the enclosing transaction be
|
|
aborted.</p></ul>
|
|
<b><a name="DB_GET_BOTH">DB_GET_BOTH</a></b><ul compact><li>Retrieve the key/data pair only if both the key and data match the
|
|
arguments.
|
|
<p>When used with the DB->pget method version of this method on a
|
|
secondary index handle, return the secondary key/primary key/data tuple
|
|
only if both the primary and secondary keys match the arguments. It is
|
|
an error to use the DB_GET_BOTH flag with the DB->get
|
|
version of this method and a secondary index handle.</p></ul>
|
|
<b><a name="DB_SET_RECNO">DB_SET_RECNO</a></b><ul compact><li>Retrieve the specified numbered key/data pair from a database. Upon
|
|
return, both the <b>key</b> and <b>data</b> items will have been
|
|
filled in.
|
|
<p>The <b>data</b> field of the specified <b>key</b> must be a pointer
|
|
to a logical record number (that is, a <b>db_recno_t</b>). This record
|
|
number determines the record to be retrieved.</p>
|
|
<p>For 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.</p></ul>
|
|
<br>
|
|
In addition, the following flags may be set by
|
|
bitwise inclusively <b>OR</b>'ing them into the <b>flags</b> parameter:
|
|
<br>
|
|
<b><a name="DB_IGNORE_LEASE">DB_IGNORE_LEASE</a></b><ul compact><li>Return the data item irrespective of the state of master leases. The
|
|
item will be returned under all conditions: if master leases are not
|
|
configured, if the request is made to a client, if the request is made
|
|
to a master with a valid lease, or if the request is made to a master
|
|
without a valid lease.</ul>
|
|
<b><a name="DB_MULTIPLE">DB_MULTIPLE</a></b><ul compact><li>Return multiple data items in the buffer to which the <b>data</b>
|
|
parameter refers.
|
|
<p>In the case of Btree or Hash databases, all of the data items associated
|
|
with the specified key are entered into the buffer. In the case of
|
|
Queue or Recno databases, all of the data items in the database,
|
|
starting at, and subsequent to, the specified key, are entered into the
|
|
buffer.</p>
|
|
<p>The buffer to which the <b>data</b> parameter refers must be provided
|
|
from user memory (see <a href="../api_c/dbt_class.html#DB_DBT_USERMEM">DB_DBT_USERMEM</a>). The buffer must be at
|
|
least as large as the page size of the underlying database, aligned for
|
|
unsigned integer access, and be a multiple of 1024 bytes in size. If
|
|
the buffer size is insufficient, then upon return from the call the size
|
|
field of the <b>data</b> parameter will have been set to an estimated
|
|
buffer size, and the error DB_BUFFER_SMALL is returned. (The size is an estimate as the
|
|
exact size needed may not be known until all entries are read. It is
|
|
best to initially provide a relatively large buffer, but applications
|
|
should be prepared to resize the buffer as necessary and repeatedly call
|
|
the method.)</p>
|
|
<p>The DB_MULTIPLE flag may only be used alone, or with the
|
|
DB_GET_BOTH and DB_SET_RECNO options. The
|
|
DB_MULTIPLE flag may not be used when accessing databases made
|
|
into secondary indices using the <a href="../api_c/db_associate.html">DB->associate</a> method.</p>
|
|
<p>See
|
|
<a href="../api_c/dbt_bulk.html#DB_MULTIPLE_INIT">DB_MULTIPLE_INIT</a>
|
|
for more information.</p></ul>
|
|
<b><a name="DB_READ_COMMITTED">DB_READ_COMMITTED</a></b><ul compact><li>Configure a transactional get operation to have degree 2 isolation (the
|
|
read is not repeatable).</ul>
|
|
<b><a name="DB_READ_UNCOMMITTED">DB_READ_UNCOMMITTED</a></b><ul compact><li>Configure a transactional get operation to have degree 1 isolation,
|
|
reading modified but not yet committed data. Silently ignored if the
|
|
<a href="../api_c/db_open.html#DB_READ_UNCOMMITTED">DB_READ_UNCOMMITTED</a> flag was not specified when the underlying
|
|
database was opened.</ul>
|
|
<b><a name="DB_RMW">DB_RMW</a></b><ul compact><li>Acquire write locks instead of read locks when doing the read, if
|
|
locking is configured. Setting this flag can eliminate deadlock during
|
|
a read-modify-write cycle by acquiring the write lock during the read
|
|
part of the cycle so that another thread of control acquiring a read
|
|
lock for the same item, in its own read-modify-write cycle, will not
|
|
result in deadlock.
|
|
<p>Because the DB->get method will not hold locks across
|
|
Berkeley DB calls in non-transactional operations, the <a href="../api_c/dbc_get.html#DB_RMW">DB_RMW</a> flag
|
|
to the DB->get call is meaningful only in the presence of
|
|
transactions.</p></ul>
|
|
<br></ul>
|
|
<b>key</b><ul compact><li>The key <a href="../api_c/dbt_class.html">DBT</a> operated on.</ul>
|
|
<b>pkey</b><ul compact><li>The <b>pkey</b> parameter is the return key from the primary database.</ul>
|
|
<b>txnid</b><ul compact><li>If the operation is part of an application-specified transaction, the
|
|
<b>txnid</b> parameter is a transaction handle returned from
|
|
<a href="../api_c/txn_begin.html">DB_ENV->txn_begin</a>; if the operation is part of a Berkeley DB Concurrent Data Store group, the
|
|
<b>txnid</b> parameter is a handle returned from
|
|
<a href="../api_c/env_cdsgroup_begin.html">DB_ENV->cdsgroup_begin</a>; otherwise NULL.
|
|
If no transaction handle is
|
|
specified, but the
|
|
operation occurs in a transactional
|
|
database,
|
|
the operation will be implicitly transaction protected.
|
|
</ul>
|
|
<br>
|
|
<br><b>Errors</b>
|
|
<p>The DB->get method
|
|
may fail and return one of the following non-zero errors:</p>
|
|
<br>
|
|
<b>DB_BUFFER_SMALL</b><ul compact><li>The requested item could not be returned due to undersized buffer.</ul>
|
|
<br>
|
|
<br>
|
|
<b>DB_LOCK_DEADLOCK</b><ul compact><li>A transactional database environment operation was selected to resolve
|
|
a deadlock.</ul>
|
|
<b>DB_LOCK_NOTGRANTED</b><ul compact><li>A Berkeley DB Concurrent Data Store database environment configured for lock timeouts was unable
|
|
to grant a lock in the allowed time.</ul>
|
|
<br>
|
|
<br>
|
|
<b>DB_LOCK_NOTGRANTED</b><ul compact><li>The DB_CONSUME_WAIT flag was specified, lock or transaction
|
|
timers were configured and the lock could not be granted before the wait-time expired.</ul>
|
|
<br>
|
|
<br>
|
|
<b>DB_REP_HANDLE_DEAD</b><ul compact><li>The database handle has been invalidated because a replication election
|
|
unrolled a committed transaction.</ul>
|
|
<br>
|
|
<br>
|
|
<b>DB_REP_LEASE_EXPIRED</b><ul compact><li>The operation failed because the site's replication master lease has expired.</ul>
|
|
<br>
|
|
<br>
|
|
<b>DB_REP_LOCKOUT</b><ul compact><li>The operation was blocked by client/master synchronization.</ul>
|
|
<br>
|
|
<br>
|
|
<b>DB_SECONDARY_BAD</b><ul compact><li>A secondary index references a nonexistent primary key.</ul>
|
|
<br>
|
|
<br>
|
|
<b>EINVAL</b><ul compact><li>If a record number of 0 was specified;
|
|
the <a href="../api_c/env_open.html#DB_THREAD">DB_THREAD</a> flag was specified to the <a href="../api_c/db_open.html">DB->open</a> method and
|
|
none of the <a href="../api_c/dbt_class.html#DB_DBT_MALLOC">DB_DBT_MALLOC</a>, <a href="../api_c/dbt_class.html#DB_DBT_REALLOC">DB_DBT_REALLOC</a> or
|
|
<a href="../api_c/dbt_class.html#DB_DBT_USERMEM">DB_DBT_USERMEM</a> flags were set in the <a href="../api_c/dbt_class.html">DBT</a>;
|
|
the DB->pget method was called with a <a href="../api_c/db_class.html">DB</a> handle that does not
|
|
refer to a secondary index; or if an
|
|
invalid flag value or parameter was specified.</ul>
|
|
<br>
|
|
<hr size=1 noshade>
|
|
<br><b>Class</b>
|
|
<a href="../api_c/db_class.html">DB</a>
|
|
<br><b>See Also</b>
|
|
<a href="../api_c/db_list.html">Databases and Related Methods</a>
|
|
</tt>
|
|
<table width="100%"><tr><td><br></td><td align=right>
|
|
<a href="../api_c/api_core.html"><img src="../images/api.gif" alt="API"></a><a href="../ref/toc.html"><img src="../images/ref.gif" alt="Ref"></a>
|
|
</td></tr></table>
|
|
<p><font size=1>Copyright (c) 1996,2008 Oracle. All rights reserved.</font>
|
|
</body>
|
|
</html>
|