1<!--$Id: db_get.so,v 11.20 2004/12/16 19:13:04 bostic Exp $--> 2<!--$Id: m4.tcl,v 11.28 2004/12/16 19:13:05 bostic Exp $--> 3<!--Copyright (c) 1997,2008 Oracle. All rights reserved.--> 4<!--See the file LICENSE for redistribution information.--> 5<html> 6<head> 7<title>Berkeley DB: db get</title> 8<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit."> 9<meta name="keywords" content="embedded,database,programmatic,toolkit,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,Java,C,C++"> 10</head> 11<body bgcolor=white> 12<table width="100%"><tr valign=top> 13<td> 14<b><i>db</i> <b>get</b></b> 15</td> 16<td align=right> 17<a href="../api_tcl/api_tcl.html"><img src="../images/api.gif" alt="API"></a> 18<a href="../ref/toc.html"><img src="../images/ref.gif" alt="Ref"></a></td> 19</tr></table> 20<hr size=1 noshade> 21<tt> 22<b><pre>db get 23 [-consume] 24 [-consume_wait] 25 [-glob] 26 [-partial {doff dlen}] 27 [-recno] 28 [-rmw] 29 [-txn txnid] 30 key 31db get 32 -get_both 33 [-partial {doff dlen}] 34 [-rmw] 35 [-txn txnid] 36 key data 37</pre></b> 38<b>Description(db get)</b> 39<p>The <i>db</i> <b>get</b> command returns key/data pairs from the database.</p> 40<p>In the presence of duplicate key values, <i>db</i> <b>get</b> will return all 41duplicate items. Duplicates are sorted by insert order except where this 42order has been overridden by cursor operations.</p> 43<p>The options are as follows:</p> 44<br> 45<b>-consume</b><ul compact><li>Return the record number and data from the available record closest to 46the head of the queue, and delete the record. The cursor will be 47positioned on the deleted record. A record is available if it is not 48deleted and is not currently locked. The underlying database must be 49of type Queue for <b>-consume</b> to be specified.</ul> 50<b>-consume_wait</b><ul compact><li>The same as the <b>-consume</b> flag except that if the Queue database 51is empty, the thread of control will wait until there is data in the 52queue before returning. The underlying database must be of type Queue 53for <b>-consume_wait</b> to be specified.</ul> 54<b>-get_both key data</b><ul compact><li>Retrieve the key/data pair only if both the key and data match the 55arguments.</ul> 56<b>-glob</b><ul compact><li>Return all keys matching the given key, where the key is a simple 57wildcard pattern. Where it is used, it replaces the use of the key with 58the given pattern of a set of keys. Any characters after the wildcard 59character are ignored. For example, in a database of last names, the 60command "db0 get Jones" will return all occurrences of "Jones" in the 61database, and the command "db0 get -glob Jo*" will return both "Jones" 62and "Johnson" from the database. The command "db0 get -glob *" will 63return all of the key/data pairs in the database. 64This option only works on databases using the Btree access method.</ul> 65<b>-partial {doff dlen}</b><ul compact><li>The <b>dlen</b> bytes starting <b>doff</b> bytes from the beginning 66of the retrieved data record are returned as if they comprised the 67entire record. If any or all of the specified bytes do not exist in the 68record, the command is successful and any existing bytes are returned.</ul> 69<b>-recno</b><ul compact><li>Retrieve the specified numbered key/data pair from a database. For 70<b>-recno</b> to be specified, the specified key must be a record 71number; and the underlying database must be of type Recno or Queue, or 72of type Btree that was created with the <b>-recnum</b> option.</ul> 73<b>-rmw</b><ul compact><li>Acquire write locks instead of read locks when doing the retrieval. 74Setting this flag may decrease the likelihood of deadlock during a 75read-modify-write cycle by immediately acquiring the write lock during 76the read part of the cycle so that another thread of control acquiring a 77read lock for the same item, in its own read-modify-write cycle, will not 78result in deadlock. 79<p>Because the <i>db</i> <b>get</b> command will not hold locks across Berkeley DB 80interface calls in nontransactional environments, the <b>-rmw</b> 81argument to the <i>db</i> <b>get</b> call is only meaningful in the presence 82of transactions.</p></ul> 83<b>-txn txnid</b><ul compact><li>If the operation is part of an application-specified transaction, the 84<b>txnid</b> parameter is a transaction handle returned from 85<i>env</i> <b>txn</b>. If no transaction handle is specified, but the 86operation occurs in a transactional 87database, 88the operation will be implicitly transaction protected.</ul> 89<br> 90<p>If the underlying database is a Queue or Recno database, the given key 91will be interpreted by Tcl as an integer. For all other database types, 92the key is interpreted by Tcl as a byte array, unless indicated by a 93given option.</p> 94<p>A list of key/data pairs is returned. In the error case that no matching 95key exists, an empty list is returned. In all other cases, a Tcl error 96is thrown.</p> 97</tt> 98<table width="100%"><tr><td><br></td><td align=right> 99<a href="../api_tcl/api_tcl.html"><img src="../images/api.gif" alt="API"></a><a href="../ref/toc.html"><img src="../images/ref.gif" alt="Ref"></a> 100</td></tr></table> 101<p><font size=1>Copyright (c) 1996,2008 Oracle. All rights reserved.</font> 102</body> 103</html> 104