1MLDBM(3) User Contributed Perl Documentation MLDBM(3)
2
6 MLDBM - store multi-level Perl 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
18 references. Thus, this module can be used for storing references and
19 other 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
30 version 2.00. However, as of version 2.00, you can use any of
31 Data::Dumper, FreezeThaw or Storable to perform the underlying
32 serialization, as hinted at by the SYNOPSIS overview above. Using
33 Storable 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
39 package), and an underlying serialization package. The respective
40 defaults are SDBM_File and Data::Dumper. Both of these defaults can be
41 changed. Changing the SDBM_File default is strongly recommended. See
42 WARNINGS below.
43 Three serialization wrappers are currently supported: Data::Dumper,
45 Storable, and FreezeThaw. Additional serializers can be supported by
46 writing a wrapper that implements the interface required by
47 MLDBM::Serializer. See the supported wrappers and the
48 MLDBM::Serializer source for details.
49 In the following, $OBJ stands for the tied object, as in:
51 $obj = tie %o, ....
53 $obj = tied %o;
54 $MLDBM::UseDB or $OBJ->UseDB([TIEDOBJECT])
56 The global $MLDBM::UseDB can be set to default to something other
57 than "SDBM_File", in case you have a more efficient DBM, or if you
58 want to use this with some other TIEHASH implementation.
59 Alternatively, you can specify the name of the package at "use"
60 time, as the first "parameter". Nested module names can be
61 specified as "Foo::Bar".
62 The corresponding method call returns the underlying TIEHASH object
64 when called without arguments. It can be called with any object
65 that implements Perl's TIEHASH interface, to set that value.
66 $MLDBM::Serializer or $OBJ->Serializer([SZROBJECT])
68 The global $MLDBM::Serializer can be set to the name of the
69 serializing package to be used. Currently can be set to one of
70 "Data::Dumper", "Storable", or "FreezeThaw". Defaults to
71 "Data::Dumper". Alternatively, you can specify the name of the
72 serializer package at "use" time, as the second "parameter".
73 The corresponding method call returns the underlying MLDBM
75 serializer object when called without arguments. It can be called
76 with an object that implements the MLDBM serializer interface, to
77 set that value.
78 Controlling Serializer Properties
80 These methods are meant to supply an interface to the properties of the
81 underlying serializer used. Do not call or set them without
82 understanding the consequences in full. The defaults are usually
83 sensible.
84 Not all of these necessarily apply to all the supplied serializers, so
86 we specify when to apply them. Failure to respect this will usually
87 lead to an exception.
88 $MLDBM::DumpMeth or $OBJ->DumpMeth([METHNAME])
90 If the serializer provides alternative serialization methods, this
91 can be used to set them.
92 With Data::Dumper (which offers a pure Perl and an XS verion of its
94 serializing routine), this is set to "Dumpxs" by default if that is
95 supported in your installation. Otherwise, defaults to the slower
96 "Dump" method.
97 With Storable, a value of "portable" requests that serialization be
99 architecture neutral, i.e. the deserialization can later occur on
100 another platform. Of course, this only makes sense if your database
101 files are themselves architecture neutral. By default, native
102 format is used for greater serializing speed in Storable. Both
103 Data::Dumper and FreezeThaw are always architecture neutral.
104 FreezeThaw does not honor this attribute.
106 $MLDBM::Key or $OBJ->Key([KEYSTRING])
108 If the serializer only deals with part of the data (perhaps because
109 the TIEHASH object can natively store some types of data), it may
110 need a unique key string to recognize the data it handles. This
111 can be used to set that string. Best left alone.
112 Defaults to the magic string used to recognize MLDBM data. It is a
114 six character wide, unique string. This is best left alone, unless
115 you know what you are doing.
116 Storable and FreezeThaw do not honor this attribute.
118 $MLDBM::RemoveTaint or $OBJ->RemoveTaint([BOOL])
120 If the serializer can optionally untaint any retrieved data subject
121 to taint checks in Perl, this can be used to request that feature.
122 Data that comes from external sources (like disk-files) must always
123 be viewed with caution, so use this only when you are sure that
124 that is not an issue.
125 Data::Dumper uses eval() to deserialize and is therefore subject to
127 taint checks. Can be set to a true value to make the Data::Dumper
128 serializer untaint the data retrieved. It is not enabled by
129 default. Use with care.
130 Storable and FreezeThaw do not honor this attribute.
132
134 Here is a simple example. Note that does not depend upon the
135 underlying serializing package--most real life examples should not,
136 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
184 modifications. In particular, something like this will NOT work
185 properly:
186 $mldb{key}{subkey}[3] = 'stuff'; # won't work
188 Instead, that must be written as:
190 $tmp = $mldb{key}; # retrieve value
192 $tmp->{subkey}[3] = 'stuff';
193 $mldb{key} = $tmp; # store value
194 This limitation exists because the perl TIEHASH interface currently
196 has no support for multidimensional ties.
197 2. The Data::Dumper serializer uses eval(). A lot. Try the Storable
199 serializer, which is generally the most efficient.
200
202 1. Many DBM implementations have arbitrary limits on the size of
203 records that can be stored. For example, SDBM and many ODBM or
204 NDBM implementations have a default limit of 1024 bytes for the
205 size of a record. MLDBM can easily exceed these limits when
206 storing large data structures, leading to mysterious failures.
207 Although SDBM_File is used by MLDBM by default, it is not a good
208 choice if you're storing large data structures. Berkeley DB and
209 GDBM both do not have these limits, so I recommend using either of
210 those instead.
211 2. MLDBM does well with data structures that are not too deep and not
213 too wide. You also need to be careful about how many "FETCH"es
214 your code actually ends up doing. Meaning, you should get the most
215 mileage out of a "FETCH" by holding on to the highest level value
216 for as long as you need it. Remember that every toplevel access of
217 the tied hash, for example $mldb{foo}, translates to a MLDBM
218 FETCH() call.
219 Too often, people end up writing something like this:
221 tie %h, 'MLDBM', ...;
223 for my $k (keys %{$h{something}}) {
224 print $h{something}{$k}[0]{foo}{bar}; # FETCH _every_ time!
225 }
226 when it should be written this for efficiency:
228 tie %h, 'MLDBM', ...;
230 my $root = $h{something}; # FETCH _once_
231 for my $k (keys %$root) {
232 print $k->[0]{foo}{bar};
233 }
234
236 Gurusamy Sarathy <gsar@umich.edu>.
237 Support for multiple serializing packages by Raphael Manfredi
239 <Raphael_Manfredi@grenoble.hp.com>.
240 Test suite fixes for perl 5.8.0 done by Josh Chamas.
242 Copyright (c) 1995-98 Gurusamy Sarathy. All rights reserved.
244 Copyright (c) 1998 Raphael Manfredi.
246 Copyright (c) 2002 Josh Chamas, Chamas Enterprises Inc.
248 Copyright (c) 2010-2013 Alexandr Ciornii (alexchorny@gmail.com).
250 This program is free software; you can redistribute it and/or modify it
252 under the same terms as Perl itself.
253
255 Version 2.05
256
258 perl(1), perltie(1), perlfunc(1), Data::Dumper, FreezeThaw, Storable,
259 DBM::Deep, MLDBM::Serializer::JSON.
260perl v5.38.0 2023-07-20 MLDBM(3)