1
<!--$Id: db_key_range.so,v 10.7 2001/04/02 00:36:34 bostic Exp $-->
2
<!--Copyright 1997-2001 by Sleepycat Software, Inc.-->
3
<!--All rights reserved.-->
6
<title>Berkeley DB: Db::key_range</title>
7
<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit.">
8
<meta name="keywords" content="embedded,database,programmatic,toolkit,b+tree,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,java,C,C++">
11
<a name="2"><!--meow--></a>
12
<table width="100%"><tr valign=top>
14
<h1>Db::key_range</h1>
17
<a href="../api_cxx/cxx_index.html"><img src="../images/api.gif" alt="API"></a><a href="../reftoc.html"><img src="../images/ref.gif" alt="Ref"></a>
22
#include <db_cxx.h>
25
Db::key_range(DbTxn *txnid
26
Dbt *key, DB_KEY_RANGE *key_range, u_int32_t flags);
29
<p>The Db::key_range method returns an estimate of the proportion of keys
30
that are less than, equal to, and greater than the specified key. The
31
underlying database must be of type Btree.
32
<p>The information is returned in the <b>key_range</b> argument, which
33
contains three elements of type double: <b>less</b>, <b>equal</b>,
34
and <b>greater</b>. Values are in the range of 0 to 1; for example,
35
if the field <b>less</b> is 0.05, 5% of the keys in the database are
36
less than the key argument. The value for <b>equal</b> will be zero
37
if there is no matching key, and will be non-zero otherwise.
38
<p>If the operation is to be transaction-protected, the <b>txnid</b>
39
parameter is a transaction handle returned from <a href="../api_cxx/txn_begin.html">DbEnv::txn_begin</a>;
41
The Db::key_range method does not retain the locks it acquires for the
42
life of the transaction, so estimates may not be repeatable.
43
<p>The <b>flags</b> parameter is currently unused, and must be set to 0.
44
<p>The Db::key_range method either returns a non-zero error value or throws an exception that
45
encapsulates a non-zero error value on failure, and returns 0 on success.
47
<p>The Db::key_range method may fail and throw an exception or return a non-zero error for the following conditions:
49
<p><dt>DB_LOCK_DEADLOCK<dd>The operation was selected to resolve a deadlock.
52
<p><dt>EINVAL<dd>An invalid flag value or parameter was specified.
53
<p>The underlying database was not of type Btree.
55
<p>The Db::key_range method may fail and throw an exception or return a non-zero error for errors specified for other Berkeley DB and C library or system methods.
56
If a catastrophic error has occurred, the Db::key_range method may fail and either
57
return <a href="../ref/program/errorret.html#DB_RUNRECOVERY">DB_RUNRECOVERY</a> or throw an exception encapsulating
58
<a href="../ref/program/errorret.html#DB_RUNRECOVERY">DB_RUNRECOVERY</a>, in which case all subsequent Berkeley DB calls will fail
61
<a href="../api_cxx/db_class.html">Db</a>
63
<a href="../api_cxx/db_associate.html">Db::associate</a>,
64
<a href="../api_cxx/db_close.html">Db::close</a>,
65
<a href="../api_cxx/db_cursor.html">Db::cursor</a>,
66
<a href="../api_cxx/db_del.html">Db::del</a>,
67
<a href="../api_cxx/db_err.html">Db::err</a>, <a href="../api_cxx/db_err.html">Db::errx</a>
68
<a href="../api_cxx/db_fd.html">Db::fd</a>,
69
<a href="../api_cxx/db_get.html">Db::get</a>,
70
<a href="../api_cxx/db_get.html">Db::pget</a>,
71
<a href="../api_cxx/db_get_byteswapped.html">Db::get_byteswapped</a>,
72
<a href="../api_cxx/db_get_type.html">Db::get_type</a>,
73
<a href="../api_cxx/db_join.html">Db::join</a>,
74
<a href="../api_cxx/db_key_range.html">Db::key_range</a>,
75
<a href="../api_cxx/db_open.html">Db::open</a>,
76
<a href="../api_cxx/db_put.html">Db::put</a>,
77
<a href="../api_cxx/db_remove.html">Db::remove</a>,
78
<a href="../api_cxx/db_rename.html">Db::rename</a>,
79
<a href="../api_cxx/db_set_alloc.html">Db::set_alloc</a>,
80
<a href="../api_cxx/db_set_append_recno.html">Db::set_append_recno</a>,
81
<a href="../api_cxx/db_set_bt_compare.html">Db::set_bt_compare</a>,
82
<a href="../api_cxx/db_set_bt_minkey.html">Db::set_bt_minkey</a>,
83
<a href="../api_cxx/db_set_bt_prefix.html">Db::set_bt_prefix</a>,
84
<a href="../api_cxx/db_set_cachesize.html">Db::set_cachesize</a>,
85
<a href="../api_cxx/db_set_dup_compare.html">Db::set_dup_compare</a>,
86
<a href="../api_cxx/db_set_errcall.html">Db::set_errcall</a>,
87
<a href="../api_cxx/db_set_errfile.html">Db::set_errfile</a>,
88
<a href="../api_cxx/db_set_errpfx.html">Db::set_errpfx</a>,
89
<a href="../api_cxx/db_set_feedback.html">Db::set_feedback</a>,
90
<a href="../api_cxx/db_set_flags.html">Db::set_flags</a>,
91
<a href="../api_cxx/db_set_h_ffactor.html">Db::set_h_ffactor</a>,
92
<a href="../api_cxx/db_set_h_hash.html">Db::set_h_hash</a>,
93
<a href="../api_cxx/db_set_h_nelem.html">Db::set_h_nelem</a>,
94
<a href="../api_cxx/db_set_lorder.html">Db::set_lorder</a>,
95
<a href="../api_cxx/db_set_pagesize.html">Db::set_pagesize</a>,
96
<a href="../api_cxx/db_set_paniccall.html">Db::set_paniccall</a>,
97
<a href="../api_cxx/db_set_q_extentsize.html">Db::set_q_extentsize</a>,
98
<a href="../api_cxx/db_set_re_delim.html">Db::set_re_delim</a>,
99
<a href="../api_cxx/db_set_re_len.html">Db::set_re_len</a>,
100
<a href="../api_cxx/db_set_re_pad.html">Db::set_re_pad</a>,
101
<a href="../api_cxx/db_set_re_source.html">Db::set_re_source</a>,
102
<a href="../api_cxx/db_stat.html">Db::stat</a>,
103
<a href="../api_cxx/db_sync.html">Db::sync</a>,
104
<a href="../api_cxx/db_truncate.html">Db::truncate</a>,
105
<a href="../api_cxx/db_upgrade.html">Db::upgrade</a>,
107
<a href="../api_cxx/db_verify.html">Db::verify</a>.
109
<table width="100%"><tr><td><br></td><td align=right>
110
<a href="../api_cxx/cxx_index.html"><img src="../images/api.gif" alt="API"></a><a href="../reftoc.html"><img src="../images/ref.gif" alt="Ref"></a>
112
<p><font size=1><a href="http://www.sleepycat.com">Copyright Sleepycat Software</a></font>
added
removed
db/docs/api_cxx/db_key_range.html
