← Back to branch summary

~ubuntu-branches/ubuntu/maverick/evolution-data-server/maverick-proposed

« back to all changes in this revision

Viewing changes to libdb/docs/ref/upgrade.3.0/envopen.html

  • Committer: Bazaar Package Importer
  • Author(s): Didier Roche
  • Date: 2010-05-17 17:02:06 UTC
  • mfrom: (1.1.79 upstream) (1.6.12 experimental)
  • Revision ID: james.westby@ubuntu.com-20100517170206-4ufr52vwrhh26yh0
Tags: 2.30.1-1ubuntu1
https://launchpad.net/bugs/42199
https://launchpad.net/bugs/229669
https://launchpad.net/bugs/173703
https://launchpad.net/bugs/360344
https://launchpad.net/bugs/508494
* Merge from debian experimental. Remaining change:
  (LP: #42199, #229669, #173703, #360344, #508494)
  + debian/control:
    - add Vcs-Bzr tag
    - don't use libgnome
    - Use Breaks instead of Conflicts against evolution 2.25 and earlier.
  + debian/evolution-data-server.install,
    debian/patches/45_libcamel_providers_version.patch:
    - use the upstream versioning, not a Debian-specific one 
  + debian/libedata-book1.2-dev.install, debian/libebackend-1.2-dev.install,
    debian/libcamel1.2-dev.install, debian/libedataserverui1.2-dev.install:
    - install html documentation
  + debian/rules:
    - don't build documentation it's shipped with the tarball

Show diffs side-by-side

added added

removed removed

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