104 lines
5.1 KiB
HTML
104 lines
5.1 KiB
HTML
<!--$Id: db_get.html 63573 2008-05-23 21:43:21Z trent.nelson $-->
|
|
<!--$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><i>db</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>db get
|
|
[-consume]
|
|
[-consume_wait]
|
|
[-glob]
|
|
[-partial {doff dlen}]
|
|
[-recno]
|
|
[-rmw]
|
|
[-txn txnid]
|
|
key
|
|
db get
|
|
-get_both
|
|
[-partial {doff dlen}]
|
|
[-rmw]
|
|
[-txn txnid]
|
|
key data
|
|
</pre></b>
|
|
<b>Description(db get)</b>
|
|
<p>The <i>db</i> <b>get</b> command returns key/data pairs from the database.</p>
|
|
<p>In the presence of duplicate key values, <i>db</i> <b>get</b> will return all
|
|
duplicate items. Duplicates are sorted by insert order except where this
|
|
order has been overridden by cursor operations.</p>
|
|
<p>The options are as follows:</p>
|
|
<br>
|
|
<b>-consume</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 cursor will be
|
|
positioned on the deleted record. A record is available if it is not
|
|
deleted and is not currently locked. The underlying database must be
|
|
of type Queue for <b>-consume</b> to be specified.</ul>
|
|
<b>-consume_wait</b><ul compact><li>The same as the <b>-consume</b> 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 <b>-consume_wait</b> to be specified.</ul>
|
|
<b>-get_both key data</b><ul compact><li>Retrieve the key/data pair only if both the key and data match the
|
|
arguments.</ul>
|
|
<b>-glob</b><ul compact><li>Return all keys matching the given key, where the key is a simple
|
|
wildcard pattern. Where it is used, it replaces the use of the key with
|
|
the given pattern of a set of keys. Any characters after the wildcard
|
|
character are ignored. For example, in a database of last names, the
|
|
command "db0 get Jones" will return all occurrences of "Jones" in the
|
|
database, and the command "db0 get -glob Jo*" will return both "Jones"
|
|
and "Johnson" from the database. The command "db0 get -glob *" will
|
|
return all of the key/data pairs in the database.
|
|
This option only works on databases using the Btree access method.</ul>
|
|
<b>-partial {doff dlen}</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>-recno</b><ul compact><li>Retrieve the specified numbered key/data pair from a database. For
|
|
<b>-recno</b> to be specified, the specified key must be a record
|
|
number; and the underlying database must be of type Recno or Queue, or
|
|
of type Btree that was created with the <b>-recnum</b> option.</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.
|
|
<p>Because the <i>db</i> <b>get</b> command will not hold locks across Berkeley DB
|
|
interface calls in nontransactional environments, the <b>-rmw</b>
|
|
argument to the <i>db</i> <b>get</b> call is only meaningful in the presence
|
|
of transactions.</p></ul>
|
|
<b>-txn 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
|
|
<i>env</i> <b>txn</b>. If no transaction handle is specified, but the
|
|
operation occurs in a transactional
|
|
database,
|
|
the operation will be implicitly transaction protected.</ul>
|
|
<br>
|
|
<p>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>A list of key/data pairs is returned. In the error case that no matching
|
|
key exists, an empty list is returned. In all other cases, 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>
|