NCCI Perl Documentation BiHashSync(3)
NAME
BiHashSync - Persistant 2-Level Hash Object
SYNOPSIS
# Access to modules (see the NOTES section for setup)
BEGIN {
...
push (@INC, "../sys/csbase/lib");
}
use BiHashSync;
$b = new BiHashSync ($mode, $fileName, $optionalDecryptionKey);
if ($b->isSick ()) { die $b->lastError(); }
$currentFieldValue = $b->get ($primaryKey, $secondaryKey);
$b->set ($primaryKey, $secondaryKey, $newFieldValue);
@primaryKeyList = $tlh->primaryKeys ();
@primaryKeyList = $tlh->primaryKeysSorted ();
@primaryKeyList = $tlh->primaryKeysSortedOnField (
$secondaryKey, $sortOrder);
@secondaryKeyList = $tlh->secondaryKeys ($primaryKey);
$tlh->clearPrimaryKey ($primaryKey);
$tlh->synchronize ();
DESCRIPTION
This Perl5 class implements a "Two-Key Table" data structure
which is (optionally) "associated" with a persistant
external datastore.
This data structure maintains values which are keyed by a
primary and secondary key. This maps nicely onto a
simplified database "Table" concept, where the primary key
implement a single primary key in the database table and the
secondary key represents the column name. It also emulates
the Windows "INI" file construct where the primary key is
the "section".
The keys and values can contain any characters including
Newlines and null characters. The keys and values can be of
any length.
When an object of this class is constructed, an access
"mode" is supplied. With "mem" access mode, this module
manages an in-memory-only class which is not persistant.
With other access modes (described below), an external
datastore is read and/or written to maintain persistance.
19/Mar/01 Last change: perl 5.004, patch 01 1
NCCI Perl Documentation BiHashSync(3)
Currently, the only external datastore implemented is a file
in "Two-Level-Hash" format. Such files have the file
extension .tlh.
Functions
BiHashSync-
>new ($accessMode [, $fileName [, $decryptionKey]])
Create a new BiHashSync object. $accessMode specifies
the access mode used for the life of the object. The
current choices are:
mem - in-memory-only data structure. Data is lost after
the object is destroyed.
r - read-only. Data is read but never written.
rw - read-write. Data is read and written.
w - write-only. No data is in the BiHashSync initially.
Data is written on a call to synchronize ().
The "rw" and "w" modes can have "c" or "e" tacked on the
end (eg. "rwc", "rwe", "wc", "we"). They change the
format of the data written on a synchronize () call:
c - compressed. Space compression of secondary keys.
e - encrypted. The data is written encrypted using a
simple encryption strategy. The key must be supplied on
the constructor.
isHealthy ()
isSick ()
After instantiating a BiHashSync, you MUST check to see
if the connection to the underlying datastore went OK.
Call one of these to determine the status
lastError ()
error ()
If thing aren't healthy, you can get the text which
describes the problem from these routines. Note that
the text is typically a full line, suitable for direct
output to a user.
numEntries ()
Return the number of "entries" - that is, the number of
values across all primary and secondary key pairs
19/Mar/01 Last change: perl 5.004, patch 01 2
NCCI Perl Documentation BiHashSync(3)
dsConnectInfo ()
Return the datastore connection info supplied on the
construction, or on a subsequent setConnectInfo ().
setConnectInfo (ConnectInfo)
Change the identity of the underlying file which we are
representing. This is tricky, and should be used in
limited ways by developers who have read the code in
this class.
In other words: "Your humble servent and faithful scribe
used it once and since hasn't even though of testing
this functionality"
setPassword ($newPassword)
Change the password. This routine lets you (effectively)
change the password used to encrypt a database by:
- opening the file with the old password
- changing the password to the new password
- synchronizing the file
dsFormat ()
format ()
Return the format of the underlying datastore. This is
typically a three-letter all lower-case string which
represents the format. The formats are listed in the
comments at the header of this module.
accessMode ()
Return the current access mode ("mem", "r", "rw", "w",
"rwc", "wc", "rwe", "we")
isDirty ()
isClean ()
Determine whether the data in memory is different from
that in the datastore. BiHashSync's using certain
datastore formats (eg Oracle) will never report isDirty,
while others (tlh) are usually dirty.
headerLineCount ()
addHeaderLine ($newLine)
The external storage has header lines (comments) at the
start of the .tlh file. This routine lets you manage
these comments.
19/Mar/01 Last change: perl 5.004, patch 01 3
NCCI Perl Documentation BiHashSync(3)
unClean ()
dirty ()
When an update to data structure is make, the BiHashSync
object becomes "Dirty". The "Dirty" bit essentially
means that the data in memory is different from that in
the external datastore. These routines declare that
this hash is Dirty and needs to be written on the next
synchronize().
get ($primaryKey, [$secondaryKey, [$default]]))
Get the value from the BiHashSync, given a primary and
secondary key. The form without a $secondaryKey can be
used if a default secondary key has been declared for
the given $primaryKey. See the setDefaultSecondaryKey()
method below.
If the value is not defined, the value of $default is
returned (or undef, if not supplied).
primaryKeys ()
Return an @list of the primary keys in the hash
primaryKeysSorted ()
Return an @list of the primary keys in the hash, sorted
on the key values
primaryKeysSortedOnField ($sortField, $sortOrder)
Primary keys, sorted on some (secondary key) field. The
sortOrder is a code specifying the comparison:
ai,a alphabetic, increasing (<-- this is the default)
ad alphabetic, decreasing (reverse order)
ci,c case-insensitive alphabetic, increasing
cd case-insensitive alphabetic, decreasing (reverse
order)
ni,n numeric, increasing
nd numeric, decreasing (reverse order)
sortOnField ($sortField, $sortOrder, @keyList)
Sort a list of supplied keys on some (secondary key)
field. The sortOrder is one of the sortOrder codes in
primaryKeysSortedOnField ().
secondaryKeys ($primaryKey)
Given a primary key, return an @list of the secondary
keys in the hash
19/Mar/01 Last change: perl 5.004, patch 01 4
NCCI Perl Documentation BiHashSync(3)
secondaryKeysSorted ($primaryKey)
Given a primary key, return an @list of the secondary
keys in the hash, sorted
set ($primaryKey, $secondaryKey, $val)
Set the value for a given primary and secondary key.
setMulti ($primaryKey, %keyValHash)
Set multiple value for a given primary and multiple
secondary keys.
clearPrimaryKey ($primaryKey)
Clobber all values for a given primary key
setDefaultSecondaryKey ($primaryKey, $secondaryKey)
getDefaultSecondaryKey ()
Establish a default secondary key for a given primary
key This allows calls of the form get ($primaryKey) to
assume the $secondaryKey supplied here.
setTimestamp ($primaryKey, $secondaryKey, $timestamp)
getTimestamp ($primaryKey, $secondaryKey)
These methods let you associate a timestamp with a given
primary/secondary key pair.
synchronize ()
Refresh the underlying datastore with our in-memory
data.
NOTE: The underlying datastore is written ONLY if it is
marked as "Dirty" (see isDirty() above). Thus, if you
want to keep the underlying datastore in tight
synchronization with memory, you can repeatedly call
synchronize() without the overhead of writing identical
databases.
Coordination of multiple file writers is done using the
Synch.pm package for lockout.
WARNING
Calls to synchronize() are synchronized between separate
processes, UNLESS THEY ARE RUNNING ON DIFFERENT HOSTS. So,
if two processes running on different hosts synchronize() on
the same external .tlh file, you WILL get data corruption
(eventually).
Since the underlying Synch.pm class is non-reentrant, this
class cannot be reliably used in a multi-threaded
application.
19/Mar/01 Last change: perl 5.004, patch 01 5
NCCI Perl Documentation BiHashSync(3)
SEE ALSO
Synch.pm Synchronized resource sharing among
cooperating processes.
NOTES
This module has not yet been set up for "installation" in
your local Perl. We currently use a set of conventions for
access to this module, until the install procedures are
developed:
- The source code lives on development and production hosts
in the directory /Volumes/app/cs/csbase/lib.
- By convention, a project maintains perl scripts in
subdirectories of some top-level directory, which we will
call $TOP.
- By convention, projects establish a $TOP/sys directory
which contains a symbolic link from csbase to
/Volummes/app/cs/csbase.
- To get access to the modules, you typically include a
BEGIN of the form:
BEGIN {
...
push (@INC, "../sys/csbase/lib");
}
AUTHOR
Clint Goss <clint@goss.com>, Feb 1997