|
DB->set_flags
|
|
#include <db.h>
int
DB->set_flags(DB *db, u_int32_t flags);
Description
Calling DB->set_flags is additive; there is no way to clear flags.
The flags value must be set to 0 or by bitwise inclusively OR'ing together one or
more of the following values:
General
The following flags may be specified for any Berkeley DB access method:
- DB_CHKSUM_SHA1
- Do checksum verification of pages read into the cache from the backing
filestore, using the SHA1 Secure Hash Algorithm.
Calling DB->set_flags with the DB_CHKSUM_SHA1 flag only affects the
specified DB handle (and any other Berkeley DB handles opened within
the scope of that handle).
If the database already exists when DB->open is called, the DB_CHKSUM_SHA1
flag
will be 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.
- DB_ENCRYPT
- Encrypt the database using the cryptographic password specified to the
DB_ENV->set_encrypt or DB->set_encrypt methods.
Calling DB->set_flags with the DB_ENCRYPT flag only affects the
specified DB handle (and any other Berkeley DB handles opened within
the scope of that handle).
If the database already exists when DB->open is called, the DB_ENCRYPT
flag
must be the same as the existing database or an error
will be returned.
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.
Btree
The following flags may be specified for the Btree access method:
- DB_DUP
- Permit duplicate data items in the tree; that is, insertion when the
key of the key/data pair being inserted already exists in the tree will
be successful. The ordering of duplicates in the tree is determined by
the order of insertion, unless the ordering is otherwise specified by
use of a cursor operation. It is an error to specify both DB_DUP
and DB_RECNUM.
Calling DB->set_flags with the DB_DUP flag affects the
database, including all threads of control accessing the database.
If the database already exists when DB->open is called, the DB_DUP
flag
must be the same as the existing database or an error
will be returned.
- DB_DUPSORT
- Permit duplicate data items in the tree; that is, insertion when the
key of the key/data pair being inserted already exists in the tree will
be successful. The ordering of duplicates in the tree is determined by
the duplicate comparison function.
If the application does not specify a comparison function using the
DB->set_dup_compare method, a default lexical comparison will be
used.
It is an error to specify both DB_DUPSORT and DB_RECNUM.
Calling DB->set_flags with the DB_DUPSORT flag affects the
database, including all threads of control accessing the database.
If the database already exists when DB->open is called, the DB_DUPSORT
flag
must be the same as the existing database or an error
will be returned.
- DB_RECNUM
- Support retrieval from the Btree using record numbers. For more
information, see the DB_SET_RECNO flag to the DB->get
and DBcursor->c_get methods.
Logical record numbers in Btree databases are mutable in the face of
record insertion or deletion. See the DB_RENUMBER flag in the
Recno access method information for further discussion.
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 tree must be locked during both
insertions and deletions, effectively single-threading the tree for
those operations. Specifying DB_RECNUM can result in serious
performance degradation for some applications and data sets.
It is an error to specify both DB_DUP and DB_RECNUM.
Calling DB->set_flags with the DB_RECNUM flag affects the
database, including all threads of control accessing the database.
If the database already exists when DB->open is called, the DB_RECNUM
flag
must be the same as the existing database or an error
will be returned.
- DB_REVSPLITOFF
- Turn off reverse splitting in the Btree. As pages are emptied in a
database, the Berkeley DB Btree implementation attempts to coalesce empty pages
into higher-level pages in order to keep the tree as small as possible
and minimize tree 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 Berkeley 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.
Calling DB->set_flags with the DB_REVSPLITOFF flag only affects the
specified DB handle (and any other Berkeley DB handles opened within
the scope of that handle).
Hash
The following flags may be specified for the Hash access method:
- DB_DUP
- Permit duplicate data items in the tree; that is, insertion when the
key of the key/data pair being inserted already exists in the tree will
be successful. The ordering of duplicates in the tree is determined by
the order of insertion, unless the ordering is otherwise specified by
use of a cursor operation. It is an error to specify both DB_DUP
and DB_RECNUM.
Calling DB->set_flags with the DB_DUP flag affects the
database, including all threads of control accessing the database.
If the database already exists when DB->open is called, the DB_DUP
flag
must be the same as the existing database or an error
will be returned.
- DB_DUPSORT
- Permit duplicate data items in the tree; that is, insertion when the
key of the key/data pair being inserted already exists in the tree will
be successful. The ordering of duplicates in the tree is determined by
the duplicate comparison function.
If the application does not specify a comparison function using the
DB->set_dup_compare method, a default lexical comparison will be
used.
It is an error to specify both DB_DUPSORT and DB_RECNUM.
Calling DB->set_flags with the DB_DUPSORT flag affects the
database, including all threads of control accessing the database.
If the database already exists when DB->open is called, the DB_DUPSORT
flag
must be the same as the existing database or an error
will be returned.
Queue
There are no additional flags that may be specified for the Queue access
method.
Recno
The following flags may be specified for the Recno access method:
- DB_RENUMBER
- Specifying the 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.
Using the DB->put or DBcursor->c_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 DB_KEYEMPTY.
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.
For these reasons, concurrent access to a Recno database with the
DB_RENUMBER flag specified may be largely meaningless, although
it is supported.
Calling DB->set_flags with the DB_RENUMBER flag affects the
database, including all threads of control accessing the database.
If the database already exists when DB->open is called, the DB_RENUMBER
flag
must be the same as the existing database or an error
will be returned.
- DB_SNAPSHOT
- This flag specifies that any specified re_source file be read
in its entirety when DB->open is called. If this flag is not
specified, the re_source file may be read lazily.
Calling DB->set_flags with the DB_SNAPSHOT flag only affects the
specified DB handle (and any other Berkeley DB handles opened within
the scope of that handle).
The DB->set_flags interface may not be called after the DB->open
interface is called.
The DB->set_flags method returns a non-zero error value on failure and 0 on success.
Errors
The DB->set_flags method may fail and return a non-zero error for the following conditions:
- EINVAL
- An invalid flag value or parameter was specified.
The DB->set_bt_compare method may fail and return a non-zero error for errors specified for other Berkeley DB and C library or system functions.
If a catastrophic error has occurred, the DB->set_bt_compare method may fail and
return DB_RUNRECOVERY,
in which case all subsequent Berkeley DB calls will fail in the same way.
Class
DB
See Also
Databases and Related Methods
Copyright Sleepycat Software
|