mirror of
https://github.com/yasuhirokimura/db18
synced 2026-06-08 18:29:23 +00:00
Yasuhiro KIMURA
204 lines
8.1 KiB
HTML
204 lines
8.1 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 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>
|