1<?xml version="1.0" encoding="UTF-8" standalone="no"?> 2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 3<html xmlns="http://www.w3.org/1999/xhtml"> 4 <head> 5 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> 6 <title>db_codegen</title> 7 <link rel="stylesheet" href="apiReference.css" type="text/css" /> 8 <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /> 9 <link rel="start" href="index.html" title="Berkeley DB C++ API Reference" /> 10 <link rel="up" href="utilities.html" title="Appendix 1. Berkeley DB Command Line Utilities" /> 11 <link rel="prev" href="db_checkpoint.html" title="db_checkpoint" /> 12 <link rel="next" href="db_deadlock.html" title="db_deadlock" /> 13 </head> 14 <body> 15 <div class="navheader"> 16 <table width="100%" summary="Navigation header"> 17 <tr> 18 <th colspan="3" align="center">db_codegen</th> 19 </tr> 20 <tr> 21 <td width="20%" align="left"><a accesskey="p" href="db_checkpoint.html">Prev</a> </td> 22 <th width="60%" align="center">Appendix 1. 23 Berkeley DB Command Line Utilities 24 </th> 25 <td width="20%" align="right"> <a accesskey="n" href="db_deadlock.html">Next</a></td> 26 </tr> 27 </table> 28 <hr /> 29 </div> 30 <div class="sect1" lang="en" xml:lang="en"> 31 <div class="titlepage"> 32 <div> 33 <div> 34 <h2 class="title" style="clear: both"><a id="db_codegen"></a>db_codegen</h2> 35 </div> 36 </div> 37 </div> 38 <pre class="programlisting">db_codegen [-Vv] [-a c] [-i file] [-o file] </pre> 39 <p> 40 The <span class="command"><strong>db_codegen</strong></span> utility generates application code to create and configure 41 Berkeley DB database environments and databases based on a simple description language, and 42 writes it to one or more output files. The generated code may need modification, in the case 43 of complicated applications, but will usually significantly reduce the time required to 44 create Berkeley DB applications. 45 </p> 46 <p> 47 The options are as follows: 48 </p> 49 <div class="itemizedlist"> 50 <ul type="disc"> 51 <li> 52 <p> 53 <span class="bold"><strong>-a</strong></span> 54 </p> 55 <p> 56 Generate code for the specified API ("c" is the default). 57 </p> 58 </li> 59 <li> 60 <p> 61 <span class="bold"><strong>-i</strong></span> 62 </p> 63 <p> 64 Specify an input file; by default, stdin is used. 65 </p> 66 </li> 67 <li> 68 <p> 69 <span class="bold"><strong>-o</strong></span> 70 </p> 71 <p> 72 Specify an output file prefix; by default, "application" is used. 73 </p> 74 </li> 75 <li> 76 <p> 77 <span class="bold"><strong>-V</strong></span> 78 </p> 79 <p> 80 Write the library version number to the standard output, and exit. 81 </p> 82 </li> 83 <li> 84 <p> 85 <span class="bold"><strong>-v</strong></span> 86 </p> 87 <p> 88 Run in verbose mode. 89 </p> 90 </li> 91 </ul> 92 </div> 93 <p> 94 The <span class="command"><strong>db_codegen</strong></span> utility exits 0 on success, and >0 if an error occurs. 95 </p> 96 <div class="sect2" lang="en" xml:lang="en"> 97 <div class="titlepage"> 98 <div> 99 <div> 100 <h3 class="title"><a id="id1718217"></a>C Language Specific Information</h3> 101 </div> 102 </div> 103 </div> 104 <p> 105 By default, when the <span class="command"><strong>db_codegen</strong></span> utility generates C-language code, 106 the output file is named "application.c". The output filename can be specified with 107 <span class="bold"><strong>-o</strong></span> option. 108 </p> 109 <p> 110 At the beginning of the output file is a list of public database environment 111 — <a class="link" href="env.html" title="Chapter 5. The DbEnv Handle">DbEnv</a> — handles and database 112 — <a class="link" href="db.html" title="Chapter 2. The Db Handle">Db</a> — handles, as specified by the description 113 language. The database environment handle variables are named "XXX_dbenv", where "XXX" 114 is the name of the environment in the input specification. For databases associated with 115 a database environment, the database handle variables are named "XXX_YYY", where "XXX" 116 is the name of the environment, and "YYY" is the name of the database. For standalone 117 databases, the database handle variables are named "XXX", where "XXX" is the name of the 118 database. 119 </p> 120 <p> 121 There are two public functions in the output file: <code class="function">bdb_startup</code> and 122 <code class="function">bdb_shutdown</code>. The bdb_startup function should be called to create 123 and configure the database environments and databases, and the bdb_shutdown function 124 should be called to gracefully shut down the environments and databases. 125 </p> 126 </div> 127 <div class="sect2" lang="en" xml:lang="en"> 128 <div class="titlepage"> 129 <div> 130 <div> 131 <h3 class="title"><a id="id1718413"></a>Specification Language</h3> 132 </div> 133 </div> 134 </div> 135 <p> 136 The <span class="command"><strong>db_codegen</strong></span> utility uses a simple description language: 137 </p> 138 <div class="itemizedlist"> 139 <ul type="disc"> 140 <li> 141 <p> 142 Lines in the input consist of white-space separated tokens. 143 </p> 144 </li> 145 <li> 146 <p> 147 Tokens are case-insensitive. 148 </p> 149 </li> 150 <li> 151 <p> 152 Empty lines, and lines where the first non-space character is hash mark ("#") 153 are ignored. In addition, hash marks may appear in lines, in which case the 154 content of the line from the hash mark to the end of the line is ignored. 155 </p> 156 </li> 157 </ul> 158 </div> 159 <p> 160 There are two top-level objects: "environment" and "database", which correspond to 161 database environments and databases, respectively. These top-level objects can be 162 associated with keywords to describe their configuration and relationships. 163 </p> 164 <p> 165 For example, the following input would create two standalone databases: 166 </p> 167 <pre class="programlisting"> database data_one { 168 type btree 169 } 170 database data_two { 171 type btree 172 } </pre> 173 <p> 174 In this case, there would be no <a class="link" href="env.html" title="Chapter 5. The DbEnv Handle">DbEnv</a> handle, and 175 the public <a class="link" href="db.html" title="Chapter 2. The Db Handle">Db</a> handles would be: 176 </p> 177 <pre class="programlisting"> DB *data_one; 178 DB *data_two; </pre> 179 <p> 180 For example, the following input would create a database environment which contains 181 three databases: 182 </p> 183 <pre class="programlisting"> environment myenv { 184 database data_one { 185 type btree 186 } 187 database data_two { 188 type btree 189 } 190 database data_three { 191 type btree 192 } 193 } </pre> 194 <p> 195 In this case, the public <a class="link" href="db.html" title="Chapter 2. The Db Handle">Db</a> handles would be: 196 </p> 197 <pre class="programlisting"> DB_ENV *myenv_dbenv; 198 DB *myenv_data_one; 199 DB *myenv_data_two; 200 DB *myenv_data_three; </pre> 201 <p> 202 A variety of keywords can be specified for the databases and the environments. For 203 example, the cache size can be specified for the database environment, and the page size 204 can be specified for the database, as well as secondary relationships: 205 </p> 206 <pre class="programlisting"> environment myenv { 207 cachesize 2 0 10 208 database data_one { 209 type btree 210 pagesize 1024 211 } 212 database data_two { 213 primary data_one 214 secondary_offset 10 15 215 type btree 216 pagesize 32768 217 } 218 database data_three { 219 type btree 220 pagesize 512 221 } 222 } </pre> 223 </div> 224 <div class="sect2" lang="en" xml:lang="en"> 225 <div class="titlepage"> 226 <div> 227 <div> 228 <h3 class="title"><a id="id1718366"></a>Environment Keywords</h3> 229 </div> 230 </div> 231 </div> 232 <p> 233 The following are the keywords that you use to configure database environments: 234 </p> 235 <div class="itemizedlist"> 236 <ul type="disc"> 237 <li> 238 <p> 239 <code class="literal">environment</code> 240 </p> 241 <p> 242 Start a database environment block. 243 </p> 244 <p> 245 There must be three tokens on the line: the keyword, the name of the environment 246 and an opening brace (<code class="literal">{</code>). 247 </p> 248 </li> 249 <li> 250 <p> 251 <code class="literal">home</code> 252 </p> 253 <p> 254 Specify the database environment home directory. 255 </p> 256 <p> 257 There must be two tokens on the line: the keyword, and the home directory. 258 </p> 259 </li> 260 <li> 261 <p> 262 <code class="literal">cachesize</code> 263 </p> 264 <p> 265 Specify the database environment cache size. 266 </p> 267 <p> 268 There must be four tokens on the line: the keyword, the gigabytes of cache, the 269 bytes of cache, and the number of caches (the number of underlying physical 270 areas into which the cache is logically divided). 271 </p> 272 </li> 273 <li> 274 <p> 275 <code class="literal">private</code> 276 </p> 277 <p> 278 Specify the database environment is private. 279 </p> 280 <p> 281 There must be one token on the line: the keyword by itself. 282 </p> 283 </li> 284 <li> 285 <p> 286 <code class="literal">}</code> 287 </p> 288 <p> 289 End the database environment block. 290 </p> 291 <p> 292 There must be one token on the line: the keyword by itself. 293 </p> 294 </li> 295 </ul> 296 </div> 297 </div> 298 <div class="sect2" lang="en" xml:lang="en"> 299 <div class="titlepage"> 300 <div> 301 <div> 302 <h3 class="title"><a id="id1718588"></a>Database Keywords</h3> 303 </div> 304 </div> 305 </div> 306 <p> 307 The following keywords are used to configure databases. 308 </p> 309 <div class="itemizedlist"> 310 <ul type="disc"> 311 <li> 312 <p> 313 <code class="literal">database</code> 314 </p> 315 <p> 316 Start a database block. 317 </p> 318 <p> 319 There must be three tokens on the line: the keyword, the name of the database 320 and an opening brace (<code class="literal">{</code>). 321 </p> 322 </li> 323 <li> 324 <p> 325 <code class="literal">custom</code> 326 </p> 327 <p> 328 Specify a custom key-comparison routine. This is used when the Btree database 329 requires a specific sort that db_codegen cannot generate. A stub key comparison 330 routine will be created and configured for the database which should be modified 331 as necessary. See the "key_type" keyword for more information. 332 </p> 333 <p> 334 There must be one token on the line: the keyword by itself. 335 </p> 336 </li> 337 <li> 338 <p> 339 <code class="literal">dupsort</code> 340 </p> 341 <p> 342 Configure the database to support sorted duplicates. 343 </p> 344 <p> 345 There must be one token on the line: the keyword by itself. 346 </p> 347 </li> 348 <li> 349 <p> 350 <code class="literal">extentsize</code> 351 </p> 352 <p> 353 Configure the size of the Queue database extent files. 354 </p> 355 <p> 356 There must be two tokens on the line: the keyword, and the extent file size, as 357 a number of pages. 358 </p> 359 </li> 360 <li> 361 <p> 362 <code class="literal">key_type</code> 363 </p> 364 <p> 365 Configure a integral type key-comparison routine. This is used when the Btree 366 database Btree database key is an integral type (such as "unsigned int", or 367 "u_int32_t"). Any C-language integral type may be specified. See the "custom" 368 keyword for more information. A Btree comparison routine based on the type of 369 the key will be created and configured. 370 </p> 371 <p> 372 There must be two tokens on the line: the keyword, and the type. 373 </p> 374 </li> 375 <li> 376 <p> 377 <code class="literal">pagesize</code> 378 </p> 379 <p> 380 Configure the database page size. 381 </p> 382 <p> 383 There must be two tokens on the line: the keyword, and the page size in bytes. 384 </p> 385 </li> 386 <li> 387 <p> 388 <code class="literal">primary</code> 389 </p> 390 <p> 391 Configure the database as a secondary index. A stub secondary callback routine 392 will be created and configured for the database, which should be modified as 393 necessary. See the "secondary_offset" keyword for more information. 394 </p> 395 <p> 396 There must be two tokens on the line: the keyword and the name of the primary database 397 for which this database is a secondary. 398 </p> 399 </li> 400 <li> 401 <p> 402 <code class="literal">recnum</code> 403 </p> 404 <p> 405 Configure the Btree database to support record number access. 406 </p> 407 <p> 408 There must be one token on the line: the keyword by itself. 409 </p> 410 </li> 411 <li> 412 <p> 413 <code class="literal">re_len</code> 414 </p> 415 <p> 416 Configure the record length for a Queue database or a fixed-length Recno 417 database. 418 </p> 419 <p> 420 There must be two tokens on the line: the keyword, and the length of a record, 421 in bytes. 422 </p> 423 </li> 424 <li> 425 <p> 426 <code class="literal">secondary_offset</code> 427 </p> 428 <p> 429 Configure a secondary callback routine based on a byte string found in the 430 primary database's data item. 431 </p> 432 <p> 433 There must be three tokens on the line: the keyword, the byte offset from the 434 beginning of the primary data item where the secondary key begins, and the 435 length of the secondary key in bytes. 436 </p> 437 </li> 438 <li> 439 <p> 440 <code class="literal">transaction</code> 441 </p> 442 <p> 443 Configure the database (and, by extension, the database environment), to be 444 transactional. 445 </p> 446 <p> 447 There must be one token on the line: the keyword by itself. 448 </p> 449 </li> 450 <li> 451 <p> 452 <code class="literal">type</code> 453 </p> 454 <p> 455 Configure the database type. 456 </p> 457 <p> 458 There must be two tokens on the line: the keyword, and the type, where the type 459 is one of <code class="literal">btree</code>, <code class="literal">hash</code>, 460 <code class="literal">queue</code> or <code class="literal">recno</code>. 461 </p> 462 </li> 463 <li> 464 <p> 465 <code class="literal">}</code> 466 </p> 467 <p> 468 End the database environment block. 469 </p> 470 <p> 471 There must be one token on the line: the keyword by itself. 472 </p> 473 </li> 474 </ul> 475 </div> 476 </div> 477 </div> 478 <div class="navfooter"> 479 <hr /> 480 <table width="100%" summary="Navigation footer"> 481 <tr> 482 <td width="40%" align="left"><a accesskey="p" href="db_checkpoint.html">Prev</a> </td> 483 <td width="20%" align="center"> 484 <a accesskey="u" href="utilities.html">Up</a> 485 </td> 486 <td width="40%" align="right"> <a accesskey="n" href="db_deadlock.html">Next</a></td> 487 </tr> 488 <tr> 489 <td width="40%" align="left" valign="top">db_checkpoint </td> 490 <td width="20%" align="center"> 491 <a accesskey="h" href="index.html">Home</a> 492 </td> 493 <td width="40%" align="right" valign="top"> db_deadlock</td> 494 </tr> 495 </table> 496 </div> 497 </body> 498</html> 499