.I<Berkeley DB Reference Guide: Programmer Notes[P6

Berkeley DB Reference Guide: Programmer Notes



;

Integrating version 1.85 applications



SIt is not difficult to upgrade Berkeley DB 1.85 applications to use the Berkeley DBLversion 2 library. The Berkeley DB version 2 library has a Berkeley DB 1.85@compatibility mode, which you can use by either recompiling yourFapplication's source code or by relinking its object files against theversion 2 library.

? The underlying databases must be converted, however, as theMBerkeley DB version 2 library has a different underlying database format.

System Integration


    

  1. NIt is possible to maintain both the Berkeley DB 1.85 and Berkeley DB version 2@libraries on your system. However, the db.h include fileHthat was distributed with Berkeley DB 1.85 is not compatible withHthe db.h file distributed with Berkeley DB version 2, so you willChave to install them in different locations. In addition, both theNBerkeley DB 1.85 and Berkeley DB version 2 libraries are named libdb.a.

    JAs the Berkeley DB 1.85 library did not have an installation target in theFMakefile, there's no way to know exactly where it was installed on theGsystem. In addition, many vendors included it in the C library insteadGof as a separate library, and so it may actually be part of libcIand the db.h include file may be installed in /usr/include.

    DFor these reasons, the simplest way to maintain both libraries is toKinstall Berkeley DB version 2 in a completely separate area of your system.KThe Berkeley DB version 2 installation process allows you to install into a7standalone directory hierarchy on your system. See theMBuilding for UNIX platforms documentationOfor more information and instructions on how to install the Berkeley DB versionC2 library, include files and documentation into specific locations.

  2. OAlternatively, you can replace Berkeley DB 1.85 on your system with Berkeley DBMversion 2. In this case, you'll probably want to install Berkeley DB versionF2 in the normal place on your system, wherever that may be, and delete?the Berkeley DB 1.85 include files, manual pages and libraries.

    ATo replace 1.85 with version 2, you must either convert your 1.85Papplications to use the version 2 API or build the Berkeley DB version 2 libraryMto include Berkeley DB 1.85 interface compatibility code. Whether convertingJyour applications to use the version 2 interface or using the version 1.85Acompatibility API, you will need to recompile or relink your 1.85Gapplications, and you must convert any persistent application databases.to the Berkeley DB version 2 database formats.

    NThere is no requirement that you recompile your Berkeley DB 1.85 applications,Kas you can simply link their object files against the Berkeley DB version 2library.

    MIf you want to recompile your Berkeley DB 1.85 applications, you will have to:change them to include the file db_185.h instead ofBdb.h. (The db_185.h file is automatically installedOduring the Berkeley DB version 2 installation process.) You can then recompileIthe applications, linking them against the Berkeley DB version 2 library.

    NFor more information on compiling the Berkeley DB 1.85 compatibility code intoOthe Berkeley DB version 2 library, see Buildingfor UNIX platforms.

    NFor more information on converting databases from the Berkeley DB 1.85 formatseto the Berkeley DB version 2 formats, see the db_dump185 and?db_load documentation.

  3. JFinally, although we certainly do not recommend it, it is possible to loadUboth Berkeley DB 1.85 and Berkeley DB version 2 into the same library. Similarly, itRis possible to use both Berkeley DB 1.85 and Berkeley DB version 2 within a singleHapplication, although it's not possible to use them from within the samefile.

    NThe name space in Berkeley DB version 2 has been changed from that of previousKBerkeley DB versions, notably version 1.85, for portability and consistencyJreasons. The only name collisions in the two libraries are the names usedıby the historic dbm, ndbm and hsearch interfaces,Nand the Berkeley DB 1.85 compatibility interfaces in the Berkeley DB version 2library.

    PIf you are loading both Berkeley DB 1.85 and Berkeley DB version 2 into a singleClibrary, remove the historic interfaces from one of the two libraryTbuilds, and configure the Berkeley DB version 2 build to not include the Berkeley DBI1.85 compatibility API, otherwise you could have collisions and undefined@behavior. This can be done by editing the library Makefiles andNreconfiguring and rebuilding the Berkeley DB version 2 library. Obviously, ifHyou use the historic interfaces, you will get the version in the libraryEfrom which you did not remove it. Similarly, you will not be able toVaccess Berkeley DB version 2 files using the Berkeley DB 1.85 compatibility interface,5since you have removed that from the library as well.

Converting Applications

VMapping the Berkeley DB 1.85 functionality into Berkeley DB version 2 is almost alwaysfa simple, one-to-one mapping. The manual page db_open replacesDthe Berkeley DB 1.85 manual pages dbopen(3), btree(3),Bhash(3) and recno(3). You should be able to convertMeach 1.85 function call into a Berkeley DB version 2 function call using justAthe db_open documentation.

,Some guidelines and things to watch out for:

    

  1. NMost access method functions have exactly the same semantics as in Berkeley DBI1.85, although the arguments to the functions have changed in some cases.ATo get your code to compile, the most common change is to add theKtransaction ID as an argument (NULL, since Berkeley DB 1.85 did not supporttransactions).

  2. CYou must always initialize DBT structures to zero before using themJwith any Berkeley DB version 2 function. (They do not normally have to beHreinitialized each time, only when they are first allocated. Do this byCdeclaring the DBT structure external or static, or by calling the C4library routine bzero(3) or memset(3).

  3. OThe error returns are completely different in the two versions. In Berkeley DBV1.85, < 0 meant an error, and > 0 meant a minor Berkeley DB exception. In Berkeley DBC2.0, > 0 means an error (the Berkeley DB version 2 functions returnBerrno on error) and < 0 means a Berkeley DB exception. SeeOError Returns to Applications formore information.

  4. JThe Berkeley DB 1.85 seq() function has been replaced by cursors inMBerkeley DB version 2. The semantics are approximately the same, but cursorsIrequire the creation of an extra object (the DBC * object), which is thenused to access the database.

    ISpecifically, the partial key match and range search functionality of the:R_CURSOR flag in db->seq() has been replaced by the€DB_SET_RANGE flag in DBcursor->c_get.

  5. JIn version 2 of the Berkeley DB library, additions or deletions into RecnoD(fixed and variable-length record) databases no longer automaticallyFlogically renumber all records after the add/delete point, by default.GThe default behavior is that deleting records does not cause subsequenteJrecords to be renumbered, and it is an error to attempt to add new recordsBbetween records already in the database. Applications wanting the9historic recno access method semantics should specify the aDB_RENUMBER flag in the DB_INFO structure.h

  6. NOpening a database in Berkeley DB version 2 is a much heavier-weight operationOthan it was in Berkeley DB 1.85. Therefore, if your historic applications were Ewritten to open a database, perform a single operation, and close theoGdatabase, you may observe performance degradation. In most cases, thisoIis due to the expense of creating the environment upon each open. WhilerGwe encourage restructuring your application to avoid repeated opens andhGcloses, you can probably recover most of the lost performance by simplym2using a persistent environment across invocations.
i

sPWhile simply converting Berkeley DB 1.85 function calls to Berkeley DB version 2Jfunction calls will work, we recommend that you eventually reconsider yourKapplication's interface to the Berkeley DB database library in light of therNadditional functionality supplied by Berkeley DB version 2, as it is likely to+result in enhanced application performance.y

Converting Databases

nLFor information on converting application databases from Berkeley DB 1.85 toBerkeley DB 2.0, see the db_dump185 and db_load documentation.

iQlA Nib ˙˙Kinstall Berkeley DB version 2 in a completely separate area of your system.KThe Berkeley DB version 2 installation process allows you to install into a7standalone directory hierarchy on your system. See theMBuilding for UNIX platforms documentationOfor more information and instructions on how to install the Berkeley DB versionC2 library, include files and documentation into specific locations.

  • OAlternatively, you can replace Berkeley DB