1<?xml version="1.0" encoding="UTF-8" standalone="no"?> 2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 3<html xmlns="http://www.w3.org/1999/xhtml"> 4 <head> 5 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> 6 <title>DB->key_range()</title> 7 <link rel="stylesheet" href="apiReference.css" type="text/css" /> 8 <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /> 9 <link rel="start" href="index.html" title="Berkeley DB C API Reference" /> 10 <link rel="up" href="db.html" title="Chapter��2.�� The DB Handle" /> 11 <link rel="prev" href="dbjoin.html" title="DB->join()" /> 12 <link rel="next" href="dbopen.html" title="DB->open()" /> 13 </head> 14 <body> 15 <div class="navheader"> 16 <table width="100%" summary="Navigation header"> 17 <tr> 18 <th colspan="3" align="center">DB->key_range()</th> 19 </tr> 20 <tr> 21 <td width="20%" align="left"><a accesskey="p" href="dbjoin.html">Prev</a>��</td> 22 <th width="60%" align="center">Chapter��2.�� 23 The DB Handle 24 </th> 25 <td width="20%" align="right">��<a accesskey="n" href="dbopen.html">Next</a></td> 26 </tr> 27 </table> 28 <hr /> 29 </div> 30 <div class="sect1" lang="en" xml:lang="en"> 31 <div class="titlepage"> 32 <div> 33 <div> 34 <h2 class="title" style="clear: both"><a id="dbkey_range"></a>DB->key_range()</h2> 35 </div> 36 </div> 37 </div> 38 <pre class="programlisting">#include <db.h> 39 40int 41DB->key_range(DB *db, DB_TXN *txnid, 42 DBT *key, DB_KEY_RANGE *key_range, u_int32_t flags); </pre> 43 <p> 44 The <code class="methodname">DB->key_range()</code> method returns an estimate of the proportion of 45 keys that are less than, equal to, and greater than the specified key. 46 The underlying database must be of type Btree. 47 </p> 48 <p> 49 The <code class="methodname">DB->key_range()</code> method fills in a structure of type DB_KEY_RANGE. 50 The following data fields are available from the DB_KEY_RANGE 51 structure: 52 </p> 53 <div class="itemizedlist"> 54 <ul type="disc"> 55 <li> 56 <p> 57 <span class="bold"><strong>double less;</strong></span> 58 </p> 59 <p> 60 A value between 0 and 1, the proportion of keys less than the 61 specified key. 62 </p> 63 </li> 64 <li> 65 <p> 66 <span class="bold"><strong>double equal;</strong></span> 67 </p> 68 <p> 69 A value between 0 and 1, the proportion of keys equal to the specified 70 key. 71 </p> 72 </li> 73 <li> 74 <p> 75 <span class="bold"><strong>double greater;</strong></span> 76 </p> 77 <p> 78 A value between 0 and 1, the proportion of keys greater than the 79 specified key. 80 </p> 81 </li> 82 </ul> 83 </div> 84 <p> 85 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 86 are less than the <span class="bold"><strong>key</strong></span> parameter. The 87 value for <span class="bold"><strong>equal</strong></span> will be zero if there 88 is no matching key, and will be non-zero otherwise. 89 </p> 90 <p> 91 The <code class="methodname">DB->key_range()</code> <span> 92 <span> 93 method returns a non-zero error value on failure and 0 on success. 94 </span> 95 96 </span> 97 </p> 98 <div class="sect2" lang="en" xml:lang="en"> 99 <div class="titlepage"> 100 <div> 101 <div> 102 <h3 class="title"><a id="id1639368"></a>Parameters</h3> 103 </div> 104 </div> 105 </div> 106 <div class="sect3" lang="en" xml:lang="en"> 107 <div class="titlepage"> 108 <div> 109 <div> 110 <h4 class="title"><a id="id1638914"></a>key</h4> 111 </div> 112 </div> 113 </div> 114 <p> 115 The key <a class="link" href="dbt.html" title="Chapter��4.�� The DBT Handle">DBT</a> operated on. 116 </p> 117 </div> 118 <div class="sect3" lang="en" xml:lang="en"> 119 <div class="titlepage"> 120 <div> 121 <div> 122 <h4 class="title"><a id="id1639426"></a>key_range</h4> 123 </div> 124 </div> 125 </div> 126 <p> 127 The estimates are returned in the <span class="bold"><strong>key_range</strong></span> parameter, which contains three 128 elements of type double: <span class="bold"><strong>less</strong></span>, 129 <span class="bold"><strong>equal</strong></span>, and <span class="bold"><strong>greater</strong></span>. Values are in the range of 0 to 1; 130 for example, if the field <span class="bold"><strong>less</strong></span> is 131 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, 132 and will be non-zero otherwise. 133 </p> 134 </div> 135 <div class="sect3" lang="en" xml:lang="en"> 136 <div class="titlepage"> 137 <div> 138 <div> 139 <h4 class="title"><a id="id1639427"></a>txnid</h4> 140 </div> 141 </div> 142 </div> 143 <p> 144 If the operation is part of an application-specified transaction, the 145 <span class="bold"><strong>txnid</strong></span> parameter is a transaction 146 handle returned from <a class="xref" href="txnbegin.html" title="DB_ENV->txn_begin()">DB_ENV->txn_begin()</a>; 147 if the operation is part of a Berkeley DB Concurrent Data Store group, the 148 <span class="bold"><strong>txnid</strong></span> parameter is a handle returned 149 from <a class="xref" href="envcdsgroup_begin.html" title="DB_ENV->cdsgroup_begin()">DB_ENV->cdsgroup_begin()</a>; 150 otherwise NULL. If no transaction handle is specified, but the 151 operation occurs in a transactional database, the operation will be 152 implicitly transaction protected. The <code class="methodname">DB->key_range()</code> method does not 153 retain the locks it acquires for the life of the transaction, so 154 estimates may not be repeatable. 155 </p> 156 </div> 157 <div class="sect3" lang="en" xml:lang="en"> 158 <div class="titlepage"> 159 <div> 160 <div> 161 <h4 class="title"><a id="id1639378"></a>flags</h4> 162 </div> 163 </div> 164 </div> 165 <p> 166 The <span class="bold"><strong>flags</strong></span> parameter is currently 167 unused, and must be set to 0. 168 </p> 169 </div> 170 </div> 171 <div class="sect2" lang="en" xml:lang="en"> 172 <div class="titlepage"> 173 <div> 174 <div> 175 <h3 class="title"><a id="id1639302"></a>Errors</h3> 176 </div> 177 </div> 178 </div> 179 <p> 180 The <code class="methodname">DB->key_range()</code> <span> 181 <span> 182 method may fail and return one of the following non-zero errors: 183 </span> 184 185 </span> 186 </p> 187 <div class="sect3" lang="en" xml:lang="en"> 188 <div class="titlepage"> 189 <div> 190 <div> 191 <h4 class="title"><a id="id1638480"></a>DB_LOCK_DEADLOCK</h4> 192 </div> 193 </div> 194 </div> 195 <p> 196 A transactional database environment operation was selected to resolve 197 a deadlock. 198 </p> 199 </div> 200 <div class="sect3" lang="en" xml:lang="en"> 201 <div class="titlepage"> 202 <div> 203 <div> 204 <h4 class="title"><a id="id1638481"></a>DB_LOCK_NOTGRANTED</h4> 205 </div> 206 </div> 207 </div> 208 <p> 209 A Berkeley DB Concurrent Data Store database environment configured 210 for lock timeouts was unable to grant a lock in the allowed time. 211 </p> 212 </div> 213 <div class="sect3" lang="en" xml:lang="en"> 214 <div class="titlepage"> 215 <div> 216 <div> 217 <h4 class="title"><a id="id1638985"></a> DB_REP_HANDLE_DEAD</h4> 218 </div> 219 </div> 220 </div> 221 <p> 222 When a client synchronizes with the master, it is possible for committed 223 transactions to be rolled back. This invalidates all the database and cursor 224 handles opened in the replication environment. Once this occurs, an attempt to use 225 such a handle will 226 227 return <code class="literal">DB_REP_HANDLE_DEAD</code>. 228 The application will need to discard the handle and open a new one in order to 229 continue processing. 230 </p> 231 </div> 232 <div class="sect3" lang="en" xml:lang="en"> 233 <div class="titlepage"> 234 <div> 235 <div> 236 <h4 class="title"><a id="id1638986"></a>DB_REP_LOCKOUT</h4> 237 </div> 238 </div> 239 </div> 240 <p> 241 The operation was blocked by client/master synchronization. 242 </p> 243 </div> 244 <div class="sect3" lang="en" xml:lang="en"> 245 <div class="titlepage"> 246 <div> 247 <div> 248 <h4 class="title"><a id="id1639433"></a>EINVAL</h4> 249 </div> 250 </div> 251 </div> 252 <p> 253 If the underlying database was not of type Btree; or if an invalid 254 flag value or parameter was specified. 255 </p> 256 </div> 257 </div> 258 <div class="sect2" lang="en" xml:lang="en"> 259 <div class="titlepage"> 260 <div> 261 <div> 262 <h3 class="title"><a id="id1639448"></a>Class</h3> 263 </div> 264 </div> 265 </div> 266 <p> 267 <a class="link" href="db.html" title="Chapter��2.�� The DB Handle">DB</a> 268 </p> 269 </div> 270 <div class="sect2" lang="en" xml:lang="en"> 271 <div class="titlepage"> 272 <div> 273 <div> 274 <h3 class="title"><a id="id1639409"></a>See Also</h3> 275 </div> 276 </div> 277 </div> 278 <p> 279 <a class="xref" href="db.html#dblist" title="Database and Related Methods">Database and Related Methods</a> 280 </p> 281 </div> 282 </div> 283 <div class="navfooter"> 284 <hr /> 285 <table width="100%" summary="Navigation footer"> 286 <tr> 287 <td width="40%" align="left"><a accesskey="p" href="dbjoin.html">Prev</a>��</td> 288 <td width="20%" align="center"> 289 <a accesskey="u" href="db.html">Up</a> 290 </td> 291 <td width="40%" align="right">��<a accesskey="n" href="dbopen.html">Next</a></td> 292 </tr> 293 <tr> 294 <td width="40%" align="left" valign="top">DB->join()��</td> 295 <td width="20%" align="center"> 296 <a accesskey="h" href="index.html">Home</a> 297 </td> 298 <td width="40%" align="right" valign="top">��DB->open()</td> 299 </tr> 300 </table> 301 </div> 302 </body> 303</html> 304