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
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
|
<?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>Opening the environment</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 Programmer's Reference Guide" />
<link rel="up" href="transapp.html" title="Chapter 11. Berkeley DB Transactional Data Store Applications" />
<link rel="prev" href="transapp_app.html" title="Architecting Transactional Data Store applications" />
<link rel="next" href="transapp_data_open.html" title="Opening the databases" />
</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">Opening the environment</th>
</tr>
<tr>
<td width="20%" align="left"><a accesskey="p" href="transapp_app.html">Prev</a> </td>
<th width="60%" align="center">Chapter 11. Berkeley DB Transactional Data Store Applications </th>
<td width="20%" align="right"> <a accesskey="n" href="transapp_data_open.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="transapp_env_open"></a>Opening the environment</h2>
</div>
</div>
</div>
<p>
Creating transaction-protected applications using the
Berkeley DB library is quite easy. Applications first use
<a href="../api_reference/C/envopen.html" class="olink">DB_ENV->open()</a> to initialize the database environment.
Transaction-protected applications normally require all four
Berkeley DB subsystems, so the <a href="../api_reference/C/envopen.html#envopen_DB_INIT_MPOOL" class="olink">DB_INIT_MPOOL</a>,
<a href="../api_reference/C/envopen.html#envopen_DB_INIT_LOCK" class="olink">DB_INIT_LOCK</a>, <a href="../api_reference/C/envopen.html#envopen_DB_INIT_LOG" class="olink">DB_INIT_LOG</a>, and <a href="../api_reference/C/envopen.html#envopen_DB_INIT_TXN" class="olink">DB_INIT_TXN</a> flags should
be specified.
</p>
<p>
Once the application has called <a href="../api_reference/C/envopen.html" class="olink">DB_ENV->open()</a>, it opens its
databases within the environment. Once the databases are
opened, the application makes changes to the databases inside
of transactions. Each set of changes that entails a unit of
work should be surrounded by the appropriate <a href="../api_reference/C/txnbegin.html" class="olink">DB_ENV->txn_begin()</a>,
<a href="../api_reference/C/txncommit.html" class="olink">DB_TXN->commit()</a> and <a href="../api_reference/C/txnabort.html" class="olink">DB_TXN->abort()</a> calls. The Berkeley DB access
methods will make the appropriate calls into the Lock, Log and
Memory Pool subsystems in order to guarantee transaction
semantics. When the application is ready to exit, all
outstanding transactions should have been committed or
aborted.
</p>
<p>
Databases accessed by a transaction must not be closed
during the transaction. Once all outstanding transactions are
finished, all open Berkeley DB files should be closed. When
the Berkeley DB database files have been closed, the
environment should be closed by calling <a href="../api_reference/C/envclose.html" class="olink">DB_ENV->close()</a>.
</p>
<p>
The following code fragment creates the database
environment directory then opens the environment, running
recovery. Our <a href="../api_reference/C/env.html" class="olink">DB_ENV</a> database environment handle is declared to
be free-threaded using the <a href="../api_reference/C/dbopen.html#open_DB_THREAD" class="olink">DB_THREAD</a> flag, and so may be
used by any number of threads that we may subsequently create.
</p>
<a id="prog_transapp1"></a>
<pre class="programlisting">#include <sys/types.h>
#include <sys/stat.h>
#include <errno.h>
#include <stdarg.h>
#include <stdlib.h>
#include <string.h>
#include <unistd.h>
#include <db.h>
#define ENV_DIRECTORY "TXNAPP"
void env_dir_create(void);
void env_open(DB_ENV **);
...
int
main(int argc, char *argv[])
{
extern int optind;
DB_ENV *dbenv;
int ch;
while ((ch = getopt(argc, argv, "")) != EOF)
switch (ch) {
case '?':
default:
usage();
}
argc -= optind;
argv += optind;
env_dir_create();
env_open(&dbenv);
...
return (0);
}
...
void
env_dir_create()
{
struct stat sb;
/*
* If the directory exists, we're done. We do not further check
* the type of the file, DB will fail appropriately if it's the
* wrong type.
*/
if (stat(ENV_DIRECTORY, &sb) == 0)
return;
/* Create the directory, read/write/access owner only. */
if (mkdir(ENV_DIRECTORY, S_IRWXU) != 0) {
fprintf(stderr,
"txnapp: mkdir: %s: %s\n", ENV_DIRECTORY, strerror(errno));
exit (1);
}
}
void
env_open(DB_ENV **dbenvp)
{
DB_ENV *dbenv;
int ret;
/* Create the environment handle. */
if ((ret = db_env_create(&dbenv, 0)) != 0) {
fprintf(stderr,
"txnapp: db_env_create: %s\n", db_strerror(ret));
exit (1);
}
/* Set up error handling. */
dbenv->set_errpfx(dbenv, "txnapp");
dbenv->set_errfile(dbenv, stderr);
/*
* Open a transactional environment:
* create if it doesn't exist
* free-threaded handle
* run recovery
* read/write owner only
*/
if ((ret = dbenv->open(dbenv, ENV_DIRECTORY,
DB_CREATE | DB_INIT_LOCK | DB_INIT_LOG |
DB_INIT_MPOOL | DB_INIT_TXN | DB_RECOVER | DB_THREAD,
S_IRUSR | S_IWUSR)) != 0) {
(void)dbenv->close(dbenv, 0);
fprintf(stderr, "dbenv->open: %s: %s\n",
ENV_DIRECTORY, db_strerror(ret));
exit (1);
}
*dbenvp = dbenv;
}</pre>
<p>
After running this initial program, we can use the
<a href="../api_reference/C/db_stat.html" class="olink">db_stat</a> utility to display the contents of the environment
directory:
</p>
<pre class="programlisting">prompt> db_stat -e -h TXNAPP
3.2.1 Environment version.
120897 Magic number.
0 Panic value.
1 References.
6 Locks granted without waiting.
0 Locks granted after waiting.
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
Mpool Region: 4.
264KB Size (270336 bytes).
-1 Segment ID.
1 Locks granted without waiting.
0 Locks granted after waiting.
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
Log Region: 3.
96KB Size (98304 bytes).
-1 Segment ID.
3 Locks granted without waiting.
0 Locks granted after waiting.
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
Lock Region: 2.
240KB Size (245760 bytes).
-1 Segment ID.
1 Locks granted without waiting.
0 Locks granted after waiting.
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
Txn Region: 5.
8KB Size (8192 bytes).
-1 Segment ID.
1 Locks granted without waiting.
0 Locks granted after waiting.</pre>
</div>
<div class="navfooter">
<hr />
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left"><a accesskey="p" href="transapp_app.html">Prev</a> </td>
<td width="20%" align="center">
<a accesskey="u" href="transapp.html">Up</a>
</td>
<td width="40%" align="right"> <a accesskey="n" href="transapp_data_open.html">Next</a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top">Architecting Transactional Data
Store applications </td>
<td width="20%" align="center">
<a accesskey="h" href="index.html">Home</a>
</td>
<td width="40%" align="right" valign="top"> Opening the databases</td>
</tr>
</table>
</div>
</body>
</html>
|
