1<!--$Id: db_codegen.so,v 10.6 2007/05/17 18:29:34 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: db_codegen</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> 13<b>db_codegen</b> 14</td> 15</tr></table> 16<hr size=1 noshade> 17<tt> 18<b><pre>db_codegen [<b>-Vv</b>] [<b>-a c</b>] [<b>-i file</b>] [<b>-o file</b>]</pre></b> 19<b>Description</b> 20<a name="2"><!--meow--></a> 21<p>The db_codegen utility generates application code to create and 22configure Berkeley DB database environments and databases based on a simple 23description language, and writes it to one or more output files. The 24generated code may need modification, in the case of complicated 25applications, but will usually significantly reduce the time required 26to create Berkeley DB applications.</p> 27<p>The options are as follows:</p> 28<br> 29<b>-a</b><ul compact><li>Generate code for the specified API (currently, only "c" is accepted).</ul> 30<b>-i</b><ul compact><li>Specify an input file; by default, stdin is used.</ul> 31<b>-o</b><ul compact><li>Specify an output file prefix; by default, "application" is used.</ul> 32<b>-V</b><ul compact><li>Write the library version number to the standard output, and exit.</ul> 33<b>-v</b><ul compact><li>Run in verbose mode.</ul> 34<br> 35<p>The db_codegen utility exits 0 on success, and >0 if an error occurs.</p> 36<b>C Language Specific Information</b> 37<p>By default, when the db_codegen utility generates C-language 38code, the output file is named "application.c". The output filename 39can be specified with <b>-o</b> option.</p> 40<p>At the beginning of the output file is a list of public database 41environment (<a href="../api_c/env_class.html">DB_ENV</a>) handles and database (<a href="../api_c/db_class.html">DB</a>) handles, 42as specified by the description language. The database environment 43handle variables are named "XXX_dbenv", where "XXX" is the name of the 44environment in the input specification. For databases associated with 45a database environment, the database handle variables are named 46"XXX_YYY", where "XXX" is the name of the environment, and "YYY" is the 47name of the database. For standalone databases, the database handle 48variables are named "XXX", where "XXX" is the name of the database.</p> 49<p>There are two public functions in the output file: bdb_startup and 50bdb_shutdown. The bdb_startup function should be called to create and 51configure the database environments and databases, and the bdb_shutdown 52function should be called to gracefully shut down the environments and 53databases.</p> 54<b>Specification Language</b> 55<p>The db_codegen uses a simple description language:</p> 56<p><ul type=disc> 57<li>Lines in the input consist of white-space separated tokens. 58<li>Tokens are case-insensitive. 59<li>Empty lines, and lines where the first non-space character 60is hash mark ("#"). are ignored. In addition, hash marks may appear 61in lines, in which case the content of the line from the hash mark to 62the end of the line is ignored. 63</ul> 64<p>There are two top-level objects: "environment" and "database", which 65correspond to database environments and databases, respectively. These 66top-level objects can be associated with keywords to describe their 67configuration and relationships.</p> 68<p>For example, the following input would create two standalone databases:</p> 69<blockquote><pre>database data_one { 70 type btree 71} 72database data_two { 73 type btree 74}</pre></blockquote> 75<p>In this case, there would be no <a href="../api_c/env_class.html">DB_ENV</a> handle, and the public 76<a href="../api_c/db_class.html">DB</a> handles would be:</p> 77<blockquote><pre>DB *data_one; 78DB *data_two;</pre></blockquote> 79<p>For example, the following input would create a database environment 80which contains three databases:</p> 81<blockquote><pre>environment myenv { 82 database data_one { 83 type btree 84 } 85 database data_two { 86 type btree 87 } 88 database data_three { 89 type btree 90 } 91}</pre></blockquote> 92<p>In this case, the public <a href="../api_c/env_class.html">DB_ENV</a> and <a href="../api_c/db_class.html">DB</a> handles would be:</p> 93<blockquote><pre>DB_ENV *myenv_dbenv; 94DB *myenv_data_one; 95DB *myenv_data_two; 96DB *myenv_data_three;</pre></blockquote> 97<p>A variety of keywords can be specified for the databases and the 98environments. For example, the cache size can be specified for 99the database environment, and the page size can be specified for 100the database, as well as secondary relationships:</p> 101<blockquote><pre>environment myenv { 102 cachesize 2 0 10 103 database data_one { 104 type btree 105 pagesize 1024 106 } 107 database data_two { 108 primary data_one 109 secondary_offset 10 15 110 type btree 111 pagesize 32768 112 } 113 database data_three { 114 type btree 115 pagesize 512 116 } 117}</pre></blockquote> 118<b>Environment Keywords</b> 119<br> 120<b>environment</b><ul compact><li>Start a database environment block. 121<p>There must be three tokens on the line: the keyword, the name of the 122environment and an opening brace ("{").</p></ul> 123<b>home</b><ul compact><li>Specify the database environment home directory. 124<p>There must be two tokens on the line: the keyword, and the home 125directory.</p></ul> 126<b>cachesize</b><ul compact><li>Specify the database environment cache size. 127<p>There must be two tokens on the line: the keyword, the gigabytes of 128cache, the bytes of cache, and the number of caches (the number of 129underlying physical areas into which the cache is logically 130divided).</p></ul> 131<b>private</b><ul compact><li>Specify the database environment is private. 132<p>There must be one token on the line: the keyword by itself.</p></ul> 133<b>}</b><ul compact><li>End the database environment block. 134<p>There must be one token on the line: the keyword by itself.</p></ul> 135<br> 136<b>Database Keywords</b> 137<br> 138<b>database</b><ul compact><li>Start a database block. 139<p>There must be three tokens on the line: the keyword, the name of the 140database and an opening brace ("{").</p></ul> 141<b>custom</b><ul compact><li>Specify a custom key-comparison routine. This is used when the Btree 142database requires a specific sort that db_codegen cannot 143generate. A stub key comparison routine will be created and configured 144for the database which should be modified as necessary. See the 145"key_type" keyword for more information. 146<p>There must be one token on the line: the keyword by itself.</p></ul> 147<b>dupsort</b><ul compact><li>Configure the database to support sorted duplicates. 148<p>There must be one token on the line: the keyword by itself.</p></ul> 149<b>extentsize</b><ul compact><li>Configure the size of the Queue database extent files. 150<p>There must be two tokens on the line: the keyword, and the extent file size, 151as a number of pages.</p></ul> 152<b>key_type</b><ul compact><li>Configure a integral type key-comparison routine. This is used when the 153Btree database Btree database key is an integral type (such as "unsigned 154int", or "u_int32_t"). Any C-language integral type may be specified. 155See the "custom" keyword for more information. A Btree comparison routine 156based on the type of the key will be created and configured. 157<p>There must be two tokens on the line: the keyword, and the type.</p></ul> 158<b>pagesize</b><ul compact><li>Configure the database page size. 159<p>There must be two tokens on the line: the keyword, and the page size 160in bytes.</p></ul> 161<b>primary</b><ul compact><li>Configure the database as a secondary index. A stub secondary callback 162routine will be created and configured for the database, which should 163be modified as necessary. See the "secondary_offset" keyword for more 164information. 165<p>name of the primary database for which this database is a secondary.</p></ul> 166<b>recnum</b><ul compact><li>Configure the Btree database to support record number access. 167<p>There must be one token on the line: the keyword by itself.</p></ul> 168<b>re_len</b><ul compact><li>Configure the record length for a Queue database or a fixed-length Recno 169database. 170<p>There must be two tokens on the line: the keyword, and the length of 171a record, in bytes.</p></ul> 172<b>secondary_offset</b><ul compact><li>Configure a secondary callback routine based on a byte string found in 173the primary database's data item. 174<p>There must be three tokens on the line: the keyword, the byte offset 175from the beginning of the primary data item where the secondary key 176occurs, and the length of the secondary key in bytes.</p></ul> 177<b>transaction</b><ul compact><li>Configure the database (and, by extension, the database environment), 178to be transactional. 179<p>There must be one token on the line: the keyword by itself.</p></ul> 180<b>type</b><ul compact><li>Configure the database type. 181<p>There must be two tokens on the line: the keyword, and the type, where 182the type is one of "btree", "hash", "queue" or "recno".</p></ul> 183<b>}</b><ul compact><li>End the database environment block. 184<p>There must be one token on the line: the keyword by itself.</p></ul> 185<br> 186</tt> 187<p><font size=1>Copyright (c) 1996,2008 Oracle. All rights reserved.</font> 188</body> 189</html> 190