Sindbad~EG File Manager
<?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 18.1.40</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: <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>
Sindbad File Manager Version 1.0, Coded By Sindbad EG ~ The Terrorists