1<?xml version="1.0" encoding="UTF-8" standalone="no"?> 2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 3<html xmlns="http://www.w3.org/1999/xhtml"> 4 <head> 5 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> 6 <title>Implementing Key 7 8 Extractors 9 </title> 10 <link rel="stylesheet" href="gettingStarted.css" type="text/css" /> 11 <meta name="generator" content="DocBook XSL Stylesheets V1.62.4" /> 12 <link rel="home" href="index.html" title="Getting Started with Berkeley DB" /> 13 <link rel="up" href="indexes.html" title="Chapter��5.��Secondary Databases" /> 14 <link rel="previous" href="indexes.html" title="Chapter��5.��Secondary Databases" /> 15 <link rel="next" href="readSecondary.html" title="Reading Secondary Databases" /> 16 </head> 17 <body> 18 <div class="navheader"> 19 <table width="100%" summary="Navigation header"> 20 <tr> 21 <th colspan="3" align="center">Implementing Key 22 23 Extractors 24 </th> 25 </tr> 26 <tr> 27 <td width="20%" align="left"><a accesskey="p" href="indexes.html">Prev</a>��</td> 28 <th width="60%" align="center">Chapter��5.��Secondary Databases</th> 29 <td width="20%" align="right">��<a accesskey="n" href="readSecondary.html">Next</a></td> 30 </tr> 31 </table> 32 <hr /> 33 </div> 34 <div class="sect1" lang="en" xml:lang="en"> 35 <div class="titlepage"> 36 <div> 37 <div> 38 <h2 class="title" style="clear: both"><a id="keyCreator"></a>Implementing Key 39 40 <span>Extractors</span> 41 </h2> 42 </div> 43 </div> 44 <div></div> 45 </div> 46 <p> 47 You must provide every secondary database with a 48 <span>class</span> 49 50 that creates keys from primary records. You identify this 51 <span>class</span> 52 53 54 55 <span> 56 when you associate your secondary database to your primary. 57 </span> 58 </p> 59 <p> 60 You can create keys using whatever data you want. Typically you will 61 base your key on some information found in a record's data, but you 62 can also use information found in the primary record's key. How you build 63 your keys is entirely dependent upon the nature of the index that you 64 want to maintain. 65 </p> 66 <p> 67 You implement a key extractor by writing a function that extracts 68 the necessary information from a primary record's key or data. 69 This function must conform to a specific prototype, and it must be 70 provided as a callback to the <tt class="methodname">associate()</tt> 71 method. 72 </p> 73 <p> 74 For example, suppose your primary database records contain data that 75 uses the following structure: 76 </p> 77 <a id="c_index3"></a> 78 <pre class="programlisting">typedef struct vendor { 79 char name[MAXFIELD]; /* Vendor name */ 80 char street[MAXFIELD]; /* Street name and number */ 81 char city[MAXFIELD]; /* City */ 82 char state[3]; /* Two-digit US state code */ 83 char zipcode[6]; /* US zipcode */ 84 char phone_number[13]; /* Vendor phone number */ 85 char sales_rep[MAXFIELD]; /* Name of sales representative */ 86 char sales_rep_phone[MAXFIELD]; /* Sales rep's phone number */ 87} VENDOR; </pre> 88 <p> 89 Further suppose that you want to be able to query your primary database 90 based on the name of a sales representative. Then you would write a 91 function that looks like this: 92 </p> 93 <a id="cxx_index4"></a> 94 <pre class="programlisting">#include <db_cxx.h> 95 96... 97 98int 99get_sales_rep(Db *sdbp, // secondary db handle 100 const Dbt *pkey, // primary db record's key 101 const Dbt *pdata, // primary db record's data 102 Dbt *skey) // secondary db record's key 103{ 104 VENDOR *vendor; 105 106 // First, extract the structure contained in the primary's data 107 vendor = (VENDOR *)pdata->get_data(); 108 109 // Now set the secondary key's data to be the representative's name 110 skey->set_data(vendor->sales_rep); 111 skey->set_size(strlen(vendor->sales_rep) + 1); 112 113 // Return 0 to indicate that the record can be created/updated. 114 return (0); 115} </pre> 116 <p> 117 In order to use this function, you provide it on the 118 <tt class="methodname">associate()</tt> method after the primary and 119 secondary databases have been created and opened: 120 </p> 121 <a id="cxx_index5"></a> 122 <pre class="programlisting">db.associate(NULL, // TXN id 123 &sdb, // Secondary database 124 get_sales_rep, // Callback used for key creation. 125 0); // Flags</pre> 126 <div class="sect2" lang="en" xml:lang="en"> 127 <div class="titlepage"> 128 <div> 129 <div> 130 <h3 class="title"><a id="multikeys"></a>Working with Multiple Keys</h3> 131 </div> 132 </div> 133 <div></div> 134 </div> 135 <p> 136 Until now we have only discussed indexes as if there is 137 a one-to-one relationship between the secondary key and 138 the primary database record. In fact, it is possible to 139 generate multiple keys for any given record, provided 140 that you take appropriate steps in your key creator 141 to do so. 142 </p> 143 <p> 144 For example, suppose you had a database that contained 145 information about books. Suppose further that you 146 sometimes want to look up books by author. Because 147 sometimes books have multiple authors, you may want to 148 return multiple secondary keys for every book that you 149 index. 150 </p> 151 <p> 152 To do this, you write a key extractor that returns a 153 154 <span>Dbt</span> 155 whose <tt class="literal">data</tt> member points to an array of 156 157 <span>Dbts.</span> 158 Each such member of this array contains a single secondary key. 159 In addition, the 160 161 <span>Dbt</span> 162 returned by your key extractor must have a size field 163 equal to the number of elements contained in the 164 165 <span>Dbt</span> 166 array. Also, the flag field for the 167 168 <span>Dbt</span> 169 returned by the callback must include 170 <tt class="literal">DB_DBT_MULTIPLE</tt>. For example: 171 </p> 172 <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> 173 <h3 class="title">Note</h3> 174 <p> 175 It is important that the array of secondary 176 keys created by your callback not contain 177 repeats. That is, every element in the array 178 must be unique. If the array does not contain 179 a unique set, then the secondary can get out 180 of sync with the primary. 181 </p> 182 </div> 183 <pre class="programlisting">int 184my_callback(Db *dbp, const Dbt *pkey, const Dbt *pdata, Dbt *skey) 185{ 186 Dbt *tmpdbt; 187 char *tmpdata1, tmpdata2; 188 189 // This example skips the step of extracting the data you 190 // want to use for building your secondary keys from the 191 // pkey or pdata Dbt. 192 193 // Assume for the purpose of this example that the data 194 // is temporarily stored in two variables, 195 // tmpdata1 and tmpdata2. 196 197 // Create an array of Dbts that is large enough for the 198 // number of keys that you want to return. In this case, 199 // we go with an array of size two. 200 201 tmpdbt = malloc(sizeof(Dbt) * 2); 202 memset(tmpdbt, 0, sizeof(Dbt) * 2); 203 204 // Now assign secondary keys to each element of the array. 205 tmpdbt[0].set_data(tmpdata1); 206 tmpdbt[0].set_size((u_int32_t)strlen(tmpdbt[0].data) + 1); 207 tmpdbt[1].set_data(tmpdata2); 208 tmpdbt[1].set_size((u_int32_t)strlen(tmpdbt[1].data) + 1); 209 210 // Now we set flags for the returned Dbt. DB_DBT_MULTIPLE is 211 // required in order for DB to know that the Dbt references an 212 // array. In addition, we set DB_DBT_APPMALLOC because we 213 // dynamically allocated memory for the Dbt's data field. 214 // DB_DBT_APPMALLOC causes DB to release that memory once it 215 // is done with the returned Dbt. 216 skey->set_flags(DB_DBT_MULTIPLE | DB_DBT_APPMALLOC); 217 218 // Point the results data field to the arrays of Dbts 219 skey->set_data(tmpdbt); 220 221 // Indicate the returned array is of size 2 222 skey->size = 2; 223 224 return (0); 225} </pre> 226 </div> 227 </div> 228 <div class="navfooter"> 229 <hr /> 230 <table width="100%" summary="Navigation footer"> 231 <tr> 232 <td width="40%" align="left"><a accesskey="p" href="indexes.html">Prev</a>��</td> 233 <td width="20%" align="center"> 234 <a accesskey="u" href="indexes.html">Up</a> 235 </td> 236 <td width="40%" align="right">��<a accesskey="n" href="readSecondary.html">Next</a></td> 237 </tr> 238 <tr> 239 <td width="40%" align="left" valign="top">Chapter��5.��Secondary Databases��</td> 240 <td width="20%" align="center"> 241 <a accesskey="h" href="index.html">Home</a> 242 </td> 243 <td width="40%" align="right" valign="top">��Reading Secondary Databases</td> 244 </tr> 245 </table> 246 </div> 247 </body> 248</html> 249