NAME

DBIx::PhraseBook - provides phrasebooked database queries, allowing client code to avoid embedding sql and direct dbi calls. supports named bind parameters only if the underlying DBD driver does.

WARNING

always returns uppercased key names and resultset is a structure as returned by fetchrow_hashref (see DBI documentation).

IMPLEMENTATION

• my %phraseBooks = DBIx::PhraseBook->load( $prefix, $propsfile );

  loads phrasebooks defined in a properties file, returning a hash keyed on phrasebook name.

  example props file:

  test.hosts.db.dsn=dbi:mysql:hostname=127.0.0.1;debug=1;port=1367;database=hosts test.hosts.db.username=testuser test.hosts.db.password=passwordstring test.hosts.db.phrasebooks.1.name=hosts test.hosts.db.phrasebooks.1.path=/fullpath/to/phrasebooks/hosts.xml test.hosts.db.phrasebooks.1.key=key1 test.hosts.db.phrasebooks.2.name=hosts test.hosts.db.phrasebooks.2.path=/fullpath/to/phrasebooks/hosts.xml test.hosts.db.phrasebooks.2.key=key1

  $prefix would be test.hosts.db for this properties file.

• my $status = $phraseBooks{keyname}->execute($queryName,$inputArg,[outarg1=>$ref])

• my $status = $phraseBooks{keyname}->execute($queryName,{inarg1=>$i1,$inarg2=>$i2},{outarg1=>$ref1,outarg2=>$ref2})

• my $status = $phraseBooks{keyname}->execute($queryName,[$i1,$i2])

• my $hashref = $phraseBooks{keyname}->fetch($queryName,$inputArg,[outarg1=>$ref])

• my @data = $phraseBooks{keyname}->fetch($queryName,$inputArg,[outarg1=>$ref])

• my @data = $phraseBooks{keyname}->fetch($queryName,{inarg1=>$i1,$inarg2=>$i2},{outarg1=>$ref1,outarg2=>$ref2})

  execute and fetch are the main methods in this class that client code will use. both execute a query retrieved from an xml file given a key, binding all necessary variables along the way. fetch returns an array or single row resultset according to what the caller expects (uses wantarray).

  execute does not do a fetch from the statement handle and only returns execute status.

  in array context, fetch will return an array containing hashrefs of all rows. in scalar context, will return one ie the first row as a hashref.

  if query only has one input bind parameter, and it is called ':id', or query has a single '?', then first form of each of execute and fetch (above) can be used.

• my @data = $phraseBooks{keyname}->fetchReport($queryName,$inputArg,[outarg1=>$ref])

  does the same as fetch, but prints a timings report to the logger.

• $phraseBooks{keyname}->prepare($queryName)

  prepares named query and returns a statement handle - is used by execute/fetch and by test scripts. not normally invoked directly by user.

• $phraseBooks{keyname}->getAllQueryNames( )

  returns names of all queries in phrasebook. used by test scripts.

• $phraseBooks{keyname}->useDbh($database_handle)

  Force use of an existing handle

• $phraseBooks{keyname}->getDbh()

  Return existing handle

• $phraseBooks{keyname}->debugOn( )

  Switch DBMS Debugging on

• $phraseBooks{keyname}->debugOff( )

  Switch DBMS Debugging off

AUTHOR

Mark Clements, February 2003

BUGS

is a relatively thin wrapper around Class::Phrasebook and DBI and is quite simplistic - have probably missed a few tricks but should be flexible enough to extend as necessary without too much trouble. possibly should be implemented as a singleton.

getAllQueryNames probably belongs in the Class::Phrasebook module - it's a bit messy having xpath in this class that directly references the phrasebook xml file.