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