2011-09-13 17:44:24 +00:00
<?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 / >
< link rel = "prev" href = "dbjoin.html" title = "DB->join()" / >
< link rel = "next" href = "dbopen.html" title = "DB->open()" / >
< / head >
< body >
< div xmlns = "" class = "navheader" >
< div class = "libver" >
< p > Library Version 11.2.5.2< / p >
< / div >
< 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
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.h>
int
DB-> key_range(DB *db, DB_TXN *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 returns a non-zero error value on failure and 0 on success.
< / span >
< / span >
< / p >
< div class = "sect2" lang = "en" xml:lang = "en" >
< div class = "titlepage" >
< div >
< div >
2011-12-20 00:07:10 +00:00
< h3 class = "title" > < a id = "id3681343" > < / a > Parameters< / h3 >
2011-09-13 17:44:24 +00:00
< / div >
< / div >
< / div >
< div class = "sect3" lang = "en" xml:lang = "en" >
< div class = "titlepage" >
< div >
< div >
2011-12-20 00:07:10 +00:00
< h4 class = "title" > < a id = "id3681339" > < / a > txnid< / h4 >
2011-09-13 17:44:24 +00:00
< / 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 = "DB_ENV->txn_begin()" > DB_ENV-> 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 = "DB_ENV->cdsgroup_begin()" > DB_ENV-> 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 >
2011-12-20 00:07:10 +00:00
< h4 class = "title" > < a id = "id3680914" > < / a > key< / h4 >
2011-09-13 17:44:24 +00:00
< / div >
< / div >
< / div >
< p >
The key < a class = "link" href = "dbt.html" title = "Chapter > DBT< / a > operated on.
< / p >
< / div >
< div class = "sect3" lang = "en" xml:lang = "en" >
< div class = "titlepage" >
< div >
< div >
2011-12-20 00:07:10 +00:00
< h4 class = "title" > < a id = "id3681431" > < / a > key_range< / h4 >
2011-09-13 17:44:24 +00:00
< / 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 >
2011-12-20 00:07:10 +00:00
< h4 class = "title" > < a id = "id3681417" > < / a > flags< / h4 >
2011-09-13 17:44:24 +00:00
< / 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 >
2011-12-20 00:07:10 +00:00
< h3 class = "title" > < a id = "id3681461" > < / a > Errors< / h3 >
2011-09-13 17:44:24 +00:00
< / div >
< / div >
< / div >
< p >
The < code class = "methodname" > DB-> key_range()< / code > < span >
< span >
method may fail and return one of the following non-zero errors:
< / span >
< / span >
< / p >
< div class = "sect3" lang = "en" xml:lang = "en" >
< div class = "titlepage" >
< div >
< div >
2011-12-20 00:07:10 +00:00
< h4 class = "title" > < a id = "id3681165" > < / a > DB_LOCK_DEADLOCK< / h4 >
2011-09-13 17:44:24 +00:00
< / div >
< / div >
< / div >
< p >
A transactional database environment operation was selected to resolve
a deadlock.
< / p >
< / div >
< div class = "sect3" lang = "en" xml:lang = "en" >
< div class = "titlepage" >
< div >
< div >
2011-12-20 00:07:10 +00:00
< h4 class = "title" > < a id = "id3681496" > < / a > DB_LOCK_NOTGRANTED< / h4 >
2011-09-13 17:44:24 +00:00
< / 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 >
< / div >
< div class = "sect3" lang = "en" xml:lang = "en" >
< div class = "titlepage" >
< div >
< div >
2011-12-20 00:07:10 +00:00
< h4 class = "title" > < a id = "id3681690" > < / a > DB_REP_HANDLE_DEAD< / h4 >
2011-09-13 17:44:24 +00:00
< / 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
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 >
2011-12-20 00:07:10 +00:00
< h4 class = "title" > < a id = "id3681529" > < / a > DB_REP_LOCKOUT< / h4 >
2011-09-13 17:44:24 +00:00
< / div >
< / div >
< / div >
< p >
The operation was blocked by client/master synchronization.
< / p >
< / div >
< div class = "sect3" lang = "en" xml:lang = "en" >
< div class = "titlepage" >
< div >
< div >
2011-12-20 00:07:10 +00:00
< h4 class = "title" > < a id = "id3681516" > < / a > EINVAL< / h4 >
2011-09-13 17:44:24 +00:00
< / 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 >
2011-12-20 00:07:10 +00:00
< h3 class = "title" > < a id = "id3681492" > < / a > Class< / h3 >
2011-09-13 17:44:24 +00:00
< / div >
< / div >
< / div >
< p >
< a class = "link" href = "db.html" title = "Chapter > DB< / a >
< / p >
< / div >
< div class = "sect2" lang = "en" xml:lang = "en" >
< div class = "titlepage" >
< div >
< div >
2011-12-20 00:07:10 +00:00
< h3 class = "title" > < a id = "id3681399" > < / a > See Also< / h3 >
2011-09-13 17:44:24 +00:00
< / 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" > > open()< / td >
< / tr >
< / table >
< / div >
< / body >
< / html >
