1<!--$Id: partial.so,v 10.25 2003/10/18 19:15:56 bostic Exp $--> 2<!--Copyright (c) 1997,2008 Oracle. All rights reserved.--> 3<!--See the file LICENSE for redistribution information.--> 4<html> 5<head> 6<title>Berkeley DB Reference Guide: Partial record storage and retrieval</title> 7<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit."> 8<meta name="keywords" content="embedded,database,programmatic,toolkit,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,Java,C,C++"> 9</head> 10<body bgcolor=white> 11<a name="2"><!--meow--></a> 12<table width="100%"><tr valign=top> 13<td><b><dl><dt>Berkeley DB Reference Guide:<dd>Access Methods</dl></b></td> 14<td align=right><a href="../am_misc/get_bulk.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../am_misc/struct.html"><img src="../../images/next.gif" alt="Next"></a> 15</td></tr></table> 16<p align=center><b>Partial record storage and retrieval</b></p> 17<p>It is possible to both store and retrieve parts of data items in all 18Berkeley DB access methods. This is done by setting the 19<a href="../../api_c/dbt_class.html#DB_DBT_PARTIAL">DB_DBT_PARTIAL</a> flag in the <a href="../../api_c/dbt_class.html">DBT</a> structure passed to the 20Berkeley DB method.</p> 21<p>The <a href="../../api_c/dbt_class.html#DB_DBT_PARTIAL">DB_DBT_PARTIAL</a> flag is based on the values of two fields 22of the <a href="../../api_c/dbt_class.html">DBT</a> structure: <b>dlen</b> and <b>doff</b>. The value 23of <b>dlen</b> is the number of bytes of the record in which the 24application is interested. The value of <b>doff</b> is the offset from 25the beginning of the data item where those bytes start.</p> 26<p>For example, if the data item were <b>ABCDEFGHIJKL</b>, a <b>doff</b> 27value of 3 would indicate that the bytes of interest started at 28<b>D</b>, and a <b>dlen</b> value of 4 would indicate that the bytes 29of interest were <b>DEFG</b>.</p> 30<p>When retrieving a data item from a database, the <b>dlen</b> bytes 31starting <b>doff</b> bytes from the beginning of the record are 32returned, as if they comprised the entire record. If any or all of the 33specified bytes do not exist in the record, the retrieval is still 34successful and any existing bytes are returned.</p> 35<p>When storing a data item into the database, the <b>dlen</b> bytes 36starting <b>doff</b> bytes from the beginning of the specified key's 37data record are replaced by the data specified by the <b>data</b> and 38<b>size</b> fields. If <b>dlen</b> is smaller than <b>size</b>, the 39record will grow, and if <b>dlen</b> is larger than <b>size</b>, the 40record will shrink. If the specified bytes do not exist, the record will 41be extended using nul bytes as necessary, and the store call will still 42succeed.</p> 43<p>The following are various examples of the put case for the 44<a href="../../api_c/dbt_class.html#DB_DBT_PARTIAL">DB_DBT_PARTIAL</a> flag. In all examples, the initial data item is 20 45bytes in length:</p> 46<p><b>ABCDEFGHIJ0123456789</b></p> 47<ol> 48<p><li><blockquote><pre>size = 20 49doff = 0 50dlen = 20 51data = abcdefghijabcdefghij 52<p> 53Result: The 20 bytes at offset 0 are replaced by the 20 bytes of data; 54that is, the entire record is replaced. 55<p> 56ABCDEFGHIJ0123456789 -> abcdefghijabcdefghij 57</pre></blockquote> 58<p><li><blockquote><pre>size = 10 59doff = 20 60dlen = 0 61data = abcdefghij 62<p> 63Result: The 0 bytes at offset 20 are replaced by the 10 bytes of data; 64that is, the record is extended by 10 bytes. 65<p> 66ABCDEFGHIJ0123456789 -> ABCDEFGHIJ0123456789abcdefghij 67</pre></blockquote> 68<p><li><blockquote><pre>size = 10 69doff = 10 70dlen = 5 71data = abcdefghij 72<p> 73Result: The 5 bytes at offset 10 are replaced by the 10 bytes of data. 74<p> 75ABCDEFGHIJ0123456789 -> ABCDEFGHIJabcdefghij56789 76</pre></blockquote> 77<p><li><blockquote><pre>size = 10 78doff = 10 79dlen = 0 80data = abcdefghij 81<p> 82Result: The 0 bytes at offset 10 are replaced by the 10 bytes of data; 83that is, 10 bytes are inserted into the record. 84<p> 85ABCDEFGHIJ0123456789 -> ABCDEFGHIJabcdefghij0123456789 86</pre></blockquote> 87<p><li><blockquote><pre>size = 10 88doff = 2 89dlen = 15 90data = abcdefghij 91<p> 92Result: The 15 bytes at offset 2 are replaced by the 10 bytes of data. 93<p> 94ABCDEFGHIJ0123456789 -> ABabcdefghij789 95</pre></blockquote> 96<p><li><blockquote><pre>size = 10 97doff = 0 98dlen = 0 99data = abcdefghij 100<p> 101Result: The 0 bytes at offset 0 are replaced by the 10 bytes of data; 102that is, the 10 bytes are inserted at the beginning of the record. 103<p> 104ABCDEFGHIJ0123456789 -> abcdefghijABCDEFGHIJ0123456789 105</pre></blockquote> 106<p><li><blockquote><pre>size = 0 107doff = 0 108dlen = 10 109data = "" 110<p> 111Result: The 10 bytes at offset 0 are replaced by the 0 bytes of data; 112that is, the first 10 bytes of the record are discarded. 113<p> 114ABCDEFGHIJ0123456789 -> 0123456789 115</pre></blockquote> 116<p><li><blockquote><pre>size = 10 117doff = 25 118dlen = 0 119data = abcdefghij 120<p> 121Result: The 0 bytes at offset 25 are replaced by the 10 bytes of data; 122that is, 10 bytes are inserted into the record past the end of the 123current data (\0 represents a nul byte). 124<p> 125ABCDEFGHIJ0123456789 -> ABCDEFGHIJ0123456789\0\0\0\0\0abcdefghij 126</pre></blockquote> 127</ol> 128<table width="100%"><tr><td><br></td><td align=right><a href="../am_misc/get_bulk.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../am_misc/struct.html"><img src="../../images/next.gif" alt="Next"></a> 129</td></tr></table> 130<p><font size=1>Copyright (c) 1996,2008 Oracle. All rights reserved.</font> 131</body> 132</html> 133
