NAME

DBM::DBass - DBM with associative arrays, file locking and XML records

SYNOPSIS

    use DBM::DBass;

    die unless DBM::DBass::gestalt (-api => 'neo');
    my $db = DBM::DBass->new (
        -api  => 'neo',
        -file => '+<file.dbm',
        -lock => 'file.lock',
        -mode => 0644
    );

DESCRIPTION

This module provides methods to read, write and delete associative arrays in DBM files, with file locking and XML records.

It uses a named argument -api for class methods new and gestalt to try to prevent later versions of the module from breaking preexisting APIs.

METHODS

gestalt

This method checks for the existence of an API:

    die 'no API neo' unless DBM::DBass::gestalt (-api => 'neo');

-api is the calling API to check for. One should use this method only for development or testing, and not in frequently used applications.

new

This method creates a new DBass object, and should be the first one called:

    my $db = DBM::DBass->new (
        '-api'  => 'neo',
        '-file' => '+<file.dbm',
        '-lock' => 'file.lock',
        '-mode' => 0644
    );

-api is the calling API to use. -file is the read/write mode (default is read-only) and DBM filename. -lock is the lock filename. -mode is the file permissions mode of the DBM file.

If the DBM file is opened for read-only access, the lock file must preexist, but can be empty. In MacOS, one can create an empty file with SimpleText. In *nix, one can create an empty file with touch:

    touch file.lock

This version of the module has APIs xeen and . The xeen API is deprecated and provided for backward compatibility only, and the neo API should be used when possible.

close

This method releases various resources in the DBass object, to allow other processes to access the DBM file:

    $db->close;

Normally this method should not be used, as it renders the object useless for the remainder of the program execution (and is automatically called when the object is destroyed).

delete

This method deletes records from the DBM file:

    $db->delete ('-keys' => \@keys);
    $db->delete ('-keys' => \%keys);
    $db->delete ('-keys' =>  $key );

Be careful. It can also delete all records:

    $db->delete;

keys

This method returns record keys:

    my @keys = $db->keys;

read

This method returns a hash reference pointing to records in the DBM file:

    my $smallerhashref = $db->read ('-keys' => \@keys, '-root' => $root);
    my $smallerhashref = $db->read ('-keys' => \%keys, '-root' => $root);
    my $smallhashref   = $db->read ('-keys' =>  $keys, '-root' => $root);
    my $entirehashref  = $db->read ('-root' =>  $root);

-keys are the keys to match against. -root is the XML root tag name used in storing the records.

write

This method writes key-value pairs to the DBM file:

    $db->write (-hash => \%hash, -root => $root);

-hash is the hash reference pointing to the key-value pairs (records). -root is the XML root tag name to use in storing the records.

KNOWN ISSUES

The xeen API is deprecated and provided for backward compatibility only, and the neo API should be used when possible. The main reason for the API name change is that the neo record format is significantly different from that of xeen.

On platforms other than MacOS, *nix or Windows NT, flock will probably cause the module to crash and burn.

The module should be pronounced /di'bas/.

The xeen API is not named after the IBM alphaWorks Xeena XML editor.

CHANGES

    0.54  2000.01.19  renamed package to DBM::DBass, as per Tim Bunce

    0.53  2000.01.11  fixed Makefile.PL (oops!)

    0.52  1999.10.30  added check for _OBJ
                      added check for _HASHREF
                      fixed neo_read handling of _UNTAGGED
                      fixed neo_read to check for _HASHREF
                      fixed neo_write to check for _OBJ
                      fixed xeen_delete to check for _OBJ
                      fixed xeen_destroy to check for _OBJ
                      fixed xeen_new die preparation
                      fixed xeen_new to include _UNTAGGED
                      fixed xeen_read handling of _UNTAGGED
                      fixed xeen_read to check for _HASHREF
                      fixed xeen_write to check for _OBJ

    0.51  1999.10.26  fixed gestalt for wantarray
                      fixed neo_read to accept hash references as -keys
                      fixed xeen_delete to accept hash references as -keys
                      fixed xeen_read to accept hash references as -keys

    0.50  1999.10.06  added neo API (valid XML tags and lists of lists)

    0.40  1999.09.20  fixed DBM file locking bug in xeen_destroy
                      fixed DBM file locking bug in xeen_new
                      fixed xeen_delete to accept scalars as -keys
                      fixed xeen_read to accept scalars as -keys

AUTHOR

Copyright 1999, 2000 Nguon Hao Ching (spiderboy@spiderboy.net).

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

CREDITS

Thanks to Tom Christiansen for Perl Cookbook recipe 14.5.

Thanks to Mark-Jason Dominus for the Perl Monger tutorial on file locking.

Thanks to David Harris and Paul Marquess for the recipe bug report.

Thanks to Chris Nandor for perlport.

Thanks to James Wismer for feedback on the initial, unreleased version.

Thanks to Jay Trolley for her patience and understanding.

Thanks to xeenie for everything else.