@node MLDBM, Mail/Address, MIME/ToolUtils, Module List
@unnumbered store multi-level hash structure in single level tied hash


@unnumberedsec NAME

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

@unnumberedsec SYNOPSIS

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

@unnumberedsec 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.

@unnumberedsubsec Configuration Variables/Methods

@table @asis
@item $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".

@item $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.

@item $MLDBM::DumpMeth  @emph{or}  $@emph{OBJ}->DumpMeth(@emph{[METHNAME]})
This controls which of the two dumping methods available from @code{Data::Dumper}
are used.  By default, this is set to "Dumpxs", the faster of the two 
methods, but only if MLDBM detects that "Dumpxs" is supported on your 
platform.  Otherwise, defaults to the slower "Dump" method.

@end table
@unnumberedsec EXAMPLE

@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)]);
@end example

@example
#
# 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
@end example

@unnumberedsec BUGS

@enumerate
@item 
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:

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

Instead, that must be written as:

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

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

@item 
MLDBM was first 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:

@example
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; @}
  @}
@}

@end example

@end enumerate
@unnumberedsec 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.

@unnumberedsec VERSION

Version 1.21    9 April 1996

@unnumberedsec SEE ALSO

perl(1)

