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