Debian Codegraph @

docs/upgrading/upgrade_3_0_envopen.html

raw
1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3 <html xmlns="http://www.w3.org/1999/xhtml">
4 <head>
5 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
6 <title>environment open/close/unlink</title>
7 <link rel="stylesheet" href="gettingStarted.css" type="text/css" />
8 <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
9 <link rel="start" href="index.html" title="Berkeley DB Upgrade Guide" />
10 <link rel="up" href="upgrade_3_0_toc.html" title="Chapter 14. Upgrading Berkeley DB 2.X applications to Berkeley DB 3.0" />
11 <link rel="prev" href="upgrade_3_0_toc.html" title="Chapter 14. Upgrading Berkeley DB 2.X applications to Berkeley DB 3.0" />
12 <link rel="next" href="upgrade_3_0_func.html" title="function arguments" />
13 </head>
14 <body>
15 <div xmlns="" class="navheader">
16 <div class="libver">
17 <p>Library Version 11.2.5.3</p>
18 </div>
19 <table width="100%" summary="Navigation header">
20 <tr>
21 <th colspan="3" align="center">environment open/close/unlink</th>
22 </tr>
23 <tr>
24 <td width="20%" align="left"><a accesskey="p" href="upgrade_3_0_toc.html">Prev</a> </td>
25 <th width="60%" align="center">Chapter 14. Upgrading Berkeley DB 2.X applications to Berkeley DB 3.0</th>
26 <td width="20%" align="right"> <a accesskey="n" href="upgrade_3_0_func.html">Next</a></td>
27 </tr>
28 </table>
29 <hr />
30 </div>
31 <div class="sect1" lang="en" xml:lang="en">
32 <div class="titlepage">
33 <div>
34 <div>
35 <h2 class="title" style="clear: both"><a id="upgrade_3_0_envopen"></a>environment open/close/unlink</h2>
36 </div>
37 </div>
38 </div>
39 <p>The hardest part of upgrading your application from a 2.X code base to
40 the 3.0 release is translating the Berkeley DB environment open, close and
41 remove calls.</p>
42 <p>There were two logical changes in this part of the Berkeley DB interface.
43 First, in Berkeley DB 3.0, there are no longer separate structures that
44 represent each subsystem (for example, DB_LOCKTAB or DB_TXNMGR) and an
45 overall <a href="../api_reference/C/env.html" class="olink">DB_ENV</a> environment structure. Instead there is only the
46 <a href="../api_reference/C/env.html" class="olink">DB_ENV</a> references should be passed around by your application instead of passing around
47 DB_LOCKTAB or DB_TXNMGR references. This is likely to be a simple
48 change for most applications as few applications use the lock_XXX,
49 log_XXX, memp_XXX or txn_XXX interfaces to create Berkeley DB environments.</p>
50 <p>The second change is that there are no longer separate open, close, and
51 unlink interfaces to the Berkeley DB subsystems. For example, in previous
52 releases, it was possible to open a lock subsystem either using
53 db_appinit or using the lock_open call. In the 3.0 release the XXX_open
54 interfaces to the subsystems have been removed, and subsystems must now
55 be opened using the 3.0 replacement for the db_appinit call.</p>
56 <p>To upgrade your application, first find each place your application opens,
57 closes and/or removes a Berkeley DB environment. This will be code of the form:</p>
58 <pre class="programlisting">db_appinit, db_appexit
59 lock_open, lock_close, lock_unlink
60 log_open, log_close, log_unlink
61 memp_open, memp_close, memp_unlink
62 txn_open, txn_close, txn_unlink</pre>
63 <p>Each of these groups of calls should be replaced with calls to
64 <a href="../api_reference/C/envcreate.html" class="olink">db_env_create()</a>, <a href="../api_reference/C/envopen.html" class="olink">DB_ENV-&gt;open()</a>, <a href="../api_reference/C/envclose.html" class="olink">DB_ENV-&gt;close()</a>, and <a href="../api_reference/C/envremove.html" class="olink">DB_ENV-&gt;remove()</a>.
65 </p>
66 <p>The <a href="../api_reference/C/envcreate.html" class="olink">db_env_create()</a> call and the call to the <a href="../api_reference/C/envopen.html" class="olink">DB_ENV-&gt;open()</a>
67 method replace the db_appinit, lock_open, log_open, memp_open and txn_open
68 calls. The <a href="../api_reference/C/envclose.html" class="olink">DB_ENV-&gt;close()</a> method replaces the db_appexit,
69 lock_close, log_close, memp_close and txn_close calls. The
70 <a href="../api_reference/C/envremove.html" class="olink">DB_ENV-&gt;remove()</a> call replaces the lock_unlink, log_unlink,
71 memp_unlink and txn_unlink calls.</p>
72 <p>Here's an example creating a Berkeley DB environment using the 2.X interface:</p>
73 <pre class="programlisting">/*
74 * db_init --
75 * Initialize the environment.
76 */
77 DB_ENV *
78 db_init(home)
79 char *home;
80 {
81 DB_ENV *dbenv;
82
83 if ((dbenv = (DB_ENV *)calloc(sizeof(DB_ENV), 1)) == NULL)
84 return (errno);
85
86 if ((errno = db_appinit(home, NULL, dbenv,
87 DB_INIT_LOCK | DB_INIT_LOG | DB_INIT_MPOOL | DB_INIT_TXN |
88 DB_USE_ENVIRON)) == 0)
89 return (dbenv);
90
91 free(dbenv);
92 return (NULL);
93 }</pre>
94 <p>In the Berkeley DB 3.0 release, this code would be written as:</p>
95 <pre class="programlisting">/*
96 * db_init --
97 * Initialize the environment.
98 */
99 int
100 db_init(home, dbenvp)
101 char *home;
102 DB_ENV **dbenvp;
103 {
104 int ret;
105 DB_ENV *dbenv;
106
107 if ((ret = db_env_create(&amp;dbenv, 0)) != 0)
108 return (ret);
109
110 if ((ret = dbenv-&gt;open(dbenv, home, NULL,
111 DB_INIT_LOCK | DB_INIT_LOG | DB_INIT_MPOOL | DB_INIT_TXN |
112 DB_USE_ENVIRON, 0)) == 0) {
113 *dbenvp = dbenv;
114 return (0);
115 }
116
117 (void)dbenv-&gt;close(dbenv, 0);
118 return (ret);
119 }</pre>
120 <p>As you can see, the arguments to db_appinit and to <a href="../api_reference/C/envopen.html" class="olink">DB_ENV-&gt;open()</a> are
121 largely the same. There is some minor re-organization: the mapping is
122 that arguments #1, 2, 3, and 4 to db_appinit become arguments #2, 3, 1
123 and 4 to <a href="../api_reference/C/envopen.html" class="olink">DB_ENV-&gt;open()</a>. There is one additional argument to
124 <a href="../api_reference/C/envopen.html" class="olink">DB_ENV-&gt;open()</a>, argument #5. For backward compatibility with the 2.X
125 Berkeley DB releases, simply set that argument to 0.</p>
126 <p>It is only slightly more complex to translate calls to XXX_open to the
127 <a href="../api_reference/C/envopen.html" class="olink">DB_ENV-&gt;open()</a> method. Here's an example of creating a lock region
128 using the 2.X interface:</p>
129 <pre class="programlisting">lock_open(dir, DB_CREATE, 0664, dbenv, &amp;regionp);</pre>
130 <p>In the Berkeley DB 3.0 release, this code would be written as:</p>
131 <pre class="programlisting">if ((ret = db_env_create(&amp;dbenv, 0)) != 0)
132 return (ret);
133
134 if ((ret = dbenv-&gt;open(dbenv,
135 dir, NULL, DB_CREATE | DB_INIT_LOCK, 0664)) == 0) {
136 *dbenvp = dbenv;
137 return (0);
138 }</pre>
139 <p>Note that in this example, you no longer need the DB_LOCKTAB structure
140 reference that was required in Berkeley DB 2.X releases.</p>
141 <p>The final issue with upgrading the db_appinit call is the DB_MPOOL_PRIVATE
142 option previously provided for the db_appinit call. If your application
143 is using this flag, it should almost certainly use the new
144 <a href="../api_reference/C/envopen.html#envopen_DB_PRIVATE" class="olink">DB_PRIVATE</a> flag to the <a href="../api_reference/C/envopen.html" class="olink">DB_ENV-&gt;open()</a> method. Regardless, you
145 should carefully consider this change before converting to use the
146 <a href="../api_reference/C/envopen.html#envopen_DB_PRIVATE" class="olink">DB_PRIVATE</a> flag.</p>
147 <p>Translating db_appexit or XXX_close calls to <a href="../api_reference/C/envclose.html" class="olink">DB_ENV-&gt;close()</a> is equally
148 simple. Instead of taking a reference to a per-subsystem structure such
149 as DB_LOCKTAB or DB_TXNMGR, all calls take a reference to a <a href="../api_reference/C/env.html" class="olink">DB_ENV</a>
150 structure. The calling sequence is otherwise unchanged. Note that as
151 the application no longer allocates the memory for the DB_ENV structure,
152 application code to discard it after the call to db_appexit() is no longer
153 needed.</p>
154 <p>Translating XXX_unlink calls to <a href="../api_reference/C/envremove.html" class="olink">DB_ENV-&gt;remove()</a> is slightly more complex.
155 As with <a href="../api_reference/C/envclose.html" class="olink">DB_ENV-&gt;close()</a>, the call takes a reference to a <a href="../api_reference/C/env.html" class="olink">DB_ENV</a>
156 structure instead of a per-subsystem structure. The calling sequence is
157 slightly different, however. Here is an example of removing a lock region
158 using the 2.X interface:</p>
159 <pre class="programlisting">DB_ENV *dbenv;
160
161 ret = lock_unlink(dir, 1, dbenv);</pre>
162 <p>In the Berkeley DB 3.0 release, this code fragment would be written as:</p>
163 <pre class="programlisting">DB_ENV *dbenv;
164
165 ret = dbenv-&gt;remove(dbenv, dir, NULL, DB_FORCE);</pre>
166 <p>The additional argument to the <a href="../api_reference/C/envremove.html" class="olink">DB_ENV-&gt;remove()</a> function is a
167 configuration argument similar to that previously taken by db_appinit and
168 now taken by the <a href="../api_reference/C/envopen.html" class="olink">DB_ENV-&gt;open()</a> method. For backward compatibility
169 this new argument should simply be set to NULL. The force argument to
170 XXX_unlink is now a flag value that is set by bitwise inclusively <span class="bold"><strong>OR</strong></span>'ing it the
171 <a href="../api_reference/C/envremove.html" class="olink">DB_ENV-&gt;remove()</a> flag argument.</p>
172 </div>
173 <div class="navfooter">
174 <hr />
175 <table width="100%" summary="Navigation footer">
176 <tr>
177 <td width="40%" align="left"><a accesskey="p" href="upgrade_3_0_toc.html">Prev</a> </td>
178 <td width="20%" align="center">
179 <a accesskey="u" href="upgrade_3_0_toc.html">Up</a>
180 </td>
181 <td width="40%" align="right"> <a accesskey="n" href="upgrade_3_0_func.html">Next</a></td>
182 </tr>
183 <tr>
184 <td width="40%" align="left" valign="top">Chapter 14. Upgrading Berkeley DB 2.X applications to Berkeley DB 3.0 </td>
185 <td width="20%" align="center">
186 <a accesskey="h" href="index.html">Home</a>
187 </td>
188 <td width="40%" align="right" valign="top"> function arguments</td>
189 </tr>
190 </table>
191 </div>
192 </body>
193 </html>