1<!--$Id: env_open.so,v 1.4 2002/06/24 14:51:07 bostic Exp $--> 2<!--Copyright (c) 1997,2008 Oracle. All rights reserved.--> 3<!--See the file LICENSE for redistribution information.--> 4<html> 5<head> 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,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,Java,C,C++"> 9</head> 10<body bgcolor=white> 11<table width="100%"><tr valign=top> 12<td><b><dl><dt>Berkeley DB Reference Guide:<dd>Berkeley DB Transactional Data Store Applications</dl></b></td> 13<td align=right><a href="/transapp/app.html"><img src="/images/prev.gif" alt="Prev"></a><a href="/toc.html"><img src="/images/ref.gif" alt="Ref"></a><a href="/transapp/data_open.html"><img src="/images/next.gif" alt="Next"></a> 14</td></tr></table> 15<p align=center><b>Opening the environment</b></p> 16<p>Creating transaction-protected applications using the Berkeley DB library is 17quite easy. Applications first use <a href="/api_c/env_open.html">DB_ENV->open</a> to initialize 18the database environment. Transaction-protected applications normally 19require all four Berkeley DB subsystems, so the <a href="/api_c/env_open.html#DB_INIT_MPOOL">DB_INIT_MPOOL</a>, 20<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 21should be specified.</p> 22<p>Once the application has called <a href="/api_c/env_open.html">DB_ENV->open</a>, it opens its 23databases within the environment. Once the databases are opened, the 24application makes changes to the databases inside of transactions. Each 25set of changes that entails a unit of work should be surrounded by the 26appropriate <a href="/api_c/txn_begin.html">DB_ENV->txn_begin</a>, <a href="/api_c/txn_commit.html">DB_TXN->commit</a>, and <a href="/api_c/txn_abort.html">DB_TXN->abort</a> 27calls. The Berkeley DB access methods will make the appropriate calls into 28the Lock, Log and Memory Pool subsystems in order to guarantee 29transaction semantics. When the application is ready to exit, all 30outstanding transactions should have been committed or aborted.</p> 31<p>Databases accessed by a transaction must not be closed during the 32transaction. Once all outstanding transactions are finished, all open 33Berkeley DB files should be closed. When the Berkeley DB database files have been 34closed, the environment should be closed by calling 35<a href="/api_c/env_close.html">DB_ENV->close</a>.</p> 36<p>The following code fragment creates the database environment directory 37then opens the environment, running recovery. Our <a href="/api_c/env_class.html">DB_ENV</a> 38database environment handle is declared to be free-threaded using the 39<a href="/api_c/env_open.html#DB_THREAD">DB_THREAD</a> flag, and so may be used by any number of threads that 40we may subsequently create.</p> 41<blockquote><pre>#include <sys/types.h> 42#include <sys/stat.h> 43<p> 44#include <errno.h> 45#include <stdarg.h> 46#include <stdlib.h> 47#include <string.h> 48#include <unistd.h> 49<p> 50#include <db.h> 51<p> 52#define ENV_DIRECTORY "TXNAPP" 53<p> 54void env_dir_create(void); 55void env_open(DB_ENV **); 56<p> 57int 58main(int argc, char *argv) 59{ 60 extern int optind; 61 DB *db_cats, *db_color, *db_fruit; 62 DB_ENV *dbenv; 63 int ch; 64<p> 65 while ((ch = getopt(argc, argv, "")) != EOF) 66 switch (ch) { 67 case '?': 68 default: 69 usage(); 70 } 71 argc -= optind; 72 argv += optind; 73<p> 74 env_dir_create(); 75 env_open(&dbenv); 76<p> 77 return (0); 78} 79<p> 80void 81env_dir_create() 82{ 83 struct stat sb; 84<p> 85 /* 86 * If the directory exists, we're done. We do not further check 87 * the type of the file, DB will fail appropriately if it's the 88 * wrong type. 89 */ 90 if (stat(ENV_DIRECTORY, &sb) == 0) 91 return; 92<p> 93 /* Create the directory, read/write/access owner only. */ 94 if (mkdir(ENV_DIRECTORY, S_IRWXU) != 0) { 95 fprintf(stderr, 96 "txnapp: mkdir: %s: %s\n", ENV_DIRECTORY, strerror(errno)); 97 exit (1); 98 } 99} 100<p> 101void 102env_open(DB_ENV **dbenvp) 103{ 104 DB_ENV *dbenv; 105 int ret; 106<p> 107 /* Create the environment handle. */ 108 if ((ret = db_env_create(&dbenv, 0)) != 0) { 109 fprintf(stderr, 110 "txnapp: db_env_create: %s\n", db_strerror(ret)); 111 exit (1); 112 } 113<p> 114 /* Set up error handling. */ 115 dbenv->set_errpfx(dbenv, "txnapp"); 116 dbenv->set_errfile(dbenv, stderr); 117<p> 118 /* 119 * Open a transactional environment: 120 * create if it doesn't exist 121 * free-threaded handle 122 * run recovery 123 * read/write owner only 124 */ 125 if ((ret = dbenv->open(dbenv, ENV_DIRECTORY, 126 DB_CREATE | DB_INIT_LOCK | DB_INIT_LOG | 127 DB_INIT_MPOOL | DB_INIT_TXN | DB_RECOVER | DB_THREAD, 128 S_IRUSR | S_IWUSR)) != 0) { 129 (void)dbenv->close(dbenv, 0); 130 fprintf(stderr, "dbenv->open: %s: %s\n", 131 ENV_DIRECTORY, db_strerror(ret)); 132 exit (1); 133 } 134<p> 135 *dbenvp = dbenv; 136}</pre></blockquote> 137<p>After running this initial program, we can use the <a href="/utility/db_stat.html">db_stat</a> 138utility to display the contents of the environment directory:</p> 139<blockquote><pre>prompt> db_stat -e -h TXNAPP 1403.2.1 Environment version. 141120897 Magic number. 1420 Panic value. 1431 References. 1446 Locks granted without waiting. 1450 Locks granted after waiting. 146=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 147Mpool Region: 4. 148264KB Size (270336 bytes). 149-1 Segment ID. 1501 Locks granted without waiting. 1510 Locks granted after waiting. 152=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 153Log Region: 3. 15496KB Size (98304 bytes). 155-1 Segment ID. 1563 Locks granted without waiting. 1570 Locks granted after waiting. 158=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 159Lock Region: 2. 160240KB Size (245760 bytes). 161-1 Segment ID. 1621 Locks granted without waiting. 1630 Locks granted after waiting. 164=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 165Txn Region: 5. 1668KB Size (8192 bytes). 167-1 Segment ID. 1681 Locks granted without waiting. 1690 Locks granted after waiting.</pre></blockquote> 170<table width="100%"><tr><td><br></td><td align=right><a href="/transapp/app.html"><img src="/images/prev.gif" alt="Prev"></a><a href="/toc.html"><img src="/images/ref.gif" alt="Ref"></a><a href="/transapp/data_open.html"><img src="/images/next.gif" alt="Next"></a> 171</td></tr></table> 172<p><font size=1>Copyright (c) 1996,2008 Oracle. All rights reserved.</font> 173</body> 174</html> 175
