Db::set_bt_compress()

#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);

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.

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.

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.

The Db::set_bt_compress() method configures operations performed using the specified Db handle, not all operations performed on the underlying database.

The Db::set_bt_compress() method may not be called after the Db::open() method is called. If the database already exists when Db::open() is called, the information specified to Db::set_bt_compress() must be the same as that historically used to create the database or corruption can occur.

The Db::set_bt_compress() 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.

Parameters

bt_compress_fcn

The bt_compress_fcn function is the application-specified Btree compression function. The compression function takes six parameters:

  • db

    The db parameter is the enclosing database handle.

  • prevKey

    The prevKey parameter is the Dbt representing the key immediately preceding the application supplied key.

  • prevData

    The prevData parameter is the Dbt representing the data associated with prevKey.

  • key

    The key parameter is the Dbt representing the application supplied key.

  • data

    The data parameter is the Dbt representing the application supplied data.

  • dest

    The dest parameter is the Dbt representing the data stored in the tree, where the function should write the compressed data.

The bt_compress_fcn function must return 0 on success and a non-zero value on failure. If the compressed data cannot fit in dest->set_data() (the size of which is returned by dest->get_ulen()), the function should identify the required buffer size in dest->set_size() and return DB_BUFFER_SMALL.

bt_decompress_fcn

The bt_decompress_fcn function is the application-specified Btree decompression function. The decompression function takes six parameters:

  • db

    The db parameter is the enclosing database handle.

  • prevKey

    The prevKey parameter is the Dbt representing the key immediately preceding the key being decompressed.

  • prevData

    The prevData parameter is the Dbt representing the data associated with prevKey.

  • compressed

    The compressed parameter is the Dbt representing the data stored in the tree, that is, the compressed data.

  • destKey

    The key parameter is the Dbt where the decompression function should store the decompressed key.

  • destData

    The data parameter is the Dbt where the decompression function should store the decompressed key.

The bt_decompress_fcn function must return 0 on success and a non-zero value on failure. If the decompressed data cannot fit in key->set_data() or data->set_data() (the size of which is returned by the Dbt's get_ulen() method), the function should identify the required buffer size using the Dbt's set_size() method and return DB_BUFFER_SMALL.

Errors

The Db::set_bt_compress() method may fail and throw a DbException exception, encapsulating one of the following non-zero errors, or return one of the following non-zero errors:

EINVAL

If the method was called after Db::open() was called; or if an invalid flag value or parameter was specified.

Class

Db

See Also

Database and Related Methods