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>Dbc::get()</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="dbc.html" title="Chapter 3. The Dbc Handle" /> 11 <link rel="prev" href="dbcdup.html" title="Dbc::dup()" /> 12 <link rel="next" href="dbcget_priority.html" title="Dbc::get_priority()" /> 13 </head> 14 <body> 15 <div class="navheader"> 16 <table width="100%" summary="Navigation header"> 17 <tr> 18 <th colspan="3" align="center">Dbc::get()</th> 19 </tr> 20 <tr> 21 <td width="20%" align="left"><a accesskey="p" href="dbcdup.html">Prev</a> </td> 22 <th width="60%" align="center">Chapter 3. 23 The Dbc Handle 24 </th> 25 <td width="20%" align="right"> <a accesskey="n" href="dbcget_priority.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="dbcget"></a>Dbc::get()</h2> 35 </div> 36 </div> 37 </div> 38 <pre class="programlisting">#include <db_cxx.h> 39 40int 41Dbc::get(Dbt *key, Dbt *data, u_int32_t flags); 42 43int 44Dbc::pget(Dbt *key, Dbt *pkey, Dbt *data, u_int32_t flags); </pre> 45 <p> 46 The <code class="methodname">Dbc::get()</code> method retrieves key/data pairs from the 47 database. The address and length of the key are returned in the 48 object to which <span class="bold"><strong>key</strong></span> refers (except 49 for the case of the DB_SET flag, in which the <span class="bold"><strong>key</strong></span> object is unchanged), and the address and 50 length of the data are returned in the object to which <span class="bold"><strong>data</strong></span> refers. 51 </p> 52 <p> 53 When called on a cursor opened on a database that has been made into a 54 secondary index using the 55 <a class="xref" href="dbassociate.html" title="Db::associate()">Db::associate()</a> method, the 56 <code class="methodname">Dbc::get()</code> and <code class="methodname">Dbc::pget()</code> 57 methods return the key from the 58 secondary index and the data item from the primary database. In 59 addition, the <code class="methodname">Dbc::pget()</code> method returns the key from the 60 primary database. In databases that are not secondary indices, the 61 <code class="methodname">Dbc::pget()</code> method will always fail. 62 </p> 63 <p> 64 Modifications to the database during a sequential scan will be 65 reflected in the scan; that is, records inserted behind a cursor will 66 not be returned while records inserted in front of a cursor will be 67 returned. 68 </p> 69 <p> 70 In Queue and Recno databases, missing entries (that is, entries that 71 were never explicitly created or that were created and then deleted) 72 will be skipped during a sequential scan. 73 </p> 74 <p> 75 Unless otherwise specified, the <code class="methodname">Dbc::get()</code> <span> 76 77 <span> 78 method either returns a non-zero error value or throws an 79 exception that encapsulates a non-zero error value on 80 failure, and returns 0 on success. 81 </span> 82 </span> 83 </p> 84 <p> 85 If <code class="methodname">Dbc::get()</code> fails for any reason, the state of the cursor will 86 be unchanged. 87 </p> 88 <div class="sect2" lang="en" xml:lang="en"> 89 <div class="titlepage"> 90 <div> 91 <div> 92 <h3 class="title"><a id="id1656028"></a>Parameters</h3> 93 </div> 94 </div> 95 </div> 96 <div class="sect3" lang="en" xml:lang="en"> 97 <div class="titlepage"> 98 <div> 99 <div> 100 <h4 class="title"><a id="id1656268"></a>data</h4> 101 </div> 102 </div> 103 </div> 104 <p> 105 The data <a class="link" href="dbt.html" title="Chapter 4. The Dbt Handle">Dbt</a> operated on. 106 </p> 107 </div> 108 <div class="sect3" lang="en" xml:lang="en"> 109 <div class="titlepage"> 110 <div> 111 <div> 112 <h4 class="title"><a id="id1656406"></a>flags</h4> 113 </div> 114 </div> 115 </div> 116 <p> 117 The <span class="bold"><strong>flags</strong></span> parameter must be set to 118 one of the following values: 119 </p> 120 <div class="itemizedlist"> 121 <ul type="disc"> 122 <li> 123 <p><a id="dbcget_DB_CURRENT"></a> 124 <code class="literal">DB_CURRENT</code> 125 </p> 126 <p> 127 Return the key/data pair to which the cursor refers. 128 </p> 129 <p> 130 The <code class="methodname">Dbc::get()</code> method will return <a href="../../programmer_reference/program_errorret.html#program_errorret.DB_KEYEMPTY" class="olink">DB_KEYEMPTY</a> if 131 DB_CURRENT is set and the cursor key/data pair was deleted. 132 </p> 133 </li> 134 <li> 135 <p><a id="dbcget_DB_FIRST"></a> 136 <code class="literal">DB_FIRST</code> 137 </p> 138 <p> 139 The cursor is set to refer to the first key/data pair of the database, 140 and that pair is returned. If the first key has duplicate values, the 141 first data item in the set of duplicates is returned. 142 </p> 143 <p> 144 If the database is a Queue or Recno database, <code class="methodname">Dbc::get()</code> using 145 the DB_FIRST flag will ignore any keys that exist but were never 146 explicitly created by the application, or were created and later 147 deleted. 148 </p> 149 <p> 150 The <code class="methodname">Dbc::get()</code> method will return <a href="../../programmer_reference/program_errorret.html#program_errorret.DB_NOTFOUND" class="olink">DB_NOTFOUND</a> if 151 DB_FIRST is set and the database is empty. 152 </p> 153 </li> 154 <li> 155 <p><a id="dbcget_DB_GET_BOTH"></a> 156 <code class="literal">DB_GET_BOTH</code> 157 </p> 158 <p> 159 Move the cursor to the specified key/data pair of the 160 database. The cursor is positioned to a key/data pair if 161 both the key and data match the values provided on the key 162 and data parameters. 163 </p> 164 <p> 165 In all other ways, this flag is identical to the 166 <a class="link" href="dbcget.html#dbcget_DB_SET">DB_SET</a> 167 flag. 168 </p> 169 <p> 170 When used with <code class="methodname">Dbc::pget()</code> on 171 a secondary index handle, both the secondary and primary keys must be 172 matched by the secondary and primary key item in the database. It is 173 an error to use the DB_GET_BOTH flag with the <code class="methodname">Dbc::get()</code> version 174 of this method and a cursor that has been opened on a secondary index 175 handle. 176 </p> 177 </li> 178 <li> 179 <p><a id="dbcget_DB_GET_BOTH_RANGE"></a> 180 <code class="literal">DB_GET_BOTH_RANGE</code> 181 </p> 182 <p> 183 Move the cursor to the specified key/data pair of the 184 database. The key parameter must be an exact match with a 185 key in the database. The data item retrieved is the item in 186 a duplicate set that is the smallest value which is greater than or equal 187 to the value provided by the data parameter (as determined by the comparison 188 function). If this flag is specified on a database 189 configured without sorted duplicate support, the behavior 190 is identical to the DB_GET_BOTH flag. Returns the datum 191 associated with the given key/data pair. 192 </p> 193 <p> 194 In all other ways, this flag is identical to the 195 <a class="link" href="dbcget.html#dbcget_DB_GET_BOTH">DB_GET_BOTH</a> 196 flag. 197 </p> 198 </li> 199 <li> 200 <p><a id="dbcget_DB_GET_RECNO"></a> 201 <code class="literal">DB_GET_RECNO</code> 202 </p> 203 <p> 204 Return the record number associated with the cursor. The record 205 number will be returned in <span class="bold"><strong>data</strong></span>, as 206 described in <a class="link" href="dbt.html" title="Chapter 4. The Dbt Handle">Dbt</a>. The 207 <span class="bold"><strong>key</strong></span> parameter is ignored. 208 </p> 209 <p> 210 For DB_GET_RECNO to be specified, the underlying database must be of 211 type Btree, and it must have been created with the 212 <a class="link" href="dbset_flags.html#dbset_flags_DB_RECNUM">DB_RECNUM</a> flag. 213 </p> 214 <p> 215 When called on a cursor opened on a database that has been made into a 216 secondary index, the <code class="methodname">Dbc::get()</code> and 217 <code class="methodname">Dbc::pget()</code> methods return the record 218 number of the primary database in <span class="bold"><strong>data</strong></span>. 219 In addition, the <code class="methodname">Dbc::pget()</code> 220 method returns the record number of the secondary index in <span class="bold"><strong>pkey</strong></span>. If either underlying database is not of 221 type Btree or is not created with the 222 <a class="link" href="dbset_flags.html#dbset_flags_DB_RECNUM">DB_RECNUM</a> 223 flag, the out-of-band record number of 0 is returned. 224 </p> 225 </li> 226 <li> 227 <p><a id="dbcget_DB_JOIN_ITEM"></a> 228 <code class="literal">DB_JOIN_ITEM</code> 229 </p> 230 <p> 231 Do not use the data value found in all of the cursors as a lookup key 232 for the primary database, but simply return it in the key parameter 233 instead. The data parameter is left unchanged. 234 </p> 235 <p> 236 For DB_JOIN_ITEM to be specified, the underlying cursor must have been 237 returned from the <a class="xref" href="dbjoin.html" title="Db::join()">Db::join()</a> method. 238 </p> 239 </li> 240 <li> 241 <p><a id="dbcget_DB_LAST"></a> 242 <code class="literal">DB_LAST</code> 243 </p> 244 <p> 245 The cursor is set to refer to the last key/data pair of the database, 246 and that pair is returned. If the last key has duplicate values, the 247 last data item in the set of duplicates is returned. 248 </p> 249 <p> 250 If the database is a Queue or Recno database, <code class="methodname">Dbc::get()</code> using 251 the DB_LAST flag will ignore any keys that exist but were never 252 explicitly created by the application, or were created and later 253 deleted. 254 </p> 255 <p> 256 The <code class="methodname">Dbc::get()</code> method will return <a href="../../programmer_reference/program_errorret.html#program_errorret.DB_NOTFOUND" class="olink">DB_NOTFOUND</a> if 257 DB_LAST is set and the database is empty. 258 </p> 259 </li> 260 <li> 261 <p><a id="dbcget_DB_NEXT"></a> 262 <code class="literal">DB_NEXT</code> 263 </p> 264 <p> 265 If the cursor is not yet initialized, DB_NEXT is identical to 266 DB_FIRST. Otherwise, the cursor is moved to the next key/data pair of 267 the database, and that pair is returned. In the presence of duplicate 268 key values, the value of the key may not change. 269 </p> 270 <p> 271 If the database is a Queue or Recno database, <code class="methodname">Dbc::get()</code> using 272 the DB_NEXT flag will skip any keys that exist but were never 273 explicitly created by the application, or those that were created and 274 later deleted. 275 </p> 276 <p> 277 The <code class="methodname">Dbc::get()</code> method will return <a href="../../programmer_reference/program_errorret.html#program_errorret.DB_NOTFOUND" class="olink">DB_NOTFOUND</a> if 278 DB_NEXT is set and the cursor is already on the last record in the 279 database. 280 </p> 281 </li> 282 <li> 283 <p><a id="dbcget_DB_NEXT_DUP"></a> 284 <code class="literal">DB_NEXT_DUP</code> 285 </p> 286 <p> 287 If the next key/data pair of the database is a duplicate data record 288 for the current key/data pair, the cursor is moved to the next 289 key/data pair of the database, and that pair is returned. 290 </p> 291 <p> 292 The <code class="methodname">Dbc::get()</code> method will return <a href="../../programmer_reference/program_errorret.html#program_errorret.DB_NOTFOUND" class="olink">DB_NOTFOUND</a> if 293 DB_NEXT_DUP is set and the next key/data pair of the database is not a 294 duplicate data record for the current key/data pair. 295 </p> 296 </li> 297 <li> 298 <p><a id="dbcget_DB_NEXT_NODUP"></a> 299 <code class="literal">DB_NEXT_NODUP</code> 300 </p> 301 <p> 302 If the cursor is not yet initialized, DB_NEXT_NODUP is identical to 303 DB_FIRST. Otherwise, the cursor is moved to the next non-duplicate 304 key of the database, and that key/data pair is returned. 305 </p> 306 <p> 307 If the database is a Queue or Recno database, <code class="methodname">Dbc::get()</code> using 308 the DB_NEXT_NODUP flag will ignore any keys that exist but were never 309 explicitly created by the application, or those that were created and 310 later deleted. 311 </p> 312 <p> 313 The <code class="methodname">Dbc::get()</code> method will return <a href="../../programmer_reference/program_errorret.html#program_errorret.DB_NOTFOUND" class="olink">DB_NOTFOUND</a> if 314 DB_NEXT_NODUP is set and no non-duplicate key/data pairs exist after 315 the cursor position in the database. 316 </p> 317 </li> 318 <li> 319 <p><a id="dbcget_DB_PREV"></a> 320 <code class="literal">DB_PREV</code> 321 </p> 322 <p> 323 If the cursor is not yet initialized, DB_PREV is identical to DB_LAST. 324 Otherwise, the cursor is moved to the previous key/data pair of the 325 database, and that pair is returned. In the presence of duplicate key 326 values, the value of the key may not change. 327 </p> 328 <p> 329 If the database is a Queue or Recno database, <code class="methodname">Dbc::get()</code> using 330 the DB_PREV flag will skip any keys that exist but were never 331 explicitly created by the application, or those that were created and 332 later deleted. 333 </p> 334 <p> 335 The <code class="methodname">Dbc::get()</code> method will return <a href="../../programmer_reference/program_errorret.html#program_errorret.DB_NOTFOUND" class="olink">DB_NOTFOUND</a> if 336 DB_PREV is set and the cursor is already on the first record in the 337 database. 338 </p> 339 </li> 340 <li> 341 <p><a id="dbcget_DB_PREV_DUP"></a> 342 <code class="literal">DB_PREV_DUP</code> 343 </p> 344 <p> 345 If the previous key/data pair of the database is a duplicate data 346 record for the current key/data pair, the cursor is moved to the 347 previous key/data pair of the database, and that pair is returned. 348 </p> 349 <p> 350 The <code class="methodname">Dbc::get()</code> method will return <a href="../../programmer_reference/program_errorret.html#program_errorret.DB_NOTFOUND" class="olink">DB_NOTFOUND</a> if 351 DB_PREV_DUP is set and the previous key/data pair of the database is 352 not a duplicate data record for the current key/data pair. 353 </p> 354 </li> 355 <li> 356 <p><a id="dbcget_DB_PREV_NODUP"></a> 357 <code class="literal">DB_PREV_NODUP</code> 358 </p> 359 <p> 360 If the cursor is not yet initialized, DB_PREV_NODUP is identical to 361 DB_LAST. Otherwise, the cursor is moved to the previous non-duplicate 362 key of the database, and that key/data pair is returned. 363 </p> 364 <p> 365 If the database is a Queue or Recno database, <code class="methodname">Dbc::get()</code> using 366 the DB_PREV_NODUP flag will ignore any keys that exist but were never 367 explicitly created by the application, or those that were created and 368 later deleted. 369 </p> 370 <p> 371 The <code class="methodname">Dbc::get()</code> method will return <a href="../../programmer_reference/program_errorret.html#program_errorret.DB_NOTFOUND" class="olink">DB_NOTFOUND</a> if 372 DB_PREV_NODUP is set and no non-duplicate key/data pairs exist before 373 the cursor position in the database. 374 </p> 375 </li> 376 <li> 377 <p><a id="dbcget_DB_SET"></a> 378 <code class="literal">DB_SET</code> 379 </p> 380 <p> 381 Move the cursor to the specified key/data pair of the database, and 382 return the datum associated with the given key. 383 </p> 384 <p> 385 The <code class="methodname">Dbc::get()</code> method will return <a href="../../programmer_reference/program_errorret.html#program_errorret.DB_NOTFOUND" class="olink">DB_NOTFOUND</a> if 386 DB_SET is set and no matching keys are found. The 387 <code class="methodname">Dbc::get()</code> method will return <a href="../../programmer_reference/program_errorret.html#program_errorret.DB_KEYEMPTY" class="olink">DB_KEYEMPTY</a> if 388 DB_SET is set and the database is a Queue or Recno database, and the 389 specified key exists, but was never explicitly created by the 390 application or was later deleted. In the presence of duplicate key 391 values, <code class="methodname">Dbc::get()</code> will return the first data item for the given 392 key. 393 </p> 394 </li> 395 <li> 396 <p><a id="dbcget_DB_SET_RANGE"></a> 397 <code class="literal">DB_SET_RANGE</code> 398 </p> 399 <p> 400 Move the cursor to the specified key/data pair of the 401 database. In the case of the Btree access method, the key 402 is returned as well as the data item and the returned 403 key/data pair is the smallest key greater than or equal to 404 the specified key (as determined by the Btree comparison 405 function), permitting partial key matches and range 406 searches. 407 </p> 408 <p> 409 In all other ways the behavior of this flag is the same 410 as the <a class="link" href="dbcget.html#dbcget_DB_SET">DB_SET</a> flag. 411 </p> 412 </li> 413 <li> 414 <p><a id="dbcget_DB_SET_RECNO"></a> 415 <code class="literal">DB_SET_RECNO</code> 416 </p> 417 <p> 418 Move the cursor to the specific numbered record of the database, and 419 return the associated key/data pair. The <span class="bold"><strong>data</strong></span> field of the specified <span class="bold"><strong>key</strong></span> must be a pointer to a memory location from 420 which a <code class="literal">db_recno_t</code> may be 421 read, as described in <a class="link" href="dbt.html" title="Chapter 4. The Dbt Handle">Dbt</a>. This memory location will 422 be read to determine the record to be retrieved. 423 </p> 424 <p> 425 For DB_SET_RECNO to be specified, the underlying database must be of 426 type Btree, and it must have been created with the 427 <a class="link" href="dbset_flags.html#dbset_flags_DB_RECNUM">DB_RECNUM</a> flag. 428 </p> 429 </li> 430 </ul> 431 </div> 432 <p> 433 In addition, the following flags may be set by bitwise inclusively 434 <span class="bold"><strong>OR</strong></span>'ing them into the <span class="bold"><strong>flags</strong></span> parameter: 435 </p> 436 <div class="itemizedlist"> 437 <ul type="disc"> 438 <li> 439 <p> 440 <code class="literal">DB_IGNORE_LEASE</code> 441 </p> 442 <p> 443 This flag is relevant only when using a replicated 444 environment. 445 </p> 446 <p> 447 Return the data item irrespective of the state of master leases. The 448 item will be returned under all conditions: if master leases are not 449 configured, if the request is made to a client, if the request is made 450 to a master with a valid lease, or if the request is made to a master 451 without a valid lease. 452 </p> 453 </li> 454 <li> 455 <p><a id="dbcget_DB_READ_COMMITTED"></a> 456 <code class="literal">DB_READ_COMMITTED</code> 457 </p> 458 <p> 459 Configure a transactional get operation to have degree 2 isolation 460 (the read is not repeatable). 461 </p> 462 </li> 463 <li> 464 <p> 465 <code class="literal">DB_READ_UNCOMMITTED</code> 466 </p> 467 <p> 468 Database items read during a transactional call will have degree 1 469 isolation, including modified but not yet committed data. Silently 470 ignored if the 471 <a class="link" href="dbopen.html#dbopen_DB_READ_UNCOMMITTED">DB_READ_UNCOMMITTED</a> 472 flag was not specified when the underlying database was opened. 473 </p> 474 </li> 475 <li> 476 <p><a id="dbcget_DB_MULTIPLE"></a> 477 <code class="literal">DB_MULTIPLE</code> 478 </p> 479 <p> 480 Return multiple data items in the <span class="bold"><strong>data</strong></span> parameter. 481 </p> 482 <p> 483 In the case of Btree or Hash databases, duplicate data items for the 484 current key, starting at the current cursor position, are entered into 485 the buffer. Subsequent calls with both the DB_NEXT_DUP and 486 DB_MULTIPLE flags specified will return additional duplicate data 487 items associated with the current key or <a href="../../programmer_reference/program_errorret.html#program_errorret.DB_NOTFOUND" class="olink">DB_NOTFOUND</a> if 488 there are no additional duplicate data items to return. Subsequent 489 calls with both the DB_NEXT and DB_MULTIPLE flags specified will 490 return additional duplicate data items associated with the current key 491 or if there are no additional duplicate data items will return the 492 next key and its data items or <a href="../../programmer_reference/program_errorret.html#program_errorret.DB_NOTFOUND" class="olink">DB_NOTFOUND</a> if 493 there are no additional keys in the database. 494 </p> 495 <p> 496 In the case of Queue or Recno databases, data items starting at the 497 current cursor position are entered into the buffer. The record 498 number of the first record will be returned in the <span class="bold"><strong>key</strong></span> parameter. The record number of each 499 subsequent returned record must be calculated from this value. 500 Subsequent calls with the DB_MULTIPLE flag specified will return 501 additional data items or <a href="../../programmer_reference/program_errorret.html#program_errorret.DB_NOTFOUND" class="olink">DB_NOTFOUND</a> if 502 there are no additional data items to return. 503 </p> 504 <p> 505 The buffer to which the <span class="bold"><strong>data</strong></span> 506 parameter refers must be provided from user memory (see 507 <a class="link" href="dbt.html#dbt_DB_DBT_USERMEM">DB_DBT_USERMEM</a> ). 508 The buffer must be at least as large as the page size of the 509 underlying database, aligned for unsigned integer access, and be a 510 multiple of 1024 bytes in size. If the buffer size is insufficient, 511 then upon return from the call the size field of the <span class="bold"><strong>data</strong></span> parameter will have been set to an 512 estimated buffer size, and the error DB_BUFFER_SMALL is returned. 513 (The size is an estimate as the exact size needed may not be known 514 until all entries are read. It is best to initially provide a 515 relatively large buffer, but applications should be prepared to resize 516 the buffer as necessary and repeatedly call the method.) 517 </p> 518 <p> 519 The multiple data items can be iterated over using the 520 521 <span> 522 <a class="xref" href="dbmultipledataiterator.html" title="DbMultipleDataIterator">DbMultipleDataIterator</a> class. 523 </span> 524 </p> 525 <p> 526 The DB_MULTIPLE flag may only be used with the DB_CURRENT, DB_FIRST, 527 DB_GET_BOTH, DB_GET_BOTH_RANGE, DB_NEXT, DB_NEXT_DUP, DB_NEXT_NODUP, 528 DB_SET, DB_SET_RANGE, and DB_SET_RECNO options. The DB_MULTIPLE flag 529 may not be used when accessing databases made into secondary indices 530 using the <a class="xref" href="dbassociate.html" title="Db::associate()">Db::associate()</a> method. 531 </p> 532 </li> 533 <li> 534 <p><a id="dbcget_DB_MULTIPLE_KEY"></a> 535 <code class="literal">DB_MULTIPLE_KEY</code> 536 </p> 537 <p> 538 Return multiple key and data pairs in the <span class="bold"><strong>data</strong></span> parameter. 539 </p> 540 <p> 541 Key and data pairs, starting at the current cursor position, are 542 entered into the buffer. Subsequent calls with both the DB_NEXT and 543 DB_MULTIPLE_KEY flags specified will return additional key and data 544 pairs or <a href="../../programmer_reference/program_errorret.html#program_errorret.DB_NOTFOUND" class="olink">DB_NOTFOUND</a> if 545 there are no additional key and data items to return. 546 </p> 547 <p> 548 In the case of Btree or Hash databases, the multiple key and data 549 pairs can be iterated over using the 550 551 <span> 552 <a class="xref" href="dbmultiplekeydataiterator.html" title="DbMultipleKeyDataIterator">DbMultipleKeyDataIterator</a> class. 553 </span> 554 </p> 555 <p> 556 In the case of Queue or Recno databases, the multiple record number 557 and data pairs can be iterated over using the 558 559 <span> 560 <a class="xref" href="dbmultiplerecnodataiterator.html" title="DbMultipleRecnoDataIterator">DbMultipleRecnoDataIterator</a> class. 561 </span> 562 </p> 563 <p> 564 The buffer to which the <span class="bold"><strong>data</strong></span> 565 parameter refers must be provided from user memory (see 566 <a class="link" href="dbt.html#dbt_DB_DBT_USERMEM">DB_DBT_USERMEM</a> ). 567 The buffer must be at least as large as the page size of the 568 underlying database, aligned for unsigned integer access, and be a 569 multiple of 1024 bytes in size. If the buffer size is insufficient, 570 then upon return from the call the size field of the <span class="bold"><strong>data</strong></span> parameter will have been set to an 571 estimated buffer size, and the error DB_BUFFER_SMALL is returned. 572 (The size is an estimate as the exact size needed may not be known 573 until all entries are read. It is best to initially provide a 574 relatively large buffer, but applications should be prepared to resize 575 the buffer as necessary and repeatedly call the method.) 576 </p> 577 <p> 578 The DB_MULTIPLE_KEY flag may only be used with the DB_CURRENT, 579 DB_FIRST, DB_GET_BOTH, DB_GET_BOTH_RANGE, DB_NEXT, DB_NEXT_DUP, 580 DB_NEXT_NODUP, DB_SET, DB_SET_RANGE, and DB_SET_RECNO options. The 581 DB_MULTIPLE_KEY flag may not be used when accessing databases made 582 into secondary indices using the 583 <a class="xref" href="dbassociate.html" title="Db::associate()">Db::associate()</a> method. 584 </p> 585 </li> 586 <li> 587 <p><a id="dbcget_DB_RMW"></a> 588 <code class="literal">DB_RMW</code> 589 </p> 590 <p> 591 Acquire write locks instead of read locks when doing the read, if 592 locking is configured. Setting this flag can eliminate deadlock 593 during a read-modify-write cycle by acquiring the write lock during 594 the read part of the cycle so that another thread of control acquiring 595 a read lock for the same item, in its own read-modify-write cycle, 596 will not result in deadlock. 597 </p> 598 </li> 599 </ul> 600 </div> 601 </div> 602 <div class="sect3" lang="en" xml:lang="en"> 603 <div class="titlepage"> 604 <div> 605 <div> 606 <h4 class="title"><a id="id1657366"></a>key</h4> 607 </div> 608 </div> 609 </div> 610 <p> 611 The key <a class="link" href="dbt.html" title="Chapter 4. The Dbt Handle">Dbt</a> operated on. 612 </p> 613 </div> 614 <div class="sect3" lang="en" xml:lang="en"> 615 <div class="titlepage"> 616 <div> 617 <div> 618 <h4 class="title"><a id="id1657221"></a>pkey</h4> 619 </div> 620 </div> 621 </div> 622 <p> 623 The secondary index key <a class="link" href="dbt.html" title="Chapter 4. The Dbt Handle">Dbt</a> operated on. 624 </p> 625 </div> 626 </div> 627 <div class="sect2" lang="en" xml:lang="en"> 628 <div class="titlepage"> 629 <div> 630 <div> 631 <h3 class="title"><a id="id1656339"></a>Errors</h3> 632 </div> 633 </div> 634 </div> 635 <p> 636 The <code class="methodname">Dbc::get()</code> <span> 637 638 <span> 639 method may fail and throw a <a class="link" href="dbexception.html" title="Chapter 6. The DbException Class">DbException</a> 640 exception, encapsulating one of the following non-zero errors, or return one 641 of the following non-zero errors: 642 </span> 643 </span> 644 </p> 645 <div class="sect3" lang="en" xml:lang="en"> 646 <div class="titlepage"> 647 <div> 648 <div> 649 <h4 class="title"><a id="id1656914"></a><span>DbMemoryException or </span>DB_BUFFER_SMALL</h4> 650 </div> 651 </div> 652 </div> 653 <p> 654 The requested item could not be returned due to undersized buffer. 655 </p> 656 <p> 657 <a class="xref" href="dbmemory.html" title="DbMemoryException">DbMemoryException</a> is thrown if 658 your Berkeley DB API is configured to throw exceptions. 659 Otherwise, <code class="literal">DB_BUFFER_SMALL</code> is returned. 660 </p> 661 </div> 662 <div class="sect3" lang="en" xml:lang="en"> 663 <div class="titlepage"> 664 <div> 665 <div> 666 <h4 class="title"><a id="id1656950"></a><span>DbDeadlockException or </span>DB_LOCK_DEADLOCK</h4> 667 </div> 668 </div> 669 </div> 670 <p> 671 A transactional database environment operation was selected to resolve 672 a deadlock. 673 </p> 674 <p> 675 <a class="xref" href="dbdeadlock.html" title="DbDeadlockException">DbDeadlockException</a> is thrown if 676 your Berkeley DB API is configured to throw exceptions. 677 Otherwise, <code class="literal">DB_LOCK_DEADLOCK</code> is returned. 678 </p> 679 </div> 680 <div class="sect3" lang="en" xml:lang="en"> 681 <div class="titlepage"> 682 <div> 683 <div> 684 <h4 class="title"><a id="id1656995"></a><span>DbLockNotGrantedException or </span>DB_LOCK_NOTGRANTED</h4> 685 </div> 686 </div> 687 </div> 688 <p> 689 A Berkeley DB Concurrent Data Store database environment configured 690 for lock timeouts was unable to grant a lock in the allowed time. 691 </p> 692 <p> 693 <a class="xref" href="dblocknotgranted.html" title="DbLockNotGrantedException">DbLockNotGrantedException</a> is thrown if 694 your Berkeley DB API is configured to throw exceptions. 695 Otherwise, <code class="literal">DB_LOCK_NOTGRANTED</code> is returned. 696 </p> 697 </div> 698 <div class="sect3" lang="en" xml:lang="en"> 699 <div class="titlepage"> 700 <div> 701 <div> 702 <h4 class="title"><a id="id1656669"></a><span>DbRepHandleDeadException or</span> DB_REP_HANDLE_DEAD</h4> 703 </div> 704 </div> 705 </div> 706 <p> 707 When a client synchronizes with the master, it is possible for committed 708 transactions to be rolled back. This invalidates all the database and cursor 709 handles opened in the replication environment. Once this occurs, an attempt to use 710 such a handle will 711 <span> 712 throw a <a class="xref" href="dbrephandledead.html" title="DbRepHandleDeadException">DbRepHandleDeadException</a> (if 713 your application is configured to throw exceptions), or 714 </span> 715 return <code class="literal">DB_REP_HANDLE_DEAD</code>. 716 The application will need to discard the handle and open a new one in order to 717 continue processing. 718 </p> 719 </div> 720 <div class="sect3" lang="en" xml:lang="en"> 721 <div class="titlepage"> 722 <div> 723 <div> 724 <h4 class="title"><a id="id1656787"></a>DB_REP_LEASE_EXPIRED</h4> 725 </div> 726 </div> 727 </div> 728 <p> 729 The operation failed because the site's replication master lease has expired. 730 </p> 731 </div> 732 <div class="sect3" lang="en" xml:lang="en"> 733 <div class="titlepage"> 734 <div> 735 <div> 736 <h4 class="title"><a id="id1656738"></a><span>DbDeadlockException or </span>DB_REP_LOCKOUT</h4> 737 </div> 738 </div> 739 </div> 740 <p> 741 The operation was blocked by client/master synchronization. 742 </p> 743 <p> 744 <a class="xref" href="dbdeadlock.html" title="DbDeadlockException">DbDeadlockException</a> is thrown if 745 your Berkeley DB API is configured to throw exceptions. 746 Otherwise, <code class="literal">DB_REP_LOCKOUT</code> is returned. 747 </p> 748 </div> 749 <div class="sect3" lang="en" xml:lang="en"> 750 <div class="titlepage"> 751 <div> 752 <div> 753 <h4 class="title"><a id="id1656725"></a>DB_SECONDARY_BAD</h4> 754 </div> 755 </div> 756 </div> 757 <p> 758 A secondary index references a nonexistent primary key. 759 </p> 760 </div> 761 <div class="sect3" lang="en" xml:lang="en"> 762 <div class="titlepage"> 763 <div> 764 <div> 765 <h4 class="title"><a id="id1657746"></a>EINVAL</h4> 766 </div> 767 </div> 768 </div> 769 <p> 770 If the DB_CURRENT, DB_NEXT_DUP or DB_PREV_DUP flags were specified and 771 the cursor has not been initialized; the <code class="methodname">Dbc::pget()</code> method was 772 called with a cursor that does not refer to a secondary index; or if 773 an invalid flag value or parameter was specified. 774 </p> 775 </div> 776 </div> 777 <div class="sect2" lang="en" xml:lang="en"> 778 <div class="titlepage"> 779 <div> 780 <div> 781 <h3 class="title"><a id="id1656479"></a>Class</h3> 782 </div> 783 </div> 784 </div> 785 <p> 786 <a class="link" href="dbc.html" title="Chapter 3. The Dbc Handle">Dbc</a> 787 </p> 788 </div> 789 <div class="sect2" lang="en" xml:lang="en"> 790 <div class="titlepage"> 791 <div> 792 <div> 793 <h3 class="title"><a id="id1656474"></a>See Also</h3> 794 </div> 795 </div> 796 </div> 797 <p> 798 <a class="xref" href="dbc.html#dbclist" title="Database Cursors and Related Methods">Database Cursors and Related Methods</a> 799 </p> 800 </div> 801 </div> 802 <div class="navfooter"> 803 <hr /> 804 <table width="100%" summary="Navigation footer"> 805 <tr> 806 <td width="40%" align="left"><a accesskey="p" href="dbcdup.html">Prev</a> </td> 807 <td width="20%" align="center"> 808 <a accesskey="u" href="dbc.html">Up</a> 809 </td> 810 <td width="40%" align="right"> <a accesskey="n" href="dbcget_priority.html">Next</a></td> 811 </tr> 812 <tr> 813 <td width="40%" align="left" valign="top">Dbc::dup() </td> 814 <td width="20%" align="center"> 815 <a accesskey="h" href="index.html">Home</a> 816 </td> 817 <td width="40%" align="right" valign="top"> Dbc::get_priority()</td> 818 </tr> 819 </table> 820 </div> 821 </body> 822</html> 823