Usage

Not EVERY query should run through the DBIAgent. If you need to run a short lookup from within a state, sometimes it can be a hassle to have to define a whole seperate state to receive its value, and resume processing from there.. The determining factor, of course, is how long your query will take to execute. If you are trying to retrieve one row from a properly indexed table, use "$dbh->selectrow_array()". If there's a join involved, or multiple rows, or a view, you probably want to use DBIAgent. If it's a longish query and startup costs (time) don't matter to you, go ahead and do it inline.. but remember the whole of your program suspends waiting for the result. If startup costs DO matter, use DBIAgent.

Return Values

 sub some_state {
     #...
     if ($enough_values_to_begin_updating) {

         $heap->{dbiagent}->query(update_values_query =>
                                  this_session =>
                                  update_next_value =>
                                  shift @{$heap->{values_to_be_updated}}
                                 );
     }
 }

 sub update_next_value {
     my ($self, $heap) = @_[OBJECT, HEAP];
     # we got 'EOF' in ARG0 here but we don't care... we know that an
     # update has been executed.

     for (1..3) {               # Do three at a time!
         my $value;
         last unless defined ($value = shift @{$heap->{values_to_be_updated}});
         $heap->{dbiagent}->query(update_values =>
                                  this_session =>
                                  update_next_value =>
                                  $value
                                 );
     }

 }

new()

DSN

An arrayref of parameters to pass to DBI->connect (usually a dsn, username, and password).

Queries

A hashref of the form Query_Name => "$SQL". For example:

 {
   sysdate => "select sysdate from dual",
   employee_record => "select * from emp where id = ?",
   increase_inventory => "update inventory
                          set count = count + ?
                          where item_id = ?",
 }
    

As the example indicates, DBI placeholders are supported, as are DML statements.

Count

The number of helper processes to spawn. Defaults to 3. The optimal value for this parameter will depend on several factors, such as: how many different queries your program will be running, how much RAM you have, how often you run queries, and most importantly, how many queries you intend to run simultaneously.

ErrorState

An listref containing a session and event name to receive error messages from the DBI. The message arrives in ARG0.

query($query_name, [ \%args, ] $session, $state, [ @parameters ])

$query_name

This parameter must be one of the keys to the Queries hashref you passed to the constructor. It is used to indicate which query you wish to execute.

\%args

This is an OPTIONAL hashref of arguments to pass to the query.

Currently supported arguments:

$session, $state

These parameters indicate the POE state that is to receive the data returned from the database. The state indicated will receive the data in its $_[ARG0] parameter. PLEASE make sure this is a valid state, otherwise you will spend a LOT of time banging your head against the wall wondering where your query data is.

@parameters

These are any parameters your query requires. WARNING: You must supply exactly as many parameters as your query has placeholders! This means that if your query has NO placeholders, then you should pass NO extra parameters to "query".

Suggestions to improve this syntax are welcome.

finish()