168 lines
8.8 KiB
HTML
168 lines
8.8 KiB
HTML
<!--$Id: dbc_get.html 63573 2008-05-23 21:43:21Z trent.nelson $-->
|
|
<!--$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: 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><i>dbc</i> <b>get</b></b>
|
|
</td>
|
|
<td align=right>
|
|
<a href="../api_tcl/api_tcl.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>dbc get
|
|
[-current]
|
|
[-first]
|
|
[-get_recno]
|
|
[-join_item]
|
|
[-last]
|
|
[-next]
|
|
[-nextdup]
|
|
[-nextnodup]
|
|
[-partial {offset length}]
|
|
[-prev]
|
|
[-prevnodup]
|
|
[-rmw]
|
|
dbc get
|
|
[-partial {offset length}]
|
|
[-rmw]
|
|
[-set]
|
|
[-set_range]
|
|
[-set_recno]
|
|
key
|
|
dbc get
|
|
-get_both
|
|
[-partial {offset length}]
|
|
[-rmw]
|
|
key data
|
|
</pre></b>
|
|
<b>Description(db get)</b>
|
|
<p>The <i>dbc</i> <b>get</b> command returns a list of {key value} pairs, except in
|
|
the case of the <b>-get_recno</b> and <b>-join_item</b> options. In
|
|
the case of the <b>-get_recno</b> option, <i>dbc</i> <b>get</b> returns a list
|
|
of the record number. In the case of the <b>-join_item</b> option,
|
|
<i>dbc</i> <b>get</b> returns a list containing the joined key.</p>
|
|
<p>The options are as follows:</p>
|
|
<br>
|
|
<b>-current</b><ul compact><li>Return the key/data pair to which the cursor currently refers.
|
|
<p>If the cursor key/data pair was deleted, <i>dbc</i> <b>get</b> will return an
|
|
empty list.</p></ul>
|
|
<b>-first</b><ul compact><li>The cursor is set to refer to the first key/data pair of the database, and
|
|
that pair is returned. In the presence of duplicate key values, the first
|
|
data item in the set of duplicates is returned.
|
|
<p>If the database is a Queue or Recno database, <i>dbc</i> <b>get</b> using the
|
|
<b>-first</b> option will skip any keys that exist but were never
|
|
explicitly created by the application, or were created and later deleted.</p>
|
|
<p>If the database is empty, <i>dbc</i> <b>get</b> will return an empty list.</p></ul>
|
|
<b>-last</b><ul compact><li>The cursor is set to refer to the last key/data pair of the database, and
|
|
that pair is returned. In the presence of duplicate key values, the last
|
|
data item in the set of duplicates is returned.
|
|
<p>If the database is a Queue or Recno database, <i>dbc</i> <b>get</b> using the
|
|
<b>-last</b> option will skip any keys that exist but were never
|
|
explicitly created by the application, or were created and later deleted.</p>
|
|
<p>If the database is empty, <i>dbc</i> <b>get</b> will return an empty list.</p></ul>
|
|
<b>-next</b><ul compact><li>If the cursor is not yet initialized, the <b>-next</b> option is
|
|
identical to <b>-first</b>.
|
|
<p>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>
|
|
<p>If the database is a Queue or Recno database, <i>dbc</i> <b>get</b> using the
|
|
<b>-next</b> option will skip any keys that exist but were never
|
|
explicitly created by the application, or were created and later deleted.</p>
|
|
<p>If the cursor is already on the last record in the database, <i>dbc</i> <b>get</b>
|
|
will return an empty list.</p></ul>
|
|
<b>-nextdup</b><ul compact><li>If the next key/data pair of the database is a duplicate 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. Otherwise, <i>dbc</i> <b>get</b> will return
|
|
an empty list.</ul>
|
|
<b>-nextnodup</b><ul compact><li>If the cursor is not yet initialized, the <b>-nextnodup</b> option is
|
|
identical to <b>-first</b>.
|
|
<p>Otherwise, the cursor is moved to the next non-duplicate
|
|
key/data pair of the database, and that pair is returned.</p>
|
|
<p>If no non-duplicate key/data pairs occur after the cursor
|
|
position in the database, <i>dbc</i> <b>get</b> will return an empty list.</p></ul>
|
|
<b>-prev</b><ul compact><li>If the cursor is not yet initialized, <b>-prev</b> is identical to
|
|
<b>-last</b>.
|
|
<p>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>
|
|
<p>If the database is a Queue or Recno database, <i>dbc</i> <b>get</b> using the
|
|
<b>-prev</b> flag will skip any keys that exist but were never explicitly
|
|
created by the application, or were created and later deleted.</p>
|
|
<p>If the cursor is already on the first record in the database,
|
|
<i>dbc</i> <b>get</b> will return an empty list.</p></ul>
|
|
<b>-prevnodup</b><ul compact><li>If the cursor is not yet initialized, the <b>-prevnodup</b> option is
|
|
identical to <b>-last</b>.
|
|
<p>Otherwise, the cursor is moved to the previous non-duplicate
|
|
key/data pair of the database, and that pair is returned.</p>
|
|
<p>If no non-duplicate key/data pairs occur before the cursor
|
|
position in the database, <i>dbc</i> <b>get</b> will return an empty list.</p></ul>
|
|
<b>-set</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>In the presence of duplicate key values, <i>dbc</i> <b>get</b> will return the
|
|
first data item for the given key.</p>
|
|
<p>If the database is a Queue or Recno database and the requested key exists,
|
|
but was never explicitly created by the application or was later deleted,
|
|
<i>dbc</i> <b>get</b> will return an empty list.</p>
|
|
<p>If no matching keys are found, <i>dbc</i> <b>get</b> will return an empty list.</p></ul>
|
|
<b>-set_range</b><ul compact><li>The <b>-set_range</b> option is identical to the <b>-set</b> option,
|
|
except that the key is returned as well as the data item, and, in the case
|
|
of the Btree access method, the returned key/data pair is the smallest
|
|
key greater than or equal to the specified key (as determined by the
|
|
comparison function), permitting partial key matches and range searches.</ul>
|
|
<b>-get_both</b><ul compact><li>The <b>-get_both</b> option is identical to the <b>-set</b> option,
|
|
except that both the key and the data arguments must be matched by the
|
|
key and data item in the database.
|
|
<p>For <b>-get_both</b> to be specified, the underlying database must be of
|
|
type Btree or Hash.</p></ul>
|
|
<b>-set_recno</b><ul compact><li>Move the cursor to the specific numbered record of the database, and
|
|
return the associated key/data pair. The key
|
|
must be a record number.
|
|
<p>For the <b>-set_recno</b> option to be specified, the underlying database
|
|
must be of type Btree, and it must have been created with the <b>-recnum</b>
|
|
option.</p></ul>
|
|
<b>-get_recno</b><ul compact><li>Return a list of the record number associated with the current cursor
|
|
position. No key argument should be specified.
|
|
<p>For <b>-get_recno</b> to be specified, the underlying database must be
|
|
of type Btree, and it must have been created with the <b>-recnum</b>
|
|
option.</p></ul>
|
|
<b>-join_item</b><ul compact><li>Do not use the data value found in all 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 <b>-join_item</b> to be specified, the cursor must have been created
|
|
by the <i>db</i> <b>join</b> command.</p></ul>
|
|
<b>-partial {offset length}</b><ul compact><li>The <b>dlen</b> bytes starting <b>doff</b> bytes from the beginning
|
|
of the retrieved data record are returned as if they comprised the
|
|
entire record. If any or all of the specified bytes do not exist in
|
|
the record, the command is successful and any existing bytes are
|
|
returned.</ul>
|
|
<b>-rmw</b><ul compact><li>Acquire write locks instead of read locks when doing the retrieval. Setting
|
|
this flag may decrease the likelihood of deadlock during a read-modify-write
|
|
cycle by immediately 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>
|
|
<p>If a key is specified, and if the underlying database is a Queue or
|
|
Recno database, the given key will be interpreted by Tcl as an integer.
|
|
For all other database types, the key is interpreted by Tcl as a byte
|
|
array, unless indicated by a given option.</p>
|
|
<p>In the normal error case of attempting to retrieve a key that does not
|
|
exist an empty list is returned.</p>
|
|
<p>In the case of error, a Tcl error is thrown.</p>
|
|
</tt>
|
|
<table width="100%"><tr><td><br></td><td align=right>
|
|
<a href="../api_tcl/api_tcl.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>
|