<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<title>Db::key_range()</title>
<link rel="stylesheet" href="apiReference.css" type="text/css" />
<meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
<link rel="start" href="index.html" title="Berkeley DB C++ API Reference" />
<link rel="up" href="db.html" title="Chapter 2. The Db Handle" />
<link rel="prev" href="dbjoin.html" title="Db::join()" />
<link rel="next" href="dbopen.html" title="Db::open()" />
</head>
<body>
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr>
<th colspan="3" align="center">Db::key_range()</th>
</tr>
<tr>
<td width="20%" align="left"><a accesskey="p" href="dbjoin.html">Prev</a> </td>
<th width="60%" align="center">Chapter 2.
The Db Handle
</th>
<td width="20%" align="right"> <a accesskey="n" href="dbopen.html">Next</a></td>
</tr>
</table>
<hr />
</div>
<div class="sect1" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both"><a id="dbkey_range"></a>Db::key_range()</h2>
</div>
</div>
</div>
<pre class="programlisting">#include <db_cxx.h>
int
Db::key_range(DbTxn *txnid
Dbt *key, DB_KEY_RANGE *key_range, u_int32_t flags);</pre>
<p>
The <code class="methodname">Db::key_range()</code> method returns an estimate of the proportion of
keys that are less than, equal to, and greater than the specified key.
The underlying database must be of type Btree.
</p>
<p>
The <code class="methodname">Db::key_range()</code> method fills in a structure of type DB_KEY_RANGE.
The following data fields are available from the DB_KEY_RANGE
structure:
</p>
<div class="itemizedlist">
<ul type="disc">
<li>
<p>
<span class="bold"><strong>double less;</strong></span>
</p>
<p>
A value between 0 and 1, the proportion of keys less than the
specified key.
</p>
</li>
<li>
<p>
<span class="bold"><strong>double equal;</strong></span>
</p>
<p>
A value between 0 and 1, the proportion of keys equal to the specified
key.
</p>
</li>
<li>
<p>
<span class="bold"><strong>double greater;</strong></span>
</p>
<p>
A value between 0 and 1, the proportion of keys greater than the
specified key.
</p>
</li>
</ul>
</div>
<p>
Values are in the range of 0 to 1; for example, if the field <span class="bold"><strong>less</strong></span> is 0.05, 5% of the keys in the database
are less than the <span class="bold"><strong>key</strong></span> parameter. The
value for <span class="bold"><strong>equal</strong></span> will be zero if there
is no matching key, and will be non-zero otherwise.
</p>
<p>
The <code class="methodname">Db::key_range()</code> <span>
<span>
method either returns a non-zero error value or throws an
exception that encapsulates a non-zero error value on
failure, and returns 0 on success.
</span>
</span>
</p>
<div class="sect2" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="id1639167"></a>Parameters</h3>
</div>
</div>
</div>
<div class="sect3" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a id="id1638754"></a>key</h4>
</div>
</div>
</div>
<p>
The key <a class="link" href="dbt.html" title="Chapter 4. The Dbt Handle">Dbt</a> operated on.
</p>
</div>
<div class="sect3" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a id="id1638709"></a>key_range</h4>
</div>
</div>
</div>
<p>
The estimates are returned in the <span class="bold"><strong>key_range</strong></span> parameter, which contains three
elements of type double: <span class="bold"><strong>less</strong></span>,
<span class="bold"><strong>equal</strong></span>, and <span class="bold"><strong>greater</strong></span>. Values are in the range of 0 to 1;
for example, if the field <span class="bold"><strong>less</strong></span> is
0.05, 5% of the keys in the database are less than the <span class="bold"><strong>key</strong></span> parameter. The value for <span class="bold"><strong>equal</strong></span> will be zero if there is no matching key,
and will be non-zero otherwise.
</p>
</div>
<div class="sect3" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a id="id1639515"></a>txnid</h4>
</div>
</div>
</div>
<p>
If the operation is part of an application-specified transaction, the
<span class="bold"><strong>txnid</strong></span> parameter is a transaction
handle returned from <a class="xref" href="txnbegin.html" title="DbEnv::txn_begin()">DbEnv::txn_begin()</a>;
if the operation is part of a Berkeley DB Concurrent Data Store group, the
<span class="bold"><strong>txnid</strong></span> parameter is a handle returned
from <a class="xref" href="envcdsgroup_begin.html" title="DbEnv::cdsgroup_begin()">DbEnv::cdsgroup_begin()</a>;
otherwise NULL. If no transaction handle is specified, but the
operation occurs in a transactional database, the operation will be
implicitly transaction protected. The <code class="methodname">Db::key_range()</code> method does not
retain the locks it acquires for the life of the transaction, so
estimates may not be repeatable.
</p>
</div>
<div class="sect3" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a id="id1638658"></a>flags</h4>
</div>
</div>
</div>
<p>
The <span class="bold"><strong>flags</strong></span> parameter is currently
unused, and must be set to 0.
</p>
</div>
</div>
<div class="sect2" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="id1639629"></a>Errors</h3>
</div>
</div>
</div>
<p>
The <code class="methodname">Db::key_range()</code> <span>
<span>
method may fail and throw a <a class="link" href="dbexception.html" title="Chapter 6. The DbException Class">DbException</a>
exception, encapsulating one of the following non-zero errors, or return one
of the following non-zero errors:
</span>
</span>
</p>
<div class="sect3" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a id="id1639039"></a><span>DbDeadlockException or </span>DB_LOCK_DEADLOCK</h4>
</div>
</div>
</div>
<p>
A transactional database environment operation was selected to resolve
a deadlock.
</p>
<p>
<a class="xref" href="dbdeadlock.html" title="DbDeadlockException">DbDeadlockException</a> is thrown if
your Berkeley DB API is configured to throw exceptions.
Otherwise, <code class="literal">DB_LOCK_DEADLOCK</code> is returned.
</p>
</div>
<div class="sect3" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a id="id1638710"></a><span>DbLockNotGrantedException or </span>DB_LOCK_NOTGRANTED</h4>
</div>
</div>
</div>
<p>
A Berkeley DB Concurrent Data Store database environment configured
for lock timeouts was unable to grant a lock in the allowed time.
</p>
<p>
<a class="xref" href="dblocknotgranted.html" title="DbLockNotGrantedException">DbLockNotGrantedException</a> is thrown if
your Berkeley DB API is configured to throw exceptions.
Otherwise, <code class="literal">DB_LOCK_NOTGRANTED</code> is returned.
</p>
</div>
<div class="sect3" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a id="id1639770"></a><span>DbRepHandleDeadException or</span> DB_REP_HANDLE_DEAD</h4>
</div>
</div>
</div>
<p>
When a client synchronizes with the master, it is possible for committed
transactions to be rolled back. This invalidates all the database and cursor
handles opened in the replication environment. Once this occurs, an attempt to use
such a handle will
<span>
throw a <a class="xref" href="dbrephandledead.html" title="DbRepHandleDeadException">DbRepHandleDeadException</a> (if
your application is configured to throw exceptions), or
</span>
return <code class="literal">DB_REP_HANDLE_DEAD</code>.
The application will need to discard the handle and open a new one in order to
continue processing.
</p>
</div>
<div class="sect3" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a id="id1638755"></a><span>DbDeadlockException or </span>DB_REP_LOCKOUT</h4>
</div>
</div>
</div>
<p>
The operation was blocked by client/master synchronization.
</p>
<p>
<a class="xref" href="dbdeadlock.html" title="DbDeadlockException">DbDeadlockException</a> is thrown if
your Berkeley DB API is configured to throw exceptions.
Otherwise, <code class="literal">DB_REP_LOCKOUT</code> is returned.
</p>
</div>
<div class="sect3" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a id="id1639797"></a>EINVAL</h4>
</div>
</div>
</div>
<p>
If the underlying database was not of type Btree; or if an invalid
flag value or parameter was specified.
</p>
</div>
</div>
<div class="sect2" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="id1638602"></a>Class</h3>
</div>
</div>
</div>
<p>
<a class="link" href="db.html" title="Chapter 2. The Db Handle">Db</a>
</p>
</div>
<div class="sect2" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="id1639358"></a>See Also</h3>
</div>
</div>
</div>
<p>
<a class="xref" href="db.html#dblist" title="Database and Related Methods">Database and Related Methods</a>
</p>
</div>
</div>
<div class="navfooter">
<hr />
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left"><a accesskey="p" href="dbjoin.html">Prev</a> </td>
<td width="20%" align="center">
<a accesskey="u" href="db.html">Up</a>
</td>
<td width="40%" align="right"> <a accesskey="n" href="dbopen.html">Next</a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top">Db::join() </td>
<td width="20%" align="center">
<a accesskey="h" href="index.html">Home</a>
</td>
<td width="40%" align="right" valign="top"> Db::open()</td>
</tr>
</table>
</div>
</body>
</html>
distrib
>
Mandriva
>
2010.1
>
x86_64
>
media
>
main-release
>
by-pkgid
>
a00abf5f94bf470fd4cc9e10b2d135e0
>
files
>
461
