1<!--$Id: data_open.so,v 1.13 2004/04/28 13:15:29 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 databases</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/env_open.html"><img src="/images/prev.gif" alt="Prev"></a><a href="/toc.html"><img src="/images/ref.gif" alt="Ref"></a><a href="/transapp/put.html"><img src="/images/next.gif" alt="Next"></a> 14</td></tr></table> 15<p align=center><b>Opening the databases</b></p> 16<p>Next, we open three databases ("color" and "fruit" and "cats"), in the 17database environment. Again, our <a href="/api_c/db_class.html">DB</a> database handles are 18declared to be free-threaded using the <a href="/api_c/env_open.html#DB_THREAD">DB_THREAD</a> flag, and so 19may be used by any number of threads we subsequently create.</p> 20<blockquote><pre>int 21main(int argc, char *argv) 22{ 23 extern int optind; 24 DB *db_cats, *db_color, *db_fruit; 25 DB_ENV *dbenv; 26 int ch; 27<p> 28 while ((ch = getopt(argc, argv, "")) != EOF) 29 switch (ch) { 30 case '?': 31 default: 32 usage(); 33 } 34 argc -= optind; 35 argv += optind; 36<p> 37 env_dir_create(); 38 env_open(&dbenv); 39<p> 40<b> /* Open database: Key is fruit class; Data is specific type. */ 41 if (db_open(dbenv, &db_fruit, "fruit", 0)) 42 return (1); 43<p> 44 /* Open database: Key is a color; Data is an integer. */ 45 if (db_open(dbenv, &db_color, "color", 0)) 46 return (1); 47<p> 48 /* 49 * Open database: 50 * Key is a name; Data is: company name, cat breeds. 51 */ 52 if (db_open(dbenv, &db_cats, "cats", 1)) 53 return (1);</b> 54<p> 55 return (0); 56} 57<p> 58<b>int 59db_open(DB_ENV *dbenv, DB **dbp, char *name, int dups) 60{ 61 DB *db; 62 int ret; 63<p> 64 /* Create the database handle. */ 65 if ((ret = db_create(&db, dbenv, 0)) != 0) { 66 dbenv->err(dbenv, ret, "db_create"); 67 return (1); 68 } 69<p> 70 /* Optionally, turn on duplicate data items. */ 71 if (dups && (ret = db->set_flags(db, DB_DUP)) != 0) { 72 (void)db->close(db, 0); 73 dbenv->err(dbenv, ret, "db->set_flags: DB_DUP"); 74 return (1); 75 } 76<p> 77 /* 78 * Open a database in the environment: 79 * create if it doesn't exist 80 * free-threaded handle 81 * read/write owner only 82 */ 83 if ((ret = db->open(db, NULL, name, NULL, DB_BTREE, 84 DB_AUTO_COMMIT | DB_CREATE | DB_THREAD, S_IRUSR | S_IWUSR)) != 0) { 85 (void)db->close(db, 0); 86 dbenv->err(dbenv, ret, "db->open: %s", name); 87 return (1); 88 } 89<p> 90 *dbp = db; 91 return (0); 92}</b></pre></blockquote> 93<p>After opening the database, we can use the <a href="/utility/db_stat.html">db_stat</a> utility to 94display information about a database we have created:</p> 95<blockquote><pre>prompt> db_stat -h TXNAPP -d color 9653162 Btree magic number. 978 Btree version number. 98Flags: 992 Minimum keys per-page. 1008192 Underlying database page size. 1011 Number of levels in the tree. 1020 Number of unique keys in the tree. 1030 Number of data items in the tree. 1040 Number of tree internal pages. 1050 Number of bytes free in tree internal pages (0% ff). 1061 Number of tree leaf pages. 1078166 Number of bytes free in tree leaf pages (0.% ff). 1080 Number of tree duplicate pages. 1090 Number of bytes free in tree duplicate pages (0% ff). 1100 Number of tree overflow pages. 1110 Number of bytes free in tree overflow pages (0% ff). 1120 Number of pages on the free list.</pre></blockquote> 113<p>The database open must be enclosed within a transaction in order to be 114recoverable. The transaction will ensure that created files are 115re-created in recovered environments (or do not appear at all). 116Additional database operations or operations on other databases can be 117included in the same transaction, of course. In the simple case, where 118the open is the only operation in the transaction, an application can 119set the <a href="/api_c/env_set_flags.html#DB_AUTO_COMMIT">DB_AUTO_COMMIT</a> flag instead of creating and managing 120its own transaction handle. The <a href="/api_c/env_set_flags.html#DB_AUTO_COMMIT">DB_AUTO_COMMIT</a> flag will 121internally wrap the operation in a transaction, simplifying application 122code.</p> 123<p>The previous example is the simplest case of transaction protection for 124database open. Obviously, additional database operations can be done 125in the scope of the same transaction. For example, an application 126maintaining a list of the databases in a database environment in a 127well-known file might include an update of the list in the same 128transaction in which the database is created. Or, an application might 129create both a primary and secondary database in a single transaction.</p> 130<p><a href="/api_c/db_class.html">DB</a> handles that will later be used for transactionally protected 131database operations must be opened within a transaction. Specifying a 132transaction handle to database operations using <a href="/api_c/db_class.html">DB</a> handles not 133opened within a transaction will return an error. Similarly, not 134specifying a transaction handle to database operations that will modify 135the database, using handles that were opened within a transaction, will 136also return an error.</p> 137<table width="100%"><tr><td><br></td><td align=right><a href="/transapp/env_open.html"><img src="/images/prev.gif" alt="Prev"></a><a href="/toc.html"><img src="/images/ref.gif" alt="Ref"></a><a href="/transapp/put.html"><img src="/images/next.gif" alt="Next"></a> 138</td></tr></table> 139<p><font size=1>Copyright (c) 1996,2008 Oracle. All rights reserved.</font> 140</body> 141</html> 142
