<?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 class="navheader">
<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>
<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 *db_cats, *db_color, *db_fruit;
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 utility</a> 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>
