267 lines
10 KiB
Plaintext
267 lines
10 KiB
Plaintext
m4_comment([$Id: db_set_flags.so,v 10.68 2004/09/28 15:04:19 bostic Exp $])
|
|
|
|
define(M4PAGELOCAL,
|
|
[dbh_set_flags, dbh_get_flags, DB_CHKSUM, DB_DUP, DB_DUPSORT,
|
|
DB_ENCRYPT, DB_INORDER, DB_RECNUM, DB_REVSPLITOFF, DB_RENUMBER,
|
|
DB_SNAPSHOT, DB_TXN_NOT_DURABLE])
|
|
include(m4/m4.seealso)
|
|
|
|
m4_pf_header(m4_ref(dbh_set_flags),
|
|
ifelse(M4API, C_API, [dnl
|
|
int
|
|
DB-__GT__set_flags(DB *db, u_int32_t flags);
|
|
m4_blank
|
|
int
|
|
DB-__GT__get_flags(DB *db, u_int32_t *flagsp);
|
|
])
|
|
ifelse(M4API, CXX_API, [dnl
|
|
int
|
|
Db::set_flags(u_int32_t flags);
|
|
m4_blank
|
|
int Db::get_flags(u_int32_t *flagsp);
|
|
]))
|
|
|
|
define(m4_scope_db_flags, [m4_p([dnl
|
|
Calling m4_ref(dbh_set_flags) with the m4_ref($1) flag affects the
|
|
database, including all threads of control accessing the database.])])
|
|
define(m4_scope_dbh_flags, [m4_p([dnl
|
|
Calling m4_ref(dbh_set_flags) with the m4_ref($1) flag only affects the
|
|
specified m4_ref(Db) handle (and any other m4_db handles opened within
|
|
the scope of that handle).])])
|
|
|
|
define(m4_db_flag_open, [m4_p([dnl
|
|
If the database already exists when m4_ref(dbh_open) is called, the $1
|
|
flag
|
|
ifelse($2, error, [must be the same as the existing database or an error
|
|
will be returned.])
|
|
ifelse($2, ignored, [will be ignored.])])])
|
|
|
|
define(m4_dupflag, [dnl
|
|
m4_tag(m4_idef(DB_DUP), [dnl
|
|
Permit duplicate data items in the database; that is, insertion when the
|
|
key of the key/data pair being inserted already exists in the database
|
|
will be successful. The ordering of duplicates in the database is
|
|
determined by the order of insertion, unless the ordering is otherwise
|
|
specified by use of a cursor operation.
|
|
m4_p([dnl
|
|
The m4_ref(DB_DUPSORT) flag is preferred to m4_ref(DB_DUP) for
|
|
performance reasons. The m4_ref(DB_DUP) flag should only be used by
|
|
applications wanting to order duplicate data items manually.])
|
|
m4_scope_db_flags(DB_DUP)
|
|
m4_db_flag_open(DB_DUP, error)
|
|
ifelse([$1],,, m4_p([$1]))])])
|
|
|
|
define(m4_dupsortflag, [dnl
|
|
m4_tag(m4_idef(DB_DUPSORT), [dnl
|
|
Permit duplicate data items in the database; that is, insertion when the
|
|
key of the key/data pair being inserted already exists in the database
|
|
will be successful. The ordering of duplicates in the database is
|
|
determined by the duplicate comparison function. If the application
|
|
does not specify a comparison function using the
|
|
m4_refT(dbh_set_dup_compare), a default lexical comparison will be used.
|
|
It is an error to specify both m4_ref(DB_DUPSORT) and m4_ref(DB_RECNUM).
|
|
m4_scope_db_flags(DB_DUPSORT)
|
|
m4_db_flag_open(DB_DUPSORT, error)])])
|
|
|
|
m4_p([dnl
|
|
Configure a database. Calling m4_ref(dbh_set_flags) is additive; there
|
|
is no way to clear flags.])
|
|
|
|
m4_when_dbopen(dbh_set_flags)
|
|
|
|
m4_return(dbh_set_flags, std)
|
|
|
|
m4_parambegin
|
|
m4_param(flags, [dnl
|
|
m4_sf_or_may
|
|
|
|
m4_section(General)
|
|
m4_p([dnl
|
|
The following flags may be specified for any m4_db access method:])
|
|
|
|
m4_tagbegin
|
|
|
|
m4_idefz([database page @checksum])
|
|
m4_tag(m4_idef(DB_CHKSUM), [dnl
|
|
Do checksum verification of pages read into the cache from the backing
|
|
filestore. m4_db uses the SHA1 Secure Hash Algorithm
|
|
if encryption is configured and a general hash algorithm if it is not.
|
|
m4_scope_dbh_flags(DB_CHKSUM)
|
|
m4_db_flag_open(DB_CHKSUM, ignored)
|
|
If creating additional databases in a file, the checksum behavior specified
|
|
must be consistent with the existing databases in the file or an error will
|
|
be returned.])
|
|
|
|
m4_idefz([database @encryption])
|
|
m4_tag(m4_idef(DB_ENCRYPT), [dnl
|
|
Encrypt the database using the cryptographic password specified to the
|
|
m4_ref(dbenv_set_encrypt) or m4_refT(dbh_set_encrypt)s.
|
|
m4_scope_dbh_flags(DB_ENCRYPT)
|
|
m4_db_flag_open(DB_ENCRYPT, error)
|
|
If creating additional databases in a file, the encryption behavior specified
|
|
must be consistent with the existing databases in the file or an error will
|
|
be returned.
|
|
m4_p([dnl
|
|
Encrypted databases are not portable between machines of different byte
|
|
orders, that is, encrypted databases created on big-endian machines
|
|
cannot be read on little-endian machines, and vice versa.])])
|
|
|
|
m4_idefz([turn off database @durability])
|
|
m4_tag(m4_idef(DB_TXN_NOT_DURABLE), [dnl
|
|
If set, m4_db will not write log records for this database. This means
|
|
that updates of this database exhibit the ACI (atomicity, consistency,
|
|
and isolation) properties, but not D (durability); that is, database
|
|
integrity will be maintained, but if the application or system fails,
|
|
integrity will not persist. The database file must be verified and/or
|
|
restored from backup after a failure. In order to ensure integrity
|
|
after application shut down, the database handles must be closed without
|
|
specifying m4_ref(DB_NOSYNC), or all database changes must be flushed
|
|
from the database environment cache using either the
|
|
m4_ref(txn_checkpoint) or m4_refT(memp_sync)s. All database handles for
|
|
a single physical file must set m4_ref(DB_TXN_NOT_DURABLE), including
|
|
database handles for different databases in a physical file.
|
|
m4_scope_dbh_flags(DB_TXN_NOT_DURABLE)])
|
|
|
|
m4_tagend
|
|
|
|
m4_section(Btree)
|
|
m4_p([dnl
|
|
The following flags may be specified for the Btree access method:])
|
|
|
|
m4_tagbegin
|
|
m4_idefz([@duplicate data items])
|
|
m4_dupflag([It is an error to specify both m4_ref(DB_DUP) and m4_ref(DB_RECNUM).])
|
|
|
|
m4_idefz([sorted @duplicate data items])
|
|
m4_dupsortflag
|
|
|
|
m4_idefz([accessing Btree records by @record number])
|
|
m4_tag(m4_idef(DB_RECNUM), [dnl
|
|
Support retrieval from the Btree using record numbers. For more
|
|
information, see the m4_ref(DB_SET_RECNO) flag to the m4_ref(dbh_get)
|
|
and m4_ref(dbc_get) methods.
|
|
m4_p([dnl
|
|
Logical record numbers in Btree databases are mutable in the face of
|
|
record insertion or deletion. See the m4_ref(DB_RENUMBER) flag in the
|
|
Recno access method information for further discussion.])
|
|
m4_p([dnl
|
|
Maintaining record counts within a Btree introduces a serious point of
|
|
contention, namely the page locations where the record counts are
|
|
stored. In addition, the entire database must be locked during both
|
|
insertions and deletions, effectively single-threading the database for
|
|
those operations. Specifying m4_ref(DB_RECNUM) can result in serious
|
|
performance degradation for some applications and data sets.])
|
|
m4_p([dnl
|
|
It is an error to specify both m4_ref(DB_DUP) and m4_ref(DB_RECNUM).])
|
|
m4_scope_db_flags(DB_RECNUM)
|
|
m4_db_flag_open(DB_RECNUM, error)])
|
|
|
|
m4_idefz([turn off @reverse splits in Btree databases],
|
|
[turn off reverse @splits in Btree databases])
|
|
m4_tag(m4_idef(DB_REVSPLITOFF), [dnl
|
|
Turn off reverse splitting in the Btree. As pages are emptied in a
|
|
database, the m4_db Btree implementation attempts to coalesce empty pages
|
|
into higher-level pages in order to keep the database as small as possible
|
|
and minimize search time. This can hurt performance in applications
|
|
with cyclical data demands; that is, applications where the database grows
|
|
and shrinks repeatedly. For example, because m4_db does page-level
|
|
locking, the maximum level of concurrency in a database of two pages is far
|
|
smaller than that in a database of 100 pages, so a database that has
|
|
shrunk to a minimal size can cause severe deadlocking when a new cycle of
|
|
data insertion begins.
|
|
m4_scope_dbh_flags(DB_REVSPLITOFF)])
|
|
|
|
m4_tagend
|
|
|
|
m4_section(Hash)
|
|
m4_p([dnl
|
|
The following flags may be specified for the Hash access method:])
|
|
|
|
m4_tagbegin
|
|
m4_dupflag
|
|
m4_dupsortflag
|
|
m4_tagend
|
|
|
|
m4_section(Queue)
|
|
m4_p([dnl
|
|
The following flags may be specified for the Queue access method:])
|
|
|
|
m4_tagbegin
|
|
m4_idefz([@ordered retrieval of records from Queue databases])
|
|
m4_tag(m4_idef(DB_INORDER), [dnl
|
|
The m4_ref(DB_INORDER) flag modifies the operation of the
|
|
m4_ref(DB_CONSUME) or m4_ref(DB_CONSUME_WAIT) flags to m4_ref(dbh_get)
|
|
to return key/data pairs in order. That is, they will always return
|
|
the key/data item from the head of the queue.
|
|
|
|
m4_p([dnl
|
|
The default behavior of queue databases is optimized for multiple
|
|
readers, and does not guarantee that record will be retrieved in the
|
|
order they are added to the queue. Specifically, if a writing thread
|
|
adds multiple records to an empty queue, reading threads may skip some
|
|
of the initial records when the next m4_ref(dbh_get) call returns.])
|
|
|
|
m4_p([dnl
|
|
This flag modifies the m4_ref(dbh_get) call to verify that the record
|
|
being returned is in fact the head of the queue. This will increase
|
|
contention and reduce concurrency when there are many reading threads.])
|
|
|
|
m4_scope_dbh_flags(DB_INORDER)])
|
|
m4_tagend
|
|
|
|
m4_section(Recno)
|
|
m4_p([dnl
|
|
The following flags may be specified for the Recno access method:])
|
|
|
|
m4_tagbegin
|
|
m4_idefz([@renumbering records in Recno databases])
|
|
m4_tag(m4_idef(DB_RENUMBER), [dnl
|
|
Specifying the m4_ref(DB_RENUMBER) flag causes the logical record
|
|
numbers to be mutable, and change as records are added to and deleted
|
|
from the database. For example, the deletion of record number 4 causes
|
|
records numbered 5 and greater to be renumbered downward by one. If a
|
|
cursor was positioned to record number 4 before the deletion, it will
|
|
refer to the new record number 4, if any such record exists, after the
|
|
deletion. If a cursor was positioned after record number 4 before the
|
|
deletion, it will be shifted downward one logical record, continuing to
|
|
refer to the same record as it did before.
|
|
m4_p([dnl
|
|
Using the m4_ref(dbh_put) or m4_ref(dbc_put) interfaces to create new
|
|
records will cause the creation of multiple records if the record number
|
|
is more than one greater than the largest record currently in the
|
|
database. For example, creating record 28, when record 25 was previously
|
|
the last record in the database, will create records 26 and 27 as well as
|
|
28. Attempts to retrieve records that were created in this manner will
|
|
result in an error return of m4_ref(DB_KEYEMPTY).])
|
|
m4_p([dnl
|
|
If a created record is not at the end of the database, all records
|
|
following the new record will be automatically renumbered upward by one.
|
|
For example, the creation of a new record numbered 8 causes records
|
|
numbered 8 and greater to be renumbered upward by one. If a cursor was
|
|
positioned to record number 8 or greater before the insertion, it will be
|
|
shifted upward one logical record, continuing to refer to the same record
|
|
as it did before.])
|
|
m4_p([dnl
|
|
For these reasons, concurrent access to a Recno database with the
|
|
m4_ref(DB_RENUMBER) flag specified may be largely meaningless, although
|
|
it is supported.])
|
|
m4_scope_db_flags(DB_RENUMBER)
|
|
m4_db_flag_open(DB_RENUMBER, error)])
|
|
|
|
m4_idefz([pre-loading @text files into Recno databases])
|
|
m4_tag(m4_idef(DB_SNAPSHOT), [dnl
|
|
This flag specifies that any specified m4_arg(re_source) file be read
|
|
in its entirety when m4_ref(dbh_open) is called. If this flag is not
|
|
specified, the m4_arg(re_source) file may be read lazily.
|
|
m4_scope_dbh_flags(DB_SNAPSHOT)])
|
|
|
|
m4_tagend])
|
|
m4_paramend
|
|
|
|
m4_err(dbh_set_flags, einval)
|
|
|
|
m4_pf_getter(dbh_get_flags, current flags,, flagsp)
|
|
|
|
m4_seealso(Db)
|
|
m4_page_footer
|