1<!--$Id: envopen.so,v 11.14 2003/10/18 19:16:12 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 3.0: environment open/close/unlink</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.3.0/intro.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../upgrade.3.0/func.html"><img src="../../images/next.gif" alt="Next"></a> 14</td></tr></table> 15<p align=center><b>Release 3.0: environment open/close/unlink</b></p> 16<p>The hardest part of upgrading your application from a 2.X code base to 17the 3.0 release is translating the Berkeley DB environment open, close and 18remove calls.</p> 19<p>There were two logical changes in this part of the Berkeley DB interface. 20First, in Berkeley DB 3.0, there are no longer separate structures that 21represent each subsystem (for example, DB_LOCKTAB or DB_TXNMGR) and an 22overall <a href="../../api_c/env_class.html">DB_ENV</a> environment structure. Instead there is only the 23<a href="../../api_c/env_class.html">DB_ENV</a> structure. This means that <a href="../../api_c/env_class.html">DB_ENV</a> references 24should be passed around by your application instead of passing around 25DB_LOCKTAB or DB_TXNMGR references. This is likely to be a simple 26change for most applications as few applications use the lock_XXX, 27log_XXX, memp_XXX or txn_XXX interfaces to create Berkeley DB environments.</p> 28<p>The second change is that there are no longer separate open, close, and 29unlink interfaces to the Berkeley DB subsystems. For example, in previous 30releases, it was possible to open a lock subsystem either using 31db_appinit or using the lock_open call. In the 3.0 release the XXX_open 32interfaces to the subsystems have been removed, and subsystems must now 33be opened using the 3.0 replacement for the db_appinit call.</p> 34<p>To upgrade your application, first find each place your application opens, 35closes and/or removes a Berkeley DB environment. This will be code of the form:</p> 36<blockquote><pre>db_appinit, db_appexit 37lock_open, lock_close, lock_unlink 38log_open, log_close, log_unlink 39memp_open, memp_close, memp_unlink 40txn_open, txn_close, txn_unlink</pre></blockquote> 41<p>Each of these groups of calls should be replaced with calls to:</p> 42<blockquote><pre><a href="../../api_c/env_class.html">db_env_create</a>, <a href="../../api_c/env_open.html">DB_ENV->open</a>, <a href="../../api_c/env_close.html">DB_ENV->close</a>, 43<a href="../../api_c/env_remove.html">DB_ENV->remove</a></pre></blockquote> 44<p>The <a href="../../api_c/env_class.html">db_env_create</a> call and the call to the <a href="../../api_c/env_open.html">DB_ENV->open</a> 45method replace the db_appinit, lock_open, log_open, memp_open and txn_open 46calls. The <a href="../../api_c/env_close.html">DB_ENV->close</a> method replaces the db_appexit, 47lock_close, log_close, memp_close and txn_close calls. The 48<a href="../../api_c/env_remove.html">DB_ENV->remove</a> call replaces the lock_unlink, log_unlink, 49memp_unlink and txn_unlink calls.</p> 50<p>Here's an example creating a Berkeley DB environment using the 2.X interface:</p> 51<blockquote><pre>/* 52 * db_init -- 53 * Initialize the environment. 54 */ 55DB_ENV * 56db_init(home) 57 char *home; 58{ 59 DB_ENV *dbenv; 60<p> 61 if ((dbenv = (DB_ENV *)calloc(sizeof(DB_ENV), 1)) == NULL) 62 return (errno); 63<p> 64 if ((errno = db_appinit(home, NULL, dbenv, 65 DB_INIT_LOCK | DB_INIT_LOG | DB_INIT_MPOOL | DB_INIT_TXN | 66 DB_USE_ENVIRON)) == 0) 67 return (dbenv); 68<p> 69 free(dbenv); 70 return (NULL); 71}</pre></blockquote> 72<p>In the Berkeley DB 3.0 release, this code would be written as:</p> 73<blockquote><pre>/* 74 * db_init -- 75 * Initialize the environment. 76 */ 77int 78db_init(home, dbenvp) 79 char *home; 80 DB_ENV **dbenvp; 81{ 82 int ret; 83 DB_ENV *dbenv; 84<p> 85 if ((ret = db_env_create(&dbenv, 0)) != 0) 86 return (ret); 87<p> 88 if ((ret = dbenv->open(dbenv, home, NULL, 89 DB_INIT_LOCK | DB_INIT_LOG | DB_INIT_MPOOL | DB_INIT_TXN | 90 DB_USE_ENVIRON, 0)) == 0) { 91 *dbenvp = dbenv; 92 return (0); 93 } 94<p> 95 (void)dbenv->close(dbenv, 0); 96 return (ret); 97}</pre></blockquote> 98<p>As you can see, the arguments to db_appinit and to <a href="../../api_c/env_open.html">DB_ENV->open</a> are 99largely the same. There is some minor re-organization: the mapping is 100that arguments #1, 2, 3, and 4 to db_appinit become arguments #2, 3, 1 101and 4 to <a href="../../api_c/env_open.html">DB_ENV->open</a>. There is one additional argument to 102<a href="../../api_c/env_open.html">DB_ENV->open</a>, argument #5. For backward compatibility with the 2.X 103Berkeley DB releases, simply set that argument to 0.</p> 104<p>It is only slightly more complex to translate calls to XXX_open to the 105<a href="../../api_c/env_open.html">DB_ENV->open</a> method. Here's an example of creating a lock region 106using the 2.X interface:</p> 107<blockquote><pre>lock_open(dir, DB_CREATE, 0664, dbenv, ®ionp);</pre></blockquote> 108<p>In the Berkeley DB 3.0 release, this code would be written as:</p> 109<blockquote><pre>if ((ret = db_env_create(&dbenv, 0)) != 0) 110 return (ret); 111<p> 112if ((ret = dbenv->open(dbenv, 113 dir, NULL, DB_CREATE | DB_INIT_LOCK, 0664)) == 0) { 114 *dbenvp = dbenv; 115 return (0); 116}</pre></blockquote> 117<p>Note that in this example, you no longer need the DB_LOCKTAB structure 118reference that was required in Berkeley DB 2.X releases.</p> 119<p>The final issue with upgrading the db_appinit call is the DB_MPOOL_PRIVATE 120option previously provided for the db_appinit call. If your application 121is using this flag, it should almost certainly use the new 122<a href="../../api_c/env_open.html#DB_PRIVATE">DB_PRIVATE</a> flag to the <a href="../../api_c/env_open.html">DB_ENV->open</a> method. Regardless, you 123should carefully consider this change before converting to use the 124<a href="../../api_c/env_open.html#DB_PRIVATE">DB_PRIVATE</a> flag.</p> 125<p>Translating db_appexit or XXX_close calls to <a href="../../api_c/env_close.html">DB_ENV->close</a> is equally 126simple. Instead of taking a reference to a per-subsystem structure such 127as DB_LOCKTAB or DB_TXNMGR, all calls take a reference to a <a href="../../api_c/env_class.html">DB_ENV</a> 128structure. The calling sequence is otherwise unchanged. Note that as 129the application no longer allocates the memory for the DB_ENV structure, 130application code to discard it after the call to db_appexit() is no longer 131needed.</p> 132<p>Translating XXX_unlink calls to <a href="../../api_c/env_remove.html">DB_ENV->remove</a> is slightly more complex. 133As with <a href="../../api_c/env_close.html">DB_ENV->close</a>, the call takes a reference to a <a href="../../api_c/env_class.html">DB_ENV</a> 134structure instead of a per-subsystem structure. The calling sequence is 135slightly different, however. Here is an example of removing a lock region 136using the 2.X interface:</p> 137<blockquote><pre>DB_ENV *dbenv; 138<p> 139ret = lock_unlink(dir, 1, dbenv);</pre></blockquote> 140<p>In the Berkeley DB 3.0 release, this code fragment would be written as:</p> 141<blockquote><pre>DB_ENV *dbenv; 142<p> 143ret = dbenv->remove(dbenv, dir, NULL, DB_FORCE);</pre></blockquote> 144<p>The additional argument to the <a href="../../api_c/env_remove.html">DB_ENV->remove</a> function is a 145configuration argument similar to that previously taken by db_appinit and 146now taken by the <a href="../../api_c/env_open.html">DB_ENV->open</a> method. For backward compatibility 147this new argument should simply be set to NULL. The force argument to 148XXX_unlink is now a flag value that is set by bitwise inclusively <b>OR</b>'ing it the 149<a href="../../api_c/env_remove.html">DB_ENV->remove</a> flag argument.</p> 150<table width="100%"><tr><td><br></td><td align=right><a href="../upgrade.3.0/intro.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../upgrade.3.0/func.html"><img src="../../images/next.gif" alt="Next"></a> 151</td></tr></table> 152<p><font size=1>Copyright (c) 1996,2008 Oracle. All rights reserved.</font> 153</body> 154</html> 155