1<!--"$Id: 2.3.html,v 1.4 2007/05/17 18:17:18 bostic Exp $ (Sleepycat) $Date: 2007/05/17 18:17:18 $"--> 2<html> 3<head> 4<title>The Berkeley DB Package: Interface Changes introduced in DB 2.3.0</title> 5<meta name="description" content="DB: A database programmatic toolkit."> 6<meta name="keywords" content="embedded,database,programmatic,toolkit,b+tree,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods"> 7</head> 8<body bgcolor=white> 9 10<h3 align=center>Interface Changes introduced in DB 2.3.0:</h3> 11 12<ol> 13 14<li> 15The DB 2.3 btree access method has been enhanced to optionally support 16retrieval by record number. 17This functionality is based on a new DB_INFO flag, DB_RECNUM. 18If the btree is created using this flag, applications may retrieve 19records in the tree by record number, 20using the DB_SET_RECNO flag to either the dbp->get() or cursor->c_get() 21interfaces. 22This is another additional cursor->c_get() flag, DB_GET_RECNO which 23returns the record number of the record referenced by the cursor. 24<p> 25<font color=red> 26Adding this feature required a change to the underlying btree database format. 27For this reason, databases created under previous versions of DB cannot 28be read by this release of DB, and vice versa. 29</font> 30If you have a support contract with Sleepycat Software, please contact 31us for further information and assistance in migrating applications and 32databases from previous releases of DB to this release. 33<p> 34See 35db_open(3) 36and 37db_cursor(3) 38for more information, as well as the example program examples/ex_btrec.c. 39 40<p><li> 41In previous versions of the DB library, additions or deletions into recno 42(fixed and variable-length record) databases would automatically renumber 43all records logically after the add/delete point. 44This behavior is no longer the default behavior as of DB version 2.3. 45<p> 46The new default behavior is that deleting records does not cause subsequent 47records to be renumbered, and it is an error to attempt to add new records 48between records already in the database. 49Attempting to retrieve deleted keys using either of the dbp->get() or 50cursor->c_get() functions will return DB_KEYEMPTY. 51The historic behavior is still available, based on a new DB_INFO flag, 52DB_RENUMBER. 53Applications depending on the historic recno access method semantics should 54specify the DB_RENUMBER flag, no other change should be necessary. 55<p> 56In previous versions of the DB library, adding a record more than one 57logical record past the current last record in the recno database caused 58the creation of the intermediate missing records as existing records with 59zero-length data. 60While the intermediate missing records are still logically created in 61DB 2.3, it is an error to attempt to retrieve them, and the get() and 62c_get() functions will return DB_KEYEMPTY. 63<p> 64In previous versions of the DB library, attempting to retrieve a deleted 65record <b>using the same cursor with which it was deleted</b> returned 66DB_NOTFOUND. 67For consistency with the new recno access method functionality, 68such attempts now return DB_KEYEMPTY. 69<p> 70See 71db_open(3) 72and 73db_cursor(3) 74for more information. 75<br><font color=red> 76These changes are NOT transparent to applications. 77</font> 78 79<p><li> 80A new flag, DB_APPEND, has been added to the db->put(3) function in 81DB 2.3. 82This flag is applicable only to the recno access method. 83It permits applications to append to the database without knowing how 84many records are in it or the current last record number. 85The DB example program examples/ex_tpcb has been modified to use this 86functionality. 87<p> 88See 89db_open(3) 90for more information. 91 92<p><li> 93An additional argument has been added to the memp_fopen(3) function 94in DB 2.3. 95The mpool functions must be able to uniquely identify files in order 96that multiple processes sharing a file will correctly share its 97underlying pages. Normally, the mpool functions use the file's device 98and inode numbers for this purpose. On some filesystems, for example, 99FAT or NFS, file device and 100inode numbers are not necessarily unique across system reboots. 101To support applications wanting to maintain a shared memory buffer pool 102across system reboots, where the pool contains pages from files stored 103on such filesystems, it is now possible to specify a unique file identifier 104to the memp_fopen() call, which the memory pool functions will then use to 105identify shared files. 106The DB access method functions have been modified to use this functionality, 107and DB databases in 2.3 will work transparently on such filesystems. 108<p> 109See 110db_mpool(3) 111for more information. 112<br><font color=red> 113This change is NOT transparent to applications using the db_mpool(3) 114interfaces directly. 115</font> 116 117<p><li> 118The interface to the DB access method stat function (dbp->stat()) has been 119changed. 120Per-thread statistics are no longer returned, only statistics for the entire 121database are returned. 122In addition, the stat function has been changed to take an additional 123``flags'' parameter. 124The only legal value for this parameter in DB 2.3 is DB_RECORDCOUNT, 125which causes the stat function to return a count of records in the tree 126without collecting other statistics. 127<p> 128A number of additional items of information have been added to the 129information returned by the stat function, 130notably database configuration flags and other information normally 131specified to the 132db_open(3) 133function when the database is created. 134<p> 135See 136db_stat(1) 137and 138db_open(3) 139for more information. 140<br><font color=red> 141This change is NOT transparent to applications. 142</font> 143 144<p><li> 145A number of new configuration options have been added to the 146db_load(1) 147utility, allowing databases to be dumped and reloaded in different 148configurations. 149See 150db_load(1) 151for more information. 152 153<p><li> 154The C++ API for DB has been reworked, and is now believed to be fairly 155close to its final form. 156There are still no manual pages for the C++ API, although we expect to 157have them together and released within a couple of weeks. 158<p> 159The C++ files and directories in the source distribution are: 160<p> 161<table border> 162<tr> 163<td>db/cxx/</td> 164<td>C++ API</td> 165</tr><tr> 166<td>db/examples_cxx/</td> 167<td>The example programs recoded in C++.</td> 168</tr><tr> 169<td>db/include/cxx_int.h</td> 170<td>Internal C++ include file.</td> 171</tr><tr> 172<td>db/include/db_cxx.h</td> 173<td>External C++ include file.</td> 174</tr> 175</table> 176<p> 177C++ support is automatically built on Win32. To configure it under UNIX, 178specify <b>--enable-cxx</b> as a configuration argument (see the file 179<b>db/build.unix/README</b> for more information). 180 181</ol> 182 183</body> 184</html> 185