1
<!--$Id: env_open.so,v 1.3 2001/05/08 15:03:08 bostic Exp $-->
2
<!--Copyright 1997-2001 by Sleepycat Software, Inc.-->
3
<!--All rights reserved.-->
6
<title>Berkeley DB Reference Guide: Opening the environment</title>
7
<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit.">
8
<meta name="keywords" content="embedded,database,programmatic,toolkit,b+tree,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,java,C,C++">
11
<table width="100%"><tr valign=top>
12
<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Berkeley DB Transactional Data Store Applications</dl></h3></td>
13
<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>
16
<h1 align=center>Opening the environment</h1>
17
<p>Creating transaction-protected applications using the Berkeley DB library is
18
quite easy. Applications first use <a href="../../api_c/env_open.html">DB_ENV->open</a> to initialize
19
the database environment. Transaction-protected applications normally
20
require all four Berkeley DB subsystems, so the <a href="../../api_c/env_open.html#DB_INIT_MPOOL">DB_INIT_MPOOL</a>,
21
<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
<p>Once the application has called <a href="../../api_c/env_open.html">DB_ENV->open</a>, it opens its
24
databases within the environment. Once the databases are opened, the
25
application makes changes to the databases inside of transactions. Each
26
set of changes that entails a unit of work should be surrounded by the
27
appropriate <a href="../../api_c/txn_begin.html">txn_begin</a>, <a href="../../api_c/txn_commit.html">txn_commit</a>, and <a href="../../api_c/txn_abort.html">txn_abort</a>
28
calls. The Berkeley DB access methods will make the appropriate calls into
29
the Lock, Log and Memory Pool subsystems in order to guarantee
30
transaction semantics. When the application is ready to exit, all
31
outstanding transactions should have been committed or aborted.
32
<p>Databases accessed by a transaction must not be closed during the
33
transaction. Once all outstanding transactions are finished, all open
34
Berkeley DB files should be closed. When the Berkeley DB database files have been
35
closed, the environment should be closed by calling
36
<a href="../../api_c/env_close.html">DB_ENV->close</a>.
37
<p>The following code fragment creates the database environment directory
38
then opens the environment, running recovery. Our DB_ENV
39
database environment handle is declared to be free-threaded using the
40
<a href="../../api_c/env_open.html#DB_THREAD">DB_THREAD</a> flag, and so may be used by any number of threads that
41
we may subsequently create.
42
<p><blockquote><pre>#include <sys/types.h>
43
#include <sys/stat.h>
45
#include <errno.h>
46
#include <pthread.h>
47
#include <stdarg.h>
48
#include <stdlib.h>
49
#include <string.h>
50
#include <unistd.h>
54
#define ENV_DIRECTORY "TXNAPP"
56
void env_dir_create(void);
57
void env_open(DB_ENV **);
60
main(int argc, char *argv)
64
DB *db_cats, *db_color, *db_fruit;
69
while ((ch = getopt(argc, argv, "")) != EOF)
90
* If the directory exists, we're done. We do not further check
91
* the type of the file, DB will fail appropriately if it's the
94
if (stat(ENV_DIRECTORY, &sb) == 0)
97
/* Create the directory, read/write/access owner only. */
98
if (mkdir(ENV_DIRECTORY, S_IRWXU) != 0) {
100
"txnapp: mkdir: %s: %s\n", ENV_DIRECTORY, strerror(errno));
106
env_open(DB_ENV **dbenvp)
111
/* Create the environment handle. */
112
if ((ret = db_env_create(&dbenv, 0)) != 0) {
114
"txnapp: db_env_create: %s\n", db_strerror(ret));
118
/* Set up error handling. */
119
dbenv->set_errpfx(dbenv, "txnapp");
122
* Open a transactional environment:
123
* create if it doesn't exist
124
* free-threaded handle
126
* read/write owner only
128
if ((ret = dbenv->open(dbenv, ENV_DIRECTORY,
129
DB_CREATE | DB_INIT_LOCK | DB_INIT_LOG |
130
DB_INIT_MPOOL | DB_INIT_TXN | DB_RECOVER | DB_THREAD,
131
S_IRUSR | S_IWUSR)) != 0) {
132
dbenv->err(dbenv, ret, "dbenv->open: %s", ENV_DIRECTORY);
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> db_stat -e -h TXNAPP
141
3.2.1 Environment version.
145
6 Locks granted without waiting.
146
0 Locks granted after waiting.
147
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
149
264KB Size (270336 bytes).
151
1 Locks granted without waiting.
152
0 Locks granted after waiting.
153
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
155
96KB Size (98304 bytes).
157
3 Locks granted without waiting.
158
0 Locks granted after waiting.
159
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
161
240KB Size (245760 bytes).
163
1 Locks granted without waiting.
164
0 Locks granted after waiting.
165
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
167
8KB Size (8192 bytes).
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>
173
<p><font size=1><a href="http://www.sleepycat.com">Copyright Sleepycat Software</a></font>
added
removed
db/docs/ref/transapp/env_open.html
