330 lines
20 KiB
HTML
330 lines
20 KiB
HTML
<!--$Id: dbc_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: DBcursor->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>DBcursor->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
|
|
DBcursor->get(DBC *DBcursor,
|
|
DBT *key, DBT *data, u_int32_t flags);
|
|
<p>
|
|
int
|
|
DBcursor->pget(DBC *DBcursor,
|
|
DBT *key, DBT *pkey, DBT *data, u_int32_t flags);
|
|
</pre></b>
|
|
<hr size=1 noshade>
|
|
<b>Description: DBcursor->get</b>
|
|
<p>The DBcursor->get method retrieves key/data pairs from the database. The
|
|
address and length of the key are returned in the object to which
|
|
<b>key</b> refers (except for the case of the DB_SET flag, in
|
|
which the <b>key</b> object is unchanged), and the address and length
|
|
of the data are returned in the object to which <b>data</b> refers.</p>
|
|
<p>When called on a cursor opened 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 DBcursor->get
|
|
and DBcursor->pget methods return the key from the secondary index and the
|
|
data item from the primary database. In addition, the DBcursor->pget method
|
|
returns the key from the primary database. In databases that are not
|
|
secondary indices, the DBcursor->pget method will always fail.</p>
|
|
<p>Modifications to the database during a sequential scan will be reflected
|
|
in the scan; that is, records inserted behind a cursor will not be
|
|
returned while records inserted in front of a cursor will be returned.</p>
|
|
<p>In Queue and Recno databases, missing entries (that is, entries that
|
|
were never explicitly created or that were created and then deleted)
|
|
will be skipped during a sequential scan.</p>
|
|
<p>Unless otherwise specified, the DBcursor->get method
|
|
returns a non-zero error value on failure
|
|
and 0 on success.
|
|
</p>
|
|
<p>If DBcursor->get fails for any reason, the state of the cursor will be
|
|
unchanged.</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 one of the following values:
|
|
<br>
|
|
<b><a name="DB_CURRENT">DB_CURRENT</a></b><ul compact><li>Return the key/data pair to which the cursor refers.
|
|
<p>The DBcursor->get method will return <a href="../ref/program/errorret.html#DB_KEYEMPTY">DB_KEYEMPTY</a> if DB_CURRENT is set and the cursor key/data pair was deleted.
|
|
</p></ul>
|
|
<b><a name="DB_FIRST">DB_FIRST</a></b><ul compact><li>The cursor is set to refer to the first key/data pair of the database,
|
|
and that pair is returned. If the first key has duplicate values, the
|
|
first data item in the set of duplicates is returned.
|
|
<p>If the database is a Queue or Recno database, DBcursor->get using the
|
|
DB_FIRST flag will ignore any keys that exist but were never
|
|
explicitly created by the application, or were created and later
|
|
deleted.</p>
|
|
<p>The DBcursor->get method will return <a href="../ref/program/errorret.html#DB_NOTFOUND">DB_NOTFOUND</a> if DB_FIRST is set and the database is empty.
|
|
</p></ul>
|
|
<b><a name="DB_GET_BOTH">DB_GET_BOTH</a></b><ul compact><li>The DB_GET_BOTH flag is identical to the DB_SET flag,
|
|
except that both the key and the data parameters must be matched by the
|
|
key and data item in the database.
|
|
<p>When used with the DBcursor->pget method version of this method on a
|
|
secondary index handle, both the secondary and primary keys must be
|
|
matched by the secondary and primary key item in the database. It is
|
|
an error to use the DB_GET_BOTH flag with the DBcursor->get
|
|
version of this method and a cursor that has been opened on a secondary
|
|
index handle.</p></ul>
|
|
<b><a name="DB_GET_BOTH_RANGE">DB_GET_BOTH_RANGE</a></b><ul compact><li>The DB_GET_BOTH_RANGE flag is identical to the DB_GET_BOTH
|
|
flag, except that, in the case of any database supporting sorted
|
|
duplicate sets, the returned key/data pair is the smallest data item
|
|
greater than or equal to the specified data item (as determined by the
|
|
comparison function), permitting partial matches and range searches in
|
|
duplicate data sets.</ul>
|
|
<b><a name="DB_GET_RECNO">DB_GET_RECNO</a></b><ul compact><li>Return the record number associated with the cursor. The record number
|
|
will be returned in <b>data</b>, as described in <a href="../api_c/dbt_class.html">DBT</a>. The
|
|
<b>key</b> parameter is ignored.
|
|
<p>For DB_GET_RECNO to be specified, the underlying database must be
|
|
of type Btree, and it must have been created with the <a href="../api_c/db_set_flags.html#DB_RECNUM">DB_RECNUM</a>
|
|
flag.</p>
|
|
<p>When called on a cursor opened on a database that has been made into a
|
|
secondary index, the DBcursor->get and DBcursor->pget methods return the
|
|
record number of the primary database in <b>data</b>. In addition, the
|
|
DBcursor->pget method returns the record number of the secondary index in
|
|
<b>pkey</b>. If either underlying database is not of type Btree or is
|
|
not created with the <a href="../api_c/db_set_flags.html#DB_RECNUM">DB_RECNUM</a> flag, the out-of-band record
|
|
number of 0 is returned.</p></ul>
|
|
<b><a name="DB_JOIN_ITEM">DB_JOIN_ITEM</a></b><ul compact><li>Do not use the data value found in all of the cursors as a lookup key for
|
|
the primary database, but simply return it in the key parameter instead.
|
|
The data parameter is left unchanged.
|
|
<p>For DB_JOIN_ITEM to be specified, the underlying cursor must have
|
|
been returned from the <a href="../api_c/db_join.html">DB->join</a> method.</p></ul>
|
|
<b><a name="DB_LAST">DB_LAST</a></b><ul compact><li>The cursor is set to refer to the last key/data pair of the database,
|
|
and that pair is returned. If the last key has duplicate values, the
|
|
last data item in the set of duplicates is returned.
|
|
<p>If the database is a Queue or Recno database, DBcursor->get using the
|
|
DB_LAST flag will ignore any keys that exist but were never
|
|
explicitly created by the application, or were created and later
|
|
deleted.</p>
|
|
<p>The DBcursor->get method will return <a href="../ref/program/errorret.html#DB_NOTFOUND">DB_NOTFOUND</a> if DB_LAST is set and the database is empty.
|
|
</p></ul>
|
|
<b><a name="DB_NEXT">DB_NEXT</a></b><ul compact><li>If the cursor is not yet initialized, DB_NEXT is identical to
|
|
DB_FIRST. Otherwise, the cursor is moved to the next key/data
|
|
pair of the database, and that pair is returned. In the presence of
|
|
duplicate key values, the value of the key may not change.
|
|
<p>If the database is a Queue or Recno database, DBcursor->get using the
|
|
DB_NEXT flag will skip any keys that exist but were never
|
|
explicitly created by the application, or those that were created and
|
|
later deleted.</p>
|
|
<p>The DBcursor->get method will return <a href="../ref/program/errorret.html#DB_NOTFOUND">DB_NOTFOUND</a> if DB_NEXT is set and the cursor is already on the last record
|
|
in the database.
|
|
</p></ul>
|
|
<b><a name="DB_NEXT_DUP">DB_NEXT_DUP</a></b><ul compact><li>If the next key/data pair of the database is a duplicate data record for
|
|
the current key/data pair, the cursor is moved to the next key/data pair
|
|
of the database, and that pair is returned.
|
|
<p>The DBcursor->get method will return <a href="../ref/program/errorret.html#DB_NOTFOUND">DB_NOTFOUND</a> if DB_NEXT_DUP is set and the next key/data pair of the
|
|
database is not a duplicate data record for the current key/data pair.
|
|
</p></ul>
|
|
<b><a name="DB_NEXT_NODUP">DB_NEXT_NODUP</a></b><ul compact><li>If the cursor is not yet initialized, DB_NEXT_NODUP is identical
|
|
to DB_FIRST. Otherwise, the cursor is moved to the next
|
|
non-duplicate key of the database, and that key/data pair is returned.
|
|
<p>If the database is a Queue or Recno database, DBcursor->get using the
|
|
DB_NEXT_NODUP flag will ignore any keys that exist but were
|
|
never explicitly created by the application, or those that were created
|
|
and later deleted.</p>
|
|
<p>The DBcursor->get method will return <a href="../ref/program/errorret.html#DB_NOTFOUND">DB_NOTFOUND</a> if DB_NEXT_NODUP is set and no non-duplicate key/data pairs
|
|
occur after the cursor position in the database.
|
|
</p></ul>
|
|
<b><a name="DB_PREV">DB_PREV</a></b><ul compact><li>If the cursor is not yet initialized, DB_PREV is identical to
|
|
DB_LAST. Otherwise, the cursor is moved to the previous
|
|
key/data pair of the database, and that pair is returned. In the
|
|
presence of duplicate key values, the value of the key may not change.
|
|
<p>If the database is a Queue or Recno database, DBcursor->get using the
|
|
DB_PREV flag will skip any keys that exist but were never
|
|
explicitly created by the application, or those that were created and
|
|
later deleted.</p>
|
|
<p>The DBcursor->get method will return <a href="../ref/program/errorret.html#DB_NOTFOUND">DB_NOTFOUND</a> if DB_PREV is set and the cursor is already on the first record
|
|
in the database.
|
|
</p></ul>
|
|
<b><a name="DB_PREV_DUP">DB_PREV_DUP</a></b><ul compact><li>If the previous key/data pair of the database is a duplicate data record
|
|
for the current key/data pair, the cursor is moved to the previous key/data
|
|
pair of the database, and that pair is returned.
|
|
<p>The DBcursor->get method will return <a href="../ref/program/errorret.html#DB_NOTFOUND">DB_NOTFOUND</a> if DB_PREV_DUP is set and the previous key/data pair of the
|
|
database is not a duplicate data record for the current key/data pair.
|
|
</p></ul>
|
|
<b><a name="DB_PREV_NODUP">DB_PREV_NODUP</a></b><ul compact><li>If the cursor is not yet initialized, DB_PREV_NODUP is identical
|
|
to DB_LAST. Otherwise, the cursor is moved to the previous
|
|
non-duplicate key of the database, and that key/data pair is returned.
|
|
<p>If the database is a Queue or Recno database, DBcursor->get using the
|
|
DB_PREV_NODUP flag will ignore any keys that exist but were
|
|
never explicitly created by the application, or those that were created
|
|
and later deleted.</p>
|
|
<p>The DBcursor->get method will return <a href="../ref/program/errorret.html#DB_NOTFOUND">DB_NOTFOUND</a> if DB_PREV_NODUP is set and no non-duplicate key/data pairs
|
|
occur before the cursor position in the database.
|
|
</p></ul>
|
|
<b><a name="DB_SET">DB_SET</a></b><ul compact><li>Move the cursor to the specified key/data pair of the database, and
|
|
return the datum associated with the given key.
|
|
<p>The DBcursor->get method will return <a href="../ref/program/errorret.html#DB_NOTFOUND">DB_NOTFOUND</a> if DB_SET is set and
|
|
no matching keys are found.
|
|
The DBcursor->get method will return <a href="../ref/program/errorret.html#DB_KEYEMPTY">DB_KEYEMPTY</a> if DB_SET is set and 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.
|
|
In the presence of duplicate key values, DBcursor->get will return the
|
|
first data item for the given key.
|
|
</p></ul>
|
|
<b><a name="DB_SET_RANGE">DB_SET_RANGE</a></b><ul compact><li>The DB_SET_RANGE flag is identical to the DB_SET flag,
|
|
except that in the case of the Btree access method, the key is returned
|
|
as well as the data item and the returned key/data pair is the smallest
|
|
key greater than or equal to the specified key (as determined by the
|
|
Btree comparison function), permitting partial key matches and range
|
|
searches.</ul>
|
|
<b><a name="DB_SET_RECNO">DB_SET_RECNO</a></b><ul compact><li>Move the cursor to the specific numbered record of the database, and
|
|
return the associated key/data pair. The <b>data</b> field of the
|
|
specified <b>key</b> must be a pointer to a memory location from which
|
|
a <a href="../api_c/dbt_class.html#db_recno_t">db_recno_t</a> may be read, as described in <a href="../api_c/dbt_class.html">DBT</a>. This
|
|
memory location will be read to determine the record to be retrieved.
|
|
<p>For DB_SET_RECNO to be specified, the underlying database must be
|
|
of type Btree, and it must have been created with the <a href="../api_c/db_set_flags.html#DB_RECNUM">DB_RECNUM</a>
|
|
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_READ_UNCOMMITTED">DB_READ_UNCOMMITTED</a></b><ul compact><li>Database items read during a transactional call will have degree 1
|
|
isolation, including 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_MULTIPLE">DB_MULTIPLE</a></b><ul compact><li>Return multiple data items in the <b>data</b> parameter.
|
|
<p>In the case of Btree or Hash databases, duplicate data items for the
|
|
current key, starting at the current cursor position, are entered into
|
|
the buffer. Subsequent calls with both the DB_NEXT_DUP and
|
|
DB_MULTIPLE flags specified will return additional duplicate
|
|
data items associated with the current key or <a href="../ref/program/errorret.html#DB_NOTFOUND">DB_NOTFOUND</a> if
|
|
there are no additional duplicate data items to return. Subsequent
|
|
calls with both the DB_NEXT and DB_MULTIPLE flags
|
|
specified will return additional duplicate data items associated with
|
|
the current key or if there are no additional duplicate data items will
|
|
return the next key and its data items or <a href="../ref/program/errorret.html#DB_NOTFOUND">DB_NOTFOUND</a> if there
|
|
are no additional keys in the database.</p>
|
|
<p>In the case of Queue or Recno databases, data items starting at the
|
|
current cursor position are entered into the buffer. The record number
|
|
of the first record will be returned in the <b>key</b> parameter. The
|
|
record number of each subsequent returned record must be calculated from
|
|
this value. Subsequent calls with the DB_MULTIPLE flag
|
|
specified will return additional data items or <a href="../ref/program/errorret.html#DB_NOTFOUND">DB_NOTFOUND</a> if
|
|
there are no additional data items to return.</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 multiple data items can be iterated over using the
|
|
<a href="../api_c/dbt_bulk.html#DB_MULTIPLE_NEXT">DB_MULTIPLE_NEXT</a> macro.</p>
|
|
<p>The DB_MULTIPLE flag may only be used with the
|
|
DB_CURRENT, DB_FIRST, DB_GET_BOTH,
|
|
DB_GET_BOTH_RANGE, DB_NEXT, DB_NEXT_DUP,
|
|
DB_NEXT_NODUP, DB_SET, DB_SET_RANGE, 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></ul>
|
|
<b><a name="DB_MULTIPLE_KEY">DB_MULTIPLE_KEY</a></b><ul compact><li>Return multiple key and data pairs in the <b>data</b> parameter.
|
|
<p>Key and data pairs, starting at the current cursor position, are entered
|
|
into the buffer. Subsequent calls with both the DB_NEXT and
|
|
DB_MULTIPLE_KEY flags specified will return additional key and data
|
|
pairs or <a href="../ref/program/errorret.html#DB_NOTFOUND">DB_NOTFOUND</a> if there are no additional key and data
|
|
items to return.</p>
|
|
<p>In the case of Btree or Hash databases,
|
|
the multiple key and data pairs can be iterated over using the
|
|
<a href="../api_c/dbt_bulk.html#DB_MULTIPLE_KEY_NEXT">DB_MULTIPLE_KEY_NEXT</a> macro.</p>
|
|
<p>In the case of Queue or Recno databases,
|
|
the multiple record number and data pairs can be iterated over using the
|
|
<a href="../api_c/dbt_bulk.html#DB_MULTIPLE_RECNO_NEXT">DB_MULTIPLE_RECNO_NEXT</a> macro.</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_KEY flag may only be used with the
|
|
DB_CURRENT, DB_FIRST, DB_GET_BOTH,
|
|
DB_GET_BOTH_RANGE, DB_NEXT, DB_NEXT_DUP,
|
|
DB_NEXT_NODUP, DB_SET, DB_SET_RANGE, and
|
|
DB_SET_RECNO options. The DB_MULTIPLE_KEY 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></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.
|
|
</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 secondary index key <a href="../api_c/dbt_class.html">DBT</a> operated on.</ul>
|
|
<br>
|
|
<br><b>Errors</b>
|
|
<p>The DBcursor->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_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 the DB_CURRENT, DB_NEXT_DUP or DB_PREV_DUP flags
|
|
were specified and the cursor has not been initialized;
|
|
the DBcursor->pget method was called with a cursor 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/dbc_class.html">DBC</a>
|
|
<br><b>See Also</b>
|
|
<a href="../api_c/dbc_list.html">Database Cursors 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>
|