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>Partial record storage and retrieval</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="Berkeley DB Programmer's Reference Guide" /> 10 <link rel="up" href="am_misc.html" title="Chapter��4.�� Access Method Wrapup" /> 11 <link rel="prev" href="am_misc_bulk.html" title="Retrieving and updating records in bulk" /> 12 <link rel="next" href="am_misc_struct.html" title="Storing C/C++ structures/objects" /> 13 </head> 14 <body> 15 <div class="navheader"> 16 <table width="100%" summary="Navigation header"> 17 <tr> 18 <th colspan="3" align="center">Partial record storage and retrieval</th> 19 </tr> 20 <tr> 21 <td width="20%" align="left"><a accesskey="p" href="am_misc_bulk.html">Prev</a>��</td> 22 <th width="60%" align="center">Chapter��4.�� 23 Access Method Wrapup 24 </th> 25 <td width="20%" align="right">��<a accesskey="n" href="am_misc_struct.html">Next</a></td> 26 </tr> 27 </table> 28 <hr /> 29 </div> 30 <div class="sect1" lang="en" xml:lang="en"> 31 <div class="titlepage"> 32 <div> 33 <div> 34 <h2 class="title" style="clear: both"><a id="am_misc_partial"></a>Partial record storage and retrieval</h2> 35 </div> 36 </div> 37 </div> 38 <p>It is possible to both store and retrieve parts of data items in all 39Berkeley DB access methods. This is done by setting the 40<a href="../api_reference/C/dbt.html#dbt_DB_DBT_PARTIAL" class="olink">DB_DBT_PARTIAL</a> flag <a href="../api_reference/C/dbt.html" class="olink">DBT</a> structure passed to the 41Berkeley DB method.</p> 42 <p>The <a href="../api_reference/C/dbt.html#dbt_DB_DBT_PARTIAL" class="olink">DB_DBT_PARTIAL</a> flag is based on the values of two fields 43of the <a href="../api_reference/C/dbt.html" class="olink">DBT</a> structure: <span class="bold"><strong>dlen</strong></span> and <span class="bold"><strong>doff</strong></span>. The value 44of <span class="bold"><strong>dlen</strong></span> is the number of bytes of the record in which the 45application is interested. The value of <span class="bold"><strong>doff</strong></span> is the offset from 46the beginning of the data item where those bytes start.</p> 47 <p>For example, if the data item were <span class="bold"><strong>ABCDEFGHIJKL</strong></span>, a <span class="bold"><strong>doff</strong></span> 48value of 3 would indicate that the bytes of interest started at 49<span class="bold"><strong>D</strong></span>, and a <span class="bold"><strong>dlen</strong></span> value of 4 would indicate that the bytes 50of interest were <span class="bold"><strong>DEFG</strong></span>.</p> 51 <p>When retrieving a data item from a database, the <span class="bold"><strong>dlen</strong></span> bytes 52starting <span class="bold"><strong>doff</strong></span> bytes from the beginning of the record are 53returned, as if they comprised the entire record. If any or all of the 54specified bytes do not exist in the record, the retrieval is still 55successful and any existing bytes are returned.</p> 56 <p>When storing a data item into the database, the <span class="bold"><strong>dlen</strong></span> bytes 57starting <span class="bold"><strong>doff</strong></span> bytes from the beginning of the specified key's 58data record are replaced by the data specified by the <span class="bold"><strong>data</strong></span> and 59<span class="bold"><strong>size</strong></span> fields. If <span class="bold"><strong>dlen</strong></span> is smaller than <span class="bold"><strong>size</strong></span>, the 60record will grow, and if <span class="bold"><strong>dlen</strong></span> is larger than <span class="bold"><strong>size</strong></span>, the 61record will shrink. If the specified bytes do not exist, the record will 62be extended using nul bytes as necessary, and the store call will still 63succeed.</p> 64 <p>The following are various examples of the put case for the 65<a href="../api_reference/C/dbt.html#dbt_DB_DBT_PARTIAL" class="olink">DB_DBT_PARTIAL</a> flag. In all examples, the initial data item is 20 66bytes in length:</p> 67 <p> 68 <span class="bold"> 69 <strong>ABCDEFGHIJ0123456789</strong> 70 </span> 71 </p> 72 <div class="orderedlist"> 73 <ol type="1"> 74 <li> 75 <pre class="programlisting">size = 20 76doff = 0 77dlen = 20 78data = abcdefghijabcdefghij 79 80Result: The 20 bytes at offset 0 are replaced by the 20 bytes of 81data; that is, the entire record is replaced. 82 83ABCDEFGHIJ0123456789 -> abcdefghijabcdefghij </pre> 84 </li> 85 <li> 86 <pre class="programlisting">size = 10 87doff = 20 88dlen = 0 89data = abcdefghij 90 91Result: The 0 bytes at offset 20 are replaced by the 10 bytes of 92data; that is, the record is extended by 10 bytes. 93 94ABCDEFGHIJ0123456789 -> ABCDEFGHIJ0123456789abcdefghij </pre> 95 </li> 96 <li> 97 <pre class="programlisting">size = 10 98doff = 10 99dlen = 5 100data = abcdefghij 101 102Result: The 5 bytes at offset 10 are replaced by the 10 bytes of 103data. 104 105ABCDEFGHIJ0123456789 -> ABCDEFGHIJabcdefghij56789 </pre> 106 </li> 107 <li> 108 <pre class="programlisting">size = 10 109doff = 10 110dlen = 0 111data = abcdefghij 112 113Result: The 0 bytes at offset 10 are replaced by the 10 bytes of 114data; that is, 10 bytes are inserted into the record. 115 116ABCDEFGHIJ0123456789 -> ABCDEFGHIJabcdefghij0123456789 </pre> 117 </li> 118 <li> 119 <pre class="programlisting">size = 10 120doff = 2 121dlen = 15 122data = abcdefghij 123 124Result: The 15 bytes at offset 2 are replaced by the 10 bytes of 125data. 126 127ABCDEFGHIJ0123456789 -> ABabcdefghij789 </pre> 128 </li> 129 <li> 130 <pre class="programlisting">size = 10 131doff = 0 132dlen = 0 133data = abcdefghij 134 135Result: The 0 bytes at offset 0 are replaced by the 10 bytes of 136data; that is, the 10 bytes are inserted at the beginning of the 137record. 138 139ABCDEFGHIJ0123456789 -> abcdefghijABCDEFGHIJ0123456789 </pre> 140 </li> 141 <li> 142 <pre class="programlisting">size = 0 143doff = 0 144dlen = 10 145data = "" 146 147Result: The 10 bytes at offset 0 are replaced by the 0 bytes of 148data; that is, the first 10 bytes of the record are discarded. 149 150ABCDEFGHIJ0123456789 -> 0123456789 </pre> 151 </li> 152 <li> 153 <pre class="programlisting">size = 10 154doff = 25 155dlen = 0 156data = abcdefghij 157 158Result: The 0 bytes at offset 25 are replaced by the 10 bytes of 159data; that is, 10 bytes are inserted into the record past the end 160of the current data (\0 represents a nul byte). 161 162ABCDEFGHIJ0123456789 -> ABCDEFGHIJ0123456789\0\0\0\0\0abcdefghij </pre> 163 </li> 164 </ol> 165 </div> 166 </div> 167 <div class="navfooter"> 168 <hr /> 169 <table width="100%" summary="Navigation footer"> 170 <tr> 171 <td width="40%" align="left"><a accesskey="p" href="am_misc_bulk.html">Prev</a>��</td> 172 <td width="20%" align="center"> 173 <a accesskey="u" href="am_misc.html">Up</a> 174 </td> 175 <td width="40%" align="right">��<a accesskey="n" href="am_misc_struct.html">Next</a></td> 176 </tr> 177 <tr> 178 <td width="40%" align="left" valign="top">Retrieving and updating records in bulk��</td> 179 <td width="20%" align="center"> 180 <a accesskey="h" href="index.html">Home</a> 181 </td> 182 <td width="40%" align="right" valign="top">��Storing C/C++ structures/objects</td> 183 </tr> 184 </table> 185 </div> 186 </body> 187</html> 188