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_cxx.h> 39 40int 41Db::key_range(DbTxn *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 93 <span> 94 method either returns a non-zero error value or throws an 95 exception that encapsulates a non-zero error value on 96 failure, and returns 0 on success. 97 </span> 98 </span> 99 </p> 100 <div class="sect2" lang="en" xml:lang="en"> 101 <div class="titlepage"> 102 <div> 103 <div> 104 <h3 class="title"><a id="id1639085"></a>Parameters</h3> 105 </div> 106 </div> 107 </div> 108 <div class="sect3" lang="en" xml:lang="en"> 109 <div class="titlepage"> 110 <div> 111 <div> 112 <h4 class="title"><a id="id1638672"></a>key</h4> 113 </div> 114 </div> 115 </div> 116 <p> 117 The key <a class="link" href="dbt.html" title="Chapter 4. The Dbt Handle">Dbt</a> operated on. 118 </p> 119 </div> 120 <div class="sect3" lang="en" xml:lang="en"> 121 <div class="titlepage"> 122 <div> 123 <div> 124 <h4 class="title"><a id="id1638627"></a>key_range</h4> 125 </div> 126 </div> 127 </div> 128 <p> 129 The estimates are returned in the <span class="bold"><strong>key_range</strong></span> parameter, which contains three 130 elements of type double: <span class="bold"><strong>less</strong></span>, 131 <span class="bold"><strong>equal</strong></span>, and <span class="bold"><strong>greater</strong></span>. Values are in the range of 0 to 1; 132 for example, if the field <span class="bold"><strong>less</strong></span> is 133 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, 134 and will be non-zero otherwise. 135 </p> 136 </div> 137 <div class="sect3" lang="en" xml:lang="en"> 138 <div class="titlepage"> 139 <div> 140 <div> 141 <h4 class="title"><a id="id1639433"></a>txnid</h4> 142 </div> 143 </div> 144 </div> 145 <p> 146 If the operation is part of an application-specified transaction, the 147 <span class="bold"><strong>txnid</strong></span> parameter is a transaction 148 handle returned from <a class="xref" href="txnbegin.html" title="DbEnv::txn_begin()">DbEnv::txn_begin()</a>; 149 if the operation is part of a Berkeley DB Concurrent Data Store group, the 150 <span class="bold"><strong>txnid</strong></span> parameter is a handle returned 151 from <a class="xref" href="envcdsgroup_begin.html" title="DbEnv::cdsgroup_begin()">DbEnv::cdsgroup_begin()</a>; 152 otherwise NULL. If no transaction handle is specified, but the 153 operation occurs in a transactional database, the operation will be 154 implicitly transaction protected. The <code class="methodname">Db::key_range()</code> method does not 155 retain the locks it acquires for the life of the transaction, so 156 estimates may not be repeatable. 157 </p> 158 </div> 159 <div class="sect3" lang="en" xml:lang="en"> 160 <div class="titlepage"> 161 <div> 162 <div> 163 <h4 class="title"><a id="id1638576"></a>flags</h4> 164 </div> 165 </div> 166 </div> 167 <p> 168 The <span class="bold"><strong>flags</strong></span> parameter is currently 169 unused, and must be set to 0. 170 </p> 171 </div> 172 </div> 173 <div class="sect2" lang="en" xml:lang="en"> 174 <div class="titlepage"> 175 <div> 176 <div> 177 <h3 class="title"><a id="id1639547"></a>Errors</h3> 178 </div> 179 </div> 180 </div> 181 <p> 182 The <code class="methodname">Db::key_range()</code> <span> 183 184 <span> 185 method may fail and throw a <a class="link" href="dbexception.html" title="Chapter 6. The DbException Class">DbException</a> 186 exception, encapsulating one of the following non-zero errors, or return one 187 of the following non-zero errors: 188 </span> 189 </span> 190 </p> 191 <div class="sect3" lang="en" xml:lang="en"> 192 <div class="titlepage"> 193 <div> 194 <div> 195 <h4 class="title"><a id="id1638957"></a><span>DbDeadlockException or </span>DB_LOCK_DEADLOCK</h4> 196 </div> 197 </div> 198 </div> 199 <p> 200 A transactional database environment operation was selected to resolve 201 a deadlock. 202 </p> 203 <p> 204 <a class="xref" href="dbdeadlock.html" title="DbDeadlockException">DbDeadlockException</a> is thrown if 205 your Berkeley DB API is configured to throw exceptions. 206 Otherwise, <code class="literal">DB_LOCK_DEADLOCK</code> is returned. 207 </p> 208 </div> 209 <div class="sect3" lang="en" xml:lang="en"> 210 <div class="titlepage"> 211 <div> 212 <div> 213 <h4 class="title"><a id="id1638628"></a><span>DbLockNotGrantedException or </span>DB_LOCK_NOTGRANTED</h4> 214 </div> 215 </div> 216 </div> 217 <p> 218 A Berkeley DB Concurrent Data Store database environment configured 219 for lock timeouts was unable to grant a lock in the allowed time. 220 </p> 221 <p> 222 <a class="xref" href="dblocknotgranted.html" title="DbLockNotGrantedException">DbLockNotGrantedException</a> is thrown if 223 your Berkeley DB API is configured to throw exceptions. 224 Otherwise, <code class="literal">DB_LOCK_NOTGRANTED</code> is returned. 225 </p> 226 </div> 227 <div class="sect3" lang="en" xml:lang="en"> 228 <div class="titlepage"> 229 <div> 230 <div> 231 <h4 class="title"><a id="id1639688"></a><span>DbRepHandleDeadException or</span> DB_REP_HANDLE_DEAD</h4> 232 </div> 233 </div> 234 </div> 235 <p> 236 When a client synchronizes with the master, it is possible for committed 237 transactions to be rolled back. This invalidates all the database and cursor 238 handles opened in the replication environment. Once this occurs, an attempt to use 239 such a handle will 240 <span> 241 throw a <a class="xref" href="dbrephandledead.html" title="DbRepHandleDeadException">DbRepHandleDeadException</a> (if 242 your application is configured to throw exceptions), or 243 </span> 244 return <code class="literal">DB_REP_HANDLE_DEAD</code>. 245 The application will need to discard the handle and open a new one in order to 246 continue processing. 247 </p> 248 </div> 249 <div class="sect3" lang="en" xml:lang="en"> 250 <div class="titlepage"> 251 <div> 252 <div> 253 <h4 class="title"><a id="id1638673"></a><span>DbDeadlockException or </span>DB_REP_LOCKOUT</h4> 254 </div> 255 </div> 256 </div> 257 <p> 258 The operation was blocked by client/master synchronization. 259 </p> 260 <p> 261 <a class="xref" href="dbdeadlock.html" title="DbDeadlockException">DbDeadlockException</a> is thrown if 262 your Berkeley DB API is configured to throw exceptions. 263 Otherwise, <code class="literal">DB_REP_LOCKOUT</code> is returned. 264 </p> 265 </div> 266 <div class="sect3" lang="en" xml:lang="en"> 267 <div class="titlepage"> 268 <div> 269 <div> 270 <h4 class="title"><a id="id1639715"></a>EINVAL</h4> 271 </div> 272 </div> 273 </div> 274 <p> 275 If the underlying database was not of type Btree; or if an invalid 276 flag value or parameter was specified. 277 </p> 278 </div> 279 </div> 280 <div class="sect2" lang="en" xml:lang="en"> 281 <div class="titlepage"> 282 <div> 283 <div> 284 <h3 class="title"><a id="id1638520"></a>Class</h3> 285 </div> 286 </div> 287 </div> 288 <p> 289 <a class="link" href="db.html" title="Chapter 2. The Db Handle">Db</a> 290 </p> 291 </div> 292 <div class="sect2" lang="en" xml:lang="en"> 293 <div class="titlepage"> 294 <div> 295 <div> 296 <h3 class="title"><a id="id1639276"></a>See Also</h3> 297 </div> 298 </div> 299 </div> 300 <p> 301 <a class="xref" href="db.html#dblist" title="Database and Related Methods">Database and Related Methods</a> 302 </p> 303 </div> 304 </div> 305 <div class="navfooter"> 306 <hr /> 307 <table width="100%" summary="Navigation footer"> 308 <tr> 309 <td width="40%" align="left"><a accesskey="p" href="dbjoin.html">Prev</a> </td> 310 <td width="20%" align="center"> 311 <a accesskey="u" href="db.html">Up</a> 312 </td> 313 <td width="40%" align="right"> <a accesskey="n" href="dbopen.html">Next</a></td> 314 </tr> 315 <tr> 316 <td width="40%" align="left" valign="top">Db::join() </td> 317 <td width="20%" align="center"> 318 <a accesskey="h" href="index.html">Home</a> 319 </td> 320 <td width="40%" align="right" valign="top"> Db::open()</td> 321 </tr> 322 </table> 323 </div> 324 </body> 325</html> 326