Edit File - File Manager

Edit File: create.html

<html>
<head>
<title>Berkeley DB Reference Guide: Creating a database environment</title>
<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit.">
<meta name="keywords" content="embedded,database,programmatic,toolkit,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,Java,C,C++">
</head>
<body bgcolor=white>
<a name="2"></a>
<table width="100%"><tr valign=top>
<td><dl><dt>Berkeley DB Reference Guide:<dd>Environment</dl></td>
<td align=right><a href="../env/intro.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../env/open.html"><img src="../../images/next.gif" alt="Next"></a>
</td></tr></table>
Creating a database environment
The Berkeley DB environment is created and described by the <a href="../../api_c/env_class.html">db_env_create</a>
and <a href="../../api_c/env_open.html">DB_ENV-&gt;open</a> interfaces. In situations where customization is
desired, such as storing log files on a separate disk drive or selection
of a particular cache size, applications must describe the customization
by either creating an environment configuration file in the environment
home directory or by arguments passed to other <a href="../../api_c/env_class.html">DB_ENV</a> handle methods.
Once an environment has been created, database files specified using
relative pathnames will be named relative to the home directory. Using
pathnames relative to the home directory allows the entire environment
to be easily moved, simplifying restoration and recovery of a database
in a different directory or on a different system.
Applications first obtain an environment handle using the
<a href="../../api_c/env_class.html">db_env_create</a> method, then call the <a href="../../api_c/env_open.html">DB_ENV-&gt;open</a> method which creates
or joins the database environment. There are a number of options you
can set to customize <a href="../../api_c/env_open.html">DB_ENV-&gt;open</a> for your environment. These
options fall into four broad categories:
 
Subsystem Initialization:<ul compact><li>These flags indicate which Berkeley DB subsystems will be initialized for the
environment, and what operations will happen automatically when
databases are accessed within the environment. The flags include
<a href="../../api_c/env_open.html#DB_INIT_CDB">DB_INIT_CDB</a>, <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>,
<a href="../../api_c/env_open.html#DB_INIT_MPOOL">DB_INIT_MPOOL</a>, and <a href="../../api_c/env_open.html#DB_INIT_TXN">DB_INIT_TXN</a>. The <a href="../../api_c/env_open.html#DB_INIT_CDB">DB_INIT_CDB</a>
flag does initialization for Berkeley DB Concurrent Data Store applications. (See
<a href="../../ref/cam/intro.html">Building Berkeley DB Concurrent Data Store applications</a> for more
information.) The rest of the flags initialize a single subsystem; that
is, when <a href="../../api_c/env_open.html#DB_INIT_LOCK">DB_INIT_LOCK</a> is specified, applications reading and
writing databases opened in this environment will be using locking to
ensure that they do not overwrite each other's changes.</ul>
Recovery options:<ul compact><li>These flags, which include <a href="../../api_c/env_open.html#DB_RECOVER">DB_RECOVER</a> and
<a href="../../api_c/env_open.html#DB_RECOVER_FATAL">DB_RECOVER_FATAL</a>, indicate what recovery is to be performed on
the environment before it is opened for normal use.</ul>
Naming options:<ul compact><li>These flags, which include <a href="../../api_c/env_open.html#DB_USE_ENVIRON">DB_USE_ENVIRON</a> and
<a href="../../api_c/env_open.html#DB_USE_ENVIRON_ROOT">DB_USE_ENVIRON_ROOT</a>, modify how file naming happens in the
environment.</ul>
Miscellaneous:<ul compact><li>Finally, there are a number of miscellaneous flags, for example,
<a href="../../api_c/env_open.html#DB_CREATE">DB_CREATE</a> which causes underlying files to be created as
necessary. See the <a href="../../api_c/env_open.html">DB_ENV-&gt;open</a> manual pages for further
information.</ul>
 
Most applications either specify only the <a href="../../api_c/env_open.html#DB_INIT_MPOOL">DB_INIT_MPOOL</a> flag or
they specify all four subsystem initialization flags
(<a href="../../api_c/env_open.html#DB_INIT_MPOOL">DB_INIT_MPOOL</a>, <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>). The former configuration is for applications that
simply want to use the basic Access Method interfaces with a shared
underlying buffer pool, but don't care about recoverability after
application or system failure. The latter is for applications that need
recoverability. There are situations in which other combinations of
the initialization flags make sense, but they are rare.
The <a href="../../api_c/env_open.html#DB_RECOVER">DB_RECOVER</a> flag is specified by applications that want to
perform any necessary database recovery when they start running. That
is, if there was a system or application failure the last time they ran,
they want the databases to be made consistent before they start running
again. It is not an error to specify this flag when no recovery needs
to be done.
The <a href="../../api_c/env_open.html#DB_RECOVER_FATAL">DB_RECOVER_FATAL</a> flag is more special-purpose. It performs
catastrophic database recovery, and normally requires that some initial
arrangements be made; that is, archived log files be brought back into
the filesystem. Applications should not normally specify this flag.
Instead, under these rare conditions, the <a href="../../utility/db_recover.html">db_recover</a> utility
should be used.
The following is a simple example of a function that opens a database
environment for a transactional program.
<blockquote><pre>DB_ENV *
db_setup(home, data_dir, errfp, progname)
	char *home, *data_dir, *progname;
	FILE *errfp;
{
	DB_ENV *dbenv;
	int ret;

	/*
	 * Create an environment and initialize it for additional error
	 * reporting.
	 */
	if ((ret = db_env_create(&dbenv, 0)) != 0) {
		fprintf(errfp, "%s: %s\n", progname, db_strerror(ret));
		return (NULL);
	}
	dbenv-&gt;set_errfile(dbenv, errfp);
	dbenv-&gt;set_errpfx(dbenv, progname);

	/*
	 * Specify the shared memory buffer pool cachesize: 5MB.
	 * Databases are in a subdirectory of the environment home.
	 */
	if ((ret = dbenv-&gt;set_cachesize(dbenv, 0, 5 * 1024 * 1024, 0)) != 0) {
		dbenv-&gt;err(dbenv, ret, "set_cachesize");
		goto err;
	}
	if ((ret = dbenv-&gt;set_data_dir(dbenv, data_dir)) != 0) {
		dbenv-&gt;err(dbenv, ret, "set_data_dir: %s", data_dir);
		goto err;
	}

	/* Open the environment with full transactional support. */
	if ((ret = dbenv-&gt;open(dbenv, home, DB_CREATE |
	 DB_INIT_LOG | DB_INIT_LOCK | DB_INIT_MPOOL | DB_INIT_TXN, 0)) != 0) {
		dbenv-&gt;err(dbenv, ret, "environment open: %s", home);
		goto err;
	}

	return (dbenv);

err:	(void)dbenv-&gt;close(dbenv, 0);
	return (NULL);
}</pre></blockquote>
<table width="100%"><tr><td> </td><td align=right><a href="../env/intro.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../env/open.html"><img src="../../images/next.gif" alt="Next"></a>
</td></tr></table>
Copyright (c) 1996,2008 Oracle. All rights reserved.
</body>
</html>

Back to File Manager