1MLDBM(3) User Contributed Perl Documentation MLDBM(3)
2
6 MLDBM - store multi-level hash structure in single level tied hash
7
9 use MLDBM; # this gets the default, SDBM
10 #use MLDBM qw(DB_File FreezeThaw); # use FreezeThaw for serializing
11 #use MLDBM qw(DB_File Storable); # use Storable for serializing
12 $dbm = tie %o, 'MLDBM' [..other DBM args..] or die $!;
14
16 This module can serve as a transparent interface to any TIEHASH package
17 that is required to store arbitrary perl data, including nested refer‐
18 ences. Thus, this module can be used for storing references and other
19 arbitrary data within DBM databases.
20 It works by serializing the references in the hash into a single
22 string. In the underlying TIEHASH package (usually a DBM database), it
23 is this string that gets stored. When the value is fetched again, the
24 string is deserialized to reconstruct the data structure into memory.
25 For historical and practical reasons, it requires the Data::Dumper
27 package, available at any CPAN site. Data::Dumper gives you really
28 nice-looking dumps of your data structures, in case you wish to look at
29 them on the screen, and it was the only serializing engine before ver‐
30 sion 2.00. However, as of version 2.00, you can use any of
31 Data::Dumper, FreezeThaw or Storable to perform the underlying serial‐
32 ization, as hinted at by the SYNOPSIS overview above. Using Storable
33 is usually much faster than the other methods.
34 See the BUGS section for important limitations.
36 Changing the Defaults
38 MLDBM relies on an underlying TIEHASH implementation (usually a DBM
40 package), and an underlying serialization package. The respective
41 defaults are SDBM_File and Data::Dumper. Both of these defaults can be
42 changed. Changing the SDBM_File default is strongly recommended. See
43 WARNINGS below.
44 Three serialization wrappers are currently supported: Data::Dumper,
46 Storable, and FreezeThaw. Additional serializers can be supported by
47 writing a wrapper that implements the interface required by
48 MLDBM::Serializer. See the supported wrappers and the MLDBM::Serial‐
49 izer source for details.
50 In the following, $OBJ stands for the tied object, as in:
52 $obj = tie %o, ....
54 $obj = tied %o;
55 $MLDBM::UseDB or $OBJ->UseDB([TIEDOBJECT])
57 The global $MLDBM::UseDB can be set to default to something other
58 than "SDBM_File", in case you have a more efficient DBM, or if you
59 want to use this with some other TIEHASH implementation. Alterna‐
60 tively, you can specify the name of the package at "use" time, as
61 the first "parameter". Nested module names can be specified as
62 "Foo::Bar".
63 The corresponding method call returns the underlying TIEHASH object
65 when called without arguments. It can be called with any object
66 that implements Perl's TIEHASH interface, to set that value.
67 $MLDBM::Serializer or $OBJ->Serializer([SZROBJECT])
69 The global $MLDBM::Serializer can be set to the name of the serial‐
70 izing package to be used. Currently can be set to one of
71 "Data::Dumper", "Storable", or "FreezeThaw". Defaults to
72 "Data::Dumper". Alternatively, you can specify the name of the
73 serializer package at "use" time, as the second "parameter".
74 The corresponding method call returns the underlying MLDBM serial‐
76 izer object when called without arguments. It can be called with
77 an object that implements the MLDBM serializer interface, to set
78 that value.
79 Controlling Serializer Properties
81 These methods are meant to supply an interface to the properties of the
83 underlying serializer used. Do not call or set them without under‐
84 standing the consequences in full. The defaults are usually sensible.
85 Not all of these necessarily apply to all the supplied serializers, so
87 we specify when to apply them. Failure to respect this will usually
88 lead to an exception.
89 $MLDBM::DumpMeth or $OBJ->DumpMeth([METHNAME])
91 If the serializer provides alternative serialization methods, this
92 can be used to set them.
93 With Data::Dumper (which offers a pure Perl and an XS verion of its
95 serializing routine), this is set to "Dumpxs" by default if that is
96 supported in your installation. Otherwise, defaults to the slower
97 "Dump" method.
98 With Storable, a value of "portable" requests that serialization be
100 architecture neutral, i.e. the deserialization can later occur on
101 another platform. Of course, this only makes sense if your database
102 files are themselves architecture neutral. By default, native for‐
103 mat is used for greater serializing speed in Storable. Both
104 Data::Dumper and FreezeThaw are always architecture neutral.
105 FreezeThaw does not honor this attribute.
107 $MLDBM::Key or $OBJ->Key([KEYSTRING])
109 If the serializer only deals with part of the data (perhaps because
110 the TIEHASH object can natively store some types of data), it may
111 need a unique key string to recognize the data it handles. This
112 can be used to set that string. Best left alone.
113 Defaults to the magic string used to recognize MLDBM data. It is a
115 six character wide, unique string. This is best left alone, unless
116 you know what you are doing.
117 Storable and FreezeThaw do not honor this attribute.
119 $MLDBM::RemoveTaint or $OBJ->RemoveTaint([BOOL])
121 If the serializer can optionally untaint any retrieved data subject
122 to taint checks in Perl, this can be used to request that feature.
123 Data that comes from external sources (like disk-files) must always
124 be viewed with caution, so use this only when you are sure that
125 that is not an issue.
126 Data::Dumper uses "eval()" to deserialize and is therefore subject
128 to taint checks. Can be set to a true value to make the
129 Data::Dumper serializer untaint the data retrieved. It is not
130 enabled by default. Use with care.
131 Storable and FreezeThaw do not honor this attribute.
133
135 Here is a simple example. Note that does not depend upon the underly‐
136 ing serializing package--most real life examples should not, usually.
137 use MLDBM; # this gets SDBM and Data::Dumper
139 #use MLDBM qw(SDBM_File Storable); # SDBM and Storable
140 use Fcntl; # to get 'em constants
141 $dbm = tie %o, 'MLDBM', 'testmldbm', O_CREAT⎪O_RDWR, 0640 or die $!;
143 $c = [\ 'c'];
145 $b = {};
146 $a = [1, $b, $c];
147 $b->{a} = $a;
148 $b->{b} = $a->[1];
149 $b->{c} = $a->[2];
150 @o{qw(a b c)} = ($a, $b, $c);
151 #
153 # to see what was stored
154 #
155 use Data::Dumper;
156 print Data::Dumper->Dump([@o{qw(a b c)}], [qw(a b c)]);
157 #
159 # to modify data in a substructure
160 #
161 $tmp = $o{a};
162 $tmp->[0] = 'foo';
163 $o{a} = $tmp;
164 #
166 # can access the underlying DBM methods transparently
167 #
168 #print $dbm->fd, "\n"; # DB_File method
169 Here is another small example using Storable, in a portable format:
171 use MLDBM qw(DB_File Storable); # DB_File and Storable
173 tie %o, 'MLDBM', 'testmldbm', O_CREAT⎪O_RDWR, 0640 or die $!;
175 (tied %o)->DumpMeth('portable'); # Ask for portable binary
177 $o{'ENV'} = \%ENV; # Stores the whole environment
178
180 1. Adding or altering substructures to a hash value is not entirely
181 transparent in current perl. If you want to store a reference or
182 modify an existing reference value in the DBM, it must first be
183 retrieved and stored in a temporary variable for further modifica‐
184 tions. In particular, something like this will NOT work properly:
185 $mldb{key}{subkey}[3] = 'stuff'; # won't work
187 Instead, that must be written as:
189 $tmp = $mldb{key}; # retrieve value
191 $tmp->{subkey}[3] = 'stuff';
192 $mldb{key} = $tmp; # store value
193 This limitation exists because the perl TIEHASH interface currently
195 has no support for multidimensional ties.
196 2. The Data::Dumper serializer uses eval(). A lot. Try the Storable
198 serializer, which is generally the most efficient.
199
201 1. Many DBM implementations have arbitrary limits on the size of
202 records that can be stored. For example, SDBM and many ODBM or
203 NDBM implementations have a default limit of 1024 bytes for the
204 size of a record. MLDBM can easily exceed these limits when stor‐
205 ing large data structures, leading to mysterious failures.
206 Although SDBM_File is used by MLDBM by default, it is not a good
207 choice if you're storing large data structures. Berkeley DB and
208 GDBM both do not have these limits, so I recommend using either of
209 those instead.
210 2. MLDBM does well with data structures that are not too deep and not
212 too wide. You also need to be careful about how many "FETCH"es
213 your code actually ends up doing. Meaning, you should get the most
214 mileage out of a "FETCH" by holding on to the highest level value
215 for as long as you need it. Remember that every toplevel access of
216 the tied hash, for example $mldb{foo}, translates to a MLDBM
217 "FETCH()" call.
218 Too often, people end up writing something like this:
220 tie %h, 'MLDBM', ...;
222 for my $k (keys %{$h{something}}) {
223 print $h{something}{$k}[0]{foo}{bar}; # FETCH _every_ time!
224 }
225 when it should be written this for efficiency:
227 tie %h, 'MLDBM', ...;
229 my $root = $h{something}; # FETCH _once_
230 for my $k (keys %$root) {
231 print $k->[0]{foo}{bar};
232 }
233
235 Gurusamy Sarathy <gsar@umich.edu>.
236 Support for multiple serializing packages by Raphael Manfredi
238 <Raphael_Manfredi@grenoble.hp.com>.
239 Test suite fixes for perl 5.8.0 done by Josh Chamas.
241 Copyright (c) 1995-98 Gurusamy Sarathy. All rights reserved.
243 Copyright (c) 1998 Raphael Manfredi.
245 Copyright (c) 2002 Josh Chamas, Chamas Enterprises Inc.
247 This program is free software; you can redistribute it and/or modify it
249 under the same terms as Perl itself.
250
252 Version 2.01 07 July 2002
253
255 perl(1), perltie(1), perlfunc(1), Data::Dumper(3), FreezeThaw(3),
256 Storable(3).
257perl v5.8.8 2002-07-08 MLDBM(3)