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="DBcursor->set_priority()" /> 12 <link rel="next" href="DB_MULTIPLE_INIT.html" title="DB_MULTIPLE_INIT" /> 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="DB_MULTIPLE_INIT.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.h> 41 42 typedef struct { 43 void *data; 44 u_int32_t size; 45 u_int32_t ulen; 46 u_int32_t dlen; 47 u_int32_t doff; 48 u_int32_t flags; 49 } DBT; 50 51 </pre> 52 <p> 53 Storage and retrieval for the <a class="link" href="db.html" title="Chapter 2. The DB Handle">DB</a> access methods are 54 based on key/data pairs. Both key and data items are represented by 55 <span> 56 the DBT data structure. (The name DBT is a mnemonic for data base thang, and was used 57 because no one could think of a reasonable name that wasn't already in use somewhere 58 else.) 59 </span> 60 61 Key and data byte strings may refer to strings of zero length up to strings of essentially 62 unlimited length. See <a href="../../programmer_reference/am_misc_dbsizes.html" class="olink">Database limits</a> for 63 more information. 64 </p> 65 <p> 66 All fields of the DBT structure that are not explicitly set should 67 be initialized to nul bytes before the first time the structure is 68 used. Do this by declaring the structure external or static, or by 69 calling the C library routine 70 <span class="bold"><strong>memset</strong></span>(3). 71 72 </p> 73 <p> 74 <span> 75 By default, the <span class="bold"><strong>flags</strong></span> structure element is expected to 76 be set to 0. In this default case, 77 </span> 78 79 80 when the application is providing Berkeley DB a key or data item to store into the database, 81 Berkeley DB expects the <span class="bold"><strong>data</strong></span> 82 83 <span> 84 structure element 85 </span> 86 87 88 to point to a byte string of <span class="bold"><strong>size</strong></span> bytes. When returning a 89 key/data item to the application, Berkeley DB will store into the <span class="bold"><strong>data</strong></span> 90 91 <span> 92 structure element 93 </span> 94 95 a pointer to a byte string of <span class="bold"><strong>size</strong></span> bytes, 96 and the memory to which the pointer refers will be 97 allocated and managed by Berkeley DB. Note that using the default flags 98 for returned <code class="classname">DBT</code>s is only compatible with 99 single threaded usage of Berkeley DB. 100 </p> 101 <p> 102 The elements of the DBT structure are defined as follows: 103 </p> 104 <div class="itemizedlist"> 105 <ul type="disc"> 106 <li> 107 <p> 108 <span class="bold"><strong>void *data;</strong></span> 109 </p> 110 <p> 111 A pointer to a byte string. 112 </p> 113 </li> 114 <li> 115 <p> 116 <span class="bold"><strong>u_int32_t size;</strong></span> 117 </p> 118 <p> 119 The length of <span class="bold"><strong>data</strong></span>, in bytes. 120 </p> 121 </li> 122 <li> 123 <p> 124 <span class="bold"><strong>u_int32_t ulen;</strong></span> 125 </p> 126 <p> 127 The size of the user's buffer (to which <span class="bold"><strong>data</strong></span> refers), in bytes. This 128 location is not written by the Berkeley DB functions. 129 </p> 130 <p> 131 Set the byte size of the user-specified buffer. 132 </p> 133 <p> 134 Note that applications can determine the length of a record by setting 135 the <code class="literal">ulen</code> field to 0 and checking the return value in the 136 <span class="bold"><strong>size</strong></span> field. See 137 the <code class="literal">DB_DBT_USERMEM</code> flag for more information. 138 </p> 139 </li> 140 <li> 141 <p> 142 <span class="bold"><strong>u_int32_t dlen;</strong></span> 143 </p> 144 <p> 145 <span> 146 The 147 </span> 148 149 length of the partial record being read or written by the 150 application, in bytes. See the <code class="literal">DB_DBT_PARTIAL</code> 151 flag for more information. 152 </p> 153 </li> 154 <li> 155 <p> 156 <span class="bold"><strong>u_int32_t doff;</strong></span> 157 </p> 158 <p> 159 <span> 160 The 161 </span> 162 163 offset of the partial record being read or written by the application, 164 in bytes. See the <code class="literal">DB_DBT_PARTIAL</code> flag for more information. 165 </p> 166 </li> 167 <li> 168 <p> 169 <span class="bold"><strong>u_int32_t flags;</strong></span> 170 </p> 171 <p> 172 The <span class="bold"><strong>flags</strong></span> parameter must be set to 0 or 173 by bitwise inclusively <span class="bold"><strong>OR</strong></span>'ing together 174 one or more of the following values: 175 </p> 176 <span> 177 <div class="itemizedlist"><ul type="circle"><li><p><a id="dbt_DB_DBT_MALLOC"></a> 178 <code class="literal">DB_DBT_MALLOC</code> 179 </p><p> 180 When this flag is set, Berkeley DB will allocate memory 181 for the returned key or data item (using 182 <span class="bold"><strong>malloc</strong></span>(3), or 183 the user-specified malloc function), and return a 184 pointer to it in the 185 <span class="bold"><strong>data</strong></span> field of the key or data 186 <code class="literal">DBT</code> 187 structure. Because any allocated memory becomes the 188 responsibility of the calling application, the caller 189 must determine whether memory was allocated using the 190 returned value of the 191 <span class="bold"><strong>data</strong></span> field. 192 </p><p> 193 It is an error to specify more than one of 194 <code class="literal">DB_DBT_MALLOC</code>, 195 <code class="literal">DB_DBT_REALLOC</code>, and 196 <code class="literal">DB_DBT_USERMEM</code>. 197 </p></li><li><p><a id="dbt_DB_DBT_REALLOC"></a> 198 <code class="literal">DB_DBT_REALLOC</code> 199 </p><p> 200 When this flag is set Berkeley DB will allocate memory 201 for the returned key or data item (using 202 <span class="bold"><strong>realloc</strong></span>(3), or 203 the user-specified realloc function), and return a 204 pointer to it in the 205 <span class="bold"><strong>data</strong></span> field of the key or data DBT 206 structure. Because any allocated memory becomes the 207 responsibility of the calling application, the caller 208 must determine whether memory was allocated using the 209 returned value of the 210 <span class="bold"><strong>data</strong></span> field. 211 </p><p> 212 The difference between 213 <code class="literal">DB_DBT_MALLOC</code> and 214 <code class="literal">DB_DBT_REALLOC</code> 215 is that the latter will call 216 <span class="bold"><strong>realloc</strong></span>(3) instead of 217 <span class="bold"><strong>malloc</strong></span>(3), 218 so the allocated memory will be grown as 219 necessary instead of the application doing repeated 220 free/malloc calls. 221 </p><p> 222 It is an error to specify more than one of 223 <code class="literal">DB_DBT_MALLOC</code>, 224 <code class="literal">DB_DBT_REALLOC</code>, and 225 <code class="literal">DB_DBT_USERMEM</code>. 226 </p></li><li><p><a id="dbt_DB_DBT_USERMEM"></a> 227 <code class="literal">DB_DBT_USERMEM</code> 228 </p><p> 229 The <span class="emphasis"><em>data</em></span> 230 field of the key or data structure must refer 231 to memory that is at least 232 <span class="emphasis"><em>ulen</em></span> 233 bytes in length. If the 234 length of the requested item is less than or equal to 235 that number of bytes, the item is copied into the memory 236 to which the 237 <span class="emphasis"><em>data</em></span> 238 field refers. Otherwise, the 239 <span class="emphasis"><em>size</em></span> 240 field is set to the length needed for the requested 241 item, and the error 242 <code class="literal">DB_BUFFER_SMALL</code> is returned. 243 </p><p> 244 It is an error to specify more than one of 245 <code class="literal">DB_DBT_MALLOC</code>, 246 <code class="literal">DB_DBT_REALLOC</code>, and 247 <code class="literal">DB_DBT_USERMEM</code>. 248 </p></li></ul></div> 249 250 251 <div class="itemizedlist"><ul type="circle"><li><p><a id="dbt_DB_DBT_PARTIAL"></a> 252 <code class="literal">DB_DBT_PARTIAL</code> 253 </p><p> 254 Do partial retrieval or storage of an item. If the 255 calling application is doing a get, the 256 <span class="bold"><strong>dlen</strong></span> bytes 257 starting 258 <span class="bold"><strong>doff</strong></span> 259 bytes from the beginning of the retrieved 260 data record are returned as if they comprised the entire 261 record. If any or all of the specified bytes do not 262 exist in the record, the get is successful, and any 263 existing bytes are returned. 264 </p><p> 265 For example, if the data portion of a retrieved record 266 was 100 bytes, and a partial retrieval was done using a 267 DBT having a 268 <span class="bold"><strong>dlen</strong></span> 269 field of 20 and a 270 <span class="bold"><strong>doff</strong></span> 271 field of 85, 272 the get call would succeed, the 273 <span class="bold"><strong>data</strong></span> 274 field would refer 275 to the last 15 bytes of the record, and the 276 <span class="bold"><strong>size</strong></span> 277 field would be set to 15. 278 </p><p> 279 If the calling application is doing a put, the 280 <span class="bold"><strong>dlen</strong></span> 281 bytes starting 282 <span class="bold"><strong>doff</strong></span> 283 bytes from the beginning of the 284 specified key's data record are replaced by the data 285 specified by the 286 <span class="bold"><strong>data</strong></span> 287 and 288 <span class="bold"><strong>size</strong></span> 289 structure elements. If 290 <span class="bold"><strong>dlen</strong></span> 291 is smaller than 292 <span class="bold"><strong>size</strong></span> 293 the record will grow; if 294 <span class="bold"><strong>dlen</strong></span> 295 is larger than 296 <span class="bold"><strong>size</strong></span> 297 the record will shrink. If the 298 specified bytes do not exist, the record will be 299 extended using nul bytes as necessary, and the put call 300 will succeed. 301 </p><p> 302 It is an error to attempt a partial put using the 303 <a class="xref" href="dbput.html" title="DB->put()">DB->put()</a> 304 method in a database that supports duplicate 305 records. Partial puts in databases supporting duplicate 306 records must be done using a 307 <a class="xref" href="dbcput.html" title="DBcursor->put()">DBcursor->put()</a> 308 method. 309 </p><p> 310 It is an error to attempt a partial put with differing 311 <span class="bold"><strong>dlen</strong></span> 312 and 313 <span class="bold"><strong>size</strong></span> 314 values in Queue or Recno databases with 315 fixed-length records. 316 </p><p> 317 For example, if the data portion of a retrieved record 318 was 100 bytes, and a partial put was done using a DBT 319 having a 320 <span class="bold"><strong>dlen</strong></span> 321 field of 20, a 322 <span class="bold"><strong>doff</strong></span> 323 field of 85, and a 324 <span class="bold"><strong>size</strong></span> 325 field of 30, the resulting record would be 115 326 bytes in length, where the last 30 bytes would be those 327 specified by the put call. 328 </p></li><li><p><a id="dbt_DB_DBT_APPMALLOC"></a> 329 <code class="literal">DB_DBT_APPMALLOC</code> 330 </p><p> 331 After an application-supplied callback routine passed to 332 either 333 <a class="xref" href="dbassociate.html" title="DB->associate()">DB->associate()</a> 334 or 335 <a class="xref" href="dbset_append_recno.html" title="DB->set_append_recno()">DB->set_append_recno()</a> 336 is executed, the 337 <span class="bold"><strong>data</strong></span> 338 field of a DBT may refer to memory allocated with 339 <span class="bold"><strong>malloc</strong></span>(3) 340 or 341 <span class="bold"><strong>realloc</strong></span>(3). 342 In that case, 343 the callback sets the 344 <code class="literal">DB_DBT_APPMALLOC</code> 345 flag in the DBT 346 so that Berkeley DB will call 347 <span class="bold"><strong>free</strong></span>(3) 348 to deallocate the 349 memory when it is no longer required. 350 </p></li><li><p><a id="dbt_DB_DBT_MULTIPLE"></a> 351 <code class="literal">DB_DBT_MULTIPLE</code> 352 </p><p> 353 Set in a secondary key creation callback routine passed 354 to 355 <a class="xref" href="dbassociate.html" title="DB->associate()">DB->associate()</a> 356 to indicate that multiple secondary 357 keys should be associated with the given primary 358 key/data pair. If set, the 359 <span class="bold"><strong>size</strong></span> 360 field indicates the 361 number of secondary keys and the 362 <span class="bold"><strong>data</strong></span> 363 field refers to an 364 array of that number of DBT structures. 365 </p><p> 366 The <code class="literal">DB_DBT_APPMALLOC</code> flag may be set on any of the DBT 367 structures to indicate that their 368 <span class="bold"><strong>data</strong></span> 369 field needs to be 370 freed. 371 </p></li></ul></div> 372</span> 373 </li> 374 </ul> 375 </div> 376 <div class="sect1" lang="en" xml:lang="en"> 377 <div class="titlepage"> 378 <div> 379 <div> 380 <h2 class="title" style="clear: both"><a id="dbtlist"></a>DBT and Bulk Operations</h2> 381 </div> 382 </div> 383 </div> 384 <div class="navtable"> 385 <table border="1" width="80%"> 386 <thead> 387 <tr> 388 <th>DBT and Bulk Operations</th> 389 <th>Description</th> 390 </tr> 391 </thead> 392 <tbody> 393 <tr> 394 <td> 395 <a class="xref" href="DB_MULTIPLE_INIT.html" title="DB_MULTIPLE_INIT">DB_MULTIPLE_INIT</a> 396 </td> 397 <td>Initialize bulk get retrieval</td> 398 </tr> 399 <tr> 400 <td> 401 <a class="xref" href="DB_MULTIPLE_NEXT.html" title="DB_MULTIPLE_NEXT">DB_MULTIPLE_NEXT</a> 402 </td> 403 <td>Next bulk get retrieval</td> 404 </tr> 405 <tr> 406 <td> 407 <a class="xref" href="DB_MULTIPLE_KEY_NEXT.html" title="DB_MULTIPLE_KEY_NEXT">DB_MULTIPLE_KEY_NEXT</a> 408 </td> 409 <td>Next bulk get retrieval</td> 410 </tr> 411 <tr> 412 <td> 413 <a class="xref" href="DB_MULTIPLE_RECNO_NEXT.html" title="DB_MULTIPLE_RECNO_NEXT">DB_MULTIPLE_RECNO_NEXT</a> 414 </td> 415 <td>Next bulk get retrieval</td> 416 </tr> 417 <tr> 418 <td> 419 <a class="xref" href="DB_MULTIPLE_WRITE_INIT.html" title="DB_MULTIPLE_WRITE_INIT">DB_MULTIPLE_WRITE_INIT</a> 420 </td> 421 <td>Initialize a bulk buffer to hold key/data pairs</td> 422 </tr> 423 <tr> 424 <td> 425 <a class="xref" href="DB_MULTIPLE_WRITE_NEXT.html" title="DB_MULTIPLE_WRITE_NEXT">DB_MULTIPLE_WRITE_NEXT</a> 426 </td> 427 <td>Append a data item to a bulk buffer</td> 428 </tr> 429 <tr> 430 <td> 431 <a class="xref" href="DB_MULTIPLE_RESERVE_NEXT.html" title="DB_MULTIPLE_RESERVE_NEXT">DB_MULTIPLE_RESERVE_NEXT</a> 432 </td> 433 <td>Reserve space for a data item in a bulk buffer</td> 434 </tr> 435 <tr> 436 <td> 437 <a class="xref" href="DB_MULTIPLE_KEY_WRITE_NEXT.html" title="DB_MULTIPLE_KEY_WRITE_NEXT">DB_MULTIPLE_KEY_WRITE_NEXT</a> 438 </td> 439 <td>Append a key / data pair to a bulk buffer</td> 440 </tr> 441 <tr> 442 <td> 443 <a class="xref" href="DB_MULTIPLE_KEY_RESERVE_NEXT.html" title="DB_MULTIPLE_KEY_RESERVE_NEXT">DB_MULTIPLE_KEY_RESERVE_NEXT</a> 444 </td> 445 <td>Reserve space for a key / data pair in a bulk buffer</td> 446 </tr> 447 <tr> 448 <td> 449 <a class="xref" href="DB_MULTIPLE_RECNO_WRITE_INIT.html" title="DB_MULTIPLE_RECNO_WRITE_INIT">DB_MULTIPLE_RECNO_WRITE_INIT</a> 450 </td> 451 <td>Initialize a bulk buffer to hold recno/data pairs</td> 452 </tr> 453 <tr> 454 <td> 455 <a class="xref" href="DB_MULTIPLE_RECNO_WRITE_NEXT.html" title="DB_MULTIPLE_RECNO_WRITE_NEXT">DB_MULTIPLE_RECNO_WRITE_NEXT</a> 456 </td> 457 <td>Append a record number / data pair to a bulk buffer</td> 458 </tr> 459 <tr> 460 <td> 461 <a class="xref" href="DB_MULTIPLE_RECNO_RESERVE_NEXT.html" title="DB_MULTIPLE_RECNO_RESERVE_NEXT">DB_MULTIPLE_RECNO_RESERVE_NEXT</a> 462 </td> 463 <td>Reserve space for a record number / data pair in a bulk buffer</td> 464 </tr> 465 </tbody> 466 </table> 467 </div> 468 </div> 469 </div> 470 <div class="navfooter"> 471 <hr /> 472 <table width="100%" summary="Navigation footer"> 473 <tr> 474 <td width="40%" align="left"><a accesskey="p" href="dbcset_priority.html">Prev</a> </td> 475 <td width="20%" align="center"> </td> 476 <td width="40%" align="right"> <a accesskey="n" href="DB_MULTIPLE_INIT.html">Next</a></td> 477 </tr> 478 <tr> 479 <td width="40%" align="left" valign="top">DBcursor->set_priority() </td> 480 <td width="20%" align="center"> 481 <a accesskey="h" href="index.html">Home</a> 482 </td> 483 <td width="40%" align="right" valign="top"> DB_MULTIPLE_INIT</td> 484 </tr> 485 </table> 486 </div> 487 </body> 488</html> 489