dup.so

berkeley db 4.6.21的源码。berkeley db是一个简单的数据库管理系统

m4_comment([$Id: dup.so,v 10.28 2003/10/18 19:15:54 bostic Exp $])

m4_ref_title(Access Methods,
    Duplicate data items,
    @duplicate data items,
    am_conf/byteorder, am_conf/malloc)

m4_p([dnl
The Btree and Hash access methods support the creation of multiple data
items for a single key item.  By default, multiple data items are not
permitted, and each database store operation will overwrite any previous
data item for that key.  To configure m4_db for duplicate data items,
call the m4_refT(dbh_set_flags) with the m4_ref(DB_DUP) flag.  Only one
copy of the key will be stored for each set of duplicate data items.
If the Btree access method comparison routine returns that two keys
compare equally, it is undefined which of the two keys will be stored
and returned from future database operations.])

m4_p([dnl
By default, m4_db stores duplicates in the order in which they were added,
that is, each new duplicate data item will be stored after any already
existing data items.  This default behavior can be overridden by using
the m4_refT(dbc_put) and one of the m4_ref(DB_AFTER), m4_ref(DB_BEFORE)
m4_ref(DB_KEYFIRST) or m4_ref(DB_KEYLAST) flags.  Alternatively, m4_db
may be configured to sort duplicate data items.])

m4_p([dnl
When stepping through the database sequentially, duplicate data items will
be returned individually, as a key/data pair, where the key item only
changes after the last duplicate data item has been returned.  For this
reason, duplicate data items cannot be accessed using the
m4_refT(dbh_get), as it always returns the first of the duplicate data
items.  Duplicate data items should be retrieved using a m4_db cursor
interface such as the m4_refT(dbc_get).])

m4_p([dnl
There is a flag that permits applications to request the following data
item only if it m4_bold(is) a duplicate data item of the current entry,
see m4_ref(DB_NEXT_DUP) for more information.  There is a flag that
permits applications to request the following data item only if it
m4_bold(is not) a duplicate data item of the current entry, see
m4_ref(DB_NEXT_NODUP) and m4_ref(DB_PREV_NODUP) for more information.])

m4_p([dnl
It is also possible to maintain duplicate records in sorted order.  Sorting
duplicates will significantly increase performance when searching them
and performing equality joins, common operations when using secondary
indices.  To configure m4_db to sort duplicate data items, the application
must call the m4_refT(dbh_set_flags) with the m4_ref(DB_DUPSORT) flag (in
addition to the m4_ref(DB_DUP) flag).  In addition, a custom comparison
function may be specified using the m4_refT(dbh_set_dup_compare).  If the
m4_ref(DB_DUPSORT) flag is given, but no comparison routine is specified,
then m4_db defaults to the same lexicographical sorting used for Btree
keys, with shorter items collating before longer items.])

m4_p([dnl
If the duplicate data items are unsorted, applications may store identical
duplicate data items, or, for those that just like the way it sounds,
m4_italic(duplicate duplicates).])

m4_p([dnl
m4_bold([In this release it is an error to attempt to store identical
duplicate data items when duplicates are being stored in a sorted order.])
This restriction is expected to be lifted in a future release.  There
is a flag that permits applications to disallow storing duplicate data
items when the database has been configured for sorted duplicates, see
m4_ref(DB_NODUPDATA) for more information.  Applications not wanting to
permit duplicate duplicates in databases configured for sorted
duplicates should begin using the m4_ref(DB_NODUPDATA) flag immediately.])

m4_p([dnl
For further information on how searching and insertion behaves in the
presence of duplicates (sorted or not), see the m4_ref(dbh_get),
m4_ref(dbh_put), m4_ref(dbc_get) and m4_ref(dbc_put) documentation.])

m4_page_footer