DBIWrapper(3)

NAME
DBIWrapper - Perl extension for generic DBI database access.

SYNOPSIS
  use DBIWrapper;
  my $db = DBIWrapper->new(dbType => "Pg",
                           dbName => "test_db",
                           dbHost => "localhost",
                           dbUser => "nobody",
                           dbPasswd => "",
                           dbPort => "5432",
                           predefinedDSN => "",
                           printError => 1,
                           raiseError => 1,
                           autoCommit => 0);
  if ($db->didErrorOccur())
  {
    die $db->errorMessage();
  }

  $db->read("SELECT * FROM test_tb");
  $db->write(sql => "INSERT INTO test_tb (name, value) VALUES (?, ?)",
                plug => [ $name, $value ]);
  # this used DBI's substitution features to plugin the name and value.

  $db->close();  # close down the database connection.  Any read's
  # or write's will no longer be valid with this object until a new is
  # issued again.

DESCRIPTION
DBIWrapper is the generic database Object for accessing the DBI database interface. It provides the lowest level of functionality needed by any program wanting to access databases via the DBI. Currently, DBIWrapper is only aware of Pg (PostgreSQL), mysql (MySQL) and ODBC DBD modules and how to work with them correctly.

Support for transactions on MySQL is now checked for and if found to be available, the AutoCommit flag is turned off so that transactions will be used.

The substitution array (if used) will cause each ##?1##, ##?2##, etc. string in the sql string to be substituted for the corresponding value in the substitution array. It must start at ?1. It is up to the user to pass in the correct number of elements for both the plug and substitution arrays. The plug array is used to pass in the values for DBI to replace in the sql string of ? which is standard DBI notation.

Exported FUNCTIONS
NOTE: bool = 1(true), 0(false)

scalar new(dbType, dbName, dbHost, dbUser, dbPasswd, dbPort, printError, raiseError, autoCommit, predefinedDSN, setDateStyle, logLevel)
     Creates a new instance of the DBIWrapper object and opens
     a connection to the specified database.  If predefinedDSN is
     specified then it is used instead of the dbName, dbHost, dbPort
     values.  This is mainly to support ODBC easier.
     If setDateStyle is 1 (default) and dbType = Pg, then the datestyle
     for PostgreSQL is set to US (MM/DD/YYYY).
     logLevel defaults to 0.  There are 4 levels 0, 1, 2 and 3 which log
     the following items when an error occurs:
     0) Nothing is output
     1) dbType, dbHost, dbName, printError, raiseError, autoCommit,
       setDateStyle, supportsTransactions, transactionType
     2) all of 1 plus dbUser, dbPort, predefinedDSN
     3) all of 2 plus dbPasswd

bool isValid()
     Returns 1 if the DBI object is valid, else 0 if invalid.

void close()
      Closes the connection to the database.

void setError(errorString)
     sets $error = 1 and $errorString = errorString

bool didErrorOccur()
     returns the value of error.

scalar errorMessage()
     returns the value of errorString.

void commit()
     causes the database to commit the current transaction.  Only works
     if AutoCommit is set to 0 and the database supports Transactions.

void rollback()
     causes the database to rollback the current transaction.  Only
     works if AutoCommit is set to 0 and the database supports
     Transactions.

ref read(sql => "", plug => [], substitute => [])
     (This function should only be called for SELECT statements).
     executes the specified sql statement passing in any values in plug
     to the execute method after doing any substitutions that are in
     substitute.  The resulting sql data is passed back to the user as a
     reference for them to do with as they please.

scalar readXML(sql, plug, substitute, columns)
     requires: sql
     optional: plug, substitute, columns = 0
     returns:  valid XML document describing the data selected from the
      database.  Calls read() to actually validate the data and
      execute the SELECT statement.  The resulting XML document
      will either have an error condition set (if read() signaled
      an error occured) or will be the result of traversing the
      sth object returned from read().

      If columns = 0, then all info will be returned in the <row>
      tag as attributes where the column name = column value.
      Ex.  <row name="test" value="testing" other="something else"/>
      When the column names were name, value and other.

      If columns = 1, then all info will be returned in <column>
      tags which are children of the <row> tag.  A column tag has
      attributes name and value.  name = column name and value =
      column value.
      Ex.
      <row>
        <column name="name" value="test"/>
        <column name="value" value="testing"/>
      </row>

      The XML format is as follows:
      <?xml version="1.0" encoding="ISO-8859-1"?>
      <resultset version="1.1">
        <select sql="" plug=""/>
        <status result="" error=""/>
        <rows numRows="" columns="0|1">
          <row/>
        </rows>
      </resultset>

      If the XML document is an error document, then:
      <status result="Error" error="Error message"/>
      else
      <status result="Ok" error=""/>

      In <select> tag, sql = The sql SELECT string, plug = the
      string made when joining all the plug array entries
      together and comma seperating them.  The entries are
      single quoted.  Ex. plug="''" would represent no plug
      entries used.  plug="'x', 'y'" would mean that 2 entries
      were passed in: x, y.

      In <rows> numRows will be equal to the number of rows
      being returned or 0 if an error had occured.

      The <row> tag will depend on the value of columns.

string encodeEntities(string)
     requires: string - string to encode
     optional:
     returns: string that has been encoded.
     summary: replaces all special characters with their XML entity
       equivalent. " => &quot;

scalar readHTML(sql, plug, substitute, tableClass, alternateRows, displayNumRows)
     requires: sql
     optional: plug, substitute, tableClass, alternateRows,
      displayNumRows
     returns:  valid HTML <table> describing the data selected from the
      database.  Calls read() to actually validate the data and
      execute the SELECT statement.  The resulting HTML <table>
      will either have the error displayed (if read() signaled
      an error occured) or will be the result of traversing the
      sth object returned from read().

     If an error occured, then the generated tr and td will have
     class="sqlError" assigned to them so you can change the way the
     sql Error row is displayed.  The error output will also be
     wrapped in a <span class="sqlError"></span> so you can change
     the display behaviour.

     tableClass defines the class to assign to this table so it knows
     how to display itself.  Defaults to "".  This allows you to have
     different readHTML generated tables on the same page and let them
     look different (border, width, cellspacing, cellpadding, etc.).

     alternateRows (boolean) lets the caller indicate they want to
     possibly have different row characteristics on every other row.
     Defaults to 1.

     displayNumRows (boolean) lets the caller indicate they want a <p>
     above the generated table that tells the user how many rows were
     returned.  Defaults to 1.  The generated paragraph has
     class="sqlNumRows" assigned to it so the caller can affect the
     characteristics of the output and the NumRows statement is wrapped
     in a <span class="sqlNumRows"></span>.

     The table header will be made up from the returned columns in the
     sql statement.  Each <th> will have the css class="column_name"
     defined so that the callers style can have th.column_name defined
     to dictate how the <th> is to be displayed.  The <tr> for the table
     header will have class="sqlHeader" assigned to it.

     Each <tr> will have class="sqlRow" assigned, unless alternateRows
     is enabled, which then causes the even rows to have class="sqlRow"
     and the odd rows to have class="sqlRow2" assigned. Each <td> will
     have the css class="column_name" defined so the callers style
     can have td.column_name defined to dictate how the <td> is to be
     displayed. The contents of the <td> entry will be wrapped in
     <span class="column_name"></span> to allow even more display
     control.

int write(sql => "", plug => [], substitute => [])
     (This function should be called for any sql statement other than
     SELECT).
     executes the specified sql statement passing in any values in plug
     to the execute method after doing any substitutions that are in
     substitute.

     Returns the number of rows affected.

string debugMessage()
     Returns the string that contains all the info that is to be logged
     at the current logLevel level.  If logLevel is not 0, 1, 2 or 3
     then a default of 3 is used.

int getLogLevel()
     returns the current logLevel value.

int setLogLevel(logLevel => 1)
     sets the logLevel value.  If the value is not specified then it
     defaults to logLevel 1.

     Returns 1 on Success, 0 on Error.

     We validate that the logLevel is 1, 2 or 3.

string boolToDBI(string)
     Takes the string and returns a 1 for 1|t|true,
     returns a 0 for anything else.

     This method basically will output a true or false
     value that any database should recognize based upon
     the input string.

string dbiToBool(string)
     Takes the 1 or 0 from the DBI and returns
     true or false.

NOTE:
 All data fields are accessible by specifying the object and
 variable as follows:
 Ex.  $value = $obj->variable;

 Any methods where it is possible to specify just a single
 argument and still have it be valid, you can now specify
 the argument without having to name it first.

 Ex:  calling read() without using the substitute or plug
 options can be done as $dbi->read("SELECT * from test");

 Methods updated to support this:
 setError, read, readXML, write, setLogLevel

AUTHOR
James A. Pattie, james at pcxperience dot com

SEE ALSO
perl(1), DBI(3), DBIWrapper::XMLParser(3), DBIWrapper::ResultSet(3)