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

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

m4_pf_header(m4_ref(dbh_set_dup_compare),
ifelse(M4API, C_API, [dnl
int
DB-__GT__set_dup_compare(DB *db,
    int (*dup_compare_fcn)(DB *, const DBT *, const DBT *));
])
ifelse(M4API, CXX_API, [dnl
extern "C" {
    typedef int (*dup_compare_fcn_type)(DB *, const DBT *, const DBT *);
};
int
Db::set_dup_compare(dup_compare_fcn_type dup_compare_fcn);
]))

define(__compareDuplicates_param, [dnl
ifelse([$1], internal, [dnl
The m4_arg(dup_compare_fcn) function is the application-specified
duplicate data item comparison function.  The function takes three
arguments:
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 the application
supplied data item.])
m4_tag(m4_arg(dbt2), [dnl
The m4_arg(dbt2) parameter is a m4_ref(Dbt) representing the current
tree's data item.])
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 the application
supplied data item.])
m4_param(dbt2, [dnl
The m4_arg(dbt2) parameter is a m4_ref(Dbt) representing the current
tree's data item.])
m4_paramend])])

define(__compareDuplicates_return, [dnl
The m4_arg(dup_compare_fcn) function must return an integer value less
than, equal to, or greater than zero if the first data item parameter
is considered to be respectively less than, equal to, or greater than
the second data item parameter.  In addition, the comparison function
must cause the data items in the set to be m4_italic(well-ordered).  The
comparison function must correctly handle any data item values used by
the application (possibly including zero-length data items).  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 comparison, and no
particular alignment of the memory to which the m4_arg(data) field
refers may be assumed.])

m4_p([dnl
Set the duplicate data item comparison function.  The comparison
function is called whenever it is necessary to compare a data item
specified by the application with a data item currently stored in the
database.  Calling m4_ref(dbh_set_dup_compare) implies calling
m4_ref(dbh_set_flags) with the m4_ref(DB_DUPSORT) flag.])

m4_p([dnl
If no comparison function is specified, the data items are compared
lexically, with shorter data items collating before longer data items.])

m4_when_dbopen(dbh_set_dup_compare, corrupt)

m4_return(dbh_set_dup_compare, std)

m4_parambegin
m4_param(dup_compare_fcn, [dnl
__compareDuplicates_param(internal)
m4_p([__compareDuplicates_return])])
m4_paramend

m4_err(dbh_set_dup_compare, einval)

m4_seealso(Db)
m4_page_footer