m4_comment([$Id: db_set_bt_prefix.so,v 10.48 2004/08/13 03:38:56 bostic Exp $])

define(M4PAGELOCAL, dbh_set_bt_prefix)
include(m4/m4.seealso)

m4_pf_header(m4_ref(dbh_set_bt_prefix),
ifelse(M4API, C_API, [dnl
int
DB-__GT__set_bt_prefix(DB *db,
    size_t (*bt_prefix_fcn)(DB *, const DBT *, const DBT *));
])
ifelse(M4API, CXX_API, [dnl
extern "C" {
    typedef size_t (*bt_prefix_fcn_type)(DB *, const DBT *, const DBT *);
};
int
Db::set_bt_prefix(bt_prefix_fcn_type bt_prefix_fcn);
]))

define(__prefix_param, [dnl
ifelse([$1], internal, [dnl
The m4_arg(bt_prefix_fcn) function is the application-specific Btree
prefix function.  The prefix function takes three parameters:
m4_tagbegin
m4_tag(m4_arg(db), [dnl
The m4_arg(db) parameter is the enclosing database handle.])
m4_tag(m4_arg(dbt1), [dnl
The m4_arg(dbt1) parameter is a m4_ref(Dbt) representing a database key.])
m4_tag(m4_arg(dbt2), [dnl
The m4_arg(dbt2) parameter is a m4_ref(Dbt) representing a database key.])
m4_tagend],[dnl
m4_parambegin
m4_param(db, [dnl
The m4_arg(db) parameter is the enclosing database handle.])
m4_param(dbt1, [dnl
The m4_arg(dbt1) parameter is a m4_ref(Dbt) representing a database key.])
m4_param(dbt2, [dnl
The m4_arg(dbt2) parameter is a m4_ref(Dbt) representing a database key.])
m4_paramend])])

define(__prefix_return, [dnl
The m4_arg(bt_prefix_fcn) function must return the number of bytes of
the second key parameter that would be required by the Btree key
comparison function to determine the second key parameter's ordering
relationship with respect to the first key parameter.  If the two keys
are equal, the key length should be returned.  The prefix function must
correctly handle any key values used by the application (possibly
including zero-length keys).  The m4_arg(data) and m4_arg(size) fields
of the m4_ref(Dbt) are the only fields that may be used for the purposes
of this determination, and no particular alignment of the memory to
which the m4_arg(data) field refers may be assumed.])

m4_p([dnl
Set the Btree prefix function.  The prefix function is used to determine
the amount by which keys stored on the Btree internal pages can be
safely truncated without losing their uniqueness.  See the
m4_link(M4RELDIR/ref/am_conf/bt_prefix, Btree prefix comparison) section
of the m4_db Reference Guide for more details about how this works.  The
usefulness of this is data-dependent, but can produce significantly
reduced tree sizes and search times in some data sets.])

m4_p([dnl
If no prefix function or key comparison function is specified by the
application, a default lexical comparison function is used as the prefix
function.  If no prefix function is specified and a key comparison
function is specified, no prefix function is used.  It is an error to
specify a prefix function without also specifying a Btree key comparison
function.])

m4_scope_dbh(dbh_set_bt_prefix)

m4_when_dbopen(dbh_set_bt_prefix, corrupt)

m4_return(dbh_set_bt_prefix, std)

m4_parambegin
m4_param(bt_prefix_fcn, [dnl
__prefix_param(internal)
m4_p([__prefix_return])])

m4_paramend

m4_err(dbh_set_bt_prefix,
einval, [the method was called after m4_ref(dbh_open) was called])

m4_seealso(Db)
m4_page_footer