docs/api_reference/C/dbkey_range.html

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