NAME¶

MLDBM - store multi-level Perl hash structure in single level tied hash

SYNOPSIS¶

    use MLDBM;                          # this gets the default, SDBM
    #use MLDBM qw(DB_File FreezeThaw);  # use FreezeThaw for serializing
    #use MLDBM qw(DB_File Storable);    # use Storable for serializing
    $dbm = tie %o, 'MLDBM' [..other DBM args..] or die $!;

DESCRIPTION¶

This module can serve as a transparent interface to any TIEHASH package that is required to store arbitrary perl data, including nested references. Thus, this module can be used for storing references and other arbitrary data within DBM databases.

It works by serializing the references in the hash into a single string. In the underlying TIEHASH package (usually a DBM database), it is this string that gets stored. When the value is fetched again, the string is deserialized to reconstruct the data structure into memory.

For historical and practical reasons, it requires the Data::Dumper package, available at any CPAN site. Data::Dumper gives you really nice-looking dumps of your data structures, in case you wish to look at them on the screen, and it was the only serializing engine before version 2.00. However, as of version 2.00, you can use any of Data::Dumper, FreezeThaw or Storable to perform the underlying serialization, as hinted at by the SYNOPSIS overview above. Using Storable is usually much faster than the other methods.

See the BUGS section for important limitations.

        $obj = tie %o, ....
        $obj = tied %o;

EXAMPLES¶

Here is a simple example. Note that does not depend upon the underlying serializing package--most real life examples should not, usually.

    use MLDBM;                          # this gets SDBM and Data::Dumper
    #use MLDBM qw(SDBM_File Storable);  # SDBM and Storable
    use Fcntl;                          # to get 'em constants
    $dbm = tie %o, 'MLDBM', 'testmldbm', O_CREAT|O_RDWR, 0640 or die $!;
    $c = [\ 'c'];
    $b = {};
    $a = [1, $b, $c];
    $b->{a} = $a;
    $b->{b} = $a->[1];
    $b->{c} = $a->[2];
    @o{qw(a b c)} = ($a, $b, $c);
    #
    # to see what was stored
    #
    use Data::Dumper;
    print Data::Dumper->Dump([@o{qw(a b c)}], [qw(a b c)]);
    #
    # to modify data in a substructure
    #
    $tmp = $o{a};
    $tmp->[0] = 'foo';
    $o{a} = $tmp;
    #
    # can access the underlying DBM methods transparently
    #
    #print $dbm->fd, "\n";              # DB_File method

Here is another small example using Storable, in a portable format:

    use MLDBM qw(DB_File Storable);     # DB_File and Storable
    tie %o, 'MLDBM', 'testmldbm', O_CREAT|O_RDWR, 0640 or die $!;
    (tied %o)->DumpMeth('portable');    # Ask for portable binary
    $o{'ENV'} = \%ENV;                  # Stores the whole environment

BUGS¶

1.

Adding or altering substructures to a hash value is not entirely transparent in current perl. If you want to store a reference or modify an existing reference value in the DBM, it must first be retrieved and stored in a temporary variable for further modifications. In particular, something like this will NOT work properly:

        $mldb{key}{subkey}[3] = 'stuff';        # won't work
    

Instead, that must be written as:

        $tmp = $mldb{key};                      # retrieve value
        $tmp->{subkey}[3] = 'stuff';
        $mldb{key} = $tmp;                      # store value
    

This limitation exists because the perl TIEHASH interface currently has no support for multidimensional ties.

2.

The Data::Dumper serializer uses eval(). A lot. Try the Storable serializer, which is generally the most efficient.

WARNINGS¶

1.

Many DBM implementations have arbitrary limits on the size of records that can be stored. For example, SDBM and many ODBM or NDBM implementations have a default limit of 1024 bytes for the size of a record. MLDBM can easily exceed these limits when storing large data structures, leading to mysterious failures. Although SDBM_File is used by MLDBM by default, it is not a good choice if you're storing large data structures. Berkeley DB and GDBM both do not have these limits, so I recommend using either of those instead.

2.

MLDBM does well with data structures that are not too deep and not too wide. You also need to be careful about how many "FETCH"es your code actually ends up doing. Meaning, you should get the most mileage out of a "FETCH" by holding on to the highest level value for as long as you need it. Remember that every toplevel access of the tied hash, for example $mldb{foo}, translates to a MLDBM "FETCH()" call.

Too often, people end up writing something like this:

        tie %h, 'MLDBM', ...;
        for my $k (keys %{$h{something}}) {
            print $h{something}{$k}[0]{foo}{bar};  # FETCH _every_ time!
        }
    

when it should be written this for efficiency:

        tie %h, 'MLDBM', ...;
        my $root = $h{something};                  # FETCH _once_
        for my $k (keys %$root) {
            print $k->[0]{foo}{bar};
        }
    

AUTHORS¶

Gurusamy Sarathy <gsar@umich.edu>.

Support for multiple serializing packages by Raphael Manfredi <Raphael_Manfredi@grenoble.hp.com>.

Test suite fixes for perl 5.8.0 done by Josh Chamas.

Copyright (c) 1995-98 Gurusamy Sarathy. All rights reserved.

Copyright (c) 1998 Raphael Manfredi.

Copyright (c) 2002 Josh Chamas, Chamas Enterprises Inc.

Copyright (c) 2010-2013 Alexandr Ciornii (alexchorny@gmail.com).

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

VERSION¶

Version 2.05

SEE ALSO¶

perl(1), perltie(1), perlfunc(1), Data::Dumper, FreezeThaw, Storable, DBM::Deep, MLDBM::Serializer::JSON.