1<!--$Id: dbt_bulk.so,v 10.14 2007/01/31 14:45:22 bostic Exp $--> 2<!--Copyright (c) 1997,2008 Oracle. All rights reserved.--> 3<!--See the file LICENSE for redistribution information.--> 4<html> 5<head> 6<title>Berkeley DB: DBT</title> 7<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit."> 8<meta name="keywords" content="embedded,database,programmatic,toolkit,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,Java,C,C++"> 9</head> 10<body bgcolor=white> 11<table width="100%"><tr valign=top> 12<td> 13<b>DBT: Bulk Retrieval</b> 14</td> 15<td align=right> 16<a href="/api_c/api_core.html"><img src="/images/api.gif" alt="API"></a> 17<a href="/ref/toc.html"><img src="/images/ref.gif" alt="Ref"></a></td> 18</tr></table> 19<hr size=1 noshade> 20<tt> 21<a name="2"><!--meow--></a> 22<p>If either of the <a href="/api_c/dbc_get.html#DB_MULTIPLE">DB_MULTIPLE</a> or <a href="/api_c/dbc_get.html#DB_MULTIPLE_KEY">DB_MULTIPLE_KEY</a> flags 23were specified to the <a href="/api_c/db_get.html">DB->get</a> or <a href="/api_c/dbc_get.html">DBcursor->get</a> methods, the data 24<a href="/api_c/dbt_class.html">DBT</a> returned by those interfaces will refer to a buffer that is 25filled with data. Access to that data is through the following 26macros:</p> 27<br> 28<b><a name="DB_MULTIPLE_INIT">DB_MULTIPLE_INIT</a></b><ul compact><li><pre>DB_MULTIPLE_INIT(void *pointer, <a href="/api_c/dbt_class.html">DBT</a> *data);</pre> 29<p>Initialize the retrieval. The <b>pointer</b> parameter is a variable 30to be initialized. The <b>data</b> parameter is a <a href="/api_c/dbt_class.html">DBT</a> 31structure returned from a successful call to <a href="/api_c/db_get.html">DB->get</a> or 32<a href="/api_c/dbc_get.html">DBcursor->get</a> for which one of the <a href="/api_c/dbc_get.html#DB_MULTIPLE">DB_MULTIPLE</a> or 33<a href="/api_c/dbc_get.html#DB_MULTIPLE_KEY">DB_MULTIPLE_KEY</a> flags was specified.</p></ul> 34<b><a name="DB_MULTIPLE_NEXT">DB_MULTIPLE_NEXT</a></b><ul compact><li><pre>DB_MULTIPLE_NEXT(void *pointer, <a href="/api_c/dbt_class.html">DBT</a> *data, void *retdata, size_t retdlen);</pre> 35<p>The <b>data</b> parameter is a <a href="/api_c/dbt_class.html">DBT</a> structure returned from a 36successful call to <a href="/api_c/db_get.html">DB->get</a> or <a href="/api_c/dbc_get.html">DBcursor->get</a> for which the 37<a href="/api_c/dbc_get.html#DB_MULTIPLE">DB_MULTIPLE</a> flag was specified. The <b>pointer</b> and 38<b>data</b> parameters must have been previously initialized by a call 39to DB_MULTIPLE_INIT. The <b>retdata</b> parameter is set to 40refer to the next data element in the returned set, and the 41<b>retdlen</b> parameter is set to the length, in bytes, of that data 42element. When used with the Queue and Recno access methods, 43<b>retdata</b> will be set to NULL for deleted records. The 44<b>pointer</b> parameter is set to NULL if there are no more data 45elements in the returned set.</p></ul> 46<b><a name="DB_MULTIPLE_KEY_NEXT">DB_MULTIPLE_KEY_NEXT</a></b><ul compact><li><pre>DB_MULTIPLE_KEY_NEXT(void *pointer, <a href="/api_c/dbt_class.html">DBT</a> *data, 47 void *retkey, size_t retklen, void *retdata, size_t retdlen);</pre> 48<p>The <b>data</b> parameter is a <a href="/api_c/dbt_class.html">DBT</a> structure returned from a 49successful call to <a href="/api_c/dbc_get.html">DBcursor->get</a> with the Btree or Hash access methods 50for which the <a href="/api_c/dbc_get.html#DB_MULTIPLE_KEY">DB_MULTIPLE_KEY</a> flag was specified. The 51<b>pointer</b> and <b>data</b> parameters must have been previously 52initialized by a call to DB_MULTIPLE_INIT. The <b>retkey</b> 53parameter is set to refer to the next key element in the returned set, 54and the <b>retklen</b> parameter is set to the length, in bytes, of 55that key element. The <b>retdata</b> parameter is set to refer to the 56next data element in the returned set, and the <b>retdlen</b> parameter 57is set to the length, in bytes, of that data element. The 58<b>pointer</b> parameter is set to NULL if there are no more key/data 59pairs in the returned set.</p></ul> 60<b><a name="DB_MULTIPLE_RECNO_NEXT">DB_MULTIPLE_RECNO_NEXT</a></b><ul compact><li><pre>DB_MULTIPLE_RECNO_NEXT(void *pointer, <a href="/api_c/dbt_class.html">DBT</a> *data, 61 db_recno_t recno, void * retdata, size_t retdlen);</pre> 62<p>The <b>data</b> parameter is a <a href="/api_c/dbt_class.html">DBT</a> structure returned from a 63successful call to <a href="/api_c/dbc_get.html">DBcursor->get</a> with the Queue or Recno access 64methods for which the <a href="/api_c/dbc_get.html#DB_MULTIPLE_KEY">DB_MULTIPLE_KEY</a> flag was specified. The 65<b>pointer</b> and <b>data</b> parameters must have been previously 66initialized by a call to DB_MULTIPLE_INIT. The <b>recno</b> 67parameter is set to the record number of the next record in the returned 68set. The <b>retdata</b> parameter is set to refer to the next data 69element in the returned set, and the <b>retdlen</b> parameter is set to 70the length, in bytes, of that data element. Deleted records are not 71included in the results. The <b>pointer</b> parameter is set to NULL 72if there are no more key/data pairs in the returned set.</p></ul> 73<br> 74<p>These macros may be called multiple times, but DB_MULTIPLE_INIT 75must be called before each new access of the data.</p> 76</tt> 77<table width="100%"><tr><td><br></td><td align=right> 78<a href="/api_c/api_core.html"><img src="/images/api.gif" alt="API"></a><a href="/ref/toc.html"><img src="/images/ref.gif" alt="Ref"></a> 79</td></tr></table> 80<p><font size=1>Copyright (c) 1996,2008 Oracle. All rights reserved.</font> 81</body> 82</html> 83
