NAME

DataLookup - Perl extension for database view lookup table.

SYNOPSIS

use DataLookup; 1. Create a DBIx::DataLookup object:

 my $country_table = new DBIx::DataLookup(
                   dbh => $dbh,
                   statement => qq{ select countrycode countryname from countries },
                   );

2. Lookup records with matching 'countrycode' field:

 my $country_rec = $country_table->get_hashref(countrycode => 'USA');
 print "Country name: " . $country_rec->[0]{COUNTRYNAME} . "\n";

Similarly, you may create DataLookup objects to allow you lookup records by multiple keys. Here's an example of just how you could do this:

1. Again, create a DBIx::DataLookup object, but a little more complex than the one before:

 #
 # Note:  '. . .' denotes SQL expression of any complexity you wish.
 #
 my $country_table = new DBIx::DataLookup(
                   dbh => $dbh,
                   statement => qq{ select provname, provcode, countryname, countrycode
                                    from . . .
                                    where . . . },
                   keys => [qw(provcode countrycode)], # lookup keys
                   );

2. (a) Lookup records with matching provcode (Province code):

 my $prov_rec = $country_table->get_hashref(provcode => 'BC');
 print "First province name: " . $prov_rec->[0]{PROVNAME} . "\n";

2. (b) Find all provinces (or states) that belong to specified country:

 my $prov_rec = $country_table->get_hashref(countrycode => 'USA');

 foreach (@$prov_rec) {
   # $_ is a HASHREF to a hash representing 
   # a matched record.
 }

DESCRIPTION

Remotely similar to DBIx::Cache but is very simpler and serves narrower purpose. This module allows you to both cache records pulled by an SQL statement from a database in the memory as well as look them up later at any time during execution of your script.

This also speeds up access to your data at run-time and subsequently reduces load on the database.

For example, in your scripts, you could simply aggregate every SQL statement inside a hash in a config file and use them later to initialize a number of DBIx::DataLookup objects. Later in the code, you would simply invoke the get_hashref() method of your DBIx::DataLookup object(s) to retrieve records matching certain key values.

This module also supports alternative key mapping. For example, if you have to deal with data supplied to you by various providers (such as news/weather syndicates etc), there's a chance for minor irregularities in otherwise similar data (say, two vendors use different identification codes for one theater ...) So, when you are talking of only a dozen (or fewer) such differing keys, key mapping offered by this module becomes quite handy.

TODO

0. Enable lookup by multiple keys so that only records containing both matching keys will get returned. Also, could implement support for complex look up rules (near to what you'd get with SQL WHERE clause).

1. Add set(field => value) method to allow user to set a record field to a new value.

2. Add commit() ? to save data back into the database. Note: may have to deal with original SQL statement in odrer to build a proper UPDATE SQL command.

3. Write more POD!

EXPORT

None.

AUTHOR

Vladimir Bogdanov <b_vlad@telus.net>

SEE ALSO

DBI.