Library Version 18.1.25

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

## Db::set_slice_callback()

    #include <db_cxx.h>

    Db->set_slice_callback(int (*func)(const Db *db, const Dbt *key,
                                       Dbt *slice));

The `Db::set_slice_callback()` method is optionally used to identify slices for applications using a sliced environment. The callback identifies the portion of a record's key that is used to allocate records across slices. This is the slice-relevant portion of the key. If no callback is specified, then the entire key is used to allocate records across slices.

The `Db::set_slice_callback()` method must be called on an opened database handle. Changing this callback after the database has been created results in undefined behavior.

The `Db::set_backup_callbacks()` 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

#### func

The func parameter is the function used to determine which part of a key is slice relevant.

This function takes three parameters:

- `db`

  The db parameter is the sliced database for which the callback is set.

- `key`

  The key parameter is the source of the slice specification fields. That is, this is the key portion of the database's records. Some portion of this key is used to determine slice location, and that portion of the key is determined by the function implemented by this callback.

- `slice`

  The slice parameter is the Dbt into which the slice-relevant portion of the key will be written. This Dbt is user-owned.

  You should zero this Dbt, with the exception of the `size` and `data` fields. When initializing the structure, set `size` to `DB_SLICE_BUFLEN`, and `data` to the address of a 32-bit word aligned buffer of `DB_SLICE_BUFLEN` bytes.

  Within the context of the callback, you can set these two fields in the following ways:

  - If the slice-relevant portion of the key is one contiguous region, the set `data` to the first relevant byte in that region, and `size` to the number of significant bytes. Change no other fields.

  - If the slice-relevant portion of the key is more than one contiguous region, then calculate the total size required to hold the slice-relevant data. If this total size is less than `DB_SLICE_BUFLEN`, then leave the initialized buffer unchanged. If the total size is greater than `DB_SLICE_BUFLEN`, then:

    1. Allocate enough memory to contain all of the slice-relevant data. By default, `malloc()` is used to allocate memory. However, if your application configured a custom memory allocator using DbEnv::set_alloc() , then use that function.

    2. Set the `flags` parameter to `DB_DBT_APPMALLOC`. DB will deallocate the memory before returning from the API call, using the free function corresponding to the allocator just used.

    Once you have created a large enough buffer, set the slice Dbt handle's size to the new buffer's size.

    After that, concatenate all of the slice-relevant data together into the newly created buffer.

    Be aware that the slice Dbt handle's size can be zero, in which case the record will be placed in slice 0. Also, this size may be larger than the key's size, if it is appropriate for your application.

### Class

Db

### See Also

Database and Related Methods

Prev | Up | Next
Db::set_re_source() | Home | Db::slice_lookup()