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