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 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="db_del.html" title="db del" /> 12 <link rel="next" href="db_get_join.html" title="db get_join" /> 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>db</em></span> get</th> 19 </tr> 20 <tr> 21 <td width="20%" align="left"><a accesskey="p" href="db_del.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="db_get_join.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_get"></a><span class="emphasis"><em>db</em></span> get</h2> 35 </div> 36 </div> 37 </div> 38 <pre class="programlisting">db get 39 [-consume] 40 [-consume_wait] 41 [-glob] 42 [-partial {doff dlen}] 43 [-recno] 44 [-rmw] 45 [-txn txnid] 46 key 47 48db get 49 -get_both 50 [-partial {doff dlen}] 51 [-rmw] 52 [-txn txnid] 53 key data </pre> 54 <p> 55 The <span class="emphasis"><em>db</em></span> <span class="bold"><strong>get</strong></span> 56 command returns key/data pairs from the database. 57 </p> 58 <p> 59 In the presence of duplicate key values, <span class="emphasis"><em>db</em></span> 60 <span class="bold"><strong>get</strong></span> will return all duplicate items. 61 Duplicates are sorted by insert order except where this order has been 62 overridden by cursor operations. 63 </p> 64 <p> 65 The options are as follows: 66 </p> 67 <div class="itemizedlist"> 68 <ul type="disc"> 69 <li> 70 <p> 71 <span class="bold"><strong>-consume</strong></span> 72 </p> 73 <p> 74 Return the record number and data from the available record closest to 75 the head of the queue, and delete the record. The cursor will be 76 positioned on the deleted record. A record is available if it is not 77 deleted and is not currently locked. The underlying database must be 78 of type Queue for <span class="bold"><strong>-consume</strong></span> to be 79 specified. 80 </p> 81 </li> 82 <li> 83 <p> 84 <span class="bold"><strong>-consume_wait</strong></span> 85 </p> 86 <p> 87 The same as the <span class="bold"><strong>-consume</strong></span> flag except 88 that if the Queue database is empty, the thread of control will wait 89 until there is data in the queue before returning. The underlying 90 database must be of type Queue for <span class="bold"><strong>-consume_wait</strong></span> to be specified. 91 </p> 92 </li> 93 <li> 94 <p> 95 <span class="bold"><strong>-get_both key data</strong></span> 96 </p> 97 <p> 98 Retrieve the key/data pair only if both the key and data match the 99 arguments. 100 </p> 101 </li> 102 <li> 103 <p> 104 <span class="bold"><strong>-glob</strong></span> 105 </p> 106 <p> 107 Return all keys matching the given key, where the key is a simple 108 wildcard pattern. Where it is used, it replaces the use of the key 109 with the given pattern of a set of keys. Any characters after the 110 wildcard character are ignored. For example, in a database of last 111 names, the command "db0 get Jones" will return all occurrences of 112 "Jones" in the database, and the command "db0 get -glob Jo*" will 113 return both "Jones" and "Johnson" from the database. The command "db0 114 get -glob *" will return all of the key/data pairs in the database. 115 This option only works on databases using the Btree access method. 116 </p> 117 </li> 118 <li> 119 <p> 120 <span class="bold"><strong>-partial {doff dlen}</strong></span> 121 </p> 122 <p> 123 The <span class="bold"><strong>dlen</strong></span> bytes starting <span class="bold"><strong>doff</strong></span> bytes from the beginning of the retrieved 124 data record are returned as if they comprised the entire record. If 125 any or all of the specified bytes do not exist in the record, the 126 command is successful and any existing bytes are returned. 127 </p> 128 </li> 129 <li> 130 <p> 131 <span class="bold"><strong>-recno</strong></span> 132 </p> 133 <p> 134 Retrieve the specified numbered key/data pair from a database. For 135 <span class="bold"><strong>-recno</strong></span> to be specified, the specified 136 key must be a record number; and the underlying database must be of 137 type Recno or Queue, or of type Btree that was created with the 138 <span class="bold"><strong>-recnum</strong></span> option. 139 </p> 140 </li> 141 <li> 142 <p> 143 <span class="bold"><strong>-rmw</strong></span> 144 </p> 145 <p> 146 Acquire write locks instead of read locks when doing the retrieval. 147 Setting this flag may decrease the likelihood of deadlock during a 148 read-modify-write cycle by immediately acquiring the write lock during 149 the read part of the cycle so that another thread of control acquiring 150 a read lock for the same item, in its own read-modify-write cycle, 151 will not result in deadlock. 152 </p> 153 <p> 154 Because the <span class="emphasis"><em>db</em></span> <span class="bold"><strong>get</strong></span> command will not hold locks across Berkeley 155 DB interface calls in nontransactional environments, the <span class="bold"><strong>-rmw</strong></span> argument to the <span class="emphasis"><em>db</em></span> 156 <span class="bold"><strong>get</strong></span> call is only meaningful in the 157 presence of transactions. 158 </p> 159 </li> 160 <li> 161 <p> 162 <span class="bold"><strong>-txn txnid</strong></span> 163 </p> 164 <p> 165 If the operation is part of an application-specified transaction, the 166 <span class="bold"><strong>txnid</strong></span> parameter is a transaction 167 handle returned from <span class="emphasis"><em>env</em></span> <span class="bold"><strong>txn</strong></span>. If no transaction handle is specified, 168 but the operation occurs in a transactional database, the operation 169 will be implicitly transaction protected. 170 </p> 171 </li> 172 </ul> 173 </div> 174 <p> 175 If the underlying database is a Queue or Recno database, the given key 176 will be interpreted by Tcl as an integer. For all other database 177 types, the key is interpreted by Tcl as a byte array, unless indicated 178 by a given option. 179 </p> 180 <p> 181 A list of key/data pairs is returned. In the error case that no 182 matching key exists, an empty list is returned. In all other cases, a 183 Tcl error is thrown. 184 </p> 185 </div> 186 <div class="navfooter"> 187 <hr /> 188 <table width="100%" summary="Navigation footer"> 189 <tr> 190 <td width="40%" align="left"><a accesskey="p" href="db_del.html">Prev</a>��</td> 191 <td width="20%" align="center"> 192 <a accesskey="u" href="tclapi.html">Up</a> 193 </td> 194 <td width="40%" align="right">��<a accesskey="n" href="db_get_join.html">Next</a></td> 195 </tr> 196 <tr> 197 <td width="40%" align="left" valign="top"><span class="emphasis"><em>db</em></span> del��</td> 198 <td width="20%" align="center"> 199 <a accesskey="h" href="index.html">Home</a> 200 </td> 201 <td width="40%" align="right" valign="top">��<span class="emphasis"><em>db</em></span> get_join</td> 202 </tr> 203 </table> 204 </div> 205 </body> 206</html> 207