1<!--$Id: renumber.so,v 10.26 2003/10/18 19:15:55 bostic Exp $--> 2<!--Copyright (c) 1997,2008 Oracle. All rights reserved.--> 3<!--See the file LICENSE for redistribution information.--> 4<html> 5<head> 6<title>Berkeley DB Reference Guide: Logically renumbering records</title> 7<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit."> 8<meta name="keywords" content="embedded,database,programmatic,toolkit,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,Java,C,C++"> 9</head> 10<body bgcolor=white> 11<a name="2"><!--meow--></a> 12<table width="100%"><tr valign=top> 13<td><b><dl><dt>Berkeley DB Reference Guide:<dd>Access Methods</dl></b></td> 14<td align=right><a href="../am_conf/re_source.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../am/ops.html"><img src="../../images/next.gif" alt="Next"></a> 15</td></tr></table> 16<p align=center><b>Logically renumbering records</b></p> 17<p>Records stored in the Queue and Recno access methods are accessed by 18logical record number. In all cases in Btree databases, and optionally 19in Recno databases (see the <a href="../../api_c/db_set_flags.html">DB->set_flags</a> method and the 20<a href="../../api_c/db_set_flags.html#DB_RENUMBER">DB_RENUMBER</a> flag for more information), record numbers are 21mutable. This means that the record numbers may change as records are 22added to and deleted from the database. The deletion of record number 234 causes any records numbered 5 and higher to be renumbered downward by 241; the addition of a new record after record number 4 causes any 25records numbered 5 and higher to be renumbered upward by 1. In all 26cases in Queue databases, and by default in Recno databases, record 27numbers are not mutable, and the addition or deletion of records to the 28database will not cause already-existing record numbers to change. For 29this reason, new records cannot be inserted between already-existing 30records in databases with immutable record numbers.</p> 31<p>Cursors pointing into a Btree database or a Recno database with mutable 32record numbers maintain a reference to a specific record, rather than 33a record number, that is, the record they reference does not change as 34other records are added or deleted. For example, if a database contains 35three records with the record numbers 1, 2, and 3, and the data items 36"A", "B", and "C", respectively, the deletion of record number 2 ("B") 37will cause the record "C" to be renumbered downward to record number 2. 38A cursor positioned at record number 3 ("C") will be adjusted and 39continue to point to "C" after the deletion. Similarly, a cursor 40previously referring to the now deleted record number 2 will be 41positioned between the new record numbers 1 and 2, and an insertion 42using that cursor will appear between those records. In this manner 43records can be added and deleted to a database without disrupting the 44sequential traversal of the database by a cursor.</p> 45<p>Only cursors created using a single <a href="../../api_c/db_class.html">DB</a> handle can adjust each 46other's position in this way, however. If multiple <a href="../../api_c/db_class.html">DB</a> handles 47have a renumbering Recno database open simultaneously (as when multiple 48processes share a single database environment), a record referred to by 49one cursor could change underfoot if a cursor created using another 50<a href="../../api_c/db_class.html">DB</a> handle inserts or deletes records into the database. For 51this reason, applications using Recno databases with mutable record 52numbers will usually make all accesses to the database using a single 53<a href="../../api_c/db_class.html">DB</a> handle and cursors created from that handle, or will 54otherwise single-thread access to the database, for example, by using 55the Berkeley DB Concurrent Data Store product.</p> 56<p>In any Queue or Recno databases, creating new records will cause the 57creation of multiple records if the record number being created is more 58than one greater than the largest record currently in the database. For 59example, creating record number 28, when record 25 was previously the 60last record in the database, will implicitly create records 26 and 27 61as well as 28. All first, last, next and previous cursor operations 62will automatically skip over these implicitly created records. So, if 63record number 5 is the only record the application has created, 64implicitly creating records 1 through 4, the <a href="../../api_c/dbc_get.html">DBcursor->get</a> method with the 65<a href="../../api_c/dbc_get.html#DB_FIRST">DB_FIRST</a> flag will return record number 5, not record number 1. 66Attempts to explicitly retrieve implicitly created records by their 67record number will result in a special error return, 68<a href="../../ref/program/errorret.html#DB_KEYEMPTY">DB_KEYEMPTY</a>.</p> 69<p>In any Berkeley DB database, attempting to retrieve a deleted record, using 70a cursor positioned on the record, results in a special error return, 71<a href="../../ref/program/errorret.html#DB_KEYEMPTY">DB_KEYEMPTY</a>. In addition, when using Queue databases or Recno 72databases with immutable record numbers, attempting to retrieve a deleted 73record by its record number will also result in the <a href="../../ref/program/errorret.html#DB_KEYEMPTY">DB_KEYEMPTY</a> 74return.</p> 75<table width="100%"><tr><td><br></td><td align=right><a href="../am_conf/re_source.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../am/ops.html"><img src="../../images/next.gif" alt="Next"></a> 76</td></tr></table> 77<p><font size=1>Copyright (c) 1996,2008 Oracle. All rights reserved.</font> 78</body> 79</html> 80
