<!--"$Id: 2.3.html,v 1.4 2007/05/17 18:17:18 bostic Exp $ (Sleepycat) $Date: 2007/05/17 18:17:18 $"--> <html> <head> <title>The Berkeley DB Package: Interface Changes introduced in DB 2.3.0</title> <meta name="description" content="DB: A database programmatic toolkit."> <meta name="keywords" content="embedded,database,programmatic,toolkit,b+tree,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods"> </head> <body bgcolor=white> <h3 align=center>Interface Changes introduced in DB 2.3.0:</h3> <ol> <li> The DB 2.3 btree access method has been enhanced to optionally support retrieval by record number. This functionality is based on a new DB_INFO flag, DB_RECNUM. If the btree is created using this flag, applications may retrieve records in the tree by record number, using the DB_SET_RECNO flag to either the dbp->get() or cursor->c_get() interfaces. This is another additional cursor->c_get() flag, DB_GET_RECNO which returns the record number of the record referenced by the cursor. <p> <font color=red> Adding this feature required a change to the underlying btree database format. For this reason, databases created under previous versions of DB cannot be read by this release of DB, and vice versa. </font> If you have a support contract with Sleepycat Software, please contact us for further information and assistance in migrating applications and databases from previous releases of DB to this release. <p> See db_open(3) and db_cursor(3) for more information, as well as the example program examples/ex_btrec.c. <p><li> In previous versions of the DB library, additions or deletions into recno (fixed and variable-length record) databases would automatically renumber all records logically after the add/delete point. This behavior is no longer the default behavior as of DB version 2.3. <p> The new default behavior is that deleting records does not cause subsequent records to be renumbered, and it is an error to attempt to add new records between records already in the database. Attempting to retrieve deleted keys using either of the dbp->get() or cursor->c_get() functions will return DB_KEYEMPTY. The historic behavior is still available, based on a new DB_INFO flag, DB_RENUMBER. Applications depending on the historic recno access method semantics should specify the DB_RENUMBER flag, no other change should be necessary. <p> In previous versions of the DB library, adding a record more than one logical record past the current last record in the recno database caused the creation of the intermediate missing records as existing records with zero-length data. While the intermediate missing records are still logically created in DB 2.3, it is an error to attempt to retrieve them, and the get() and c_get() functions will return DB_KEYEMPTY. <p> In previous versions of the DB library, attempting to retrieve a deleted record <b>using the same cursor with which it was deleted</b> returned DB_NOTFOUND. For consistency with the new recno access method functionality, such attempts now return DB_KEYEMPTY. <p> See db_open(3) and db_cursor(3) for more information. <br><font color=red> These changes are NOT transparent to applications. </font> <p><li> A new flag, DB_APPEND, has been added to the db->put(3) function in DB 2.3. This flag is applicable only to the recno access method. It permits applications to append to the database without knowing how many records are in it or the current last record number. The DB example program examples/ex_tpcb has been modified to use this functionality. <p> See db_open(3) for more information. <p><li> An additional argument has been added to the memp_fopen(3) function in DB 2.3. The mpool functions must be able to uniquely identify files in order that multiple processes sharing a file will correctly share its underlying pages. Normally, the mpool functions use the file's device and inode numbers for this purpose. On some filesystems, for example, FAT or NFS, file device and inode numbers are not necessarily unique across system reboots. To support applications wanting to maintain a shared memory buffer pool across system reboots, where the pool contains pages from files stored on such filesystems, it is now possible to specify a unique file identifier to the memp_fopen() call, which the memory pool functions will then use to identify shared files. The DB access method functions have been modified to use this functionality, and DB databases in 2.3 will work transparently on such filesystems. <p> See db_mpool(3) for more information. <br><font color=red> This change is NOT transparent to applications using the db_mpool(3) interfaces directly. </font> <p><li> The interface to the DB access method stat function (dbp->stat()) has been changed. Per-thread statistics are no longer returned, only statistics for the entire database are returned. In addition, the stat function has been changed to take an additional ``flags'' parameter. The only legal value for this parameter in DB 2.3 is DB_RECORDCOUNT, which causes the stat function to return a count of records in the tree without collecting other statistics. <p> A number of additional items of information have been added to the information returned by the stat function, notably database configuration flags and other information normally specified to the db_open(3) function when the database is created. <p> See db_stat(1) and db_open(3) for more information. <br><font color=red> This change is NOT transparent to applications. </font> <p><li> A number of new configuration options have been added to the db_load(1) utility, allowing databases to be dumped and reloaded in different configurations. See db_load(1) for more information. <p><li> The C++ API for DB has been reworked, and is now believed to be fairly close to its final form. There are still no manual pages for the C++ API, although we expect to have them together and released within a couple of weeks. <p> The C++ files and directories in the source distribution are: <p> <table border> <tr> <td>db/cxx/</td> <td>C++ API</td> </tr><tr> <td>db/examples_cxx/</td> <td>The example programs recoded in C++.</td> </tr><tr> <td>db/include/cxx_int.h</td> <td>Internal C++ include file.</td> </tr><tr> <td>db/include/db_cxx.h</td> <td>External C++ include file.</td> </tr> </table> <p> C++ support is automatically built on Win32. To configure it under UNIX, specify <b>--enable-cxx</b> as a configuration argument (see the file <b>db/build.unix/README</b> for more information). </ol> </body> </html>