NAME

Data::Shark::DBI -- Database Functions

DESCRIPTION

This module contains some DBI wrappers for the Data::Shark. By using the simple wrappers a single point of database access and error/status logging can be achieved, along with code size reduction. Native DBI/DBD functions can still be used on the object.

Example:

  #
  # Construct DB object and connect
  #
  my $dsn = "dbi:Pg:dbname=$dbmain";
  my $db  = Data::Shark::DBI->new($dsn, $user, $pass,{ AutoCommit => 1 });
  # setup logging function
  $db->db_log(sub {my ($data) = @_;mylog('SQL',$data);});

Example:

  #
  #  Grab Orders
  #
  $sth = $db->db_sql(q{
      SELECT custnum,custname,address,phone,suburb,ubd,comments,
             lastorder_num,lastorder_date,bad_cust,
             discount,deliv_charge
        FROM customers
       WHERE custnum = ?
     },$cust_id);
  @d = $db->db_fetch($sth);
  $db->db_done($sth);

OBJECT INTERFACE

new ( $dsn, $user, $password, $options ) or new ( $dbi_handle )

New creates the DB object. It either returns the object on successful creation or undef upon failure. $! is the error code if any. The object contains the following hash members:

• dsn datasource string passed to new

• user username passed to new

• pass password passed to new

• dbh the newly created database handle (DBI) or the passed handle

• log a pointer the logging function

• log_fetch flag to indicate if fetched values should be joined with a comma and passed to the logging function. The default is 0

• log_fetchall flag to indicate if fetch all values should be joined with a comma and passed to the logging function. The default is 0

DATABASE INTERACTION OBJECT INTERFACE

db_sql ( $sql, @args )

This function does a prepare on the passed sql statement and then executes the statement passing the args array. The statement and execute call along witht the passed args are logged via the logging function. A DBI statement handle is returned.

If the prepare fails then an error is logged and no statement handle is returned.

If the execute fails then an error is logged and the statement handle is cleaned up, and nothing is returned.

db_fetch ( $sth )

This function executes fetchrow on the passed statement handle. If $self->{'log_fetch'} is non zero then the values returned are logged via the logging function. The results array is returned.

db_fetch_arrayref ( $sth )

This function executes fetchrow_arrayref on the passed statement handle. If $self->{'log_fetch'} is non zero then the values returned are logged via the logging function. The results array reference is returned.

db_fetchall ( $sth )

This function executes fetchall_arrayref on the passed statement handle. If $self->{'log_fetchall'} is non zero then the values returned are logged via the logging function. The results array reference is returned.

db_exec_fetchall_args ( $sql, @args )

This function executes the DBI function as follows:

  selectall_arrayref($sql, {Slice => {}}, @args);

This utility method combines "prepare", "execute" and "fetchall_arrayref" into a single call. It returns a reference to an array containing a reference to a hash for each row of data fetched.

The $sql parameter can be a previously prepared statement handle, in which case the "prepare" is skipped. This is recommended if the statement is going to be executed many times.

If $self->{'log_fetchall'} is non zero then the values returned are logged via the logging function.

db_done ( $sth )

This function executes finish on the statement handle. No logging occurs.

db_log ( &logfunction, [$log_fetch] )

This function sets the logging function to be called for logging operations. The log function is passed the string to log. If the log_fetch argument is passed and equals 1 then the fetched values from any sql statements will be present in the log.

db_rows ( $sth )

This function executes rows on the statement handle and returns the result.

db_prep ( $sql )

This function only executes the prepare function on the sql statement and returns the DBI statement handle. The prepare is logged. If the prepare fails then nothing is returned.

db_exec ( $sth, @args )

This function executes the statement handle and passes the args array. The result is logged. If the execute fails then an error is logged.

SEE ALSO

perl

Data::Shark

DBI

AUTHORS

    William Walz (Jack)

LICENSE AND COPYRIGHT

Copyright (c) 2007 William Walz. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

cpanm Data::Shark

perl -MCPAN -e shell
install Data::Shark