NNAAMMEE Dbt - Db key/data class SSYYNNOOPPSSIISS vvooiidd **DDbbtt::::ggeett__ddaattaa(()) ccoonnsstt;; vvooiidd DDbbtt::::sseett__ddaattaa((vvooiidd **));; uu__iinntt3322__tt DDbbtt::::ggeett__ssiizzee(()) ccoonnsstt;; vvooiidd DDbbtt::::sseett__ssiizzee((uu__iinntt3322__tt));; uu__iinntt3322__tt DDbbtt::::ggeett__uulleenn(()) ccoonnsstt;; vvooiidd DDbbtt::::sseett__uulleenn((uu__iinntt3322__tt));; uu__iinntt3322__tt DDbbtt::::ggeett__ddlleenn(()) ccoonnsstt;; vvooiidd DDbbtt::::sseett__ddlleenn((uu__iinntt3322__tt));; uu__iinntt3322__tt DDbbtt::::ggeett__ddooffff(()) ccoonnsstt;; vvooiidd DDbbtt::::sseett__ddooffff((uu__iinntt3322__tt));; uu__iinntt3322__tt DDbbtt::::ggeett__ffllaaggss(()) ccoonnsstt;; vvooiidd DDbbtt::::sseett__ffllaaggss((uu__iinntt3322__tt));; DDbbtt::::DDbbtt((vvooiidd **ddaattaa,, ssiizzee__tt ssiizzee));; DDbbtt::::DDbbtt(());; DDbbtt::::~~DDbbtt(());; DDbbtt::::DDbbtt((ccoonnsstt DDbbtt &&));; DDbbtt::::DDbbtt &&ooppeerraattoorr == ((ccoonnsstt DDbbtt &&));; DDEESSCCRRIIPPTTIIOONN The DB library is a family of classes that provides a mod- ular programming interface to transactions and record-ori- ented file access. The library includes support for transactions, locking, logging and file page caching, as well as various indexed access methods. Many of the classes (e.g., the file page caching class) are useful independent of the other DB classes, although some classes are explicitly based on other classes (e.g., transactions and logging). For a general description of the DB pack- age, see _d_b___i_n_t_r_o(3). This manual page describes the spe- cific details of the _D_b_t class, used to encode keys and data items in a database. KKEEYY//DDAATTAA PPAAIIRRSS Storage and retrieval for the Db access methods are based on key/data pairs. Both key and data items are repre- sented by Dbt objects. Key and data byte strings may reference strings of essen- tially unlimited length, although any two keys must fit into available memory at the same time so that they may be compared, and any one data item must fit into available memory so that it may be returned. The Dbt class provides simple access to an underlying data structure, whose elements can be examined or changed using the _s_e_t__ or _g_e_t__ methods. The remainder of the manual page sometimes refers to these accesses using the underlying name, e.g., simply _u_l_e_n instead of _g_e_t___u_l_e_n and _s_e_t___u_l_e_n. The constructors set all elements of the under- lying structure to zero. The constructor with two argu- ments has the effect of setting all elements to zero except for the specified _d_a_t_a and _s_i_z_e elements. In the case where the _f_l_a_g_s structure element is 0, when being provided a key or data item by the application, the DB package expects the _d_a_t_a object to point to a byte string of _s_i_z_e bytes. When returning a key/data item to the application, the DB package will store into the _d_a_t_a object a pointer to a byte string of _s_i_z_e bytes. BByy ddeeffaauulltt,, tthhee mmeemmoorryy rreeffeerreenncceedd bbyy tthhiiss ssttoorreedd ppooiinntteerr iiss oonnllyy vvaalliidd uunnttiill tthhee nneexxtt ccaallll ttoo tthhee DDBB ppaacckkaaggee uussiinngg tthhee DDbb hhaannddllee rreettuurrnneedd bbyy _D_b_:_:_o_p_e_n. TThhee aacccceessss mmeetthhooddss pprroovviiddee nnoo gguuaarraanntteeeess aabboouutt bbyyttee ssttrriinngg aalliiggnnmmeenntt,, aanndd aapppplliiccaattiioonnss aarree rreessppoonnssiibbllee ffoorr mmaaiinnttaaiinn-- iinngg aannyy nneecceessssaarryy aalliiggnnmmeenntt.. Use the DB_DBT_USERMEM flag to cause returned items to be placed in memory of arbi- trary alignment. Although Java normally maintains proper alignment of byte arrays, the set_offset method can be used to specify unaligned addresses. Unaligned address accesses that are not supported by the underlying hardware may be reported as an exception, or may stop the running Java program. The elements of the structure underlying the Dbt class are defined as follows: void *data; A pointer to a byte string. This element is accessed using _g_e_t___d_a_t_a and _s_e_t___d_a_t_a, and may be initialized using one of the constructors. int offset; The number of bytes offset into the _d_a_t_a array to determine the portion of the array actually used. This element is accessed using _g_e_t___o_f_f_s_e_t and _s_e_t___o_f_f_s_e_t. u_int32_t size; The length of _d_a_t_a, in bytes. This element is accessed using _g_e_t___s_i_z_e and _s_e_t___s_i_z_e, and may be ini- tialized using the constructor with two arguments. u_int32_t ulen; The size of the user's buffer (referenced by _d_a_t_a), in bytes. This location is not written by the Db functions. See the DB_DBT_USERMEM flag for more information. This element is accessed using _g_e_t___u_l_e_n and _s_e_t___u_l_e_n. u_int32_t dlen; The length of the partial record being read or written by the application, in bytes. See the DB_DBT_PARTIAL flag for more information. This ele- ment is accessed using _g_e_t___d_l_e_n and _s_e_t___d_l_e_n. u_int32_t doff; The offset of the partial record being read or writ- ten by the application, in bytes. See the DB_DBT_PARTIAL flag for more information. This ele- ment is accessed using _g_e_t___d_o_f_f and _s_e_t___d_o_f_f. u_int32_t flags; This element is accessed using _g_e_t___f_l_a_g_s and _s_e_t___f_l_a_g_s. The flags value is specified by oorr'ing together one or more of the following values: DB_DBT_MALLOC Ignored except when retrieving information from a database, e.g., a _D_b_:_:_g_e_t or _D_b_c_:_:_g_e_t call. This flag causes Db to allocate memory for the returned key or data item (using _m_a_l_l_o_c(3), or the user-specified malloc method) and return a pointer to it in the _d_a_t_a field of the key or data Dbt object. The allocated memory becomes the responsibility of the calling application. It is an error to specify both DB_DBT_MALLOC and DB_DBT_USERMEM. DB_DBT_USERMEM Ignored except when retrieving information from a database, e.g., a _D_b_:_:_g_e_t or _D_b_c_:_:_g_e_t call. The _d_a_t_a field of the key or data object must reference memory that is at least _u_l_e_n bytes in length. If the length of the requested item is less than or equal to that number of bytes, the item is copied into the memory referenced by the _d_a_t_a field. Otherwise, an error is returned, the _s_i_z_e field is set to the length needed for the requested item, and the _e_r_r_n_o variable is set to ENOMEM. It is an error to specify both DB_DBT_MALLOC and DB_DBT_USERMEM. DB_DBT_PARTIAL Ignored except when specified for a data parame- ter, where this flag causes the partial retrieval or storage of an item. If the calling application is doing a get, the _d_l_e_n bytes starting _d_o_f_f bytes from the beginning of the retrieved data record are returned as if they comprised the entire record. If any or all of the specified bytes do not exist in the record, the get is successful and the existing bytes or 0 bytes are returned. For example, if the data portion of a retrieved record was 100 bytes, and a partial retrieval was done using a Dbt having a _d_l_e_n field of 20 and a _d_o_f_f field of 85, the get call would suc- ceed, the _d_a_t_a field would reference the last 15 bytes of the record, and the _s_i_z_e field would be set to 15. If the calling application is doing a put, the _d_l_e_n bytes starting _d_o_f_f bytes from the begin- ning of the specified key's data record are replaced by the data specified by the _d_a_t_a and _s_i_z_e objects. If _d_l_e_n is smaller than _s_i_z_e, the record will grow, and if _d_l_e_n is larger than _s_i_z_e, the record will shrink. If the specified bytes do not exist, the record will be extended using nul bytes as necessary, and the put call will succeed. It is an error to attempt a partial put using the _D_b_:_:_p_u_t method in a database that supports duplicate records. Partial puts in databases supporting duplicate records must be done using a _D_b_:_:_c_u_r_s_o_r method. It is an error to attempt a partial put with differing _d_l_e_n and _s_i_z_e val- ues in a recno database with fixed-length records. For example, if the data portion of a retrieved record was 100 bytes, and a partial put was done using a Dbt having a _d_l_e_n field of 20, a _d_o_f_f field of 85, and a _s_i_z_e field of 30, the result- ing record would be 115 bytes in length, where the last 30 bytes would be those specified by the put call. The default algorithm of associating returned key or data items with the Db handle returned by _D_b_:_:_o_p_e_n(3) will obviously not work when Db handles are being used concur- rently by multiple threads within a process, i.e, when DB_THREAD was specified to _D_b_:_:_o_p_e_n(3). WWhheenn mmuullttiippllee tthhrreeaaddss aarree uussiinngg tthhee rreettuurrnneedd DDbb hhaannddllee ccoonnccuurrrreennttllyy,, eeiitthheerr tthhee DDBB__DDBBTT__MMAALLLLOOCC oorr DDBB__DDBBTT__UUSSEERRMMEEMM ffllaaggss mmuusstt bbee ssppeecciiffiieedd ffoorr aannyy DDbbtt uusseedd ffoorr kkeeyy oorr ddaattaa rreettrriieevvaall.. LLOOGGIICCAALL RREECCOORRDD NNUUMMBBEERRSS In all cases for the recno access method, and when calling the _D_b_:_:_g_e_t and _D_b_c_:_:_g_e_t functions with the DB_GET_RECNO flag specified, the _d_a_t_a field of the key must be a pointer to a memory location of type _d_b___r_e_c_n_o___t, as typedef'd in the include file. This type is a 32-bit unsigned type, (which limits the number of logical records in a recno database, and the maximum logical record which may be directly retrieved from a btree database, to 4,294,967,296). The _s_i_z_e field of the key should be the size of that type, e.g., in the C programming language, ``sizeof(db_recno_t)''. Logical record numbers are 1-based, not 0-based, i.e., the first record in the database is record number 1. BBUUGGSS The Db access methods provide no guarantees about byte string alignment, and applications are responsible for maintaining any necessary alignment. The name Dbt is a mnemonic for ``data base thang'', and was used because noone could think of a reasonable name that wasn't already in use somewhere else. SSEEEE AALLSSOO _d_b___a_r_c_h_i_v_e(1), _d_b___c_h_e_c_k_p_o_i_n_t(1), _d_b___d_e_a_d_l_o_c_k(1), _d_b___d_u_m_p(1), _d_b___l_o_a_d(1), _d_b___r_e_c_o_v_e_r(1), _d_b___s_t_a_t(1), _d_b___i_n_t_r_o(3), _d_b___i_n_t_e_r_n_a_l(3), _d_b___t_h_r_e_a_d(3), _D_b(3), _D_b_c(3), _D_b_E_n_v(3), _D_b_E_x_c_e_p_t_i_o_n(3), _D_b_I_n_f_o(3), _D_b_L_o_c_k(3), _D_b_L_o_c_k_T_a_b(3), _D_b_L_o_g(3), _D_b_L_s_n(3), _D_b_M_p_o_o_l(3), _D_b_M_p_o_o_l_F_i_l_e(3), _D_b_t(3), _D_b_T_x_n(3), _D_b_T_x_n_M_g_r(3)