1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
|
<?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 class="navheader">
<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>
|
