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
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
|
<?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>Using C Structures with DB</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="Getting Started with Berkeley DB" />
<link rel="up" href="DBEntry.html" title="Chapter 3. Database Records" />
<link rel="prev" href="usingDbt.html" title="Reading and Writing Database Records" />
<link rel="next" href="DbUsage.html" title="Database Usage Example" />
</head>
<body>
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr>
<th colspan="3" align="center">Using C Structures with DB</th>
</tr>
<tr>
<td width="20%" align="left"><a accesskey="p" href="usingDbt.html">Prev</a> </td>
<th width="60%" align="center">Chapter 3. Database Records</th>
<td width="20%" align="right"> <a accesskey="n" href="DbUsage.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="cstructs"></a>Using C Structures with DB</h2>
</div>
</div>
</div>
<div class="toc">
<dl>
<dt>
<span class="sect2">
<a href="cstructs.html#cstructdynamic">C Structures with Pointers</a>
</span>
</dt>
</dl>
</div>
<p>
Storing data in structures is a handy way to pack varied types of
information into each database record. DB databases are sometimes
thought of as a two column table where column 1 is the key and column 2 is
the data. By using structures, you can effectively turn this table into
<span class="emphasis"><em>n</em></span> columns where <span class="emphasis"><em>n-1</em></span> columns
are contained in the structure.
</p>
<p>
So long as a C structure contains fields that are not pointers, you can safely
store and retrieve them in the same way as you would any primitive
datatype. The following code fragment illustrates this:
</p>
<a id="c_dbt6"></a>
<pre class="programlisting">#include <db.h>
#include <string.h>
typedef struct my_struct {
int id;
char familiar_name[MAXLINE]; /* Some suitably large value */
char surname[MAXLINE];
} MY_STRUCT;
...
DBT key, data;
DB *my_database;
MY_STRUCT user;
char *fname = "David";
char *sname = "Rider";
/* Database open omitted for clarity */
user.id = 1;
strncpy(user.familiar_name, fname, strlen(fname)+1);
strncpy(user.surname, sname, strlen(sname)+1);
/* Zero out the DBTs before using them. */
memset(&key, 0, sizeof(DBT));
memset(&data, 0, sizeof(DBT));
key.data = &(user.id);
key.size = sizeof(int);
data.data = &user;
data.size = sizeof(MY_STRUCT);
my_database->put(my_database, NULL, &key, &data, DB_NOOVERWRITE);</pre>
<p>
To retrieve the structure, make sure you supply your own
memory. The reason why is that like real numbers, some systems require
structures to be aligned in a specific way. Because it is possible that
the memory DB provides is not aligned properly, for safest result simply
use your own memory:
</p>
<a id="c_dbt7"></a>
<pre class="programlisting">#include <db.h>
#include <string.h>
...
DBT key, data;
DB *my_database;
MY_STRUCT user;
/* Database open omitted for clarity */
/* Zero out the DBTs before using them. */
memset(&key, 0, sizeof(DBT));
memset(&data, 0, sizeof(DBT));
/* Initialize the structure */
memset(&user, 0, sizeof(MY_STRUCT));
user.id = 1;
key.data = &user.id;
key.size = sizeof(int);
/* Use our memory to retrieve the structure */
data.data = &user;
data.ulen = sizeof(MY_STRUCT);
data.flags = DB_DBT_USERMEM;
my_database->get(my_database, NULL, &key, &data, 0);
printf("Familiar name: %s\n", user.familiar_name);
printf("Surname: %s\n", user.surname); </pre>
<p>
Be aware that while this is the easiest way to manage structures stored
in DB databases, this approach does suffer from causing your
database to be larger than is strictly necessary. Each structure stored
in the database is of a fixed size, and you do not see any space savings
from storing a (for example) 5 character surname versus a 20 character
surname.
</p>
<p>
For a simple example such as this, the padding stored with each record
is probably not critical. However, if you are storing structures that
contain a very large number of character arrays, or if you are simply
storing millions of records, then you may want to avoid this approach.
The wasted space in each record will only serve to make your databases
larger than need be, which will in turn require a larger cache and more
disk I/O than you would ordinarily need.
</p>
<p>
An alternative approach is described next.
</p>
<div class="sect2" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="cstructdynamic"></a>C Structures with Pointers</h3>
</div>
</div>
</div>
<p>
It is often necessary in C structures
to use fields
that are pointers to
dynamically allocated memory. This is particularly
true if you want to store character strings (or any kind of an array for
that matter), and you want to avoid any overhead caused by
pre-designating the size of the array.
</p>
<p>
When storing structures
like these you need to make sure that all of
the data pointed to and contained by the structure
is lined up in a
single contiguous block of memory. Remember that DB stores data
located at a specific address and of a particular size. If your structure
includes fields
that are pointing to dynamically allocated memory, then
the data that you want to store can be located in different, not
necessarily contiguous, locations on the heap.
</p>
<p>
The easiest way to solve this problem is to pack your data
into a single memory location and then store the data in that location.
(This process is sometimes called <span class="emphasis"><em>marshalling the
data</em></span>.)
For example:
</p>
<a id="c_dbt8"></a>
<pre class="programlisting">#include <db.h>
#include <string.h>
#include <stdlib.h>
typedef struct my_struct {
int id;
char *familiar_name;
char *surname;
} MY_STRUCT;
...
DBT key, data;
DB *my_database;
MY_STRUCT user;
int buffsize, bufflen;
char fname[ ] = "Pete";
char sname[10];
char *databuff;
strncpy(sname, "Oar", strlen("Oar")+1);
/* Database open omitted for clarity */
user.id = 1;
user.familiar_name = fname;
user.surname = sname;
/* Some of the structure's data is on the stack, and
* some is on the heap. To store this structure's data, we
* need to marshall it -- pack it all into a single location
* in memory.
*/
/* Get the buffer */
buffsize = sizeof(int) +
(strlen(user.familiar_name) + strlen(user.surname) + 2);
databuff = malloc(buffsize);
memset(databuff, 0, buffsize);
/* copy everything to the buffer */
memcpy(databuff, &(user.id), sizeof(int));
bufflen = sizeof(int);
memcpy(databuff + bufflen, user.familiar_name,
strlen(user.familiar_name) + 1);
bufflen += strlen(user.familiar_name) + 1;
memcpy(databuff + bufflen, user.surname,
strlen(user.surname) + 1);
bufflen += strlen(user.surname) + 1;
/* Now store it */
/* Zero out the DBTs before using them. */
memset(&key, 0, sizeof(DBT));
memset(&data, 0, sizeof(DBT));
key.data = &(user.id);
key.size = sizeof(int);
data.data = databuff;
data.size = bufflen;
my_database->put(my_database, NULL, &key, &data, DB_NOOVERWRITE);
free(sname);
free(databuff);</pre>
<p>
To retrieve the stored structure:
</p>
<a id="c_dbt9"></a>
<pre class="programlisting">#include <db.h>
#include <string.h>
#include <stdlib.h>
typedef struct my_struct {
char *familiar_name;
char *surname;
int id;
} MY_STRUCT;
...
int id;
DBT key, data;
DB *my_database;
MY_STRUCT user;
char *buffer;
/* Database open omitted for clarity */
/* Zero out the DBTs before using them. */
memset(&key, 0, sizeof(DBT));
memset(&data, 0, sizeof(DBT));
id = 1;
key.data = &id;
key.size = sizeof(int);
my_database->get(my_database, NULL, &key, &data, 0);
/*
* Some compilers won't allow pointer arithmetic on void *'s,
* so use a char * instead.
*/
buffer = data.data;
user.id = *((int *)data.data);
user.familiar_name = buffer + sizeof(int);
user.surname = buffer + sizeof(int) + strlen(user.familiar_name) + 1; </pre>
</div>
</div>
<div class="navfooter">
<hr />
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left"><a accesskey="p" href="usingDbt.html">Prev</a> </td>
<td width="20%" align="center">
<a accesskey="u" href="DBEntry.html">Up</a>
</td>
<td width="40%" align="right"> <a accesskey="n" href="DbUsage.html">Next</a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top">Reading and Writing Database Records </td>
<td width="20%" align="center">
<a accesskey="h" href="index.html">Home</a>
</td>
<td width="40%" align="right" valign="top"> Database Usage Example</td>
</tr>
</table>
</div>
</body>
</html>
|
