#include <db_cxx.h>

int
Db::set_flags(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:

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.

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.

DB_RECNUM

Support retrieval from the Btree using record numbers. For more information, see the DB_GET_RECNO flag to the Db::get and Dbc::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.

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.

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.

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.

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 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 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.

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.

The Db::set_flags interface may be used only to configure Berkeley DB before the Db::open interface is called.

The Db::set_flags method either returns a non-zero error value or throws an exception that encapsulates a non-zero error value on failure, and returns 0 on success.

Errors

The Db::set_flags method may fail and throw an exception or 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 throw an exception or return a non-zero error for errors specified for other Berkeley DB and C library or system methods. If a catastrophic error has occurred, the Db::set_bt_compare method may fail and either return DB_RUNRECOVERY or throw an exception encapsulating DB_RUNRECOVERY, in which case all subsequent Berkeley DB calls will fail in the same way.

Class

See Also