~ubuntu-branches/ubuntu/edgy/rpm/edgy

<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 are specified to

the <a href="../../api_c/db_get.html">DB->get</a> or <a href="../../api_c/dbc_get.html">DBcursor->c_get</a> functions, which cause multiple records

to be returned in the specified buffer.

<p>The difference between <a href="../../api_c/dbc_get.html#DB_MULTIPLE">DB_MULTIPLE</a> and <a href="../../api_c/dbc_get.html#DB_MULTIPLE_KEY">DB_MULTIPLE_KEY</a>

is as follows: <a href="../../api_c/dbc_get.html#DB_MULTIPLE">DB_MULTIPLE</a> returns multiple data items for a

single key. For example, the <a href="../../api_c/dbc_get.html#DB_MULTIPLE">DB_MULTIPLE</a> flag would be used to

retrieve all of the duplicate data items for a single key in a single

call. The <a href="../../api_c/dbc_get.html#DB_MULTIPLE_KEY">DB_MULTIPLE_KEY</a> flag is used to retrieve multiple

key/data pairs, where each returned key may or may not have duplicate

data items.

<p>Once the <a href="../../api_c/db_get.html">DB->get</a> or <a href="../../api_c/dbc_get.html">DBcursor->c_get</a> function has returned, the

application will walk through the buffer handling the returned records.

This is implemented for the C and C++ APIs using four macros:

<a href="../../api_c/dbt_bulk.html#DB_MULTIPLE_INIT">DB_MULTIPLE_INIT</a>, <a href="../../api_c/dbt_bulk.html#DB_MULTIPLE_NEXT">DB_MULTIPLE_NEXT</a>,

<a href="../../api_c/dbt_bulk.html#DB_MULTIPLE_KEY_NEXT">DB_MULTIPLE_KEY_NEXT</a>, and <a href="../../api_c/dbt_bulk.html#DB_MULTIPLE_RECNO_NEXT">DB_MULTIPLE_RECNO_NEXT</a>. For

the Java API, this is implemented as three iterator classes:

<a href="../../api_java/dbt_bulk_class.html">DbMultipleDataIterator</a>,

<a href="../../api_java/dbt_bulk_class.html">DbMultipleKeyDataIterator</a>, and

<a href="../../api_java/dbt_bulk_class.html">DbMultipleRecnoDataIterator</a>.

<p>The <a href="../../api_c/dbt_bulk.html#DB_MULTIPLE_INIT">DB_MULTIPLE_INIT</a> macro is always called first. It

initializes a local application variable and the <b>data</b>

<a href="../../api_c/dbt.html">DBT</a> for stepping through the set of returned records. Then,

the application calls one of the remaining three macros:

<a href="../../api_c/dbt_bulk.html#DB_MULTIPLE_NEXT">DB_MULTIPLE_NEXT</a>, <a href="../../api_c/dbt_bulk.html#DB_MULTIPLE_KEY_NEXT">DB_MULTIPLE_KEY_NEXT</a>, and

<a href="../../api_c/dbt_bulk.html#DB_MULTIPLE_RECNO_NEXT">DB_MULTIPLE_RECNO_NEXT</a>.

<p>If the <a href="../../api_c/dbc_get.html#DB_MULTIPLE">DB_MULTIPLE</a> flag was specified to the <a href="../../api_c/db_get.html">DB->get</a> or

<a href="../../api_c/dbc_get.html">DBcursor->c_get</a> function, the application will always call the

<a href="../../api_c/dbt_bulk.html#DB_MULTIPLE_NEXT">DB_MULTIPLE_NEXT</a> macro. If the <a href="../../api_c/dbc_get.html#DB_MULTIPLE_KEY">DB_MULTIPLE_KEY</a> flag

was specified to the <a href="../../api_c/db_get.html">DB->get</a> or <a href="../../api_c/dbc_get.html">DBcursor->c_get</a> function, and, the

underlying database is a Btree or Hash database, the application will

always call the <a href="../../api_c/dbt_bulk.html#DB_MULTIPLE_KEY_NEXT">DB_MULTIPLE_KEY_NEXT</a> macro. If the

<a href="../../api_c/dbc_get.html#DB_MULTIPLE_KEY">DB_MULTIPLE_KEY</a> flag was specified to the <a href="../../api_c/db_get.html">DB->get</a> or

<a href="../../api_c/dbc_get.html">DBcursor->c_get</a> function, and, the underlying database is a Queue or Recno

database, the application will always call the

<a href="../../api_c/dbt_bulk.html#DB_MULTIPLE_RECNO_NEXT">DB_MULTIPLE_RECNO_NEXT</a> macro. The <a href="../../api_c/dbt_bulk.html#DB_MULTIPLE_NEXT">DB_MULTIPLE_NEXT</a>,

<a href="../../api_c/dbt_bulk.html#DB_MULTIPLE_KEY_NEXT">DB_MULTIPLE_KEY_NEXT</a>, and <a href="../../api_c/dbt_bulk.html#DB_MULTIPLE_RECNO_NEXT">DB_MULTIPLE_RECNO_NEXT</a> macros

are called repeatedly, until the end of the returned records is reached.

The end of the returned records is detected by the application's local

pointer variable being set to NULL.

<p>The following is an example of a routine that displays the contents of

a Btree database using the bulk return interfaces.

<p><blockquote><pre>int

rec_display(dbp)

DB *dbp;

{

DBC *dbcp;

DBT key, data;

size_t retklen, retdlen;

char *retkey, *retdata;

int ret, t_ret;

void *p;

<p>

memset(&key, 0, sizeof(key));

memset(&data, 0, sizeof(data));

<p>

/* Review the database in 5MB chunks. */

#define BUFFER_LENGTH (5 * 1024 * 1024)

if ((data.data = malloc(BUFFER_LENGTH)) == NULL)

return (errno);

data.ulen = BUFFER_LENGTH;

data.flags = DB_DBT_USERMEM;

<p>

/* Acquire a cursor for the database. */

if ((ret = dbp->cursor(dbp, NULL, &dbcp, 0)) != 0) {

dbp->err(dbp, ret, "DB->cursor");

free(data.data);

return (ret);

}

<p>

for (;;) {

* Acquire the next set of key/data pairs. This code does

100

* not handle single key/data pairs that won't fit in a

101

* BUFFER_LENGTH size buffer, instead returning ENOMEM to

102

* our caller.

103

104

if ((ret = dbcp->c_get(dbcp,

105

&key, &data, DB_MULTIPLE_KEY | DB_NEXT)) != 0) {

106

if (ret != DB_NOTFOUND)

107

dbp->err(dbp, ret, "DBcursor->c_get");

108

break;

109

}

110

<p>

111

for (DB_MULTIPLE_INIT(p, &data);;) {

112

DB_MULTIPLE_KEY_NEXT(p,

113

&data, retkey, retklen, retdata, retdlen);

114

if (p == NULL)

115

break;

116

printf("key: %.*s, data: %.*s\n",

117

(int)retklen, retkey, (int)retdlen, retdata);

118

}

119

}

120

<p>

121

if ((t_ret = dbcp->c_close(dbcp)) != 0) {

122

dbp->err(dbp, ret, "DBcursor->close");

123

if (ret == 0)

124

ret = t_ret;

125

}

126

<p>

127

free(data.data);

128

<p>

129

return (ret);

130

}</pre></blockquote>

131

132

</td></tr></table>

133

<p><font size=1><a href="http://www.sleepycat.com">Copyright Sleepycat Software</a></font>

134

</body>

135

</html>

Older »