#include <db.h> int DB->set_bt_compress(DB *db, int (*bt_compress_fcn)(DB *db, const DBT *prevKey, const DBT *prevData, const DBT *key, const DBT *data, DBT *dest), int (*bt_decompress_fcn)(DB *db, const DBT *prevKey, const DBT *prevData, DBT *compressed, DBT *destKey, DBT *destData));
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 returns a non-zero error value on failure and 0 on success.
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->data
(the size of which is
stored in
dest->ulen),
the function should identify the required buffer size in
dest->size
and return DB_BUFFER_SMALL
.
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->data
or
data->data
(the size of which is
available in the DBT's
ulen field),
the function should identify the required buffer size
using the DBT's
size
field
and return DB_BUFFER_SMALL
.
The DB->set_bt_compress()
method may fail and return one of the following non-zero errors:
If the method was called after DB->open() was called; or if an invalid flag value or parameter was specified.