mirror of
https://github.com/berkeleydb/libdb.git
synced 2024-11-17 01:26:25 +00:00
593 lines
31 KiB
HTML
593 lines
31 KiB
HTML
|
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
|||
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|||
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|||
|
|
<head>
|
|||
|
|
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
|
|||
|
|
<title>DB->set_flags()</title>
|
|||
|
|
<link rel="stylesheet" href="apiReference.css" type="text/css" />
|
|||
|
|
<meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
|
|||
|
|
<link rel="start" href="index.html" title="Berkeley DB C API Reference" />
|
|||
|
|
<link rel="up" href="db.html" title="Chapter 2. The DB Handle" />
|
|||
|
|
<link rel="prev" href="dbset_feedback.html" title="DB->set_feedback()" />
|
|||
|
|
<link rel="next" href="dbset_h_compare.html" title="DB->set_h_compare()" />
|
|||
|
|
</head>
|
|||
|
|
<body>
|
|||
|
|
<div xmlns="" class="navheader">
|
|||
|
|
<div class="libver">
|
|||
|
|
<p>Library Version 11.2.5.2</p>
|
|||
|
|
</div>
|
|||
|
|
<table width="100%" summary="Navigation header">
|
|||
|
|
<tr>
|
|||
|
|
<th colspan="3" align="center">DB->set_flags()</th>
|
|||
|
|
</tr>
|
|||
|
|
<tr>
|
|||
|
|
<td width="20%" align="left"><a accesskey="p" href="dbset_feedback.html">Prev</a> </td>
|
|||
|
|
<th width="60%" align="center">Chapter 2.
|
|||
|
|
The DB Handle
|
|||
|
|
</th>
|
|||
|
|
<td width="20%" align="right"> <a accesskey="n" href="dbset_h_compare.html">Next</a></td>
|
|||
|
|
</tr>
|
|||
|
|
</table>
|
|||
|
|
<hr />
|
|||
|
|
</div>
|
|||
|
|
<div class="sect1" lang="en" xml:lang="en">
|
|||
|
|
<div class="titlepage">
|
|||
|
|
<div>
|
|||
|
|
<div>
|
|||
|
|
<h2 class="title" style="clear: both"><a id="dbset_flags"></a>DB->set_flags()</h2>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
<pre class="programlisting">#include <db.h>
|
|||
|
|
|
|||
|
|
int
|
|||
|
|
DB->set_flags(DB *db, u_int32_t flags); </pre>
|
|||
|
|
<p>
|
|||
|
|
Configure a database. Calling <code class="methodname">DB->set_flags()</code> is additive; there is
|
|||
|
|
no way to clear flags.
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
The <code class="methodname">DB->set_flags()</code> method may not be called after the
|
|||
|
|
<a class="xref" href="dbopen.html" title="DB->open()">DB->open()</a> method is called.
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
The <code class="methodname">DB->set_flags()</code> <span>
|
|||
|
|
<span>
|
|||
|
|
method returns a non-zero error value on failure and 0 on success.
|
|||
|
|
</span>
|
|||
|
|
|
|||
|
|
</span>
|
|||
|
|
</p>
|
|||
|
|
<div class="sect2" lang="en" xml:lang="en">
|
|||
|
|
<div class="titlepage">
|
|||
|
|
<div>
|
|||
|
|
<div>
|
|||
|
|
<h3 class="title"><a id="id3868756"></a>Parameters</h3>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
<div class="sect3" lang="en" xml:lang="en">
|
|||
|
|
<div class="titlepage">
|
|||
|
|
<div>
|
|||
|
|
<div>
|
|||
|
|
<h4 class="title"><a id="id3868737"></a>flags</h4>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
<p>
|
|||
|
|
The <span class="bold"><strong>flags</strong></span> parameter must be set to 0
|
|||
|
|
or by bitwise inclusively <span class="bold"><strong>OR</strong></span>'ing
|
|||
|
|
together one or more of the following values:
|
|||
|
|
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
<span class="bold"><strong>General</strong></span>
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
The following flags may be specified for any Berkeley DB access
|
|||
|
|
method:
|
|||
|
|
</p>
|
|||
|
|
<div class="itemizedlist">
|
|||
|
|
<ul type="disc">
|
|||
|
|
<li>
|
|||
|
|
<p><a id="dbset_flags_DB_CHKSUM"></a>
|
|||
|
|
<code class="literal">DB_CHKSUM</code>
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
Do checksum verification of pages read into the cache from the backing
|
|||
|
|
filestore. Berkeley DB uses the SHA1 Secure Hash Algorithm if
|
|||
|
|
encryption is configured and a general hash algorithm if it is not.
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
Calling <code class="methodname">DB->set_flags()</code> with the DB_CHKSUM flag only affects the
|
|||
|
|
specified <a class="link" href="db.html" title="Chapter 2. The DB Handle">DB</a> handle (and
|
|||
|
|
any other Berkeley DB handles opened within the scope of that handle).
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
If the database already exists when <a class="xref" href="dbopen.html" title="DB->open()">DB->open()</a>
|
|||
|
|
is called, the DB_CHKSUM flag will be ignored.
|
|||
|
|
</p>
|
|||
|
|
</li>
|
|||
|
|
<li>
|
|||
|
|
<p><a id="dbset_flags_DB_ENCRYPT"></a>
|
|||
|
|
<code class="literal">DB_ENCRYPT</code>
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
Encrypt the database using the cryptographic password specified to the
|
|||
|
|
<a class="xref" href="envset_encrypt.html" title="DB_ENV->set_encrypt()">DB_ENV->set_encrypt()</a> or
|
|||
|
|
<a class="xref" href="dbset_encrypt.html" title="DB->set_encrypt()">DB->set_encrypt()</a>
|
|||
|
|
methods.
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
Calling <code class="methodname">DB->set_flags()</code> with the DB_ENCRYPT flag only affects the
|
|||
|
|
specified <a class="link" href="db.html" title="Chapter 2. The DB Handle">DB</a> handle (and
|
|||
|
|
any other Berkeley DB handles opened within the scope of that handle).
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
If the database already exists when <a class="xref" href="dbopen.html" title="DB->open()">DB->open()</a>
|
|||
|
|
is called, the DB_ENCRYPT flag must be the same as the existing database or an error
|
|||
|
|
will be returned.
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
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.
|
|||
|
|
</p>
|
|||
|
|
</li>
|
|||
|
|
<li>
|
|||
|
|
<p><a id="dbset_flags_DB_TXN_NOT_DURABLE"></a>
|
|||
|
|
<code class="literal">DB_TXN_NOT_DURABLE</code>
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
If set, Berkeley 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
|
|||
|
|
<a class="link" href="dbclose.html#dbclose_DB_NOSYNC">DB_NOSYNC</a>, or all
|
|||
|
|
database changes must be flushed from the database environment cache
|
|||
|
|
using either the <a class="xref" href="txncheckpoint.html" title="DB_ENV->txn_checkpoint()">DB_ENV->txn_checkpoint()</a>
|
|||
|
|
or <a class="xref" href="mempsync.html" title="DB_ENV->memp_sync()">DB_ENV->memp_sync()</a>
|
|||
|
|
methods. All database handles for a single physical file must set
|
|||
|
|
DB_TXN_NOT_DURABLE, including database handles for different databases
|
|||
|
|
in a physical file.
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
Calling <code class="methodname">DB->set_flags()</code>
|
|||
|
|
with the DB_TXN_NOT_DURABLE flag only affects the
|
|||
|
|
specified <a class="link" href="db.html" title="Chapter 2. The DB Handle">DB</a>
|
|||
|
|
handle (and any other Berkeley DB handles opened
|
|||
|
|
within the scope of that handle).
|
|||
|
|
</p>
|
|||
|
|
</li>
|
|||
|
|
</ul>
|
|||
|
|
</div>
|
|||
|
|
<p>
|
|||
|
|
<span class="bold"><strong>Btree</strong></span>
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
The following flags may be specified for the Btree access method:
|
|||
|
|
</p>
|
|||
|
|
<div class="itemizedlist">
|
|||
|
|
<ul type="disc">
|
|||
|
|
<li>
|
|||
|
|
<p><a id="dbset_flags_DB_DUP"></a>
|
|||
|
|
<code class="literal">DB_DUP</code>
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
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 or a
|
|||
|
|
duplicate sort function.
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
The DB_DUPSORT flag is preferred to DB_DUP for performance reasons.
|
|||
|
|
The DB_DUP flag should only be used by applications wanting to order
|
|||
|
|
duplicate data items manually.
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
Calling <code class="methodname">DB->set_flags()</code>
|
|||
|
|
with the DB_DUP flag affects the database,
|
|||
|
|
including all threads of control accessing the
|
|||
|
|
database.
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
If the database already exists when
|
|||
|
|
<a class="xref" href="dbopen.html" title="DB->open()">DB->open()</a>
|
|||
|
|
is called, the DB_DUP flag must be the same as
|
|||
|
|
the existing database or an error will be
|
|||
|
|
returned.
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
It is an error to specify both DB_DUP and DB_RECNUM.
|
|||
|
|
</p>
|
|||
|
|
</li>
|
|||
|
|
<li>
|
|||
|
|
<p><a id="dbset_flags_DB_DUPSORT"></a>
|
|||
|
|
<code class="literal">DB_DUPSORT</code>
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
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
|
|||
|
|
<a class="xref" href="dbset_dup_compare.html" title="DB->set_dup_compare()">DB->set_dup_compare()</a>
|
|||
|
|
method, a default lexical comparison will be used. It is an error to
|
|||
|
|
specify both DB_DUPSORT and DB_RECNUM.
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
Calling <code class="methodname">DB->set_flags()</code>
|
|||
|
|
with the DB_DUPSORT flag affects the database,
|
|||
|
|
including all threads of control accessing the
|
|||
|
|
database.
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
If the database already exists when
|
|||
|
|
<a class="xref" href="dbopen.html" title="DB->open()">DB->open()</a>
|
|||
|
|
is called, the DB_DUPSORT flag must be the same
|
|||
|
|
as the existing database or an error will be
|
|||
|
|
returned.
|
|||
|
|
</p>
|
|||
|
|
</li>
|
|||
|
|
<li>
|
|||
|
|
<p><a id="dbset_flags_DB_RECNUM"></a>
|
|||
|
|
<code class="literal">DB_RECNUM</code>
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
Support retrieval from the Btree using record numbers. For more
|
|||
|
|
information, see the
|
|||
|
|
<a class="link" href="dbget.html#dbget_DB_SET_RECNO">DB_SET_RECNO</a>
|
|||
|
|
flag to the <a class="xref" href="dbget.html" title="DB->get()">DB->get()</a> and
|
|||
|
|
<a class="xref" href="dbcget.html" title="DBcursor->get()">DBcursor->get()</a> methods.
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
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.
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
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 DB_RECNUM can result in serious
|
|||
|
|
performance degradation for some applications and data sets.
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
It is an error to specify both DB_DUP and DB_RECNUM.
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
Calling <code class="methodname">DB->set_flags()</code> with the DB_RECNUM flag affects the database,
|
|||
|
|
including all threads of control accessing the database.
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
If the database already exists when <a class="xref" href="dbopen.html" title="DB->open()">DB->open()</a>
|
|||
|
|
is called, the DB_RECNUM flag must be the same as the existing database or an error
|
|||
|
|
will be returned.
|
|||
|
|
</p>
|
|||
|
|
</li>
|
|||
|
|
<li>
|
|||
|
|
<p><a id="dbset_flags_DB_REVSPLITOFF"></a>
|
|||
|
|
<code class="literal">DB_REVSPLITOFF</code>
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
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 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
|
|||
|
|
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.
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
Calling <code class="methodname">DB->set_flags()</code>
|
|||
|
|
with the DB_REVSPLITOFF flag only affects the
|
|||
|
|
specified <a class="link" href="db.html" title="Chapter 2. The DB Handle">DB</a>
|
|||
|
|
handle (and any other Berkeley DB handles opened
|
|||
|
|
within the scope of that handle).
|
|||
|
|
</p>
|
|||
|
|
</li>
|
|||
|
|
</ul>
|
|||
|
|
</div>
|
|||
|
|
<p>
|
|||
|
|
<span class="bold"><strong>Hash</strong></span>
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
The following flags may be specified for the Hash access method:
|
|||
|
|
</p>
|
|||
|
|
<div class="itemizedlist">
|
|||
|
|
<ul type="disc">
|
|||
|
|
<li>
|
|||
|
|
<p><a id="dbset_flags_h_DB_DUP"></a>
|
|||
|
|
<code class="literal">DB_DUP</code>
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
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.
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
The DB_DUPSORT flag is preferred to DB_DUP for performance reasons.
|
|||
|
|
The DB_DUP flag should only be used by applications wanting to order
|
|||
|
|
duplicate data items manually.
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
Calling <code class="methodname">DB->set_flags()</code> with the DB_DUP flag affects the database,
|
|||
|
|
including all threads of control accessing the database.
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
If the database already exists when <a class="xref" href="dbopen.html" title="DB->open()">DB->open()</a>
|
|||
|
|
is called, the DB_DUP flag must be the same as the existing database or an error will be
|
|||
|
|
returned.
|
|||
|
|
</p>
|
|||
|
|
</li>
|
|||
|
|
<li>
|
|||
|
|
<p>
|
|||
|
|
<code class="literal">DB_DUPSORT</code>
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
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
|
|||
|
|
<a class="xref" href="dbset_dup_compare.html" title="DB->set_dup_compare()">DB->set_dup_compare()</a>
|
|||
|
|
method, a default lexical comparison will be used.
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
Calling <code class="methodname">DB->set_flags()</code> with the DB_DUPSORT flag affects the
|
|||
|
|
database, including all threads of control accessing the database.
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
If the database already exists when <a class="xref" href="dbopen.html" title="DB->open()">DB->open()</a>
|
|||
|
|
is called, the DB_DUPSORT flag must be the same as the existing database or an error
|
|||
|
|
will be returned.
|
|||
|
|
</p>
|
|||
|
|
</li>
|
|||
|
|
<li>
|
|||
|
|
<p><a id="dbset_flags_hash_DB_REVSPLITOFF"></a>
|
|||
|
|
<code class="literal">DB_REVSPLITOFF</code>
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
Turns off hash bucket compaction. When a hash bucket is
|
|||
|
|
emptied, the Berkeley DB Hash implementation will decrease
|
|||
|
|
the hash table size, coalescing buckets. This will
|
|||
|
|
decrease the number of pages in the database.
|
|||
|
|
This can hurt performance in applications with cyclical
|
|||
|
|
data demands — that is, applications where the
|
|||
|
|
database grows and shrinks repeatedly — because of
|
|||
|
|
the cost of resplitting buckets when they grow again.
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
Calling <code class="methodname">DB->set_flags()</code> with the
|
|||
|
|
DB_REVSPLITOFF flag only affects the
|
|||
|
|
specified <a class="link" href="db.html" title="Chapter 2. The DB Handle">DB</a> handle (and
|
|||
|
|
any other Berkeley DB handles opened within the scope of that handle).
|
|||
|
|
</p>
|
|||
|
|
</li>
|
|||
|
|
</ul>
|
|||
|
|
</div>
|
|||
|
|
<p>
|
|||
|
|
<span class="bold"><strong>Queue</strong></span>
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
The following flags may be specified for the Queue access method:
|
|||
|
|
</p>
|
|||
|
|
<div class="itemizedlist">
|
|||
|
|
<ul type="disc">
|
|||
|
|
<li>
|
|||
|
|
<p>
|
|||
|
|
<code class="literal">DB_INORDER</code>
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
The DB_INORDER flag modifies the operation of the
|
|||
|
|
<a class="link" href="dbget.html#dbget_DB_CONSUME">DB_CONSUME</a> or
|
|||
|
|
<a class="link" href="dbget.html#dbget_DB_CONSUME_WAIT">DB_CONSUME_WAIT</a>
|
|||
|
|
flags to <a class="xref" href="dbget.html" title="DB->get()">DB->get()</a> to
|
|||
|
|
return key/data pairs in order. That is, they will always return the
|
|||
|
|
key/data item from the head of the queue.
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
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 <a class="xref" href="dbget.html" title="DB->get()">DB->get()</a>
|
|||
|
|
call returns.
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
This flag modifies the <a class="xref" href="dbget.html" title="DB->get()">DB->get()</a>
|
|||
|
|
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.
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
Calling <code class="methodname">DB->set_flags()</code> with the DB_INORDER flag only affects the
|
|||
|
|
specified <a class="link" href="db.html" title="Chapter 2. The DB Handle">DB</a> handle (and
|
|||
|
|
any other Berkeley DB handles opened within the scope of that handle).
|
|||
|
|
</p>
|
|||
|
|
</li>
|
|||
|
|
</ul>
|
|||
|
|
</div>
|
|||
|
|
<p>
|
|||
|
|
<span class="bold"><strong>Recno</strong></span>
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
The following flags may be specified for the Recno access method:
|
|||
|
|
</p>
|
|||
|
|
<div class="itemizedlist">
|
|||
|
|
<ul type="disc">
|
|||
|
|
<li>
|
|||
|
|
<p><a id="dbset_flags_DB_RENUMBER"></a>
|
|||
|
|
<code class="literal">DB_RENUMBER</code>
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
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.
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
Using the <a class="xref" href="dbput.html" title="DB->put()">DB->put()</a> or
|
|||
|
|
<a class="xref" href="dbcput.html" title="DBcursor->put()">DBcursor->put()</a> 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 <a href="../../programmer_reference/program_errorret.html#program_errorret.DB_KEYEMPTY" class="olink">DB_KEYEMPTY</a>.
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
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.
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
If a deleted record is not at the end of the database, all records
|
|||
|
|
following the removed record will be automatically renumbered downward
|
|||
|
|
by one. For example, deleting the record numbered 8 causes records
|
|||
|
|
numbered 9 and greater to be renumbered downward by one. If a
|
|||
|
|
cursor was positioned to record number 9 or greater before the
|
|||
|
|
removal, it will be shifted downward one logical record, continuing to
|
|||
|
|
refer to the same record as it did before.
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
If a record is deleted, all cursors that were positioned on that record
|
|||
|
|
prior to the removal will no longer be positioned on a valid entry.
|
|||
|
|
This includes cursors used to delete an item. For example, if
|
|||
|
|
a cursor was positioned to record number 8 before the removal of
|
|||
|
|
that record, subsequent calls to <a class="xref" href="dbcget.html" title="DBcursor->get()">DBcursor->get()</a>
|
|||
|
|
with flags of DB_CURRENT will result in an error return of
|
|||
|
|
<a href="../../programmer_reference/program_errorret.html#program_errorret.DB_KEYEMPTY" class="olink">DB_KEYEMPTY</a>
|
|||
|
|
until the cursor is moved to another record. A call to
|
|||
|
|
<a class="xref" href="dbcget.html" title="DBcursor->get()">DBcursor->get()</a> with flags of DB_NEXT
|
|||
|
|
will return the new record numbered 8 - which is the record that was
|
|||
|
|
numbered 9 prior to the delete (if such a record existed).
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
For these reasons, concurrent access to a Recno database with the
|
|||
|
|
DB_RENUMBER flag specified may be largely meaningless, although it is
|
|||
|
|
supported.
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
Calling <code class="methodname">DB->set_flags()</code> with the DB_RENUMBER flag affects the
|
|||
|
|
database, including all threads of control accessing the database.
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
If the database already exists when <a class="xref" href="dbopen.html" title="DB->open()">DB->open()</a>
|
|||
|
|
is called, the DB_RENUMBER flag must be the same as the existing database or an error
|
|||
|
|
will be returned.
|
|||
|
|
</p>
|
|||
|
|
</li>
|
|||
|
|
<li>
|
|||
|
|
<p><a id="dbset_flags_DB_SNAPSHOT"></a>
|
|||
|
|
<code class="literal">DB_SNAPSHOT</code>
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
This flag specifies that any specified <span class="bold"><strong>re_source</strong></span> file be read in its entirety when
|
|||
|
|
<a class="xref" href="dbopen.html" title="DB->open()">DB->open()</a> is called. If
|
|||
|
|
this flag is not specified, the <span class="bold"><strong>re_source</strong></span> file may be read lazily.
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
See the <a class="xref" href="dbset_re_source.html" title="DB->set_re_source()">DB->set_re_source()</a>
|
|||
|
|
method for information on the <span class="bold"><strong>re_source</strong></span> file.
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
Calling <code class="methodname">DB->set_flags()</code> with the DB_SNAPSHOT flag only affects the
|
|||
|
|
specified <a class="link" href="db.html" title="Chapter 2. The DB Handle">DB</a> handle (and
|
|||
|
|
any other Berkeley DB handles opened within the scope of that handle).
|
|||
|
|
</p>
|
|||
|
|
</li>
|
|||
|
|
</ul>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
<div class="sect2" lang="en" xml:lang="en">
|
|||
|
|
<div class="titlepage">
|
|||
|
|
<div>
|
|||
|
|
<div>
|
|||
|
|
<h3 class="title"><a id="id3868636"></a>Errors</h3>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
<p>
|
|||
|
|
The <code class="methodname">DB->set_flags()</code> <span>
|
|||
|
|
<span>
|
|||
|
|
method may fail and return one of the following non-zero errors:
|
|||
|
|
</span>
|
|||
|
|
|
|||
|
|
</span>
|
|||
|
|
</p>
|
|||
|
|
<div class="sect3" lang="en" xml:lang="en">
|
|||
|
|
<div class="titlepage">
|
|||
|
|
<div>
|
|||
|
|
<div>
|
|||
|
|
<h4 class="title"><a id="id3868217"></a>EINVAL</h4>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
<p>
|
|||
|
|
An invalid flag value or parameter was specified.
|
|||
|
|
</p>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
<div class="sect2" lang="en" xml:lang="en">
|
|||
|
|
<div class="titlepage">
|
|||
|
|
<div>
|
|||
|
|
<div>
|
|||
|
|
<h3 class="title"><a id="id3869419"></a>Class</h3>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
<p>
|
|||
|
|
<a class="link" href="db.html" title="Chapter 2. The DB Handle">DB</a>
|
|||
|
|
</p>
|
|||
|
|
</div>
|
|||
|
|
<div class="sect2" lang="en" xml:lang="en">
|
|||
|
|
<div class="titlepage">
|
|||
|
|
<div>
|
|||
|
|
<div>
|
|||
|
|
<h3 class="title"><a id="id3868390"></a>See Also</h3>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
<p>
|
|||
|
|
<a class="xref" href="db.html#dblist" title="Database and Related Methods">Database and Related Methods</a>
|
|||
|
|
</p>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
<div class="navfooter">
|
|||
|
|
<hr />
|
|||
|
|
<table width="100%" summary="Navigation footer">
|
|||
|
|
<tr>
|
|||
|
|
<td width="40%" align="left"><a accesskey="p" href="dbset_feedback.html">Prev</a> </td>
|
|||
|
|
<td width="20%" align="center">
|
|||
|
|
<a accesskey="u" href="db.html">Up</a>
|
|||
|
|
</td>
|
|||
|
|
<td width="40%" align="right"> <a accesskey="n" href="dbset_h_compare.html">Next</a></td>
|
|||
|
|
</tr>
|
|||
|
|
<tr>
|
|||
|
|
<td width="40%" align="left" valign="top">DB->set_feedback() </td>
|
|||
|
|
<td width="20%" align="center">
|
|||
|
|
<a accesskey="h" href="index.html">Home</a>
|
|||
|
|
</td>
|
|||
|
|
<td width="40%" align="right" valign="top"> DB->set_h_compare()</td>
|
|||
|
|
</tr>
|
|||
|
|
</table>
|
|||
|
|
</div>
|
|||
|
|
</body>
|
|||
|
|
</html>
|