Library Version 12.1.6.0

Db::set_bt_compress()
Prev | Chapter 2. The Db Handle | Next

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

Prev | Up | Next
Db::set_bt_compare() | Home | Db::set_bt_minkey()