<?xml version="1.0" encoding="UTF-8" standalone="no"?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> <title>Db::set_bt_compress()</title> <link rel="stylesheet" href="apiReference.css" type="text/css" /> <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /> <link rel="start" href="index.html" title="Berkeley DB C++ API Reference" /> <link rel="up" href="db.html" title="Chapter 2. The Db Handle" /> <link rel="prev" href="dbset_bt_compare.html" title="Db::set_bt_compare()" /> <link rel="next" href="dbset_bt_minkey.html" title="Db::set_bt_minkey()" /> </head> <body> <div xmlns="" class="navheader"> <div class="libver"> <p>Library Version 11.2.5.3</p> </div> <table width="100%" summary="Navigation header"> <tr> <th colspan="3" align="center">Db::set_bt_compress()</th> </tr> <tr> <td width="20%" align="left"><a accesskey="p" href="dbset_bt_compare.html">Prev</a> </td> <th width="60%" align="center">Chapter 2. The Db Handle </th> <td width="20%" align="right"> <a accesskey="n" href="dbset_bt_minkey.html">Next</a></td> </tr> </table> <hr /> </div> <div class="sect1" lang="en" xml:lang="en"> <div class="titlepage"> <div> <div> <h2 class="title" style="clear: both"><a id="dbset_bt_compress"></a>Db::set_bt_compress()</h2> </div> </div> </div> <pre class="programlisting">#include <db_cxx.h> extern "C" { typedef int (*bt_compress_fcn_type)(DB *db, const DBT *prevKey, const DBT *prevData, const DBT *key, const DBT *data, DBT *dest); typedef int (*bt_decompress_fcn_typ)(DB *db, const DBT *prevKey, const DBT *prevData, DBT *compressed, DBT *destKey, DBT *destData); }; int Db::set_bt_compress(bt_compress_fcn_type bt_compress_fcn, bt_decompress_fcn_type bt_decompress_fcn);</pre> <p> Set the Btree compression and decompression functions. The compression function is called whenever a key/data pair is added to the tree and the decompression function is called whenever data is requested from the tree. </p> <p> This method is only compatible with prefix-based compression routines. This callback is mostly intended for compressing keys. From a performance perspective, it is better to perform compression of the data portion of your records outside of the Berkeley DB library. </p> <p> If NULL function pointers are specified, then default compression and decompression functions are used. Berkeley DB's default compression function performs prefix compression on all keys and prefix compression on data values for duplicate keys. If using default compression, both the default compression and decompression functions must be used. </p> <p> The <code class="methodname">Db::set_bt_compress()</code> method configures operations performed using the specified <a class="link" href="db.html" title="Chapter 2. The Db Handle">Db</a> handle, not all operations performed on the underlying database. </p> <p> The <code class="methodname">Db::set_bt_compress()</code> method may not be called after the <a class="xref" href="dbopen.html" title="Db::open()">Db::open()</a> method is called. If the database already exists when <a class="xref" href="dbopen.html" title="Db::open()">Db::open()</a> is called, the information specified to <code class="methodname">Db::set_bt_compress()</code> must be the same as that historically used to create the database or corruption can occur. </p> <p> The <code class="methodname">Db::set_bt_compress()</code> <span> <span> method either returns a non-zero error value or throws an exception that encapsulates a non-zero error value on failure, and returns 0 on success. </span> </span> </p> <div class="sect2" lang="en" xml:lang="en"> <div class="titlepage"> <div> <div> <h3 class="title"><a id="idm5219440"></a>Parameters</h3> </div> </div> </div> <div class="sect3" lang="en" xml:lang="en"> <div class="titlepage"> <div> <div> <h4 class="title"><a id="idm5012680"></a>bt_compress_fcn</h4> </div> </div> </div> <p> The <span class="bold"><strong>bt_compress_fcn</strong></span> function is the application-specified Btree compression function. The compression function takes six parameters: </p> <div class="itemizedlist"> <ul type="disc"> <li> <p> <code class="literal">db</code> </p> <p> The <span class="bold"><strong>db</strong></span> parameter is the enclosing database handle. </p> </li> <li> <p> <code class="literal">prevKey</code> </p> <p> The <span class="bold"><strong>prevKey</strong></span> parameter is the <a class="link" href="dbt.html" title="Chapter 4. The Dbt Handle">Dbt</a> representing the key immediately preceding the application supplied key. </p> </li> <li> <p> <code class="literal">prevData</code> </p> <p> The <span class="bold"><strong>prevData</strong></span> parameter is the <a class="link" href="dbt.html" title="Chapter 4. The Dbt Handle">Dbt</a> representing the data associated with <span class="bold"><strong>prevKey</strong></span>. </p> </li> <li> <p> <code class="literal">key</code> </p> <p> The <span class="bold"><strong>key</strong></span> parameter is the <a class="link" href="dbt.html" title="Chapter 4. The Dbt Handle">Dbt</a> representing the application supplied key. </p> </li> <li> <p> <code class="literal">data</code> </p> <p> The <span class="bold"><strong>data</strong></span> parameter is the <a class="link" href="dbt.html" title="Chapter 4. The Dbt Handle">Dbt</a> representing the application supplied data. </p> </li> <li> <p> <code class="literal">dest</code> </p> <p> The <span class="bold"><strong>dest</strong></span> parameter is the <a class="link" href="dbt.html" title="Chapter 4. The Dbt Handle">Dbt</a> representing the data stored in the tree, where the function should write the compressed data. </p> </li> </ul> </div> <p> The <span class="bold"><strong>bt_compress_fcn</strong></span> function must return 0 on success and a non-zero value on failure. If the compressed data cannot fit in <span class="bold"><strong>dest->set_data()</strong></span> (the size of which is <span> returned by <span class="bold"><strong>dest->get_ulen()</strong></span>), </span> the function should identify the required buffer size in <span class="bold"><strong>dest->set_size()</strong></span> and return <code class="literal">DB_BUFFER_SMALL</code>. </p> </div> <div class="sect3" lang="en" xml:lang="en"> <div class="titlepage"> <div> <div> <h4 class="title"><a id="idm454456"></a>bt_decompress_fcn</h4> </div> </div> </div> <p> The <span class="bold"><strong>bt_decompress_fcn</strong></span> function is the application-specified Btree decompression function. The decompression function takes six parameters: </p> <div class="itemizedlist"> <ul type="disc"> <li> <p> <code class="literal">db</code> </p> <p> The <span class="bold"><strong>db</strong></span> parameter is the enclosing database handle. </p> </li> <li> <p> <code class="literal">prevKey</code> </p> <p> The <span class="bold"><strong>prevKey</strong></span> parameter is the <a class="link" href="dbt.html" title="Chapter 4. The Dbt Handle">Dbt</a> representing the key immediately preceding the key being decompressed. </p> </li> <li> <p> <code class="literal">prevData</code> </p> <p> The <span class="bold"><strong>prevData</strong></span> parameter is the <a class="link" href="dbt.html" title="Chapter 4. The Dbt Handle">Dbt</a> representing the data associated with <span class="bold"><strong>prevKey</strong></span>. </p> </li> <li> <p> <code class="literal">compressed</code> </p> <p> The <span class="bold"><strong>compressed</strong></span> parameter is the <a class="link" href="dbt.html" title="Chapter 4. The Dbt Handle">Dbt</a> representing the data stored in the tree, that is, the compressed data. </p> </li> <li> <p> <code class="literal">destKey</code> </p> <p> The <span class="bold"><strong>key</strong></span> parameter is the <a class="link" href="dbt.html" title="Chapter 4. The Dbt Handle">Dbt</a> where the decompression function should store the decompressed key. </p> </li> <li> <p> <code class="literal">destData</code> </p> <p> The <span class="bold"><strong>data</strong></span> parameter is the <a class="link" href="dbt.html" title="Chapter 4. The Dbt Handle">Dbt</a> where the decompression function should store the decompressed key. </p> </li> </ul> </div> <p> The <span class="bold"><strong>bt_decompress_fcn</strong></span> function must return 0 on success and a non-zero value on failure. If the decompressed data cannot fit in <span class="bold"><strong>key->set_data()</strong></span> or <span class="bold"><strong>data->set_data()</strong></span> (the size of which is <span> returned by the <a class="link" href="dbt.html" title="Chapter 4. The Dbt Handle">Dbt</a>'s <span class="bold"><strong>get_ulen()</strong></span> method), </span> the function should identify the required buffer size <span> using the <a class="link" href="dbt.html" title="Chapter 4. The Dbt Handle">Dbt</a>'s <span class="bold"><strong>set_size()</strong></span> method </span> and return <code class="literal">DB_BUFFER_SMALL</code>. </p> </div> </div> <div class="sect2" lang="en" xml:lang="en"> <div class="titlepage"> <div> <div> <h3 class="title"><a id="idm2371768"></a>Errors</h3> </div> </div> </div> <p> The <code class="methodname">Db::set_bt_compress()</code> <span> <span> method may fail and throw a <a class="link" href="dbexception.html" title="Chapter 6. The DbException Class">DbException</a> exception, encapsulating one of the following non-zero errors, or return one of the following non-zero errors: </span> </span> </p> <div class="sect3" lang="en" xml:lang="en"> <div class="titlepage"> <div> <div> <h4 class="title"><a id="idm4018032"></a>EINVAL</h4> </div> </div> </div> <p> If the method was called after <a class="xref" href="dbopen.html" title="Db::open()">Db::open()</a> was called; or if an invalid flag value or parameter was specified. </p> </div> </div> <div class="sect2" lang="en" xml:lang="en"> <div class="titlepage"> <div> <div> <h3 class="title"><a id="idm5020072"></a>Class</h3> </div> </div> </div> <p> <a class="link" href="db.html" title="Chapter 2. The Db Handle">Db</a> </p> </div> <div class="sect2" lang="en" xml:lang="en"> <div class="titlepage"> <div> <div> <h3 class="title"><a id="idm4036800"></a>See Also</h3> </div> </div> </div> <p> <a class="xref" href="db.html#dblist" title="Database and Related Methods">Database and Related Methods</a> </p> </div> </div> <div class="navfooter"> <hr /> <table width="100%" summary="Navigation footer"> <tr> <td width="40%" align="left"><a accesskey="p" href="dbset_bt_compare.html">Prev</a> </td> <td width="20%" align="center"> <a accesskey="u" href="db.html">Up</a> </td> <td width="40%" align="right"> <a accesskey="n" href="dbset_bt_minkey.html">Next</a></td> </tr> <tr> <td width="40%" align="left" valign="top">Db::set_bt_compare() </td> <td width="20%" align="center"> <a accesskey="h" href="index.html">Home</a> </td> <td width="40%" align="right" valign="top"> Db::set_bt_minkey()</td> </tr> </table> </div> </body> </html>