mirror of
https://github.com/MariaDB/server.git
synced 2025-01-30 18:41:56 +01:00
156 lines
8.4 KiB
HTML
156 lines
8.4 KiB
HTML
<!--$Id: db_get.so,v 10.31 2000/11/28 20:12:30 bostic Exp $-->
|
|
<!--Copyright 1997, 1998, 1999, 2000 by Sleepycat Software, Inc.-->
|
|
<!--All rights reserved.-->
|
|
<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,b+tree,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,java,C,C++">
|
|
</head>
|
|
<body bgcolor=white>
|
|
<a name="2"><!--meow--></a>
|
|
<table><tr valign=top>
|
|
<td>
|
|
<h1>DB->get</h1>
|
|
</td>
|
|
<td width="1%">
|
|
<a href="../api_c/c_index.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>
|
|
<h3><pre>
|
|
#include <db.h>
|
|
<p>
|
|
int
|
|
DB->get(DB *db,
|
|
DB_TXN *txnid, DBT *key, DBT *data, u_int32_t flags);
|
|
</pre></h3>
|
|
<h1>Description</h1>
|
|
<p>The DB->get function 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 referenced by <b>data</b>.
|
|
<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->c_get</a> for details.
|
|
<p>If the file is being accessed under transaction protection, the
|
|
<b>txnid</b> parameter is a transaction ID returned from
|
|
<a href="../api_c/txn_begin.html">txn_begin</a>, otherwise, NULL.
|
|
<p>The <b>flags</b> parameter must be set to 0 or one of the following
|
|
values:
|
|
<p><dl compact>
|
|
<p><dt><a name="DB_CONSUME">DB_CONSUME</a><dd>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. The record number will be returned
|
|
in <b>key</b> as described in <a href="../api_c/dbt.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.
|
|
<p><dt><a name="DB_CONSUME_WAIT">DB_CONSUME_WAIT</a><dd>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><dt><a name="DB_GET_BOTH">DB_GET_BOTH</a><dd>Retrieve the key/data pair only if both the key and data match the
|
|
arguments.
|
|
<p><dt><a name="DB_SET_RECNO">DB_SET_RECNO</a><dd>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, not just the data item as is done for all other uses of the
|
|
DB->get function.
|
|
<p>The <b>data</b> field of the specified <b>key</b>
|
|
must be a pointer to a logical record number (i.e., a <b>db_recno_t</b>).
|
|
This record number determines 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 DB_RECNUM flag.
|
|
</dl>
|
|
<p>In addition, the following flag may be set by bitwise inclusively <b>OR</b>'ing it into the
|
|
<b>flags</b> parameter:
|
|
<p><dl compact>
|
|
<p><dt><a name="DB_RMW">DB_RMW</a><dd>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>As the DB->get interface will not hold locks across
|
|
Berkeley DB interface calls in non-transactional environments, the
|
|
<a href="../api_c/dbc_get.html#DB_RMW">DB_RMW</a> flag to the DB->get call is only meaningful in
|
|
the presence of transactions.
|
|
</dl>
|
|
<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,
|
|
the DB->get function returns <a href="../ref/program/errorret.html#DB_KEYEMPTY">DB_KEYEMPTY</a>.
|
|
<p>Otherwise, if the requested key is not in the database, the
|
|
DB->get function returns <a href="../ref/program/errorret.html#DB_NOTFOUND">DB_NOTFOUND</a>.
|
|
<p>Otherwise, the DB->get function returns a non-zero error value on failure and 0 on success.
|
|
<h1>Errors</h1>
|
|
<p>The DB->get function may fail and return a non-zero error for the following conditions:
|
|
<p><dl compact>
|
|
<p><dt>DB_LOCK_DEADLOCK<dd>The operation was selected to resolve a deadlock.
|
|
</dl>
|
|
<p><dl compact>
|
|
<p><dt>ENOMEM<dd>There was insufficient memory to return the requested item.
|
|
</dl>
|
|
<p><dl compact>
|
|
<p><dt>EINVAL<dd>An invalid flag value or parameter was specified.
|
|
<p>A record number of 0 was specified.
|
|
<p>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> function and none of the <a href="../api_c/dbt.html#DB_DBT_MALLOC">DB_DBT_MALLOC</a>,
|
|
<a href="../api_c/dbt.html#DB_DBT_REALLOC">DB_DBT_REALLOC</a> or <a href="../api_c/dbt.html#DB_DBT_USERMEM">DB_DBT_USERMEM</a> flags were set in the
|
|
<a href="../api_c/dbt.html">DBT</a>.
|
|
</dl>
|
|
<p>The DB->get function may fail and return a non-zero error for errors specified for other Berkeley DB and C library or system functions.
|
|
If a catastrophic error has occurred, the DB->get function may fail and return
|
|
<a href="../ref/program/errorret.html#DB_RUNRECOVERY">DB_RUNRECOVERY</a>, in which case all subsequent Berkeley DB calls will fail
|
|
in the same way.
|
|
<h1>See Also</h1>
|
|
<a href="../api_c/db_create.html">db_create</a>,
|
|
<a href="../api_c/db_close.html">DB->close</a>,
|
|
<a href="../api_c/db_cursor.html">DB->cursor</a>,
|
|
<a href="../api_c/db_del.html">DB->del</a>,
|
|
<a href="../api_c/db_err.html">DB->err</a>,
|
|
<a href="../api_c/db_fd.html">DB->fd</a>,
|
|
<a href="../api_c/db_get.html">DB->get</a>,
|
|
<a href="../api_c/db_get_byteswapped.html">DB->get_byteswapped</a>,
|
|
<a href="../api_c/db_get_type.html">DB->get_type</a>,
|
|
<a href="../api_c/db_join.html">DB->join</a>,
|
|
<a href="../api_c/db_key_range.html">DB->key_range</a>,
|
|
<a href="../api_c/db_open.html">DB->open</a>,
|
|
<a href="../api_c/db_put.html">DB->put</a>,
|
|
<a href="../api_c/db_remove.html">DB->remove</a>,
|
|
<a href="../api_c/db_set_bt_compare.html">DB->set_bt_compare</a>,
|
|
<a href="../api_c/db_set_bt_minkey.html">DB->set_bt_minkey</a>,
|
|
<a href="../api_c/db_set_bt_prefix.html">DB->set_bt_prefix</a>,
|
|
<a href="../api_c/db_set_cachesize.html">DB->set_cachesize</a>,
|
|
<a href="../api_c/db_set_dup_compare.html">DB->set_dup_compare</a>,
|
|
<a href="../api_c/db_set_errcall.html">DB->set_errcall</a>,
|
|
<a href="../api_c/db_set_errfile.html">DB->set_errfile</a>,
|
|
<a href="../api_c/db_set_errpfx.html">DB->set_errpfx</a>,
|
|
<a href="../api_c/db_set_flags.html">DB->set_flags</a>,
|
|
<a href="../api_c/db_set_h_ffactor.html">DB->set_h_ffactor</a>,
|
|
<a href="../api_c/db_set_h_hash.html">DB->set_h_hash</a>,
|
|
<a href="../api_c/db_set_h_nelem.html">DB->set_h_nelem</a>,
|
|
<a href="../api_c/db_set_lorder.html">DB->set_lorder</a>,
|
|
<a href="../api_c/db_set_malloc.html">DB->set_malloc</a>,
|
|
<a href="../api_c/db_set_pagesize.html">DB->set_pagesize</a>,
|
|
<a href="../api_c/db_set_paniccall.html">DB->set_paniccall</a>,
|
|
<a href="../api_c/db_set_q_extentsize.html">DB->set_q_extentsize</a>,
|
|
<a href="../api_c/db_set_realloc.html">DB->set_realloc</a>,
|
|
<a href="../api_c/db_set_re_delim.html">DB->set_re_delim</a>,
|
|
<a href="../api_c/db_set_re_len.html">DB->set_re_len</a>,
|
|
<a href="../api_c/db_set_re_pad.html">DB->set_re_pad</a>,
|
|
<a href="../api_c/db_set_re_source.html">DB->set_re_source</a>,
|
|
<a href="../api_c/db_stat.html">DB->stat</a>,
|
|
<a href="../api_c/db_sync.html">DB->sync</a>,
|
|
<a href="../api_c/db_upgrade.html">DB->upgrade</a>
|
|
and
|
|
<a href="../api_c/db_verify.html">DB->verify</a>.
|
|
</tt>
|
|
<table><tr><td><br></td><td width="1%">
|
|
<a href="../api_c/c_index.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><a href="http://www.sleepycat.com">Copyright Sleepycat Software</a></font>
|
|
</body>
|
|
</html>
|