← 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/transapp/env_open.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/transapp/env_open.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: Opening the environment</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>Berkeley DB Transactional Data Store Applications</dl></h3></td>
14
 
<td align=right><a href="../../ref/transapp/app.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/transapp/data_open.html"><img src="../../images/next.gif" alt="Next"></a>
15
 
</td></tr></table>
16
 
<p>
17
 
<h1 align=center>Opening the environment</h1>
18
 
<p>Creating transaction-protected applications using the Berkeley DB library is
19
 
quite easy.  Applications first use <a href="../../api_c/env_open.html">DB_ENV-&gt;open</a> to initialize
20
 
the database environment.  Transaction-protected applications normally
21
 
require all four Berkeley DB subsystems, so the <a href="../../api_c/env_open.html#DB_INIT_MPOOL">DB_INIT_MPOOL</a>,
22
 
<a href="../../api_c/env_open.html#DB_INIT_LOCK">DB_INIT_LOCK</a>, <a href="../../api_c/env_open.html#DB_INIT_LOG">DB_INIT_LOG</a>, and <a href="../../api_c/env_open.html#DB_INIT_TXN">DB_INIT_TXN</a> flags
23
 
should be specified.
24
 
<p>Once the application has called <a href="../../api_c/env_open.html">DB_ENV-&gt;open</a>, it opens its
25
 
databases within the environment.  Once the databases are opened, the
26
 
application makes changes to the databases inside of transactions.  Each
27
 
set of changes that entails a unit of work should be surrounded by the
28
 
appropriate <a href="../../api_c/txn_begin.html">DB_ENV-&gt;txn_begin</a>, <a href="../../api_c/txn_commit.html">DB_TXN-&gt;commit</a>, and <a href="../../api_c/txn_abort.html">DB_TXN-&gt;abort</a>
29
 
calls.  The Berkeley DB access methods will make the appropriate calls into
30
 
the Lock, Log and Memory Pool subsystems in order to guarantee
31
 
transaction semantics.  When the application is ready to exit, all
32
 
outstanding transactions should have been committed or aborted.
33
 
<p>Databases accessed by a transaction must not be closed during the
34
 
transaction.  Once all outstanding transactions are finished, all open
35
 
Berkeley DB files should be closed.  When the Berkeley DB database files have been
36
 
closed, the environment should be closed by calling
37
 
<a href="../../api_c/env_close.html">DB_ENV-&gt;close</a>.
38
 
<p>The following code fragment creates the database environment directory
39
 
then opens the environment, running recovery.  Our <a href="../../api_c/env_class.html">DB_ENV</a>
40
 
database environment handle is declared to be free-threaded using the
41
 
<a href="../../api_c/env_open.html#DB_THREAD">DB_THREAD</a> flag, and so may be used by any number of threads that
42
 
we may subsequently create.
43
 
<p><blockquote><pre>#include &lt;sys/types.h&gt;
44
 
#include &lt;sys/stat.h&gt;
45
 
<p>
46
 
#include &lt;errno.h&gt;
47
 
#include &lt;stdarg.h&gt;
48
 
#include &lt;stdlib.h&gt;
49
 
#include &lt;string.h&gt;
50
 
#include &lt;unistd.h&gt;
51
 
<p>
52
 
#include &lt;db.h&gt;
53
 
<p>
54
 
#define ENV_DIRECTORY   "TXNAPP"
55
 
<p>
56
 
void  env_dir_create(void);
57
 
void  env_open(DB_ENV **);
58
 
<p>
59
 
int
60
 
main(int argc, char *argv)
61
 
{
62
 
        extern char *optarg;
63
 
        extern int optind;
64
 
        DB *db_cats, *db_color, *db_fruit;
65
 
        DB_ENV *dbenv;
66
 
        int ch;
67
 
<p>
68
 
        while ((ch = getopt(argc, argv, "")) != EOF)
69
 
                switch (ch) {
70
 
                case '?':
71
 
                default:
72
 
                        usage();
73
 
                }
74
 
        argc -= optind;
75
 
        argv += optind;
76
 
<p>
77
 
        env_dir_create();
78
 
        env_open(&dbenv);
79
 
<p>
80
 
        return (0);
81
 
}
82
 
<p>
83
 
void
84
 
env_dir_create()
85
 
{
86
 
        struct stat sb;
87
 
<p>
88
 
        /*
89
 
         * If the directory exists, we're done.  We do not further check
90
 
         * the type of the file, DB will fail appropriately if it's the
91
 
         * wrong type.
92
 
         */
93
 
        if (stat(ENV_DIRECTORY, &sb) == 0)
94
 
                return;
95
 
<p>
96
 
        /* Create the directory, read/write/access owner only. */
97
 
        if (mkdir(ENV_DIRECTORY, S_IRWXU) != 0) {
98
 
                fprintf(stderr,
99
 
                    "txnapp: mkdir: %s: %s\n", ENV_DIRECTORY, strerror(errno));
100
 
                exit (1);
101
 
        }
102
 
}
103
 
<p>
104
 
void
105
 
env_open(DB_ENV **dbenvp)
106
 
{
107
 
        DB_ENV *dbenv;
108
 
        int ret;
109
 
<p>
110
 
        /* Create the environment handle. */
111
 
        if ((ret = db_env_create(&dbenv, 0)) != 0) {
112
 
                fprintf(stderr,
113
 
                    "txnapp: db_env_create: %s\n", db_strerror(ret));
114
 
                exit (1);
115
 
        }
116
 
<p>
117
 
        /* Set up error handling. */
118
 
        dbenv-&gt;set_errpfx(dbenv, "txnapp");
119
 
<p>
120
 
        /*
121
 
         * Open a transactional environment:
122
 
         *      create if it doesn't exist
123
 
         *      free-threaded handle
124
 
         *      run recovery
125
 
         *      read/write owner only
126
 
         */
127
 
        if ((ret = dbenv-&gt;open(dbenv, ENV_DIRECTORY,
128
 
            DB_CREATE | DB_INIT_LOCK | DB_INIT_LOG |
129
 
            DB_INIT_MPOOL | DB_INIT_TXN | DB_RECOVER | DB_THREAD,
130
 
            S_IRUSR | S_IWUSR)) != 0) {
131
 
                (void)dbenv-&gt;close(dbenv, 0);
132
 
                dbenv-&gt;err(dbenv, ret, "dbenv-&gt;open: %s", ENV_DIRECTORY);
133
 
                exit (1);
134
 
        }
135
 
<p>
136
 
        *dbenvp = dbenv;
137
 
}</pre></blockquote>
138
 
<p>After running this initial program, we can use the <a href="../../utility/db_stat.html">db_stat</a>
139
 
utility to display the contents of the environment directory:
140
 
<p><blockquote><pre>prompt&gt; db_stat -e -h TXNAPP
141
 
3.2.1   Environment version.
142
 
120897  Magic number.
143
 
0       Panic value.
144
 
1       References.
145
 
6       Locks granted without waiting.
146
 
0       Locks granted after waiting.
147
 
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
148
 
Mpool Region: 4.
149
 
264KB   Size (270336 bytes).
150
 
-1      Segment ID.
151
 
1       Locks granted without waiting.
152
 
0       Locks granted after waiting.
153
 
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
154
 
Log Region: 3.
155
 
96KB    Size (98304 bytes).
156
 
-1      Segment ID.
157
 
3       Locks granted without waiting.
158
 
0       Locks granted after waiting.
159
 
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
160
 
Lock Region: 2.
161
 
240KB   Size (245760 bytes).
162
 
-1      Segment ID.
163
 
1       Locks granted without waiting.
164
 
0       Locks granted after waiting.
165
 
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
166
 
Txn Region: 5.
167
 
8KB     Size (8192 bytes).
168
 
-1      Segment ID.
169
 
1       Locks granted without waiting.
170
 
0       Locks granted after waiting.</pre></blockquote>
171
 
<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/transapp/app.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/transapp/data_open.html"><img src="../../images/next.gif" alt="Next"></a>
172
 
</td></tr></table>
173
 
<p><font size=1><a href="http://www.sleepycat.com">Copyright Sleepycat Software</a></font>
174
 
</body>
175
 
</html>