← Back to branch summary

~ubuntu-branches/ubuntu/maverick/evolution-data-server/maverick-proposed

« back to all changes in this revision

Viewing changes to libdb/docs/ref/am_misc/partial.html

  • Committer: Bazaar Package Importer
  • Author(s): Didier Roche
  • Date: 2010-05-17 17:02:06 UTC
  • mfrom: (1.1.79 upstream) (1.6.12 experimental)
  • Revision ID: james.westby@ubuntu.com-20100517170206-4ufr52vwrhh26yh0
Tags: 2.30.1-1ubuntu1
https://launchpad.net/bugs/42199
https://launchpad.net/bugs/229669
https://launchpad.net/bugs/173703
https://launchpad.net/bugs/360344
https://launchpad.net/bugs/508494
* Merge from debian experimental. Remaining change:
  (LP: #42199, #229669, #173703, #360344, #508494)
  + debian/control:
    - add Vcs-Bzr tag
    - don't use libgnome
    - Use Breaks instead of Conflicts against evolution 2.25 and earlier.
  + debian/evolution-data-server.install,
    debian/patches/45_libcamel_providers_version.patch:
    - use the upstream versioning, not a Debian-specific one 
  + debian/libedata-book1.2-dev.install, debian/libebackend-1.2-dev.install,
    debian/libcamel1.2-dev.install, debian/libedataserverui1.2-dev.install:
    - install html documentation
  + debian/rules:
    - don't build documentation it's shipped with the tarball

Show diffs side-by-side

added added

removed removed

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