mirror of
https://github.com/berkeleydb/libdb.git
synced 2024-11-16 09:06:25 +00:00
190 lines
7.8 KiB
HTML
190 lines
7.8 KiB
HTML
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
||
<html xmlns="http://www.w3.org/1999/xhtml">
|
||
<head>
|
||
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
|
||
<title>Partial record storage and retrieval</title>
|
||
<link rel="stylesheet" href="gettingStarted.css" type="text/css" />
|
||
<meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
|
||
<link rel="start" href="index.html" title="Berkeley DB Programmer's Reference Guide" />
|
||
<link rel="up" href="am_misc.html" title="Chapter 4. Access Method Wrapup" />
|
||
<link rel="prev" href="am_misc_bulk.html" title="Retrieving and updating records in bulk" />
|
||
<link rel="next" href="am_misc_struct.html" title="Storing C/C++ structures/objects" />
|
||
</head>
|
||
<body>
|
||
<div xmlns="" class="navheader">
|
||
<div class="libver">
|
||
<p>Library Version 11.2.5.3</p>
|
||
</div>
|
||
<table width="100%" summary="Navigation header">
|
||
<tr>
|
||
<th colspan="3" align="center">Partial record storage and retrieval</th>
|
||
</tr>
|
||
<tr>
|
||
<td width="20%" align="left"><a accesskey="p" href="am_misc_bulk.html">Prev</a> </td>
|
||
<th width="60%" align="center">Chapter 4.
|
||
Access Method Wrapup
|
||
</th>
|
||
<td width="20%" align="right"> <a accesskey="n" href="am_misc_struct.html">Next</a></td>
|
||
</tr>
|
||
</table>
|
||
<hr />
|
||
</div>
|
||
<div class="sect1" lang="en" xml:lang="en">
|
||
<div class="titlepage">
|
||
<div>
|
||
<div>
|
||
<h2 class="title" style="clear: both"><a id="am_misc_partial"></a>Partial record storage and retrieval</h2>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<p>It is possible to both store and retrieve parts of data items in all
|
||
Berkeley DB access methods. This is done by setting the
|
||
<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
|
||
Berkeley DB method.</p>
|
||
<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
|
||
of 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
|
||
of <span class="bold"><strong>dlen</strong></span> is the number of bytes of the record in which the
|
||
application is interested. The value of <span class="bold"><strong>doff</strong></span> is the offset from
|
||
the beginning of the data item where those bytes start.</p>
|
||
<p>For example, if the data item were <span class="bold"><strong>ABCDEFGHIJKL</strong></span>, a <span class="bold"><strong>doff</strong></span>
|
||
value of 3 would indicate that the bytes of interest started at
|
||
<span class="bold"><strong>D</strong></span>, and a <span class="bold"><strong>dlen</strong></span> value of 4 would indicate that the bytes
|
||
of interest were <span class="bold"><strong>DEFG</strong></span>.</p>
|
||
<p>When retrieving a data item from a database, the <span class="bold"><strong>dlen</strong></span> bytes
|
||
starting <span class="bold"><strong>doff</strong></span> bytes from the beginning of the 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 retrieval is still
|
||
successful and any existing bytes are returned.</p>
|
||
<p>When storing a data item into the database, the <span class="bold"><strong>dlen</strong></span> bytes
|
||
starting <span class="bold"><strong>doff</strong></span> bytes from the beginning of the specified key's
|
||
data record are replaced by the data specified by the <span class="bold"><strong>data</strong></span> and
|
||
<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
|
||
record will grow, and if <span class="bold"><strong>dlen</strong></span> is larger than <span class="bold"><strong>size</strong></span>, the
|
||
record will shrink. If the specified bytes do not exist, the record will
|
||
be extended using nul bytes as necessary, and the store call will still
|
||
succeed.</p>
|
||
<p>The following are various examples of the put case for the
|
||
<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
|
||
bytes in length:</p>
|
||
<p>
|
||
<span class="bold">
|
||
<strong>ABCDEFGHIJ0123456789</strong>
|
||
</span>
|
||
</p>
|
||
<div class="orderedlist">
|
||
<ol type="1">
|
||
<li>
|
||
<pre class="programlisting">size = 20
|
||
doff = 0
|
||
dlen = 20
|
||
data = abcdefghijabcdefghij
|
||
|
||
Result: The 20 bytes at offset 0 are replaced by the 20 bytes of
|
||
data; that is, the entire record is replaced.
|
||
|
||
ABCDEFGHIJ0123456789 -> abcdefghijabcdefghij </pre>
|
||
</li>
|
||
<li>
|
||
<pre class="programlisting">size = 10
|
||
doff = 20
|
||
dlen = 0
|
||
data = abcdefghij
|
||
|
||
Result: The 0 bytes at offset 20 are replaced by the 10 bytes of
|
||
data; that is, the record is extended by 10 bytes.
|
||
|
||
ABCDEFGHIJ0123456789 -> ABCDEFGHIJ0123456789abcdefghij </pre>
|
||
</li>
|
||
<li>
|
||
<pre class="programlisting">size = 10
|
||
doff = 10
|
||
dlen = 5
|
||
data = abcdefghij
|
||
|
||
Result: The 5 bytes at offset 10 are replaced by the 10 bytes of
|
||
data.
|
||
|
||
ABCDEFGHIJ0123456789 -> ABCDEFGHIJabcdefghij56789 </pre>
|
||
</li>
|
||
<li>
|
||
<pre class="programlisting">size = 10
|
||
doff = 10
|
||
dlen = 0
|
||
data = abcdefghij
|
||
|
||
Result: The 0 bytes at offset 10 are replaced by the 10 bytes of
|
||
data; that is, 10 bytes are inserted into the record.
|
||
|
||
ABCDEFGHIJ0123456789 -> ABCDEFGHIJabcdefghij0123456789 </pre>
|
||
</li>
|
||
<li>
|
||
<pre class="programlisting">size = 10
|
||
doff = 2
|
||
dlen = 15
|
||
data = abcdefghij
|
||
|
||
Result: The 15 bytes at offset 2 are replaced by the 10 bytes of
|
||
data.
|
||
|
||
ABCDEFGHIJ0123456789 -> ABabcdefghij789 </pre>
|
||
</li>
|
||
<li>
|
||
<pre class="programlisting">size = 10
|
||
doff = 0
|
||
dlen = 0
|
||
data = abcdefghij
|
||
|
||
Result: The 0 bytes at offset 0 are replaced by the 10 bytes of
|
||
data; that is, the 10 bytes are inserted at the beginning of the
|
||
record.
|
||
|
||
ABCDEFGHIJ0123456789 -> abcdefghijABCDEFGHIJ0123456789 </pre>
|
||
</li>
|
||
<li>
|
||
<pre class="programlisting">size = 0
|
||
doff = 0
|
||
dlen = 10
|
||
data = ""
|
||
|
||
Result: The 10 bytes at offset 0 are replaced by the 0 bytes of
|
||
data; that is, the first 10 bytes of the record are discarded.
|
||
|
||
ABCDEFGHIJ0123456789 -> 0123456789 </pre>
|
||
</li>
|
||
<li>
|
||
<pre class="programlisting">size = 10
|
||
doff = 25
|
||
dlen = 0
|
||
data = abcdefghij
|
||
|
||
Result: The 0 bytes at offset 25 are replaced by the 10 bytes of
|
||
data; that is, 10 bytes are inserted into the record past the end
|
||
of the current data (\0 represents a nul byte).
|
||
|
||
ABCDEFGHIJ0123456789 -> ABCDEFGHIJ0123456789\0\0\0\0\0abcdefghij </pre>
|
||
</li>
|
||
</ol>
|
||
</div>
|
||
</div>
|
||
<div class="navfooter">
|
||
<hr />
|
||
<table width="100%" summary="Navigation footer">
|
||
<tr>
|
||
<td width="40%" align="left"><a accesskey="p" href="am_misc_bulk.html">Prev</a> </td>
|
||
<td width="20%" align="center">
|
||
<a accesskey="u" href="am_misc.html">Up</a>
|
||
</td>
|
||
<td width="40%" align="right"> <a accesskey="n" href="am_misc_struct.html">Next</a></td>
|
||
</tr>
|
||
<tr>
|
||
<td width="40%" align="left" valign="top">Retrieving and updating records in bulk </td>
|
||
<td width="20%" align="center">
|
||
<a accesskey="h" href="index.html">Home</a>
|
||
</td>
|
||
<td width="40%" align="right" valign="top"> Storing C/C++ structures/objects</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
</body>
|
||
</html>
|