1<!--$Id: convert.so,v 11.6 2000/03/18 21:43:19 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: Release 2.0: converting applications</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<table width="100%"><tr valign=top> 12<td><b><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></b></td> 13<td align=right><a href="../upgrade.2.0/system.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../upgrade.2.0/disk.html"><img src="../../images/next.gif" alt="Next"></a> 14</td></tr></table> 15<p align=center><b>Release 2.0: converting applications</b></p> 16<p>Mapping the Berkeley DB 1.85 functionality into Berkeley DB version 2 is almost always 17simple. The manual page <a href="../../api_c/db_open.html">DB->open</a> replaces the Berkeley DB 1.85 manual 18pages <b>dbopen</b>(3), <b>btree</b>(3), <b>hash</b>(3) and 19<b>recno</b>(3). You should be able to convert each 1.85 function 20call into a Berkeley DB version 2 function call using just the <a href="../../api_c/db_open.html">DB->open</a> 21documentation.</p> 22<p>Some guidelines and things to watch out for:</p> 23<ol> 24<p><li>Most access method functions have exactly the same semantics as in Berkeley DB 251.85, although the arguments to the functions have changed in some cases. 26To get your code to compile, the most common change is to add the 27transaction ID as an argument (NULL, since Berkeley DB 1.85 did not support 28transactions.) 29<p><li>You must always initialize DBT structures to zero before using them with 30any Berkeley DB version 2 function. (They do not normally have to be 31reinitialized each time, only when they are first allocated. Do this by 32declaring the DBT structure external or static, or by calling the C 33library routine <b>bzero</b>(3) or <b>memset</b>(3).) 34<p><li>The error returns are completely different in the two versions. In Berkeley DB 351.85, < 0 meant an error, and > 0 meant a minor Berkeley DB exception. 36In Berkeley DB 2.0, > 0 means an error (the Berkeley DB version 2 functions 37return <b>errno</b> on error) and < 0 means a Berkeley DB exception. 38See <a href="../../ref/program/errorret.html">Error Returns to Applications</a> 39for more information. 40<p><li>The Berkeley DB 1.85 DB->seq function has been replaced by cursors in Berkeley DB 41version 2. The semantics are approximately the same, but cursors require 42the creation of an extra object (the DBC object), which is then used to 43access the database. 44<p>Specifically, the partial key match and range search functionality of the 45R_CURSOR flag in DB->seq has been replaced by the 46<a href="../../api_c/dbc_get.html#DB_SET_RANGE">DB_SET_RANGE</a> flag in <a href="../../api_c/dbc_get.html">DBcursor->get</a>.</p> 47<p><li>In version 2 of the Berkeley DB library, additions or deletions into Recno 48(fixed and variable-length record) databases no longer automatically 49logically renumber all records after the add/delete point, by default. 50The default behavior is that deleting records does not cause subsequent 51records to be renumbered, and it is an error to attempt to add new records 52between records already in the database. Applications wanting the 53historic Recno access method semantics should call the 54<a href="../../api_c/db_set_flags.html">DB->set_flags</a> method with the <a href="../../api_c/db_set_flags.html#DB_RENUMBER">DB_RENUMBER</a> flag. 55<p><li>Opening a database in Berkeley DB version 2 is a much heavier-weight operation 56than it was in Berkeley DB 1.85. Therefore, if your historic applications were 57written to open a database, perform a single operation, and close the 58database, you may observe performance degradation. In most cases, this 59is due to the expense of creating the environment upon each open. While 60we encourage restructuring your application to avoid repeated opens and 61closes, you can probably recover most of the lost performance by simply 62using a persistent environment across invocations. 63</ol> 64<p>While simply converting Berkeley DB 1.85 function calls to Berkeley DB version 2 65function calls will work, we recommend that you eventually reconsider your 66application's interface to the Berkeley DB database library in light of the 67additional functionality supplied by Berkeley DB version 2, as it is likely to 68result in enhanced application performance.</p> 69<table width="100%"><tr><td><br></td><td align=right><a href="../upgrade.2.0/system.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../upgrade.2.0/disk.html"><img src="../../images/next.gif" alt="Next"></a> 70</td></tr></table> 71<p><font size=1>Copyright (c) 1996,2008 Oracle. All rights reserved.</font> 72</body> 73</html> 74
