docs/gsg/CXX/CoreCursorUsage.html

   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>Cursor Example</title>
   7     <link rel="stylesheet" href="gettingStarted.css" type="text/css" />
   8     <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
   9     <link rel="start" href="index.html" title="Getting Started with Berkeley DB" />
  10     <link rel="up" href="Cursors.html" title="Chapter 4. Using Cursors" />
  11     <link rel="prev" href="ReplacingEntryWCursor.html" title="Replacing Records Using Cursors" />
  12     <link rel="next" href="indexes.html" title="Chapter 5. Secondary Databases" />
  13   </head>
  14   <body>
  15     <div xmlns="" class="navheader">
  16       <div class="libver">
  17         <p>Library Version 11.2.5.3</p>
  18       </div>
  19       <table width="100%" summary="Navigation header">
  20         <tr>
  21           <th colspan="3" align="center">Cursor Example</th>
  22         </tr>
  23         <tr>
  24           <td width="20%" align="left"><a accesskey="p" href="ReplacingEntryWCursor.html">Prev</a> </td>
  25           <th width="60%" align="center">Chapter 4. Using Cursors</th>
  26           <td width="20%" align="right"> <a accesskey="n" href="indexes.html">Next</a></td>
  27         </tr>
  28       </table>
  29       <hr />
  30     </div>
  31     <div class="sect1" lang="en" xml:lang="en">
  32       <div class="titlepage">
  33         <div>
  34           <div>
  35             <h2 class="title" style="clear: both"><a id="CoreCursorUsage"></a>Cursor Example</h2>
  36           </div>
  37         </div>
  38       </div>
  39       <p>
  40         In
  41
  42             <a class="xref" href="DbCXXUsage.html" title="Database Usage Example">Database Usage Example</a>
  43         we wrote an
  44         application that loaded two databases with
  45         vendor and inventory information. In this example, we will write an
  46         application to display all of the items in the inventory database. As a
  47         part of showing any given inventory item, we will look up the vendor who
  48         can provide the item and show the vendor's contact information.
  49     </p>
  50       <p>
  51         Specifically, the <code class="classname">example_database_read</code>
  52         application does the following:
  53     </p>
  54       <div class="orderedlist">
  55         <ol type="1">
  56           <li>
  57             <p>
  58             Opens the the inventory and vendor databases
  59             that were created by our <code class="classname">example_database_load</code>
  60             application. See
  61
  62                 <a class="xref" href="DbCXXUsage.html#exampledbload-cxx" title="Example 3.3 example_database_load">example_database_load</a>
  63             for information on how that
  64             application creates the databases and writes data to them.
  65          </p>
  66           </li>
  67           <li>
  68             <p>Obtains a cursor from the inventory database.</p>
  69           </li>
  70           <li>
  71             <p>
  72             Steps through the inventory database, displaying
  73             each record as it goes.
  74         </p>
  75           </li>
  76           <li>
  77             <p>
  78             Gets the name of the vendor for that inventory item from the
  79             inventory record.
  80         </p>
  81           </li>
  82           <li>
  83             <p>
  84             Uses the vendor name to look up the vendor record in the vendor
  85             database.
  86         </p>
  87           </li>
  88           <li>
  89             <p>Displays the vendor record.</p>
  90           </li>
  91         </ol>
  92       </div>
  93       <p>
  94         Remember that you can find the complete implementation of this application
  95         in:
  96     </p>
  97       <pre class="programlisting"><span class="emphasis"><em>DB_INSTALL</em></span>/examples_cxx/getting_started</pre>
  98       <p>
  99         where <code class="literal"><span class="emphasis"><em>DB_INSTALL</em></span></code> is the location where you
 100         placed your DB distribution.
 101     </p>
 102       <div class="example">
 103         <a id="CoreEIR-cxx"></a>
 104         <p class="title">
 105           <b>Example 4.1 example_database_read</b>
 106         </p>
 107         <div class="example-contents">
 108           <p>
 109             To begin, we include the necessary header files and perform our
 110             forward declarations. We also write our <code class="function">usage()</code>
 111             function.
 112         </p>
 113           <a id="cxx_cursor10"></a>
 114           <pre class="programlisting">// File: example_database_read.cpp
 115 #include &lt;iostream&gt;
 116 #include &lt;fstream&gt;
 117 #include &lt;cstdlib&gt;
 118
 119 #include "MyDb.hpp"
 120 #include "gettingStartedCommon.hpp"
 121
 122 // Forward declarations
 123 int show_all_records(MyDb &amp;inventoryDB, MyDb &amp;vendorDB);
 124 int show_vendor(MyDb &amp;vendorDB, const char *vendor); </pre>
 125           <p>
 126         Next we write our <code class="function">main()</code> function. Note that it is
 127         somewhat unnecessarily complicated here because we will be extending it
 128         in the next chapter to perform inventory item lookups.
 129    </p>
 130           <a id="cxx_cursor11"></a>
 131           <pre class="programlisting">// Displays all inventory items and the associated vendor record.
 132 int
 133 main (int argc, char *argv[])
 134 {
 135     // Initialize the path to the database files
 136     std::string databaseHome("./");
 137
 138     // Database names
 139     std::string vDbName("vendordb.db");
 140     std::string iDbName("inventorydb.db");
 141
 142     // Parse the command line arguments
 143     // Omitted for brevity
 144
 145     try
 146     {
 147         // Open all databases.
 148         MyDb inventoryDB(databaseHome, iDbName);
 149         MyDb vendorDB(databaseHome, vDbName);
 150
 151         show_all_records(inventoryDB, vendorDB);
 152     } catch(DbException &amp;e) {
 153         std::cerr &lt;&lt; "Error reading databases. " &lt;&lt; std::endl;
 154         std::cerr &lt;&lt; e.what() &lt;&lt; std::endl;
 155         return(e.get_errno());
 156     } catch(std::exception &amp;e) {
 157         std::cerr &lt;&lt; "Error reading databases. " &lt;&lt; std::endl;
 158         std::cerr &lt;&lt; e.what() &lt;&lt; std::endl;
 159         return(-1);
 160     }
 161
 162     return(0);
 163 } // End main </pre>
 164           <p>
 165         Next we need to write the <code class="function">show_all_records()</code>
 166         function. This function displays all
 167         of the inventory records found in the inventory database. Once it shows
 168         the inventory record, it retrieves the vendor's name from that record
 169         and uses it to look up and display the appropriate vendor record:
 170     </p>
 171           <a id="cxx_cursor12"></a>
 172           <pre class="programlisting">// Shows all the records in the inventory database.
 173 // For each inventory record shown, the appropriate
 174 // vendor record is also displayed.
 175 int
 176 show_all_records(MyDb &amp;inventoryDB, MyDb &amp;vendorDB)
 177 {
 178     // Get a cursor to the inventory db
 179     Dbc *cursorp;
 180     try {
 181         inventoryDB.getDb().cursor(NULL, &amp;cursorp, 0);
 182
 183         // Iterate over the inventory database, from the first record
 184         // to the last, displaying each in turn
 185         Dbt key, data;
 186         int ret;
 187         while ((ret = cursorp-&gt;get(&amp;key, &amp;data, DB_NEXT)) == 0 )
 188         {
 189             InventoryData inventoryItem(data.get_data());
 190             inventoryItem.show();
 191
 192             show_vendor(vendorDB, inventoryItem.getVendor().c_str());
 193         }
 194     } catch(DbException &amp;e) {
 195         inventoryDB.getDb().err(e.get_errno(),
 196                                 "Error in show_all_records");
 197         cursorp-&gt;close();
 198         throw e;
 199     } catch(std::exception &amp;e) {
 200         cursorp-&gt;close();
 201         throw e;
 202     }
 203
 204     cursorp-&gt;close();
 205     return (0);
 206 } </pre>
 207           <p>
 208         Note that the <code class="classname">InventoryData</code> class that we use here
 209         is described in
 210         <a class="xref" href="DbCXXUsage.html#InventoryData" title="Example 3.2 InventoryData Class">InventoryData Class</a>.
 211     </p>
 212           <p>
 213         Having displayed the inventory record, we now want to display the
 214         vendor record corresponding to this record.
 215         In this case we do not need to use a
 216         cursor to display the vendor record. Using a cursor here complicates our
 217         code slightly for no good gain. Instead, we simply perform a
 218         <code class="function">get()</code> directly against the vendor database.
 219     </p>
 220           <a id="cxx_cursor13"></a>
 221           <pre class="programlisting">// Shows a vendor record. Each vendor record is an instance of
 222 // a vendor structure. See loadVendorDB() in
 223 // example_database_load for how this structure was originally
 224 // put into the database.
 225 int
 226 show_vendor(MyDb &amp;vendorDB, const char *vendor)
 227 {
 228     Dbt data;
 229     VENDOR my_vendor;
 230
 231     try {
 232         // Set the search key to the vendor's name
 233         // vendor is explicitly cast to char * to stop a compiler
 234         // complaint.
 235         Dbt key((char *)vendor, strlen(vendor) + 1);
 236
 237         // Make sure we use the memory we set aside for the VENDOR
 238         // structure rather than the memory that DB allocates.
 239         // Some systems may require structures to be aligned in memory
 240         // in a specific way, and DB may not get it right.
 241
 242         data.set_data(&amp;my_vendor);
 243         data.set_ulen(sizeof(VENDOR));
 244         data.set_flags(DB_DBT_USERMEM);
 245
 246         // Get the record
 247         vendorDB.getDb().get(NULL, &amp;key, &amp;data, 0);
 248         std::cout &lt;&lt; "        " &lt;&lt; my_vendor.street &lt;&lt; "\n"
 249                   &lt;&lt; "        " &lt;&lt; my_vendor.city &lt;&lt; ", "
 250                   &lt;&lt; my_vendor.state &lt;&lt; "\n"
 251                   &lt;&lt; "        " &lt;&lt; my_vendor.zipcode &lt;&lt; "\n"
 252                   &lt;&lt; "        " &lt;&lt; my_vendor.phone_number &lt;&lt; "\n"
 253                   &lt;&lt; "        Contact: " &lt;&lt; my_vendor.sales_rep &lt;&lt; "\n"
 254                   &lt;&lt; "                 " &lt;&lt; my_vendor.sales_rep_phone
 255                   &lt;&lt; std::endl;
 256
 257     } catch(DbException &amp;e) {
 258         vendorDB.getDb().err(e.get_errno(), "Error in show_vendor");
 259         throw e;
 260     } catch(std::exception &amp;e) {
 261         throw e;
 262     }
 263     return (0);
 264 } </pre>
 265         </div>
 266       </div>
 267       <br class="example-break" />
 268       <p>
 269         That completes the implementation of
 270         <code class="classname">example_database_read()</code>. In the next chapter, we
 271         will extend this application to make use of a secondary database so that
 272         we can query the inventory database for a specific inventory item.
 273     </p>
 274     </div>
 275     <div class="navfooter">
 276       <hr />
 277       <table width="100%" summary="Navigation footer">
 278         <tr>
 279           <td width="40%" align="left"><a accesskey="p" href="ReplacingEntryWCursor.html">Prev</a> </td>
 280           <td width="20%" align="center">
 281             <a accesskey="u" href="Cursors.html">Up</a>
 282           </td>
 283           <td width="40%" align="right"> <a accesskey="n" href="indexes.html">Next</a></td>
 284         </tr>
 285         <tr>
 286           <td width="40%" align="left" valign="top">Replacing Records Using Cursors </td>
 287           <td width="20%" align="center">
 288             <a accesskey="h" href="index.html">Home</a>
 289           </td>
 290           <td width="40%" align="right" valign="top"> Chapter 5. Secondary Databases</td>
 291         </tr>
 292       </table>
 293     </div>
 294   </body>
 295 </html>