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::set_bt_prefix()</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="dbset_bt_minkey.html" title="Db::set_bt_minkey()" /> 12 <link rel="next" href="dbset_cachesize.html" title="Db::set_cachesize()" /> 13 </head> 14 <body> 15 <div class="navheader"> 16 <table width="100%" summary="Navigation header"> 17 <tr> 18 <th colspan="3" align="center">Db::set_bt_prefix()</th> 19 </tr> 20 <tr> 21 <td width="20%" align="left"><a accesskey="p" href="dbset_bt_minkey.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="dbset_cachesize.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="dbset_bt_prefix"></a>Db::set_bt_prefix()</h2> 35 </div> 36 </div> 37 </div> 38 <pre class="programlisting">#include <db_cxx.h> 39 40extern "C" { 41 typedef size_t (*bt_prefix_fcn_type)(DB *, const DBT *, const DBT *); 42}; 43int 44Db::set_bt_prefix(bt_prefix_fcn_type bt_prefix_fcn);</pre> 45 <p> 46 Set the Btree prefix function. The prefix function is used to 47 determine the amount by which keys stored on the Btree internal pages 48 can be safely truncated without losing their uniqueness. See the 49 <a href="../../programmer_reference/bt_conf.html#am_conf_bt_prefix" class="olink">Btree prefix comparison</a> section of the Berkeley DB Reference Guide for more 50 details about how this works. The usefulness of this is 51 data-dependent, but can produce significantly reduced tree sizes and 52 search times in some data sets. 53 </p> 54 <p> 55 If no prefix function or key comparison function is specified by the 56 application, a default lexical comparison function is used as the 57 prefix function. If no prefix function is specified and a key 58 comparison function is specified, no prefix function is used. It is 59 an error to specify a prefix function without also specifying a Btree 60 key comparison function. 61 </p> 62 <p> 63 The <code class="methodname">Db::set_bt_prefix()</code> method configures operations performed using 64 the specified <a class="link" href="db.html" title="Chapter 2. The Db Handle">Db</a> handle, 65 not all operations performed on the underlying database. 66 </p> 67 <p> 68 The <code class="methodname">Db::set_bt_prefix()</code> method may not be called after the 69 <a class="xref" href="dbopen.html" title="Db::open()">Db::open()</a> method is called. If 70 the database already exists when <a class="xref" href="dbopen.html" title="Db::open()">Db::open()</a> 71 is called, the information specified to <code class="methodname">Db::set_bt_prefix()</code> must be the same as that 72 historically used to create the database or corruption can occur. 73 </p> 74 <p> 75 The <code class="methodname">Db::set_bt_prefix()</code> <span> 76 77 <span> 78 method either returns a non-zero error value or throws an 79 exception that encapsulates a non-zero error value on 80 failure, and returns 0 on success. 81 </span> 82 </span> 83 </p> 84 <div class="sect2" lang="en" xml:lang="en"> 85 <div class="titlepage"> 86 <div> 87 <div> 88 <h3 class="title"><a id="id1643933"></a>Parameters</h3> 89 </div> 90 </div> 91 </div> 92 <div class="sect3" lang="en" xml:lang="en"> 93 <div class="titlepage"> 94 <div> 95 <div> 96 <h4 class="title"><a id="id1644605"></a>bt_prefix_fcn</h4> 97 </div> 98 </div> 99 </div> 100 <p> 101 The <span class="bold"><strong>bt_prefix_fcn</strong></span> function is the 102 application-specific Btree prefix function. The prefix function takes 103 three parameters: 104 </p> 105 <div class="itemizedlist"> 106 <ul type="disc"> 107 <li> 108 <p> 109 <code class="literal">db</code> 110 </p> 111 <p> 112 The <span class="bold"><strong>db</strong></span> parameter is the enclosing 113 database handle. 114 </p> 115 </li> 116 <li> 117 <p> 118 <code class="literal">dbt1</code> 119 </p> 120 <p> 121 The <span class="bold"><strong>dbt1</strong></span> parameter is a 122 <a class="link" href="dbt.html" title="Chapter 4. The Dbt Handle">Dbt</a> representing a database key. 123 </p> 124 </li> 125 <li> 126 <p> 127 <code class="literal">dbt2</code> 128 </p> 129 <p> 130 The <span class="bold"><strong>dbt2</strong></span> parameter is a 131 <a class="link" href="dbt.html" title="Chapter 4. The Dbt Handle">Dbt</a> representing a database key. 132 </p> 133 </li> 134 </ul> 135 </div> 136 <p> 137 The <span class="bold"><strong>bt_prefix_fcn</strong></span> function must return the 138 number of bytes of the second key parameter that would be required by the Btree 139 key comparison function to determine the second key parameter's ordering 140 relationship with respect to the first key parameter. If the two keys are equal, 141 the key length should be returned. The prefix function must correctly handle any 142 key values used by the application (possibly including zero-length keys). The 143 <span class="bold"><strong>data</strong></span> and <span class="bold"><strong>size</strong></span> 144 fields of the <a class="link" href="dbt.html" title="Chapter 4. The Dbt Handle">Dbt</a> are the only fields 145 that may be used for the purposes of this determination, and no particular 146 alignment of the memory to which the <span class="bold"><strong>data</strong></span> field 147 refers may be assumed. 148 </p> 149 </div> 150 </div> 151 <div class="sect2" lang="en" xml:lang="en"> 152 <div class="titlepage"> 153 <div> 154 <div> 155 <h3 class="title"><a id="id1644927"></a>Errors</h3> 156 </div> 157 </div> 158 </div> 159 <p> 160 The <code class="methodname">Db::set_bt_prefix()</code> <span> 161 162 <span> 163 method may fail and throw a <a class="link" href="dbexception.html" title="Chapter 6. The DbException Class">DbException</a> 164 exception, encapsulating one of the following non-zero errors, or return one 165 of the following non-zero errors: 166 </span> 167 </span> 168 </p> 169 <div class="sect3" lang="en" xml:lang="en"> 170 <div class="titlepage"> 171 <div> 172 <div> 173 <h4 class="title"><a id="id1644944"></a>EINVAL</h4> 174 </div> 175 </div> 176 </div> 177 <p> 178 If the method was called after <a class="xref" href="dbopen.html" title="Db::open()">Db::open()</a> 179 was called; or if an invalid flag value or parameter was specified. 180 </p> 181 </div> 182 </div> 183 <div class="sect2" lang="en" xml:lang="en"> 184 <div class="titlepage"> 185 <div> 186 <div> 187 <h3 class="title"><a id="id1644805"></a>Class</h3> 188 </div> 189 </div> 190 </div> 191 <p> 192 <a class="link" href="db.html" title="Chapter 2. The Db Handle">Db</a> 193 </p> 194 </div> 195 <div class="sect2" lang="en" xml:lang="en"> 196 <div class="titlepage"> 197 <div> 198 <div> 199 <h3 class="title"><a id="id1644794"></a>See Also</h3> 200 </div> 201 </div> 202 </div> 203 <p> 204 <a class="xref" href="db.html#dblist" title="Database and Related Methods">Database and Related Methods</a> 205 </p> 206 </div> 207 </div> 208 <div class="navfooter"> 209 <hr /> 210 <table width="100%" summary="Navigation footer"> 211 <tr> 212 <td width="40%" align="left"><a accesskey="p" href="dbset_bt_minkey.html">Prev</a> </td> 213 <td width="20%" align="center"> 214 <a accesskey="u" href="db.html">Up</a> 215 </td> 216 <td width="40%" align="right"> <a accesskey="n" href="dbset_cachesize.html">Next</a></td> 217 </tr> 218 <tr> 219 <td width="40%" align="left" valign="top">Db::set_bt_minkey() </td> 220 <td width="20%" align="center"> 221 <a accesskey="h" href="index.html">Home</a> 222 </td> 223 <td width="40%" align="right" valign="top"> Db::set_cachesize()</td> 224 </tr> 225 </table> 226 </div> 227 </body> 228</html> 229