NAME

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

SYNOPSIS

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

DESCRIPTION

This module, intended primarily for use with DBM packages, can serve as a transparent interface to any TIEHASH package that must be used to store arbitrary perl data, including nested references.

It works by converting the values in the hash that are references, to their string representation in perl syntax. When using a DBM database, it is this string that gets stored.

It requires the Data::Dumper package, available at any CPAN site.

See the BUGS section for important limitations.

Configuration Variables

$MLDBM::UseDB

You may want to set $MLDBM::UseDB to default to something other than "SDBM_File", in case you have a more efficient DBM, or if you want to use this with some other TIEHASH implementation. Alternatively, you can specify the name of the package at use time. Nested module names can be specified as "Foo::Bar".

$MLDBM::Key

Defaults to the magic string used to recognize MLDBM data. It is a six character wide, unique string. This is best left alone, unless you know what you're doing.

EXAMPLE

use MLDBM;                            # this gets SDBM
#use MLDBM qw(DB_File);
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 wuz 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

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. This not as efficient as one would like.

3. The previous version was released along with the Data::Dumper package as an example. If you got serious with that and have a DBM file from that version, you can do something like this to convert the old records to the new format:

       use MLDBM (DB_File);              # be sure it's the new MLDBM
       use Fcntl;
       tie %o, MLDBM, 'oldmldbm.file', O_RDWR, 0640 or die $!;
       for $k (keys %o) {
         my $v = $o{$k};
         if ($v =~ /^\$CrYpTiCkEy/o) {
   	$v = eval $v;
   	if ($@) { warn "Error: $@\twhile evaluating $v\n"; }
   	else    { $o{$k} = $v; }
         }
       }
       

AUTHOR

Gurusamy Sarathy gsar@umich.edu

Copyright (c) 1995 Gurusamy Sarathy. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

VERSION

Version 1.10 19 January 1996

SEE ALSO

perl(1)