diff options
Diffstat (limited to 'docs/programmer_reference/env_create.html')
| -rw-r--r-- | docs/programmer_reference/env_create.html | 162 |
1 files changed, 102 insertions, 60 deletions
diff --git a/docs/programmer_reference/env_create.html b/docs/programmer_reference/env_create.html index 1b48e5d3..931f589a 100644 --- a/docs/programmer_reference/env_create.html +++ b/docs/programmer_reference/env_create.html @@ -14,17 +14,16 @@ <body> <div xmlns="" class="navheader"> <div class="libver"> - <p>Library Version 11.2.5.3</p> + <p>Library Version 12.1.6.1</p> </div> <table width="100%" summary="Navigation header"> <tr> - <th colspan="3" align="center">Creating a database environment</th> + <th colspan="3" align="center">Creating a database + environment</th> </tr> <tr> <td width="20%" align="left"><a accesskey="p" href="env.html">Prev</a> </td> - <th width="60%" align="center">Chapter 9. - The Berkeley DB Environment - </th> + <th width="60%" align="center">Chapter 9. The Berkeley DB Environment </th> <td width="20%" align="right"> <a accesskey="n" href="env_size.html">Next</a></td> </tr> </table> @@ -34,75 +33,120 @@ <div class="titlepage"> <div> <div> - <h2 class="title" style="clear: both"><a id="env_create"></a>Creating a database environment</h2> + <h2 class="title" style="clear: both"><a id="env_create"></a>Creating a database + environment</h2> </div> </div> </div> - <p>The Berkeley DB environment is created and described by the <a href="../api_reference/C/envcreate.html" class="olink">db_env_create()</a> -and <a href="../api_reference/C/envopen.html" class="olink">DB_ENV->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_reference/C/env.html" class="olink">DB_ENV</a> handle methods.</p> - <p>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.</p> - <p>Applications first obtain an environment handle using the -<a href="../api_reference/C/envcreate.html" class="olink">db_env_create()</a> method, then call the <a href="../api_reference/C/envopen.html" class="olink">DB_ENV->open()</a> method which creates -or joins the database environment. There are a number of options you -can set to customize <a href="../api_reference/C/envopen.html" class="olink">DB_ENV->open()</a> for your environment. These -options fall into four broad categories:</p> + <p> + The Berkeley DB environment is created and described by the + <a href="../api_reference/C/envcreate.html" class="olink">db_env_create()</a> and <a href="../api_reference/C/envopen.html" class="olink">DB_ENV->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_reference/C/env.html" class="olink">DB_ENV</a> handle + methods. + </p> + <p> + 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. + </p> + <p> + Applications first obtain an environment handle using the + <a href="../api_reference/C/envcreate.html" class="olink">db_env_create()</a> method, then call the <a href="../api_reference/C/envopen.html" class="olink">DB_ENV->open()</a> method which + creates or joins the database environment. There are a number + of options you can set to customize <a href="../api_reference/C/envopen.html" class="olink">DB_ENV->open()</a> for your + environment. These options fall into four broad + categories: + </p> <div class="variablelist"> <dl> <dt> <span class="term">Subsystem Initialization:</span> </dt> - <dd>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_reference/C/envopen.html#envopen_DB_INIT_CDB" class="olink">DB_INIT_CDB</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>, <a href="../api_reference/C/envopen.html#envopen_DB_INIT_MPOOL" class="olink">DB_INIT_MPOOL</a>, and <a href="../api_reference/C/envopen.html#envopen_DB_INIT_TXN" class="olink">DB_INIT_TXN</a>. The <a href="../api_reference/C/envopen.html#envopen_DB_INIT_CDB" class="olink">DB_INIT_CDB</a> -flag does initialization for Berkeley DB Concurrent Data Store applications. (See -<a class="xref" href="cam.html#cam_intro" title="Concurrent Data Store introduction">Concurrent Data Store introduction</a> for more -information.) The rest of the flags initialize a single subsystem; that -is, when <a href="../api_reference/C/envopen.html#envopen_DB_INIT_LOCK" class="olink">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.</dd> + <dd> + 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_reference/C/envopen.html#envopen_DB_INIT_CDB" class="olink">DB_INIT_CDB</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>, <a href="../api_reference/C/envopen.html#envopen_DB_INIT_MPOOL" class="olink">DB_INIT_MPOOL</a>, and <a href="../api_reference/C/envopen.html#envopen_DB_INIT_TXN" class="olink">DB_INIT_TXN</a>. The + <a href="../api_reference/C/envopen.html#envopen_DB_INIT_CDB" class="olink">DB_INIT_CDB</a> flag does initialization for Berkeley DB + Concurrent Data Store applications. (See <a class="xref" href="cam.html#cam_intro" title="Concurrent Data Store introduction">Concurrent Data Store + introduction</a> + for more information.) The rest of the flags + initialize a single subsystem; that is, when + <a href="../api_reference/C/envopen.html#envopen_DB_INIT_LOCK" class="olink">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. + </dd> <dt> <span class="term">Recovery options:</span> </dt> - <dd>These flags, which include <a href="../api_reference/C/envopen.html#envopen_DB_RECOVER" class="olink">DB_RECOVER</a> and -<a href="../api_reference/C/envopen.html#envopen_DB_RECOVER_FATAL" class="olink">DB_RECOVER_FATAL</a>, indicate what recovery is to be performed on -the environment before it is opened for normal use.</dd> + <dd> + These flags, which include <a href="../api_reference/C/envopen.html#envopen_DB_RECOVER" class="olink">DB_RECOVER</a> and + <a href="../api_reference/C/envopen.html#envopen_DB_RECOVER_FATAL" class="olink">DB_RECOVER_FATAL</a>, indicate what recovery is to be + performed on the environment before it is opened for + normal use. + </dd> <dt> <span class="term">Naming options:</span> </dt> - <dd>These flags, which include -<a href="../api_reference/C/envopen.html#envopen_DB_USE_ENVIRON" class="olink">DB_USE_ENVIRON</a> and <a href="../api_reference/C/envopen.html#envopen_DB_USE_ENVIRON_ROOT" class="olink">DB_USE_ENVIRON_ROOT</a>, modify how file naming happens in the -environment.</dd> + <dd> + These flags, which include <a href="../api_reference/C/envopen.html#envopen_DB_USE_ENVIRON" class="olink">DB_USE_ENVIRON</a> and + <a href="../api_reference/C/envopen.html#envopen_DB_USE_ENVIRON_ROOT" class="olink">DB_USE_ENVIRON_ROOT</a>, modify how file naming happens + in the environment. + </dd> <dt> <span class="term">Miscellaneous:</span> </dt> - <dd>Finally, there are a number of miscellaneous flags, for example, -<a href="../api_reference/C/dbopen.html#open_DB_CREATE" class="olink">DB_CREATE</a> which causes underlying files to be created as -necessary. See the <a href="../api_reference/C/envopen.html" class="olink">DB_ENV->open()</a> manual pages for further -information.</dd> + <dd> + Finally, there are a number of miscellaneous + flags, for example, <a href="../api_reference/C/dbopen.html#open_DB_CREATE" class="olink">DB_CREATE</a> which causes + underlying files to be created as necessary. See the + <a href="../api_reference/C/envopen.html" class="olink">DB_ENV->open()</a> manual pages for further + information. + </dd> </dl> </div> - <p>Most applications either specify only the <a href="../api_reference/C/envopen.html#envopen_DB_INIT_MPOOL" class="olink">DB_INIT_MPOOL</a> flag or -they specify all four subsystem initialization flags -(<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>). -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.</p> - <p>The <a href="../api_reference/C/envopen.html#envopen_DB_RECOVER" class="olink">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.</p> - <p>The <a href="../api_reference/C/envopen.html#envopen_DB_RECOVER_FATAL" class="olink">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="../api_reference/C/db_recover.html" class="olink">db_recover</a> utility should be used.</p> - <p>The following is a simple example of a function that opens a database -environment for a transactional program.</p> + <p> + Most applications either specify only the <a href="../api_reference/C/envopen.html#envopen_DB_INIT_MPOOL" class="olink">DB_INIT_MPOOL</a> + flag or they specify all four subsystem initialization flags + (<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>). 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. + </p> + <p> + The <a href="../api_reference/C/envopen.html#envopen_DB_RECOVER" class="olink">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. + </p> + <p> + The <a href="../api_reference/C/envopen.html#envopen_DB_RECOVER_FATAL" class="olink">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="../api_reference/C/db_recover.html" class="olink">db_recover</a> utility should be used. + </p> + <p> + The following is a simple example of a function that opens a + database environment for a transactional program. + </p> <a id="prog_env27"></a> <pre class="programlisting">DB_ENV * db_setup(char *home, char *data_dir, FILE *errfp, char *progname) @@ -130,8 +174,8 @@ db_setup(char *home, char *data_dir, FILE *errfp, char *progname) dbenv->err(dbenv, ret, "set_cachesize"); goto err; } - if ((ret = dbenv->set_data_dir(dbenv, data_dir)) != 0) { - dbenv->err(dbenv, ret, "set_data_dir: %s", data_dir); + if ((ret = dbenv->add_data_dir(dbenv, data_dir)) != 0) { + dbenv->err(dbenv, ret, "add_data_dir: %s", data_dir); goto err; } @@ -160,9 +204,7 @@ err: (void)dbenv->close(dbenv, 0); <td width="40%" align="right"> <a accesskey="n" href="env_size.html">Next</a></td> </tr> <tr> - <td width="40%" align="left" valign="top">Chapter 9. - The Berkeley DB Environment - </td> + <td width="40%" align="left" valign="top">Chapter 9. The Berkeley DB Environment </td> <td width="20%" align="center"> <a accesskey="h" href="index.html">Home</a> </td> |