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_compress()</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_compare.html" title="DB->set_bt_compare()" /> 12 <link rel="next" href="dbset_bt_minkey.html" title="DB->set_bt_minkey()" /> 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_compress()</th> 19 </tr> 20 <tr> 21 <td width="20%" align="left"><a accesskey="p" href="dbset_bt_compare.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_bt_minkey.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_compress"></a>DB->set_bt_compress()</h2> 35 </div> 36 </div> 37 </div> 38 <pre class="programlisting">#include <db.h> 39 40int 41DB->set_bt_compress(DB *db, 42 int (*bt_compress_fcn)(DB *db, const DBT *prevKey, 43 const DBT *prevData, const DBT *key, const DBT *data, DBT *dest), 44 int (*bt_decompress_fcn)(DB *db, const DBT *prevKey, 45 const DBT *prevData, DBT *compressed, DBT *destKey, 46 DBT *destData)); </pre> 47 <p> 48 Set the Btree compression and decompression functions. The 49 compression function is called whenever a key/data pair is added to 50 the tree and the decompression function is called whenever data is 51 requested from the tree. 52 </p> 53 <p> 54 If NULL function pointers are specified, then default compression 55 and decompression functions are used. Berkeley DB's default 56 compression function performs prefix compression on all keys and 57 prefix compression on data values for duplicate keys. If using 58 default compression, both the default compression and decompression 59 functions must be used. 60 </p> 61 <p> 62 The <code class="methodname">DB->set_bt_compress()</code> method 63 configures operations performed using the specified <a class="link" href="db.html" title="Chapter 2. The DB Handle">DB</a> handle, not all operations 64 performed on the underlying database. 65 </p> 66 <p> 67 The <code class="methodname">DB->set_bt_compress()</code> method may not be called after the 68 <a class="xref" href="dbopen.html" title="DB->open()">DB->open()</a> method is called. If 69 the database already exists when <a class="xref" href="dbopen.html" title="DB->open()">DB->open()</a> 70 is called, the information specified to <code class="methodname">DB->set_bt_compress()</code> must be the same as 71 that historically used to create the database or corruption can occur. 72 </p> 73 <p> 74 The <code class="methodname">DB->set_bt_compress()</code> <span> 75 <span> 76 method returns a non-zero error value on failure and 0 on success. 77 </span> 78 79 </span> 80 </p> 81 <div class="sect2" lang="en" xml:lang="en"> 82 <div class="titlepage"> 83 <div> 84 <div> 85 <h3 class="title"><a id="id1643268"></a>Parameters</h3> 86 </div> 87 </div> 88 </div> 89 <div class="sect3" lang="en" xml:lang="en"> 90 <div class="titlepage"> 91 <div> 92 <div> 93 <h4 class="title"><a id="id1643272"></a>bt_compress_fcn</h4> 94 </div> 95 </div> 96 </div> 97 <p> 98 The <span class="bold"><strong>bt_compress_fcn</strong></span> function is the 99 application-specified Btree compression function. The compression 100 function takes six parameters: 101 </p> 102 <div class="itemizedlist"> 103 <ul type="disc"> 104 <li> 105 <p> 106 <code class="literal">db</code> 107 </p> 108 <p> 109 The <span class="bold"><strong>db</strong></span> parameter is the enclosing 110 database handle. 111 </p> 112 </li> 113 <li> 114 <p> 115 <code class="literal">prevKey</code> 116 </p> 117 <p> 118 The <span class="bold"><strong>prevKey</strong></span> 119 parameter is the <a class="link" href="dbt.html" title="Chapter 4. The DBT Handle">DBT</a> 120 representing the key immediately preceding 121 the application supplied key. 122 </p> 123 </li> 124 <li> 125 <p> 126 <code class="literal">prevData</code> 127 </p> 128 <p> 129 The <span class="bold"><strong>prevData</strong></span> 130 parameter is the <a class="link" href="dbt.html" title="Chapter 4. The DBT Handle">DBT</a> 131 representing the data associated with 132 <span class="bold"><strong>prevKey</strong></span>. 133 </p> 134 </li> 135 <li> 136 <p> 137 <code class="literal">key</code> 138 </p> 139 <p> 140 The <span class="bold"><strong>key</strong></span> 141 parameter is the 142 <a class="link" href="dbt.html" title="Chapter 4. The DBT Handle">DBT</a> 143 representing the application supplied key. 144 </p> 145 </li> 146 <li> 147 <p> 148 <code class="literal">data</code> 149 </p> 150 <p> 151 The <span class="bold"><strong>data</strong></span> parameter is the 152 <a class="link" href="dbt.html" title="Chapter 4. The DBT Handle">DBT</a> representing the application 153 supplied data. 154 </p> 155 </li> 156 <li> 157 <p> 158 <code class="literal">dest</code> 159 </p> 160 <p> 161 The <span class="bold"><strong>dest</strong></span> 162 parameter is the 163 <a class="link" href="dbt.html" title="Chapter 4. The DBT Handle">DBT</a> 164 representing the data stored in the tree, 165 where the function should write the 166 compressed data. 167 </p> 168 </li> 169 </ul> 170 </div> 171 <p> 172 The <span class="bold"><strong>bt_compress_fcn</strong></span> 173 function must return 0 on success and a non-zero value 174 on failure. If the compressed data cannot fit in 175 <span class="bold"><strong>dest->data</strong></span> 176 177 (the size of which is 178 <span> 179 stored in 180 <span class="bold"><strong>dest->ulen</strong></span>), 181 </span> 182 183 the function should identify the required buffer size in 184 <span class="bold"><strong>dest->size</strong></span> 185 186 and return <code class="literal">DB_BUFFER_SMALL</code>. 187 </p> 188 </div> 189 <div class="sect3" lang="en" xml:lang="en"> 190 <div class="titlepage"> 191 <div> 192 <div> 193 <h4 class="title"><a id="id1643492"></a>bt_decompress_fcn</h4> 194 </div> 195 </div> 196 </div> 197 <p> 198 The <span class="bold"><strong>bt_decompress_fcn</strong></span> function is the 199 application-specified Btree decompression function. The decompression 200 function takes six parameters: 201 </p> 202 <div class="itemizedlist"> 203 <ul type="disc"> 204 <li> 205 <p> 206 <code class="literal">db</code> 207 </p> 208 <p> 209 The <span class="bold"><strong>db</strong></span> parameter is the enclosing 210 database handle. 211 </p> 212 </li> 213 <li> 214 <p> 215 <code class="literal">prevKey</code> 216 </p> 217 <p> 218 The <span class="bold"><strong>prevKey</strong></span> 219 parameter is the 220 <a class="link" href="dbt.html" title="Chapter 4. The DBT Handle">DBT</a> 221 representing the key immediately preceding 222 the key being decompressed. 223 </p> 224 </li> 225 <li> 226 <p> 227 <code class="literal">prevData</code> 228 </p> 229 <p> 230 The <span class="bold"><strong>prevData</strong></span> 231 parameter is the 232 <a class="link" href="dbt.html" title="Chapter 4. The DBT Handle">DBT</a> 233 representing the data associated with 234 <span class="bold"><strong>prevKey</strong></span>. 235 </p> 236 </li> 237 <li> 238 <p> 239 <code class="literal">compressed</code> 240 </p> 241 <p> 242 The 243 <span class="bold"><strong>compressed</strong></span> 244 parameter is the 245 <a class="link" href="dbt.html" title="Chapter 4. The DBT Handle">DBT</a> 246 representing the data stored in the tree, 247 that is, the compressed data. 248 </p> 249 </li> 250 <li> 251 <p> 252 <code class="literal">key</code> 253 </p> 254 <p> 255 The <span class="bold"><strong>key</strong></span> 256 parameter is the <a class="link" href="dbt.html" title="Chapter 4. The DBT Handle">DBT</a> where 257 the decompression function should store the 258 decompressed key. 259 </p> 260 </li> 261 <li> 262 <p> 263 <code class="literal">data</code> 264 </p> 265 <p> 266 The <span class="bold"><strong>data</strong></span> 267 parameter is the 268 <a class="link" href="dbt.html" title="Chapter 4. The DBT Handle">DBT</a> where 269 the decompression function should store the 270 decompressed key. 271 </p> 272 </li> 273 </ul> 274 </div> 275 <p> 276 The <span class="bold"><strong>bt_decompress_fcn</strong></span> 277 function must return 0 on success and a non-zero value 278 on failure. 279 If the decompressed data cannot fit in 280 <span class="bold"><strong>key->data</strong></span> 281 282 or 283 <span class="bold"><strong>data->data</strong></span> 284 285 (the size of which is 286 <span> 287 available in the <a class="link" href="dbt.html" title="Chapter 4. The DBT Handle">DBT</a>'s 288 <span class="bold"><strong>ulen</strong></span> field), 289 </span> 290 291 the function should identify the required buffer size 292 <span> 293 using the <a class="link" href="dbt.html" title="Chapter 4. The DBT Handle">DBT</a>'s 294 <span class="bold"><strong>size</strong></span> 295 field 296 </span> 297 298 and return <code class="literal">DB_BUFFER_SMALL</code>. 299 </p> 300 </div> 301 </div> 302 <div class="sect2" lang="en" xml:lang="en"> 303 <div class="titlepage"> 304 <div> 305 <div> 306 <h3 class="title"><a id="id1643744"></a>Errors</h3> 307 </div> 308 </div> 309 </div> 310 <p> 311 The <code class="methodname">DB->set_bt_compress()</code> <span> 312 <span> 313 method may fail and return one of the following non-zero errors: 314 </span> 315 316 </span> 317 </p> 318 <div class="sect3" lang="en" xml:lang="en"> 319 <div class="titlepage"> 320 <div> 321 <div> 322 <h4 class="title"><a id="id1643610"></a>EINVAL</h4> 323 </div> 324 </div> 325 </div> 326 <p> 327 If the method was called after <a class="xref" href="dbopen.html" title="DB->open()">DB->open()</a> 328 was called; or if an invalid flag value or parameter was specified. 329 </p> 330 </div> 331 </div> 332 <div class="sect2" lang="en" xml:lang="en"> 333 <div class="titlepage"> 334 <div> 335 <div> 336 <h3 class="title"><a id="id1643322"></a>Class</h3> 337 </div> 338 </div> 339 </div> 340 <p> 341 <a class="link" href="db.html" title="Chapter 2. The DB Handle">DB</a> 342 </p> 343 </div> 344 <div class="sect2" lang="en" xml:lang="en"> 345 <div class="titlepage"> 346 <div> 347 <div> 348 <h3 class="title"><a id="id1643314"></a>See Also</h3> 349 </div> 350 </div> 351 </div> 352 <p> 353 <a class="xref" href="db.html#dblist" title="Database and Related Methods">Database and Related Methods</a> 354 </p> 355 </div> 356 </div> 357 <div class="navfooter"> 358 <hr /> 359 <table width="100%" summary="Navigation footer"> 360 <tr> 361 <td width="40%" align="left"><a accesskey="p" href="dbset_bt_compare.html">Prev</a> </td> 362 <td width="20%" align="center"> 363 <a accesskey="u" href="db.html">Up</a> 364 </td> 365 <td width="40%" align="right"> <a accesskey="n" href="dbset_bt_minkey.html">Next</a></td> 366 </tr> 367 <tr> 368 <td width="40%" align="left" valign="top">DB->set_bt_compare() </td> 369 <td width="20%" align="center"> 370 <a accesskey="h" href="index.html">Home</a> 371 </td> 372 <td width="40%" align="right" valign="top"> DB->set_bt_minkey()</td> 373 </tr> 374 </table> 375 </div> 376 </body> 377</html> 378