summaryrefslogtreecommitdiff
path: root/docs/programmer_reference/rq_conf.html
diff options
context:
space:
mode:
Diffstat (limited to 'docs/programmer_reference/rq_conf.html')
-rw-r--r--docs/programmer_reference/rq_conf.html444
1 files changed, 255 insertions, 189 deletions
diff --git a/docs/programmer_reference/rq_conf.html b/docs/programmer_reference/rq_conf.html
index ab9c302d..a7379d26 100644
--- a/docs/programmer_reference/rq_conf.html
+++ b/docs/programmer_reference/rq_conf.html
@@ -14,7 +14,7 @@
<body>
<div xmlns="" class="navheader">
<div class="libver">
- <p>Library Version 11.2.5.3</p>
+ <p>Library Version 12.1.6.1</p>
</div>
<table width="100%" summary="Navigation header">
<tr>
@@ -22,9 +22,7 @@
</tr>
<tr>
<td width="20%" align="left"><a accesskey="p" href="heap_conf.html">Prev</a> </td>
- <th width="60%" align="center">Chapter 2. 
- Access Method Configuration
- </th>
+ <th width="60%" align="center">Chapter 2.  Access Method Configuration </th>
<td width="20%" align="right"> <a accesskey="n" href="am.html">Next</a></td>
</tr>
</table>
@@ -42,265 +40,334 @@
<dl>
<dt>
<span class="sect2">
- <a href="rq_conf.html#am_conf_recno">Managing record-based databases</a>
+ <a href="rq_conf.html#am_conf_recno">Managing record-based
+ databases</a>
</span>
</dt>
<dt>
<span class="sect2">
- <a href="rq_conf.html#am_conf_extentsize">Selecting a Queue extent size</a>
+ <a href="rq_conf.html#am_conf_extentsize">Selecting a Queue extent
+ size</a>
</span>
</dt>
<dt>
<span class="sect2">
- <a href="rq_conf.html#am_conf_re_source">Flat-text backing files</a>
+ <a href="rq_conf.html#am_conf_re_source">Flat-text backing
+ files</a>
</span>
</dt>
<dt>
<span class="sect2">
- <a href="rq_conf.html#am_conf_renumber">Logically renumbering records</a>
+ <a href="rq_conf.html#am_conf_renumber">Logically renumbering
+ records</a>
</span>
</dt>
</dl>
</div>
- <p>
- There are a series of configuration tasks which you can perform when
- using the Queue and Recno access methods. They are described in the following sections.
-</p>
+ <p>
+ There are a series of configuration tasks which you can
+ perform when using the Queue and Recno access methods. They
+ are described in the following sections.
+ </p>
<div class="sect2" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
- <h3 class="title"><a id="am_conf_recno"></a>Managing record-based databases</h3>
+ <h3 class="title"><a id="am_conf_recno"></a>Managing record-based
+ databases</h3>
</div>
</div>
</div>
- <p>When using fixed- or variable-length record-based databases, particularly
-with flat-text backing files, there are several items that the user can
-control. The Recno access method can be used to store either variable-
-or fixed-length data items. By default, the Recno access method stores
-variable-length data items. The Queue access method can only store
-fixed-length data items.</p>
+ <p>
+ When using fixed- or variable-length record-based databases,
+ particularly with flat-text backing files, there are several
+ items that the user can control. The Recno access method can
+ be used to store either variable- or fixed-length data items.
+ By default, the Recno access method stores variable-length
+ data items. The Queue access method can only store
+ fixed-length data items.
+ </p>
<div class="sect3" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
- <h4 class="title"><a id="idp704256"></a>Record Delimiters</h4>
+ <h4 class="title"><a id="idm2664864"></a>Record Delimiters</h4>
</div>
</div>
</div>
- <p>When using the Recno access method to store variable-length records,
-records read from any backing source file are separated by a specific
-byte value which marks the end of one record and the beginning of the
-next. This delimiting value is ignored except when reading records from
-a backing source file, that is, records may be stored into the database
-that include the delimiter byte. However, if such records are written
-out to the backing source file and the backing source file is
-subsequently read into a database, the records will be split where
-delimiting bytes were found.</p>
- <p>For example, UNIX text files can usually be interpreted as a sequence of
-variable-length records separated by ASCII newline characters. This byte
-value (ASCII 0x0a) is the default delimiter. Applications may specify a
-different delimiting byte using the <a href="../api_reference/C/dbset_re_delim.html" class="olink">DB-&gt;set_re_delim()</a> method. If no
-backing source file is being used, there is no reason to set the
-delimiting byte value.</p>
+ <p>
+ When using the Recno access method to store
+ variable-length records, records read from any backing
+ source file are separated by a specific byte value which
+ marks the end of one record and the beginning of the next.
+ This delimiting value is ignored except when reading
+ records from a backing source file, that is, records may
+ be stored into the database that include the delimiter
+ byte. However, if such records are written out to the
+ backing source file and the backing source file is
+ subsequently read into a database, the records will be
+ split where delimiting bytes were found.
+ </p>
+ <p>
+ For example, UNIX text files can usually be interpreted
+ as a sequence of variable-length records separated by
+ ASCII newline characters. This byte value (ASCII 0x0a) is
+ the default delimiter. Applications may specify a
+ different delimiting byte using the <a href="../api_reference/C/dbset_re_delim.html" class="olink">DB-&gt;set_re_delim()</a>
+ method. If no backing source file is being used, there is
+ no reason to set the delimiting byte value.
+ </p>
</div>
<div class="sect3" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
- <h4 class="title"><a id="idp719456"></a>Record Length</h4>
+ <h4 class="title"><a id="idm2240344"></a>Record Length</h4>
</div>
</div>
</div>
- <p>When using the Recno or Queue access methods to store fixed-length
-records, the record length must be specified. Since the Queue access
-method always uses fixed-length records, the user must always set the
-record length prior to creating the database. Setting the record length
-is what causes the Recno access method to store fixed-length, not
-variable-length, records.</p>
- <p>The length of the records is specified by calling the
-<a href="../api_reference/C/dbset_re_len.html" class="olink">DB-&gt;set_re_len()</a> method. The default length of the records is 0 bytes.
-Any record read from a backing source file or otherwise stored in the
-database that is shorter than the declared length will automatically be
-padded as described for the <a href="../api_reference/C/dbset_re_pad.html" class="olink">DB-&gt;set_re_pad()</a> method. Any record stored
-that is longer than the declared length results in an error. For
-further information on backing source files, see
-<a class="xref" href="rq_conf.html#am_conf_re_source" title="Flat-text backing files">Flat-text backing files</a>.</p>
+ <p>
+ When using the Recno or Queue access methods to store
+ fixed-length records, the record length must be specified.
+ Since the Queue access method always uses fixed-length
+ records, the user must always set the record length prior
+ to creating the database. Setting the record length is
+ what causes the Recno access method to store fixed-length,
+ not variable-length, records.
+ </p>
+ <p>
+ The length of the records is specified by calling the
+ <a href="../api_reference/C/dbset_re_len.html" class="olink">DB-&gt;set_re_len()</a> method. The default length of the records
+ is 0 bytes. Any record read from a backing source file or
+ otherwise stored in the database that is shorter than the
+ declared length will automatically be padded as described
+ for the <a href="../api_reference/C/dbset_re_pad.html" class="olink">DB-&gt;set_re_pad()</a> method. Any record stored that is
+ longer than the declared length results in an error. For
+ further information on backing source files, see <a class="xref" href="rq_conf.html#am_conf_re_source" title="Flat-text backing files">Flat-text backing
+ files</a>.
+ </p>
</div>
<div class="sect3" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
- <h4 class="title"><a id="idm2290720"></a>Record Padding Byte Value</h4>
+ <h4 class="title"><a id="idm2071320"></a>Record Padding Byte Value</h4>
</div>
</div>
</div>
- <p>When storing fixed-length records in a Queue or Recno database, a pad
-character may be specified by calling the <a href="../api_reference/C/dbset_re_pad.html" class="olink">DB-&gt;set_re_pad()</a> method. Any
-record read from the backing source file or otherwise stored in the
-database that is shorter than the expected length will automatically be
-padded with this byte value. If fixed-length records are specified but
-no pad value is specified, a space character (0x20 in the ASCII
-character set) will be used. For further information on backing source
-files, see <a class="xref" href="rq_conf.html#am_conf_re_source" title="Flat-text backing files">Flat-text backing files</a>.</p>
+ <p>
+ When storing fixed-length records in a Queue or Recno
+ database, a pad character may be specified by calling the
+ <a href="../api_reference/C/dbset_re_pad.html" class="olink">DB-&gt;set_re_pad()</a> method. Any record read from the backing
+ source file or otherwise stored in the database that is
+ shorter than the expected length will automatically be
+ padded with this byte value. If fixed-length records are
+ specified but no pad value is specified, a space character
+ (0x20 in the ASCII character set) will be used. For
+ further information on backing source files, see <a class="xref" href="rq_conf.html#am_conf_re_source" title="Flat-text backing files">Flat-text backing
+ files</a>.
+ </p>
</div>
</div>
<div class="sect2" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
- <h3 class="title"><a id="am_conf_extentsize"></a>Selecting a Queue extent size</h3>
+ <h3 class="title"><a id="am_conf_extentsize"></a>Selecting a Queue extent
+ size</h3>
</div>
</div>
</div>
<p>
- In Queue databases, records are allocated sequentially and directly
- mapped to an offset within the file storage for the database. As
- records are deleted from the Queue, pages will become empty and will
- not be reused in normal queue operations. To facilitate the
- reclamation of disk space a Queue may be partitioned into extents.
- Each extent is kept in a separate physical file.
+ In Queue databases, records are allocated sequentially and
+ directly mapped to an offset within the file storage for the
+ database. As records are deleted from the Queue, pages will
+ become empty and will not be reused in normal queue
+ operations. To facilitate the reclamation of disk space a
+ Queue may be partitioned into extents. Each extent is kept in
+ a separate physical file.
</p>
- <p>
- Extent files are automatically created as needed and marked for
- deletion when the head of the queue moves off the extent. The extent
- will not be deleted until all processes close the extent. In addition,
- Berkeley DB caches a small number of extents that have been recently
- used; this may delay when an extent will be deleted. The number of
- extents left open depends on queue activity.
+ <p>
+ Extent files are automatically created as needed and marked
+ for deletion when the head of the queue moves off the extent.
+ The extent will not be deleted until all processes close the
+ extent. In addition, Berkeley DB caches a small number of
+ extents that have been recently used; this may delay when an
+ extent will be deleted. The number of extents left open
+ depends on queue activity.
</p>
<p>
- The extent size specifies the number of pages that make up each extent.
- By default, if no extent size is specified, the Queue resides in a
- single file and disk space is not reclaimed. In choosing an extent
- size there is a tradeoff between the amount of disk space used and the
- overhead of creating and deleting files. If the extent size is too
- small, the system will pay a performance penalty, creating and deleting
- files frequently. In addition, if the active part of the queue spans
- many files, all those files will need to be open at the same time,
- consuming system and process file resources.
+ The extent size specifies the number of pages that make up
+ each extent. By default, if no extent size is specified, the
+ Queue resides in a single file and disk space is not
+ reclaimed. In choosing an extent size there is a tradeoff
+ between the amount of disk space used and the overhead of
+ creating and deleting files. If the extent size is too small,
+ the system will pay a performance penalty, creating and
+ deleting files frequently. In addition, if the active part of
+ the queue spans many files, all those files will need to be
+ open at the same time, consuming system and process file
+ resources.
</p>
<p>
- You can set the Queue extent size using the <a href="../api_reference/C/dbset_q_extentsize.html" class="olink">DB-&gt;set_q_extentsize()</a>
- method. You can see the current extent size using the
- <a href="../api_reference/C/dbget_q_extentsize.html" class="olink">DB-&gt;get_q_extentsize()</a> method.
+ You can set the Queue extent size using the
+ <a href="../api_reference/C/dbset_q_extentsize.html" class="olink">DB-&gt;set_q_extentsize()</a> method. You can see the current extent
+ size using the <a href="../api_reference/C/dbget_q_extentsize.html" class="olink">DB-&gt;get_q_extentsize()</a> method.
</p>
</div>
<div class="sect2" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
- <h3 class="title"><a id="am_conf_re_source"></a>Flat-text backing files</h3>
+ <h3 class="title"><a id="am_conf_re_source"></a>Flat-text backing
+ files</h3>
</div>
</div>
</div>
- <p>It is possible to back any Recno database (either fixed or variable
-length) with a flat-text source file. This provides fast read (and
-potentially write) access to databases that are normally created and
-stored as flat-text files. The backing source file may be specified by
-calling the <a href="../api_reference/C/dbset_re_source.html" class="olink">DB-&gt;set_re_source()</a> method.</p>
- <p>The backing source file will be read to initialize the database. In the
-case of variable length records, the records are assumed to be separated
-as described for the <a href="../api_reference/C/dbset_re_delim.html" class="olink">DB-&gt;set_re_delim()</a> method. For example, standard
-UNIX byte stream files can be interpreted as a sequence of variable
-length records separated by ASCII newline characters. This is the
-default.</p>
- <p>When cached data would normally be written back to the underlying
-database file (for example, when the <a href="../api_reference/C/dbclose.html" class="olink">DB-&gt;close()</a> or
-<a href="../api_reference/C/dbsync.html" class="olink">DB-&gt;sync()</a> methods are called), the in-memory copy of the database will
-be written back to the backing source file.</p>
- <p>The backing source file must already exist (but may be zero-length) when
-<a href="../api_reference/C/dbopen.html" class="olink">DB-&gt;open()</a> is called. By default, the backing source file is read
-lazily, that is, records are not read from the backing source file until
-they are requested by the application. If multiple processes (not
-threads) are accessing a Recno database concurrently and either
-inserting or deleting records, the backing source file must be read in
-its entirety before more than a single process accesses the database,
-and only that process should specify the backing source file as part of
-the <a href="../api_reference/C/dbopen.html" class="olink">DB-&gt;open()</a> call. This can be accomplished by calling the
-<a href="../api_reference/C/dbset_flags.html" class="olink">DB-&gt;set_flags()</a> method with the <a href="../api_reference/C/dbset_flags.html#dbset_flags_DB_SNAPSHOT" class="olink">DB_SNAPSHOT</a> flag.</p>
- <p>Reading and writing the backing source file cannot be transactionally
-protected because it involves filesystem operations that are not part of
-the Berkeley DB transaction methodology. For this reason, if a temporary
-database is used to hold the records (a NULL was specified as the file
-argument to <a href="../api_reference/C/dbopen.html" class="olink">DB-&gt;open()</a>), <span class="bold"><strong>it is possible to lose the
-contents of the backing source file if the system crashes at the right
-instant</strong></span>. If a permanent file is used to hold the database (a filename
-was specified as the file argument to <a href="../api_reference/C/dbopen.html" class="olink">DB-&gt;open()</a>), normal database
-recovery on that file can be used to prevent information loss. It is
-still possible that the contents of the backing source file itself will
-be corrupted or lost if the system crashes.</p>
- <p>For all of the above reasons, the backing source file is generally used
-to specify databases that are read-only for Berkeley DB applications, and that
-are either generated on the fly by software tools, or modified using a
-different mechanism such as a text editor.</p>
+ <p>
+ It is possible to back any Recno database (either fixed or
+ variable length) with a flat-text source file. This provides
+ fast read (and potentially write) access to databases that are
+ normally created and stored as flat-text files. The backing
+ source file may be specified by calling the <a href="../api_reference/C/dbset_re_source.html" class="olink">DB-&gt;set_re_source()</a>
+ method.
+ </p>
+ <p>
+ The backing source file will be read to initialize the
+ database. In the case of variable length records, the records
+ are assumed to be separated as described for the
+ <a href="../api_reference/C/dbset_re_delim.html" class="olink">DB-&gt;set_re_delim()</a> method. For example, standard UNIX byte
+ stream files can be interpreted as a sequence of variable
+ length records separated by ASCII newline characters. This is
+ the default.
+ </p>
+ <p>
+ When cached data would normally be written back to the
+ underlying database file (for example, when the <a href="../api_reference/C/dbclose.html" class="olink">DB-&gt;close()</a> or
+ <a href="../api_reference/C/dbsync.html" class="olink">DB-&gt;sync()</a> methods are called), the in-memory copy of the
+ database will be written back to the backing source
+ file.
+ </p>
+ <p>
+ The backing source file must already exist (but may be
+ zero-length) when <a href="../api_reference/C/dbopen.html" class="olink">DB-&gt;open()</a> is called. By default, the backing
+ source file is read lazily, that is, records are not read from
+ the backing source file until they are requested by the
+ application. If multiple processes (not threads) are accessing
+ a Recno database concurrently and either inserting or deleting
+ records, the backing source file must be read in its entirety
+ before more than a single process accesses the database, and
+ only that process should specify the backing source file as
+ part of the <a href="../api_reference/C/dbopen.html" class="olink">DB-&gt;open()</a> call. This can be accomplished by calling
+ the <a href="../api_reference/C/dbset_flags.html" class="olink">DB-&gt;set_flags()</a> method with the <a href="../api_reference/C/dbset_flags.html#dbset_flags_DB_SNAPSHOT" class="olink">DB_SNAPSHOT</a> flag.
+ </p>
+ <p>
+ Reading and writing the backing source file cannot be
+ transactionally protected because it involves filesystem
+ operations that are not part of the Berkeley DB transaction
+ methodology. For this reason, if a temporary database is used
+ to hold the records (a NULL was specified as the file argument
+ to <a href="../api_reference/C/dbopen.html" class="olink">DB-&gt;open()</a>), <span class="bold"><strong>it is possible to lose the
+ contents of the backing source file if the system crashes
+ at the right instant</strong></span>. If a permanent file is
+ used to hold the database (a filename was specified as the
+ file argument to <a href="../api_reference/C/dbopen.html" class="olink">DB-&gt;open()</a>), normal database recovery on that
+ file can be used to prevent information loss. It is still
+ possible that the contents of the backing source file itself
+ will be corrupted or lost if the system crashes.
+ </p>
+ <p>
+ For all of the above reasons, the backing source file is
+ generally used to specify databases that are read-only for
+ Berkeley DB applications, and that are either generated on the
+ fly by software tools, or modified using a different mechanism
+ such as a text editor.
+ </p>
</div>
<div class="sect2" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
- <h3 class="title"><a id="am_conf_renumber"></a>Logically renumbering records</h3>
+ <h3 class="title"><a id="am_conf_renumber"></a>Logically renumbering
+ records</h3>
</div>
</div>
</div>
- <p>Records stored in the Queue and Recno access methods are accessed by
-logical record number. In all cases in Btree databases, and optionally
-in Recno databases (see the <a href="../api_reference/C/dbset_flags.html" class="olink">DB-&gt;set_flags()</a> method and the
-<a href="../api_reference/C/dbset_flags.html#dbset_flags_DB_RENUMBER" class="olink">DB_RENUMBER</a> flag for more information), record numbers are
-mutable. This means that the record numbers may change as records are
-added to and deleted from the database. The deletion of record number
-4 causes any records numbered 5 and higher to be renumbered downward by
-1; the addition of a new record after record number 4 causes any
-records numbered 5 and higher to be renumbered upward by 1. In all
-cases in Queue databases, and by default in Recno databases, record
-numbers are not mutable, and the addition or deletion of records to the
-database will not cause already-existing record numbers to change. For
-this reason, new records cannot be inserted between already-existing
-records in databases with immutable record numbers.</p>
- <p>Cursors pointing into a Btree database or a Recno database with mutable
-record numbers maintain a reference to a specific record, rather than
-a record number, that is, the record they reference does not change as
-other records are added or deleted. For example, if a database contains
-three records with the record numbers 1, 2, and 3, and the data items
-"A", "B", and "C", respectively, the deletion of record number 2 ("B")
-will cause the record "C" to be renumbered downward to record number 2.
-A cursor positioned at record number 3 ("C") will be adjusted and
-continue to point to "C" after the deletion. Similarly, a cursor
-previously referring to the now deleted record number 2 will be
-positioned between the new record numbers 1 and 2, and an insertion
-using that cursor will appear between those records. In this manner
-records can be added and deleted to a database without disrupting the
-sequential traversal of the database by a cursor.</p>
- <p>Only cursors created using a single <a href="../api_reference/C/db.html" class="olink">DB</a> handle can adjust each
-other's position in this way, however. If multiple <a href="../api_reference/C/db.html" class="olink">DB</a> handles
-have a renumbering Recno database open simultaneously (as when multiple
-processes share a single database environment), a record referred to by
-one cursor could change underfoot if a cursor created using another
-<a href="../api_reference/C/db.html" class="olink">DB</a> handle inserts or deletes records into the database. For
-this reason, applications using Recno databases with mutable record
-numbers will usually make all accesses to the database using a single
-<a href="../api_reference/C/db.html" class="olink">DB</a> handle and cursors created from that handle, or will
-otherwise single-thread access to the database, for example, by using
-the Berkeley DB Concurrent Data Store product.</p>
- <p>In any Queue or Recno databases, creating new records will cause the
-creation of multiple records if the record number being created is more
-than one greater than the largest record currently in the database. For
-example, creating record number 28, when record 25 was previously the
-last record in the database, will implicitly create records 26 and 27
-as well as 28. All first, last, next and previous cursor operations
-will automatically skip over these implicitly created records. So, if
-record number 5 is the only record the application has created,
-implicitly creating records 1 through 4, the <a href="../api_reference/C/dbcget.html" class="olink">DBC-&gt;get()</a> method with the
-<a href="../api_reference/C/dbcget.html#dbcget_DB_FIRST" class="olink">DB_FIRST</a> flag will return record number 5, not record number 1.
-Attempts to explicitly retrieve implicitly created records by their
-record number will result in a special error return,
-<a class="link" href="program_errorret.html#program_errorret.DB_KEYEMPTY">DB_KEYEMPTY</a>.</p>
- <p>In any Berkeley DB database, attempting to retrieve a deleted record, using
-a cursor positioned on the record, results in a special error return,
-<a class="link" href="program_errorret.html#program_errorret.DB_KEYEMPTY">DB_KEYEMPTY</a>. In addition, when using Queue databases or Recno
-databases with immutable record numbers, attempting to retrieve a deleted
-record by its record number will also result in the <a class="link" href="program_errorret.html#program_errorret.DB_KEYEMPTY">DB_KEYEMPTY</a>
-return.</p>
+ <p>
+ Records stored in the Queue and Recno access methods are
+ accessed by logical record number. In all cases in Btree
+ databases, and optionally in Recno databases (see the
+ <a href="../api_reference/C/dbset_flags.html" class="olink">DB-&gt;set_flags()</a> method and the <a href="../api_reference/C/dbset_flags.html#dbset_flags_DB_RENUMBER" class="olink">DB_RENUMBER</a> flag for more
+ information), record numbers are mutable. This means that the
+ record numbers may change as records are added to and deleted
+ from the database. The deletion of record number 4 causes any
+ records numbered 5 and higher to be renumbered downward by 1;
+ the addition of a new record after record number 4 causes any
+ records numbered 5 and higher to be renumbered upward by 1. In
+ all cases in Queue databases, and by default in Recno
+ databases, record numbers are not mutable, and the addition or
+ deletion of records to the database will not cause
+ already-existing record numbers to change. For this reason,
+ new records cannot be inserted between already-existing
+ records in databases with immutable record numbers.
+ </p>
+ <p>
+ Cursors pointing into a Btree database or a Recno database
+ with mutable record numbers maintain a reference to a specific
+ record, rather than a record number, that is, the record they
+ reference does not change as other records are added or
+ deleted. For example, if a database contains three records
+ with the record numbers 1, 2, and 3, and the data items "A",
+ "B", and "C", respectively, the deletion of record number 2
+ ("B") will cause the record "C" to be renumbered downward to
+ record number 2. A cursor positioned at record number 3 ("C")
+ will be adjusted and continue to point to "C" after the
+ deletion. Similarly, a cursor previously referring to the now
+ deleted record number 2 will be positioned between the new
+ record numbers 1 and 2, and an insertion using that cursor
+ will appear between those records. In this manner records can
+ be added and deleted to a database without disrupting the
+ sequential traversal of the database by a cursor.
+ </p>
+ <p>
+ Only cursors created using a single <a href="../api_reference/C/db.html" class="olink">DB</a> handle can adjust
+ each other's position in this way, however. If multiple <a href="../api_reference/C/db.html" class="olink">DB</a>
+ handles have a renumbering Recno database open simultaneously
+ (as when multiple processes share a single database
+ environment), a record referred to by one cursor could change
+ underfoot if a cursor created using another <a href="../api_reference/C/db.html" class="olink">DB</a> handle
+ inserts or deletes records into the database. For this reason,
+ applications using Recno databases with mutable record numbers
+ will usually make all accesses to the database using a single
+ <a href="../api_reference/C/db.html" class="olink">DB</a> handle and cursors created from that handle, or will
+ otherwise single-thread access to the database, for example,
+ by using the Berkeley DB Concurrent Data Store product.
+ </p>
+ <p>
+ In any Queue or Recno databases, creating new records will
+ cause the creation of multiple records if the record number
+ being created is more than one greater than the largest record
+ currently in the database. For example, creating record number
+ 28, when record 25 was previously the last record in the
+ database, will implicitly create records 26 and 27 as well as
+ 28. All first, last, next and previous cursor operations will
+ automatically skip over these implicitly created records. So,
+ if record number 5 is the only record the application has
+ created, implicitly creating records 1 through 4, the <a href="../api_reference/C/dbcget.html" class="olink">DBC-&gt;get()</a>
+ method with the <a href="../api_reference/C/dbcget.html#dbcget_DB_FIRST" class="olink">DB_FIRST</a> flag will return record number 5,
+ not record number 1. Attempts to explicitly retrieve
+ implicitly created records by their record number will result
+ in a special error return, <a class="link" href="program_errorret.html#program_errorret.DB_KEYEMPTY">DB_KEYEMPTY</a>.
+ </p>
+ <p>
+ In any Berkeley DB database, attempting to retrieve a
+ deleted record, using a cursor positioned on the record,
+ results in a special error return, <a class="link" href="program_errorret.html#program_errorret.DB_KEYEMPTY">DB_KEYEMPTY</a>.
+ In addition, when using Queue databases or Recno databases
+ with immutable record numbers, attempting to retrieve a
+ deleted record by its record number will also result in the
+ <a class="link" href="program_errorret.html#program_errorret.DB_KEYEMPTY">DB_KEYEMPTY</a> return.
+ </p>
</div>
</div>
<div class="navfooter">
@@ -314,13 +381,12 @@ return.</p>
<td width="40%" align="right"> <a accesskey="n" href="am.html">Next</a></td>
</tr>
<tr>
- <td width="40%" align="left" valign="top">Heap access method specific configuration </td>
+ <td width="40%" align="left" valign="top">Heap access method specific
+ configuration </td>
<td width="20%" align="center">
<a accesskey="h" href="index.html">Home</a>
</td>
- <td width="40%" align="right" valign="top"> Chapter 3. 
- Access Method Operations
- </td>
+ <td width="40%" align="right" valign="top"> Chapter 3.  Access Method Operations </td>
</tr>
</table>
</div>