/ 
FlatFile-DataStore-1.01
River stage zero No dependents
/ FlatFile::DataStore::DBM

NAME

FlatFile::DataStore::DBM - Perl module that implements a flatfile datastore with a DBM file key access.

SYNOPSYS

use Fctnl;
use FlatFile::DataStore::DBM;

$FlatFile::DataStore::DBM::dbm_package  = "SDBM_File";  # the defaults
$FlatFile::DataStore::DBM::dbm_parms    = [ O_CREAT|O_RDWR, 0666 ];
$FlatFile::DataStore::DBM::dbm_lock_ext = ".dir";

# new object

my $obj = tie my %dshash, 'FlatFile::DataStore::DBM', {
    name => "dsname",
    dir  => "/my/datastore/directory",
};

# create a record and retrieve it

my $id     = "testrec1";
my $record = $dshash{ $id } = { data => "Test record", user => "Test user data" };

# update it

$record->data( "Updating the test record." );
$dshash{ $id } = $record;

# delete it

delete $dshash{ $id };

# get its history

my @records = $obj->history( $id );

DESCRIPTION

FlatFile::DataStore::DBM implements a tied hash interface to a flatfile datastore. The hash keys are strings that you provide. These keys do not necessarily have to exist as data in the record.

In the case of delete, you're limited in the tied interface -- you can't supply a "delete record" (one that has information about the delete operation). Instead, it will simply retrieve the existing record and store that as the delete record.

Record data may be created or updated (i.e., STORE'd) three ways:

As a data string (or scalar reference), e.g.,

$record = $dshash{ $id } = $record_data;

As a hash reference, e.g.

$record = $dshash{ $id } = { data => $record_data, user => $user_data };

As a record object (record data and user data gotten from object), e.g.,

$record->data( $record_data );
$record->user( $user_data );
$record = $dshash{ $id } = $record;

In the last line above, the object fetched is not the same as the one given to be stored (it has a different preamble).

FWIW, this module is not a subclass of FlatFile::DataStore. Instead, it is a wrapper, so it's a "has a" relationship rather than an "is a" one. But many of the public flatfile methods are available via the tied object, as illustrated by the history() call in the synopsis. These methods include

retrieve
retrieve_preamble
locate_record_data
history
userdata
howmany
lastkeynum
nextkeynum

Note that create(), update(), and delete() are not included in this list. If a datastore is set up using this module, all updates to its data should use this module. This will keep the keys in sync with the data.

VERSION

FlatFile::DataStore::DBM version 1.01

DESCRIPTION

Tieing the hash

Accepts hash ref giving values for dir and name.

tie my %dshash, 'FlatFile::DataStore::DBM', {
    name => $name,
    dir  => $dir,
};

To initialize a new datastore, pass the URI as the value of the uri parameter, e.g.,

tie my %dshash, 'FlatFile::DataStore::DBM', {
    dir  => $dir,
    name => $name,
    uri  => join( ";" =>
        "http://example.com?name=$name",
        "desc=My%20Data%20Store",
        "defaults=medium",
        "user=8-%20-%7E",
        "recsep=%0A",
    ),
};

(See URI Configuration in FlatFile::DataStore.) Also accepts a userdata parameter, which sets the default user data for this instance.

Returns a reference to the FlatFile::DataStore::DBM object.

Object Methods

#---------------------------------------------------------------------

get_key( $keynum );

Gets the key associated with a record sequence number (keynum). This could be handy if you have a record, but don't have its key in the DBM file, e.g.,

# have a record to update, but forgot its key
# (the key isn't necessarily in the record)

my $id = tied(%dshash)->get_key( $record->keynum );
$dshash{ $id } = $record;

get_keynum( $key );

Gets the record sequence number (keynum) associated with a key. Don't have a good use case yet -- included this method as a complement to get_key().