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