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 TCL API Reference" /> 10 <link rel="up" href="tclapi.html" title="Chapter��1.�� Berkeley DB Tcl APIs" /> 11 <link rel="prev" href="dbc_dup.html" title="dbc dup" /> 12 <link rel="next" href="dbc_put.html" title="dbc put" /> 13 </head> 14 <body> 15 <div class="navheader"> 16 <table width="100%" summary="Navigation header"> 17 <tr> 18 <th colspan="3" align="center"><span class="emphasis"><em>dbc</em></span> get</th> 19 </tr> 20 <tr> 21 <td width="20%" align="left"><a accesskey="p" href="dbc_dup.html">Prev</a>��</td> 22 <th width="60%" align="center">Chapter��1.�� 23 Berkeley DB Tcl APIs 24 </th> 25 <td width="20%" align="right">��<a accesskey="n" href="dbc_put.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="dbc_get"></a><span class="emphasis"><em>dbc</em></span> get</h2> 35 </div> 36 </div> 37 </div> 38 <pre class="programlisting">dbc get 39 [-current] 40 [-first] 41 [-get_recno] 42 [-join_item] 43 [-last] 44 [-next] 45 [-nextdup] 46 [-nextnodup] 47 [-partial {offset length}] 48 [-prev] 49 [-prevnodup] 50 [-rmw] 51 52dbc get 53 [-partial {offset length}] 54 [-rmw] 55 [-set] 56 [-set_range] 57 [-set_recno] 58 key 59 60dbc get 61 -get_both 62 [-partial {offset length}] 63 [-rmw] 64 key data </pre> 65 <p> 66 The <span class="emphasis"><em>dbc</em></span> <span class="bold"><strong>get</strong></span> 67 command returns a list of {key value} pairs, except in the case of the 68 <span class="bold"><strong>-get_recno</strong></span> and <span class="bold"><strong>-join_item</strong></span> options. In the case of the 69 <span class="bold"><strong>-get_recno</strong></span> option, 70 <span class="emphasis"><em>dbc</em></span> <span class="bold"><strong>get</strong></span> returns 71 a list of the record number. In the case of the <span class="bold"><strong>-join_item</strong></span> option, <span class="emphasis"><em>dbc</em></span> 72 <span class="bold"><strong>get</strong></span> returns a list containing the 73 joined key. 74 </p> 75 <p> 76 The options follow, and are grouped by the action they perform. 77 </p> 78 <p> 79 The first group affects the position of the cursor in the database 80 without regard for the key or data item. 81 </p> 82 <div class="itemizedlist"> 83 <ul type="disc"> 84 <li> 85 <p> 86 <span class="bold"><strong>-current</strong></span> 87 </p> 88 <p> 89 Return the key/data pair to which the cursor currently refers. 90 </p> 91 <p> 92 If the cursor key/data pair was deleted, <span class="emphasis"><em>dbc</em></span> 93 <span class="bold"><strong>get</strong></span> will return an empty list. 94 </p> 95 </li> 96 <li> 97 <p> 98 <span class="bold"><strong>-first</strong></span> 99 </p> 100 <p> 101 The cursor is set to refer to the first key/data pair of the database, 102 and that pair is returned. In the presence of duplicate key values, 103 the first data item in the set of duplicates is returned. 104 </p> 105 <p> 106 If the database is a Queue or Recno database, <span class="emphasis"><em>dbc</em></span> 107 <span class="bold"><strong>get</strong></span> using the <span class="bold"><strong>-first</strong></span> option will skip any keys that exist but 108 were never explicitly created by the application, or were created and 109 later deleted. 110 </p> 111 <p> 112 If the database is empty, <span class="emphasis"><em>dbc</em></span> <span class="bold"><strong>get</strong></span> will return an empty list. 113 </p> 114 </li> 115 <li> 116 <p> 117 <span class="bold"><strong>-last</strong></span> 118 </p> 119 <p> 120 The cursor is set to refer to the last key/data pair of the database, 121 and that pair is returned. In the presence of duplicate key values, 122 the last data item in the set of duplicates is returned. 123 </p> 124 <p> 125 If the database is a Queue or Recno database, <span class="emphasis"><em>dbc</em></span> 126 <span class="bold"><strong>get</strong></span> using the <span class="bold"><strong>-last</strong></span> option will skip any keys that exist but 127 were never explicitly created by the application, or were created and 128 later deleted. 129 </p> 130 <p> 131 If the database is empty, <span class="emphasis"><em>dbc</em></span> <span class="bold"><strong>get</strong></span> will return an empty list. 132 </p> 133 </li> 134 <li> 135 <p> 136 <span class="bold"><strong>-next</strong></span> 137 </p> 138 <p> 139 If the cursor is not yet initialized, the <span class="bold"><strong>-next</strong></span> option is identical to <span class="bold"><strong>-first</strong></span>. 140 </p> 141 <p> 142 Otherwise, the cursor is moved to the next key/data pair of the 143 database, and that pair is returned. In the presence of duplicate key 144 values, the value of the key may not change. 145 </p> 146 <p> 147 If the database is a Queue or Recno database, <span class="emphasis"><em>dbc</em></span> 148 <span class="bold"><strong>get</strong></span> using the <span class="bold"><strong>-next</strong></span> option will skip any keys that exist but 149 were never explicitly created by the application, or were created and 150 later deleted. 151 </p> 152 <p> 153 If the cursor is already on the last record in the database, 154 <span class="emphasis"><em>dbc</em></span> <span class="bold"><strong>get</strong></span> will 155 return an empty list. 156 </p> 157 </li> 158 <li> 159 <p> 160 <span class="bold"><strong>-nextdup</strong></span> 161 </p> 162 <p> 163 If the next key/data pair of the database is a duplicate record for 164 the current key/data pair, the cursor is moved to the next key/data 165 pair of the database, and that pair is returned. Otherwise, 166 <span class="emphasis"><em>dbc</em></span> <span class="bold"><strong>get</strong></span> will 167 return an empty list. 168 </p> 169 </li> 170 <li> 171 <p> 172 <span class="bold"><strong>-nextnodup</strong></span> 173 </p> 174 <p> 175 If the cursor is not yet initialized, the <span class="bold"><strong>-nextnodup</strong></span> option is identical to <span class="bold"><strong>-first</strong></span>. 176 </p> 177 <p> 178 Otherwise, the cursor is moved to the next non-duplicate key/data pair 179 of the database, and that pair is returned. 180 </p> 181 <p> 182 If no non-duplicate key/data pairs occur after the cursor position in 183 the database, <span class="emphasis"><em>dbc</em></span> <span class="bold"><strong>get</strong></span> will return an empty list. 184 </p> 185 </li> 186 <li> 187 <p> 188 <span class="bold"><strong>-prev</strong></span> 189 </p> 190 <p> 191 If the cursor is not yet initialized, <span class="bold"><strong>-prev</strong></span> is identical to <span class="bold"><strong>-last</strong></span>. 192 </p> 193 <p> 194 Otherwise, the cursor is moved to the previous key/data pair of the 195 database, and that pair is returned. In the presence of duplicate key 196 values, the value of the key may not change. 197 </p> 198 <p> 199 If the database is a Queue or Recno database, <span class="emphasis"><em>dbc</em></span> 200 <span class="bold"><strong>get</strong></span> using the <span class="bold"><strong>-prev</strong></span> flag will skip any keys that exist but 201 were never explicitly created by the application, or were created and 202 later deleted. 203 </p> 204 <p> 205 If the cursor is already on the first record in the database, 206 <span class="emphasis"><em>dbc</em></span> <span class="bold"><strong>get</strong></span> will 207 return an empty list. 208 </p> 209 </li> 210 <li> 211 <p> 212 <span class="bold"><strong>-prevnodup</strong></span> 213 </p> 214 <p> 215 If the cursor is not yet initialized, the <span class="bold"><strong>-prevnodup</strong></span> option is identical to <span class="bold"><strong>-last</strong></span>. 216 </p> 217 <p> 218 Otherwise, the cursor is moved to the previous non-duplicate key/data 219 pair of the database, and that pair is returned. 220 </p> 221 <p> 222 If no non-duplicate key/data pairs occur before the cursor position in 223 the database, <span class="emphasis"><em>dbc</em></span> <span class="bold"><strong>get</strong></span> will return an empty list. 224 </p> 225 </li> 226 </ul> 227 </div> 228 <p> 229 The next group of options are used to move the cursor to a 230 location in the database based on characteristics of the 231 key and/or data items. 232 </p> 233 <div class="itemizedlist"> 234 <ul type="disc"> 235 <li> 236 <p> 237 <span class="bold"><strong>-set</strong></span> 238 </p> 239 <p> 240 Move the cursor to the specified key/data pair of the database, and 241 return the datum associated with the given key. 242 </p> 243 <p> 244 In the presence of duplicate key values, <span class="emphasis"><em>dbc</em></span> 245 <span class="bold"><strong>get</strong></span> will return the first data item 246 for the given key. 247 </p> 248 <p> 249 If the database is a Queue or Recno database and the requested key 250 exists, but was never explicitly created by the application or was 251 later deleted, <span class="emphasis"><em>dbc</em></span> <span class="bold"><strong>get</strong></span> will return an empty list. 252 </p> 253 <p> 254 If no matching keys are found, <span class="emphasis"><em>dbc</em></span> <span class="bold"><strong>get</strong></span> will return an empty list. 255 </p> 256 </li> 257 <li> 258 <p> 259 <span class="bold"><strong>-set_range</strong></span> 260 </p> 261 <p> 262 The <span class="bold"><strong>-set_range</strong></span> option is identical to 263 the <span class="bold"><strong>-set</strong></span> option, except that the key 264 is returned as well as the data item, and, in the case of the Btree 265 access method, the returned key/data pair is the smallest key greater 266 than or equal to the specified key (as determined by the comparison 267 function), permitting partial key matches and range searches. 268 </p> 269 </li> 270 <li> 271 <p> 272 <span class="bold"><strong>-get_both</strong></span> 273 </p> 274 <p> 275 The <span class="bold"><strong>-get_both</strong></span> option is identical to 276 the <span class="bold"><strong>-set</strong></span> option, except that both the 277 key and the data arguments must be matched by the key and data item in 278 the database. 279 </p> 280 <p> 281 For <span class="bold"><strong>-get_both</strong></span> to be specified, the 282 underlying database must be of type Btree or Hash. 283 284 </p> 285 </li> 286 </ul> 287 </div> 288 <p> 289 The last group of options is a general collection of 290 operations. Some of these involve positioning the cursor to 291 a location in the database based in information other than 292 what can be found in the key and/or data items. Others of 293 these have to do with the cursor's behavior upon retrieving 294 information. 295 </p> 296 <div class="itemizedlist"> 297 <ul type="disc"> 298 <li> 299 <p> 300 <span class="bold"><strong>-set_recno</strong></span> 301 </p> 302 <p> 303 Move the cursor to the specific numbered record of the database, and 304 return the associated key/data pair. The key must be a record number. 305 </p> 306 <p> 307 For the <span class="bold"><strong>-set_recno</strong></span> option to be 308 specified, the underlying database must be of type Btree, and it must 309 have been created with the <span class="bold"><strong>-recnum</strong></span> 310 option. 311 </p> 312 </li> 313 <li> 314 <p> 315 <span class="bold"><strong>-get_recno</strong></span> 316 </p> 317 <p> 318 Return a list of the record number associated with the current cursor 319 position. No key argument should be specified. 320 </p> 321 <p> 322 For <span class="bold"><strong>-get_recno</strong></span> to be specified, the 323 underlying database must be of type Btree, and it must have been 324 created with the <span class="bold"><strong>-recnum</strong></span> option. 325 </p> 326 </li> 327 <li> 328 <p> 329 <span class="bold"><strong>-join_item</strong></span> 330 </p> 331 <p> 332 Do not use the data value found in all the cursors as a lookup key for 333 the primary database, but simply return it in the key parameter 334 instead. The data parameter is left unchanged. 335 </p> 336 <p> 337 For <span class="bold"><strong>-join_item</strong></span> to be specified, the 338 cursor must have been created by the <span class="emphasis"><em>db</em></span> <span class="bold"><strong>join</strong></span> command. 339 </p> 340 </li> 341 <li> 342 <p> 343 <span class="bold"><strong>-partial {offset length}</strong></span> 344 </p> 345 <p> 346 The <span class="bold"><strong>dlen</strong></span> bytes starting <span class="bold"><strong>doff</strong></span> bytes from the beginning of the retrieved 347 data record are returned as if they comprised the entire record. If 348 any or all of the specified bytes do not exist in the record, the 349 command is successful and any existing bytes are returned. 350 </p> 351 </li> 352 <li> 353 <p> 354 <span class="bold"><strong>-rmw</strong></span> 355 </p> 356 <p> 357 Acquire write locks instead of read locks when doing the retrieval. 358 Setting this flag may decrease the likelihood of deadlock during a 359 read-modify-write cycle by immediately acquiring the write lock during 360 the read part of the cycle so that another thread of control acquiring 361 a read lock for the same item, in its own read-modify-write cycle, 362 will not result in deadlock. 363 </p> 364 </li> 365 </ul> 366 </div> 367 <p> 368 If a key is specified, and if the underlying database is a Queue or 369 Recno database, the given key will be interpreted by Tcl as an 370 integer. For all other database types, the key is interpreted by Tcl 371 as a byte array, unless indicated by a given option. 372 </p> 373 <p> 374 In the normal error case of attempting to retrieve a key that does not 375 exist an empty list is returned. 376 </p> 377 <p> 378 In the case of error, a Tcl error is thrown. 379 </p> 380 </div> 381 <div class="navfooter"> 382 <hr /> 383 <table width="100%" summary="Navigation footer"> 384 <tr> 385 <td width="40%" align="left"><a accesskey="p" href="dbc_dup.html">Prev</a>��</td> 386 <td width="20%" align="center"> 387 <a accesskey="u" href="tclapi.html">Up</a> 388 </td> 389 <td width="40%" align="right">��<a accesskey="n" href="dbc_put.html">Next</a></td> 390 </tr> 391 <tr> 392 <td width="40%" align="left" valign="top"><span class="emphasis"><em>dbc</em></span> dup��</td> 393 <td width="20%" align="center"> 394 <a accesskey="h" href="index.html">Home</a> 395 </td> 396 <td width="40%" align="right" valign="top">��<span class="emphasis"><em>dbc</em></span> put</td> 397 </tr> 398 </table> 399 </div> 400 </body> 401</html> 402