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>Chapter 4. The Dbt Handle</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="index.html" title="Berkeley DB C++ API Reference" /> 11 <link rel="prev" href="dbcset_priority.html" title="Dbc::set_priority()" /> 12 <link rel="next" href="dbmultipleiterator.html" title="DbMultipleIterator" /> 13 </head> 14 <body> 15 <div class="navheader"> 16 <table width="100%" summary="Navigation header"> 17 <tr> 18 <th colspan="3" align="center">Chapter 4. 19 The Dbt Handle 20 </th> 21 </tr> 22 <tr> 23 <td width="20%" align="left"><a accesskey="p" href="dbcset_priority.html">Prev</a> </td> 24 <th width="60%" align="center"> </th> 25 <td width="20%" align="right"> <a accesskey="n" href="dbmultipleiterator.html">Next</a></td> 26 </tr> 27 </table> 28 <hr /> 29 </div> 30 <div class="chapter" lang="en" xml:lang="en"> 31 <div class="titlepage"> 32 <div> 33 <div> 34 <h2 class="title"><a id="dbt"></a>Chapter 4. 35 The Dbt Handle 36 </h2> 37 </div> 38 </div> 39 </div> 40 <pre class="programlisting">#include <db_cxx.h> 41 42class Dbt { 43public: 44 Dbt(void *data, size_t size); 45 Dbt(); 46 Dbt(const Dbt &); 47 Dbt &operator = (const Dbt &); 48 ~Dbt(); 49 50 void *get_data() const; 51 void set_data(void *); 52 53 u_int32_t get_size() const; 54 void set_size(u_int32_t); 55 56 u_int32_t get_ulen() const; 57 void set_ulen(u_int32_t); 58 59 u_int32_t get_dlen() const; 60 void set_dlen(u_int32_t); 61 62 u_int32_t get_doff() const; 63 void set_doff(u_int32_t); 64 65 u_int32_t get_flags() const; 66 void set_flags(u_int32_t); 67 68 DBT *Dbt::get_DBT(); 69 const DBT *Dbt::get_const_DBT() const; 70 static Dbt *Dbt::get_Dbt(DBT *dbt); 71 static const Dbt *Dbt::get_const_Dbt(const DBT *dbt); 72}; </pre> 73 <p> 74 The <code class="classname">Dbt</code> class is used to encode key and data 75 items in a Berkeley DB database. 76 </p> 77 <p> 78 Storage and retrieval for the <a class="link" href="db.html" title="Chapter 2. The Db Handle">Db</a> access methods are 79 based on key/data pairs. Both key and data items are represented by 80 81 <span> 82 <code class="classname">Dbt</code> objects. 83 </span> 84 Key and data byte strings may refer to strings of zero length up to strings of essentially 85 unlimited length. See <a href="../../programmer_reference/am_misc_dbsizes.html" class="olink">Database limits</a> for 86 more information. 87 </p> 88 <p> 89 90 <span> 91 In the case when the <span class="bold"><strong>flags</strong></span> structure element is set to 92 0, 93 </span> 94 95 when the application is providing Berkeley DB a key or data item to store into the database, 96 Berkeley DB expects the <span class="bold"><strong>data</strong></span> 97 98 99 <span> 100 object 101 </span> 102 103 to point to a byte string of <span class="bold"><strong>size</strong></span> bytes. When returning a 104 key/data item to the application, Berkeley DB will store into the <span class="bold"><strong>data</strong></span> 105 106 107 <span> 108 object 109 </span> 110 a pointer to a byte string of <span class="bold"><strong>size</strong></span> bytes, 111 and the memory to which the pointer refers will be 112 allocated and managed by Berkeley DB. Note that using the default flags 113 for returned <code class="classname">Dbt</code>s is only compatible with 114 single threaded usage of Berkeley DB. 115 </p> 116 <p> 117 Access to <code class="classname">Dbt</code> objects is not re-entrant. In particular, if multiple 118 threads simultaneously access the same Dbt object using 119 <a class="link" href="db.html" title="Chapter 2. The Db Handle">Db</a> API calls, the results are undefined, and may 120 result in a crash. One easy way to avoid problems is to use <code class="classname">Dbt</code> 121 objects that are constructed as stack variables. 122 </p> 123 <p> 124 Each <code class="classname">Dbt</code> object has an associated <code class="literal">DBT</code> struct, 125 which is used by the underlying implementation of Berkeley DB and its C-language API. The 126 <code class="methodname">Dbt::get_DBT()</code> method returns a pointer to this struct. Given a 127 const <code class="classname">Dbt</code> object, <code class="methodname">Dbt::get_const_DBT()</code> 128 returns a const pointer to the same struct. 129 </p> 130 <p> 131 Given a <code class="literal">DBT</code> struct, the <code class="methodname">Dbt::get_Dbt()</code> method 132 returns the corresponding <code class="classname">Dbt</code> object, if there is one. If the 133 <code class="literal">DBT</code> object was not associated with a <code class="classname">Dbt</code> (that is, 134 it was not returned from a call to <code class="methodname">Dbt::get_DBT()</code>), then the 135 result of <code class="methodname">Dbt::get_Dbt()</code> is undefined. Given a const 136 <code class="literal">DBT</code> struct, <code class="methodname">Dbt::get_const_Dbt()</code> returns the 137 associated const <code class="classname">Dbt</code> object, if there is one. 138 </p> 139 <p> 140 These methods may be useful for Berkeley DB applications including both C and C++ language 141 software. It should not be necessary to use these calls in a purely C++ application. 142 </p> 143 <div class="itemizedlist"> 144 <ul type="disc"> 145 <li> 146 <p> 147 <code class="methodname">Dbt::set_data(void *data)</code> 148 </p> 149 <p> 150 Set the data array. 151 </p> 152 <p> 153 The <code class="literal">data</code> parameter is an array 154 of bytes to be used to set the content for the 155 <code class="classname">Dbt</code>. 156 </p> 157 </li> 158 <li> 159 <p> 160 <code class="methodname">Dbt::get_data()</code> 161 </p> 162 <p> 163 Return the data array. 164 </p> 165 </li> 166 <li> 167 <p> 168 <code class="methodname">Dbt::set_size(u_int32_t size)</code> 169 </p> 170 <p> 171 Sets the byte size of the data array, in bytes. 172 </p> 173 </li> 174 <li> 175 <p> 176 <code class="methodname">Dbt::get_size()</code> 177 </p> 178 <p> 179 Return the data array size. 180 </p> 181 </li> 182 <li> 183 <p> 184 <code class="methodname">Dbt::set_ulen(u_int32_t value)</code> 185 </p> 186 <p> 187 Set the byte size of the user-specified buffer. 188 </p> 189 <p> 190 Note that applications can determine the length of a record by setting 191 the <code class="literal">ulen</code> field to 0 and checking the return value in the 192 <span class="bold"><strong>size</strong></span> field. See 193 the <code class="literal">DB_DBT_USERMEM</code> flag for more information. 194 </p> 195 </li> 196 <li> 197 <p> 198 <code class="methodname">Dbt::get_ulen()</code> 199 </p> 200 <p> 201 Return the length in bytes of the user-specified 202 buffer. 203 </p> 204 <p> 205 Note that applications can determine the length of a record by setting 206 the <code class="literal">ulen</code> field to 0 and checking the return value in the 207 <span class="bold"><strong>size</strong></span> field. See 208 the <code class="literal">DB_DBT_USERMEM</code> flag for more information. 209 </p> 210 </li> 211 <li> 212 <p> 213 <code class="methodname">Dbt::set_dlen(u_int32_t dlen)</code> 214 </p> 215 <p> 216 217 <span> 218 Set the 219 </span> 220 length of the partial record being read or written by the 221 application, in bytes. See the <code class="literal">DB_DBT_PARTIAL</code> 222 flag for more information. 223 </p> 224 </li> 225 <li> 226 <p> 227 <code class="methodname">Dbt::get_dlen()</code> 228 </p> 229 <p> 230 Return the length of the partial record, in bytes. 231 </p> 232 </li> 233 <li> 234 <p> 235 <code class="methodname">Dbt::set_doff(u_int32_t value)</code> 236 </p> 237 <p> 238 239 <span> 240 Sets the 241 </span> 242 offset of the partial record being read or written by the application, 243 in bytes. See the <code class="literal">DB_DBT_PARTIAL</code> flag for more information. 244 </p> 245 </li> 246 <li> 247 <p> 248 <code class="methodname">Dbt::get_doff()</code> 249 </p> 250 <p> 251 Return the offset of the partial record, in bytes. 252 </p> 253 </li> 254 <li> 255 <p> 256 <code class="methodname">Dbt::set_flags(u_int32_t flags)</code> 257 </p> 258 <p> 259 Set the object flag value. 260 </p> 261 <p> 262 The <span class="bold"><strong>flags</strong></span> parameter must be set to 0 or 263 by bitwise inclusively <span class="bold"><strong>OR</strong></span>'ing together 264 one or more of the following values: 265 </p> 266 <span> 267 <div class="itemizedlist"><ul type="circle"><li><p><a id="dbt_DB_DBT_MALLOC"></a> 268 <code class="literal">DB_DBT_MALLOC</code> 269 </p><p> 270 When this flag is set, Berkeley DB will allocate memory 271 for the returned key or data item (using 272 <span class="bold"><strong>malloc</strong></span>(3), or 273 the user-specified malloc function), and return a 274 pointer to it in the 275 <span class="bold"><strong>data</strong></span> field of the key or data 276 <code class="literal">DBT</code> 277 structure. Because any allocated memory becomes the 278 responsibility of the calling application, the caller 279 must determine whether memory was allocated using the 280 returned value of the 281 <span class="bold"><strong>data</strong></span> field. 282 </p><p> 283 It is an error to specify more than one of 284 <code class="literal">DB_DBT_MALLOC</code>, 285 <code class="literal">DB_DBT_REALLOC</code>, and 286 <code class="literal">DB_DBT_USERMEM</code>. 287 </p></li><li><p><a id="dbt_DB_DBT_REALLOC"></a> 288 <code class="literal">DB_DBT_REALLOC</code> 289 </p><p> 290 When this flag is set Berkeley DB will allocate memory 291 for the returned key or data item (using 292 <span class="bold"><strong>realloc</strong></span>(3), or 293 the user-specified realloc function), and return a 294 pointer to it in the 295 <span class="bold"><strong>data</strong></span> field of the key or data DBT 296 structure. Because any allocated memory becomes the 297 responsibility of the calling application, the caller 298 must determine whether memory was allocated using the 299 returned value of the 300 <span class="bold"><strong>data</strong></span> field. 301 </p><p> 302 It is an error to specify more than one of 303 <code class="literal">DB_DBT_MALLOC</code>, 304 <code class="literal">DB_DBT_REALLOC</code>, and 305 <code class="literal">DB_DBT_USERMEM</code>. 306 </p></li><li><p><a id="dbt_DB_DBT_USERMEM"></a> 307 <code class="literal">DB_DBT_USERMEM</code> 308 </p><p> 309 The <span class="emphasis"><em>data</em></span> 310 field of the key or data structure must refer 311 to memory that is at least 312 <span class="emphasis"><em>ulen</em></span> 313 bytes in length. If the 314 length of the requested item is less than or equal to 315 that number of bytes, the item is copied into the memory 316 to which the 317 <span class="emphasis"><em>data</em></span> 318 field refers. Otherwise, the 319 <span class="emphasis"><em>size</em></span> 320 field is set to the length needed for the requested 321 item, and the error 322 <code class="literal">DB_BUFFER_SMALL</code> is returned. 323 </p><p> 324 It is an error to specify more than one of 325 <code class="literal">DB_DBT_MALLOC</code>, 326 <code class="literal">DB_DBT_REALLOC</code>, and 327 <code class="literal">DB_DBT_USERMEM</code>. 328 </p></li></ul></div> 329 330 <span> 331 <p> 332 If <code class="literal">DB_DBT_MALLOC</code> or 333 <code class="literal">DB_DBT_REALLOC</code> is specified, Berkeley DB 334 allocates a properly sized byte array to contain the data. This 335 can be convenient if you know little about the nature of the 336 data, specifically the size of data in the database. However, if 337 your application makes repeated calls to retrieve keys or data, 338 you may notice increased garbage collection due to this 339 allocation. If you know the maximum size of data you are 340 retrieving, you might decrease the memory burden and speed your 341 application by allocating your own byte array and using 342 <code class="literal">DB_DBT_USERMEM</code>. Even if you don't know the 343 maximum size, you can use this option and reallocate your array 344 whenever your retrieval API call returns an 345 <code class="literal">DB_BUFFER_SMALL</code> error or throws an exception 346 encapsulating an <code class="literal">DB_BUFFER_SMALL</code>. 347 </p> 348 </span> 349 <div class="itemizedlist"><ul type="circle"><li><p><a id="dbt_DB_DBT_PARTIAL"></a> 350 <code class="literal">DB_DBT_PARTIAL</code> 351 </p><p> 352 Do partial retrieval or storage of an item. If the 353 calling application is doing a get, the 354 <span class="bold"><strong>dlen</strong></span> bytes 355 starting 356 <span class="bold"><strong>doff</strong></span> 357 bytes from the beginning of the retrieved 358 data record are returned as if they comprised the entire 359 record. If any or all of the specified bytes do not 360 exist in the record, the get is successful, and any 361 existing bytes are returned. 362 </p><p> 363 For example, if the data portion of a retrieved record 364 was 100 bytes, and a partial retrieval was done using a 365 DBT having a 366 <span class="bold"><strong>dlen</strong></span> 367 field of 20 and a 368 <span class="bold"><strong>doff</strong></span> 369 field of 85, 370 the get call would succeed, the 371 <span class="bold"><strong>data</strong></span> 372 field would refer 373 to the last 15 bytes of the record, and the 374 <span class="bold"><strong>size</strong></span> 375 field would be set to 15. 376 </p><p> 377 If the calling application is doing a put, the 378 <span class="bold"><strong>dlen</strong></span> 379 bytes starting 380 <span class="bold"><strong>doff</strong></span> 381 bytes from the beginning of the 382 specified key's data record are replaced by the data 383 specified by the 384 <span class="bold"><strong>data</strong></span> 385 and 386 <span class="bold"><strong>size</strong></span> 387 structure elements. If 388 <span class="bold"><strong>dlen</strong></span> 389 is smaller than 390 <span class="bold"><strong>size</strong></span> 391 the record will grow; if 392 <span class="bold"><strong>dlen</strong></span> 393 is larger than 394 <span class="bold"><strong>size</strong></span> 395 the record will shrink. If the 396 specified bytes do not exist, the record will be 397 extended using nul bytes as necessary, and the put call 398 will succeed. 399 </p><p> 400 It is an error to attempt a partial put using the 401 <a class="xref" href="dbput.html" title="Db::put()">Db::put()</a> 402 method in a database that supports duplicate 403 records. Partial puts in databases supporting duplicate 404 records must be done using a 405 <a class="xref" href="dbcput.html" title="Dbc::put()">Dbc::put()</a> 406 method. 407 </p><p> 408 It is an error to attempt a partial put with differing 409 <span class="bold"><strong>dlen</strong></span> 410 and 411 <span class="bold"><strong>size</strong></span> 412 values in Queue or Recno databases with 413 fixed-length records. 414 </p><p> 415 For example, if the data portion of a retrieved record 416 was 100 bytes, and a partial put was done using a DBT 417 having a 418 <span class="bold"><strong>dlen</strong></span> 419 field of 20, a 420 <span class="bold"><strong>doff</strong></span> 421 field of 85, and a 422 <span class="bold"><strong>size</strong></span> 423 field of 30, the resulting record would be 115 424 bytes in length, where the last 30 bytes would be those 425 specified by the put call. 426 </p></li><li><p><a id="dbt_DB_DBT_APPMALLOC"></a> 427 <code class="literal">DB_DBT_APPMALLOC</code> 428 </p><p> 429 After an application-supplied callback routine passed to 430 either 431 <a class="xref" href="dbassociate.html" title="Db::associate()">Db::associate()</a> 432 or 433 <a class="xref" href="dbset_append_recno.html" title="Db::set_append_recno()">Db::set_append_recno()</a> 434 is executed, the 435 <span class="bold"><strong>data</strong></span> 436 field of a DBT may refer to memory allocated with 437 <span class="bold"><strong>malloc</strong></span>(3) 438 or 439 <span class="bold"><strong>realloc</strong></span>(3). 440 In that case, 441 the callback sets the 442 <code class="literal">DB_DBT_APPMALLOC</code> 443 flag in the DBT 444 so that Berkeley DB will call 445 <span class="bold"><strong>free</strong></span>(3) 446 to deallocate the 447 memory when it is no longer required. 448 </p></li><li><p><a id="dbt_DB_DBT_MULTIPLE"></a> 449 <code class="literal">DB_DBT_MULTIPLE</code> 450 </p><p> 451 Set in a secondary key creation callback routine passed 452 to 453 <a class="xref" href="dbassociate.html" title="Db::associate()">Db::associate()</a> 454 to indicate that multiple secondary 455 keys should be associated with the given primary 456 key/data pair. If set, the 457 <span class="bold"><strong>size</strong></span> 458 field indicates the 459 number of secondary keys and the 460 <span class="bold"><strong>data</strong></span> 461 field refers to an 462 array of that number of DBT structures. 463 </p><p> 464 The <code class="literal">DB_DBT_APPMALLOC</code> flag may be set on any of the DBT 465 structures to indicate that their 466 <span class="bold"><strong>data</strong></span> 467 field needs to be 468 freed. 469 </p></li></ul></div> 470</span> 471 </li> 472 </ul> 473 </div> 474 <div class="sect1" lang="en" xml:lang="en"> 475 <div class="titlepage"> 476 <div> 477 <div> 478 <h2 class="title" style="clear: both"><a id="dbtlist"></a>DBT and Bulk Operations</h2> 479 </div> 480 </div> 481 </div> 482 <div class="navtable"> 483 <table border="1" width="80%"> 484 <thead> 485 <tr> 486 <th>DBT and Bulk Operations</th> 487 <th>Description</th> 488 </tr> 489 </thead> 490 <tbody> 491 <tr> 492 <td> 493 <a class="xref" href="dbmultipleiterator.html" title="DbMultipleIterator">DbMultipleIterator</a> 494 </td> 495 <td>Base class for bulk get retrieval</td> 496 </tr> 497 <tr> 498 <td> 499 <a class="xref" href="dbmultipledataiterator.html" title="DbMultipleDataIterator">DbMultipleDataIterator</a> 500 </td> 501 <td>Bulk retrieval iterator for data items</td> 502 </tr> 503 <tr> 504 <td> 505 <a class="xref" href="dbmultiplekeydataiterator.html" title="DbMultipleKeyDataIterator">DbMultipleKeyDataIterator</a> 506 </td> 507 <td>Bulk retrieval iterator for key/data pairs</td> 508 </tr> 509 <tr> 510 <td> 511 <a class="xref" href="dbmultiplerecnodataiterator.html" title="DbMultipleRecnoDataIterator">DbMultipleRecnoDataIterator</a> 512 </td> 513 <td>Bulk retrieval iterator for record number / data item pairs</td> 514 </tr> 515 <tr> 516 <td> 517 <a class="xref" href="dbmultiplebuilder.html" title="DbMultipleBuilder">DbMultipleBuilder</a> 518 </td> 519 <td>Base class for bulk buffer building</td> 520 </tr> 521 <tr> 522 <td> 523 <a class="xref" href="dbmultipledatabuilder.html" title="DbMultipleDataBuilder">DbMultipleDataBuilder</a> 524 </td> 525 <td>Bulk buffer builder for data items</td> 526 </tr> 527 <tr> 528 <td> 529 <a class="xref" href="dbmultiplekeydatabuilder.html" title="DbMultipleKeyDataBuilder">DbMultipleKeyDataBuilder</a> 530 </td> 531 <td>Bulk buffer builder for key/data pairs</td> 532 </tr> 533 <tr> 534 <td> 535 <a class="xref" href="dbmultiplerecnodatabuilder.html" title="DbMultipleRecnoDataBuilder">DbMultipleRecnoDataBuilder</a> 536 </td> 537 <td>Bulk buffer builder for record number / data pairs</td> 538 </tr> 539 </tbody> 540 </table> 541 </div> 542 </div> 543 </div> 544 <div class="navfooter"> 545 <hr /> 546 <table width="100%" summary="Navigation footer"> 547 <tr> 548 <td width="40%" align="left"><a accesskey="p" href="dbcset_priority.html">Prev</a> </td> 549 <td width="20%" align="center"> </td> 550 <td width="40%" align="right"> <a accesskey="n" href="dbmultipleiterator.html">Next</a></td> 551 </tr> 552 <tr> 553 <td width="40%" align="left" valign="top">Dbc::set_priority() </td> 554 <td width="20%" align="center"> 555 <a accesskey="h" href="index.html">Home</a> 556 </td> 557 <td width="40%" align="right" valign="top"> DbMultipleIterator</td> 558 </tr> 559 </table> 560 </div> 561 </body> 562</html> 563