1<!--$Id: dbt_class.so,v 10.1 2002/08/24 18:22:30 bostic Exp $--> 2<!--$Id: dbt_cxx.so,v 10.72 2007/02/27 00:41:24 mjc 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: Dbt</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>Dbt</b> 15</td> 16<td align=right> 17<a href="../api_cxx/api_core.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> 23#include <db_cxx.h> 24<p> 25class Dbt { 26public: 27 Dbt(void *data, size_t size); 28 Dbt(); 29 Dbt(const Dbt &); 30 Dbt &operator = (const Dbt &); 31 ~Dbt(); 32<p> 33 void *get_data() const; 34 void set_data(void *); 35<p> 36 u_int32_t get_size() const; 37 void set_size(u_int32_t); 38<p> 39 u_int32_t get_ulen() const; 40 void set_ulen(u_int32_t); 41<p> 42 u_int32_t get_dlen() const; 43 void set_dlen(u_int32_t); 44<p> 45 u_int32_t get_doff() const; 46 void set_doff(u_int32_t); 47<p> 48 u_int32_t get_flags() const; 49 void set_flags(u_int32_t); 50<p> 51 DBT *Dbt::get_DBT(); 52 const DBT *Dbt::get_const_DBT() const; 53 static Dbt *Dbt::get_Dbt(DBT *dbt); 54 static const Dbt *Dbt::get_const_Dbt(const DBT *dbt); 55}; 56</pre></b> 57<hr size=1 noshade> 58<b>Description: Dbt</b> 59<p>This information describes the specific details of the Dbt class, 60used to encode keys and data items in a database.</p> 61<a name="2"><!--meow--></a> 62<b>Key/Data Pairs</b> 63<p>Storage and retrieval for the <a href="../api_cxx/db_class.html">Db</a> access methods are based on 64key/data pairs. Both key and data items are represented by Dbt 65objects. Key and data byte strings may refer to strings of zero length 66up to strings of essentially unlimited length. See 67<a href="../ref/am_misc/dbsizes.html">Database limits</a> for more 68information.</p> 69<p>The Dbt class provides simple access to an underlying data 70structure, whose elements can be examined or changed using the usual 71<b>set</b> or <b>get</b> methods. Dbt can be subclassed, 72providing a way to associate with it additional data or references to 73other structures.</p> 74<p>The constructors set all elements of the underlying structure to zero. 75The constructor with two parameters has the effect of setting all elements 76to zero except for the <b>data</b> and <b>size</b> elements.</p> 77<p>In the case in which the <b>flags</b> structure element is set to 0, when 78the application is providing Berkeley DB a key or data item to store into the 79database, Berkeley DB expects the <b>data</b> object to point to a byte 80string of <b>size</b> bytes. When returning a key/data item to the 81application, Berkeley DB will store into the <b>data</b> object a pointer to 82a byte string of <b>size</b> bytes, and the memory to which the pointer 83refers will be allocated and managed by Berkeley DB.</p> 84<p>Access to Dbt objects is not re-entrant. In particular, if 85multiple threads simultaneously access the same Dbt object using 86<a href="../api_cxx/db_class.html">Db</a> API calls, the results are undefined, and may result in a 87crash. One easy way to avoid problems is to use Dbt objects 88that are constructed as stack variables.</p> 89<p>Each Dbt object has an associated DBT struct, which is used by 90the underlying implementation of Berkeley DB and its C-language API. The 91Dbt::get_DBT method returns a pointer to this struct. Given a const 92Dbt object, Dbt::get_const_DBT returns a const pointer to the 93same struct.</p> 94<p>Given a DBT struct, the Dbt::get_Dbt method returns the corresponding 95Dbt object, if there is one. If the DBT object was not 96associated with a Dbt (that is, it was not returned from a call 97to Dbt::get_DBT), then the result of Dbt::get_Dbt is undefined. Given 98a const DBT struct, Dbt::get_const_Dbt returns the associated const 99Dbt object, if there is one.</p> 100<p>These methods may be useful for Berkeley DB applications including both C 101and C++ language software. It should not be necessary to use these 102calls in a purely C++ application.</p> 103<hr size=1 noshade> 104<b>Description: Dbt::set_data</b> 105<p>Set the data array.</p> 106<b>Parameters</b> <br> 107 <b>data</b><ul compact><li>The <b>data</b> parameter is an array of bytes to be used to set the 108content for the Dbt.</ul> 109<br> 110<hr size=1 noshade> 111<b>Description: Dbt::get_data</b> 112<p>Return the data array.</p> 113<hr size=1 noshade> 114<b>Description: Dbt::set_recno_key_data</b> 115<p>Initialize the data array from a logical record number. Recno database 116records are ordered by integer keys starting at 1. When the 117Dbt::set_recno_key_data method is called, the data, size and offset 118fields in the Dbt are implicitly set to hold a byte array 119representation of the integer key.</p> 120<b>Parameters</b> <br> 121 <b>recno</b><ul compact><li>The <b>recno</b> parameter logical record number used to initialize the 122data array.</ul> 123<br> 124<hr size=1 noshade> 125<b>Description: Dbt::get_recno_key_data</b> 126<p>Return an object from the data array, expecting that data to be a 127logical record number.</p> 128<hr size=1 noshade> 129<b>Description: Dbt::set_offset</b> 130<p>Set the byte offset into the data array.</p> 131<p>The number of bytes offset into the <b>data</b> array determine the 132portion of the array actually used. This element is accessed using 133Dbt::get_offset and Dbt::set_offset.</p> 134<b>Parameters</b> <br> 135 <b>offset</b><ul compact><li>The <b>offset</b> parameter is the byte offset into the data array.</ul> 136<br> 137<hr size=1 noshade> 138<b>Description: Dbt::get_offset</b> 139<p>Return the byte offset into the data array.</p> 140<hr size=1 noshade> 141<b>Description: Dbt::set_size</b> 142<p>Set the byte size of the data array.</p> 143<b>Parameters</b> <br> 144 <b>size</b><ul compact><li>The <b>size</b> parameter is the size of the data array in bytes.</ul> 145<br> 146<hr size=1 noshade> 147<b>Description: Dbt::get_size</b> 148<p>Return the data array size.</p> 149<hr size=1 noshade> 150<b>Description: Dbt::set_ulen</b> 151<p>Set the byte size of the user-specified buffer.</p> 152<p>Note that applications can determine the length of a record by setting 153the <b>ulen</b> to 0 and checking the return value found in <b>size</b>. 154See the DB_DBT_USERMEM flag for more information.</p> 155<b>Parameters</b> <br> 156 <b>ulen</b><ul compact><li>The <b>ulen</b> parameter the size of the data array in bytes.</ul> 157<br> 158<hr size=1 noshade> 159<b>Description: Dbt::get_ulen</b> 160<p>Return the length in bytes of the user-specified buffer.</p> 161<hr size=1 noshade> 162<b>Description: Dbt::set_dlen</b> 163<p>Set the byte length of the partial record being read or written by the 164application, in bytes. See the DB_DBT_PARTIAL flag for more 165information.</p> 166<b>Parameters</b> <br> 167 <b>dlen</b><ul compact><li>The <b>dlen</b> parameter is the length of the partial record in bytes.</ul> 168<br> 169<hr size=1 noshade> 170<b>Description: Dbt::get_dlen</b> 171<p>Return the length of the partial record, in bytes.</p> 172<hr size=1 noshade> 173<b>Description: Dbt::set_doff</b> 174<p>Set the offset of the partial record being read or written by the 175application, in bytes. See the DB_DBT_PARTIAL flag for more 176information.</p> 177<b>Parameters</b> <br> 178 <b>doff</b><ul compact><li>The <b>doff</b> parameter is the offset of the partial record.</ul> 179<br> 180<hr size=1 noshade> 181<b>Description: Dbt::get_doff</b> 182<p>Return the offset of the partial record, in bytes.</p> 183<hr size=1 noshade> 184<b>Description: Dbt::set_flags</b> 185<p>Set the object flag value.</p> 186<b>Parameters</b> <br> 187 <b>flags</b><ul compact><li>The <b>flags</b> parameter is Dbt flag value.</ul> 188The <b>flags</b> parameter must be set to 0 or by bitwise inclusively <b>OR</b>'ing together one 189or more of the following values: 190<br> 191<b><a name="DB_DBT_MALLOC">DB_DBT_MALLOC</a></b><ul compact><li>When this flag is set, Berkeley DB will allocate memory for the returned key 192or data item (using <b>malloc</b>(3) or the user-specified malloc 193method), and return a pointer to it in the <b>data</b> field of the key 194or data Dbt object. Because any allocated memory becomes the 195responsibility of the calling application, the caller must determine 196whether memory was allocated using the returned value of the 197<b>data</b> field. 198<p>It is an error to specify more than one of DB_DBT_MALLOC, 199DB_DBT_REALLOC, and DB_DBT_USERMEM.</p></ul> 200<b><a name="DB_DBT_REALLOC">DB_DBT_REALLOC</a></b><ul compact><li>When this flag is set Berkeley DB will allocate memory for the returned key 201or data item (using <b>realloc</b>(3) or the user-specified realloc 202method), and return a pointer to it in the <b>data</b> field of the key 203or data Dbt object. Because any allocated memory becomes the 204responsibility of the calling application, the caller must determine 205whether memory was allocated using the returned value of the 206<b>data</b> field. 207<p>It is an error to specify more than one of DB_DBT_MALLOC, 208DB_DBT_REALLOC, and DB_DBT_USERMEM.</p></ul> 209<a name="3"><!--meow--></a> 210<b><a name="DB_DBT_USERMEM">DB_DBT_USERMEM</a></b><ul compact><li>The <b>data</b> field of the key or data object must refer to memory 211that is at least <b>ulen</b> bytes in length. If the length of the 212requested item is less than or equal to that number of bytes, the item 213is copied into the memory referred to by the <b>data</b> field. 214Otherwise, the <b>size</b> fields of both the key and data Dbt 215objects are set to the length needed for the requested item, and the 216error DB_BUFFER_SMALL is returned. 217<p>It is an error to specify more than one of DB_DBT_MALLOC, 218DB_DBT_REALLOC, and DB_DBT_USERMEM.</p></ul> 219<br> 220<p>If DB_DBT_MALLOC or DB_DBT_REALLOC is specified, Berkeley DB 221allocates a properly sized byte array to contain the data. This can be 222convenient if you know little about the nature of the data, specifically 223the size of data in the database. However, if your application makes 224repeated calls to retrieve keys or data, you may notice increased garbage 225collection due to this allocation. If you know the maximum size of data 226you are retrieving, you might decrease the memory burden and speed your 227application by allocating your own byte array and using 228DB_DBT_USERMEM. Even if you don't know the maximum size, you can 229use this option and reallocate your array whenever your retrieval API call 230returns an DB_BUFFER_SMALL error or throws an exception 231encapsulating an DB_BUFFER_SMALL.</p> 232<br> 233<b><a name="DB_DBT_PARTIAL">DB_DBT_PARTIAL</a></b><ul compact><li>Do partial retrieval or storage of an item. If the calling application 234is doing a get, the <b>dlen</b> bytes starting <b>doff</b> bytes from 235the beginning of the retrieved data record are returned as if they 236comprised the entire record. If any or all of the specified bytes do 237not exist in the record, the get is successful, and any existing bytes 238are returned. 239<p>For example, if the data portion of a retrieved record was 100 bytes, 240and a partial retrieval was done using a Dbt having a <b>dlen</b> 241field of 20 and a <b>doff</b> field of 85, the get call would succeed, 242the <b>data</b> field would refer to the last 15 bytes of the record, 243and the <b>size</b> field would be set to 15.</p> 244<p>If the calling application is doing a put, the <b>dlen</b> bytes starting 245<b>doff</b> bytes from the beginning of the specified key's data record 246are replaced by the data specified by the <b>data</b> and <b>size</b> 247objects. 248If <b>dlen</b> is smaller than <b>size</b>, the record will grow; if 249<b>dlen</b> is larger than <b>size</b>, the record will shrink. 250If the specified bytes do not exist, the record will be extended using nul 251bytes as necessary, and the put call will succeed.</p> 252<p>It is an error to attempt a partial put using the <a href="../api_cxx/db_put.html">Db::put</a> 253method in a database that supports duplicate records. 254Partial puts in databases supporting duplicate records must be done 255using a <a href="../api_cxx/dbc_class.html">Dbc</a> method.</p> 256<p>It is an error to attempt a partial put with differing <b>dlen</b> and 257<b>size</b> values in Queue or Recno databases with fixed-length records.</p> 258<p>For example, if the data portion of a retrieved record was 100 bytes, 259and a partial put was done using a Dbt having a <b>dlen</b> 260field of 20, a <b>doff</b> field of 85, and a <b>size</b> field of 30, 261the resulting record would be 115 bytes in length, where the last 30 262bytes would be those specified by the put call.</p></ul> 263<b><a name="DB_DBT_APPMALLOC">DB_DBT_APPMALLOC</a></b><ul compact><li>After an application-supplied callback routine passed to either 264<a href="../api_cxx/db_associate.html">Db::associate</a> or <a href="../api_cxx/db_set_append_recno.html">Db::set_append_recno</a> is executed, the 265<b>data</b> field of a Dbt may refer to memory allocated with 266<b>malloc</b>(3) or <b>realloc</b>(3). In that case, the 267callback sets the DB_DBT_APPMALLOC flag in the Dbt so 268that Berkeley DB will call <b>free</b>(3) to deallocate the memory when it 269is no longer required.</ul> 270<b><a name="DB_DBT_MULTIPLE">DB_DBT_MULTIPLE</a></b><ul compact><li>Set in a secondary key creation callback routine passed to 271<a href="../api_cxx/db_associate.html">Db::associate</a> to indicate that multiple secondary keys should be 272associated with the given primary key/data pair. If set, the 273<b>size</b> field indicates the number of secondary keys and the 274<b>data</b> field refers to an array of that number of Dbt 275structures. 276<p>The DB_DBT_APPMALLOC flag may be set on any of the Dbt 277structures to indicate that their <b>data</b> field needs to be 278freed.</p></ul> 279<br> 280<br> 281<hr size=1 noshade> 282<b>Description: Dbt::get_flags</b> 283<p>Return the object flag value.</p> 284</tt> 285<table width="100%"><tr><td><br></td><td align=right> 286<a href="../api_cxx/api_core.html"><img src="../images/api.gif" alt="API"></a><a href="../ref/toc.html"><img src="../images/ref.gif" alt="Ref"></a> 287</td></tr></table> 288<p><font size=1>Copyright (c) 1996,2008 Oracle. All rights reserved.</font> 289</body> 290</html> 291