NAME

DBD::Unify - DBI driver for Unify database systems

SYNOPSIS

 # Examples marked NYT are Not Yet Tested, they might work
 #  all others have been tested.
 # man DBI for explanation of each method

 $dbh = DBI->connect ("DBI:Unify:[\$dbname]", "", $schema, {
			 AutoCommit => 0,
			 ChopBlanks => 1,
			 ScanLevel  => 2,
			 });
 $dbh->do ($statement);
 $dbh->do ($statement, \%attr);                      # NYT
 $dbh->do ($statement, \%attr, @bind);               # NYT
 $dbh->commit;
 $dbh->rollback;
 $dbh->disconnect;

 $all = $dbh->selectall_arrayref ($statement);
 @row = $dbh->selectrow_array ($statement);
 $col = $dbh->selectcol_arrayref ($statement);

 $sth = $dbh->prepare ($statement);
 $sth = $dbh->prepare_cached ($statement);           # NYT
 $sth->execute;
 @row = $sth->fetchrow_array;
 $row = $sth->fetchrow_arrayref;
 $row = $sth->fetchrow_hashref;
 $all = $sth->fetchall_arrayref;
 $sth->finish;

 # Statement has placeholders like where field = ?
 $sth = $dbh->prepare ($statement);
 $sth->bind_param ($p_num, $bind_value);             # NYT
 $sth->bind_param ($p_num, $bind_value, $bind_type); # NYT
 $sth->bind_param ($p_num, $bind_value, \%attr);     # NYT
 $sth->bind_col ($col_num, \$col_variable);          # NYT
 $sth->bind_columns (@list_of_refs_to_vars_to_bind); # NYT
 $sth->execute (3);
 @row = $sth->fetchrow_array;
 $sth->finish;

 $cnt = $sth->rows;                                  # NYT

 $sql = $dbh->quote ($string);

 $err = $dbh->err;
 $err = $sth->err;
 $str = $dbh->errstr;
 $str = $sth->errstr;
 $stt = $dbh->state;
 $stt = $sth->state;

DESCRIPTION

DBD::Unify is an extension to Perl which allows access to Unify databases. It is built on top of the standard DBI extension an implements the methods that DBI require.

This document describes the differences between the "generic" DBD and DBD::Unify.

Extensions/Changes

• returned types

  The DBI docs state that:

  Most data is returned to the perl script as strings (null values
  are returned as undef).  This allows arbitrary precision numeric
  data to be handled without loss of accuracy.  Be aware that perl
  may  not preserve the same accuracy when the string is used as a
  number.

  Integers are returned as integer values (perl's IVs).

  (Huge) amounts, floats, reals and doubles are returned as strings for which numeric context (perl's NVs) has been invoked already, so adding zero to force convert to numeric context is not needed.

  Chars are returned as strings (perl's PVs).

  Dates, varchars and others are returned as undef (for the moment).

• connect

  connect ("DBI:Unify:dbname[;options]" [, user [, auth [, attr]]]);

  Options to the connection are passed in the datasource argument. This argument should contain the database name possibly followed by a semicolon and the database options which are ignored.

  Since Unify database authorisation is done using grant's using the user name, the user argument me be empty or undef. The auth field will be used as a default schema. If the auth field is empty or undefined connect will check for the environment variable $USCHEMA to use as a default schema. If neither exists, you will end up in your default schema, or if none is assigned, in the schema PUBLIC.

  At the moment none of the attributes documented in DBI's "ATTRIBUTES COMMON TO ALL HANDLES" are implemented specifically for the Unify DBD driver, but they might have been inhereted from DBI. The ChopBlanks attribute is implemented, but defaults to 1 for DBD::Unify. The Unify driver supports "ScanLevel" to set the transaction scan level to a value between 1 and 16 and "DBDverbose" to set DBD specific debugging, allowing to show only massages from DBD-Unify without using the default DBI->trace () call.

  The connect call will result in statements like:

  CONNECT;
  SET CURRENT SCHEMA TO PUBLIC;  -- if auth = "PUBLIC"
  SET TRANSACTION SCAN LEVEL 7;  -- if attr has { ScanLevel => 7 }

  local database

  connect ("/data/db/unify/v63AB", "", "SYS")

• AutoCommit

  It is recommended that the connect call ends with the attributes { AutoCommit = 0 }>, although it is not implemented (yet).

  If you dont want to check for errors after every call use { AutoCommit = 0, RaiseError => 1 }> instead. This will die with an error message if any DBI call fails.

• re-connect

  Though both the syntax and the module support connecting to different databases, even at the same time, the Unify libraries seem to quit connecting to a new database, even if the old one is closed following every rule of precaution.

  To be safe in closing a handle of all sorts, undef it after it is done with, it will than be destroyed.

  my $dbh = DBI-connect (...);
  my $sth = $dbh->prepare (...);
  :
  $sth->finish ();     $sth = undef;
  $dbh->disconnect (); $dbh = undef;

• do

  $dbh->do ($statement)

  This is implemented as a call to 'EXECUTE IMMEDIATE' with all the limitations that this implies.

• commit and rollback invalidates open cursors

  DBD::Unify does warn when a commit or rollback is isssued on a $dbh with open cursors.

  Possibly a commit/rollback should also undef the $sth's. (This should probably be done in the DBI-layer as other drivers will have the same problems).

  After a commit or rollback the cursors are all ->finish'ed, ie. they are closed and the DBI/DBD will warn if an attempt is made to fetch from them.

  A future version of DBD::Unify might re-prepare the statement.

NOTES

Far from complete ...

SEE ALSO

The DBI documentation in DBI, a lot of web pages, some very good, the Perl 5 DBI FAQ (http://www.symbolstone.org/technology/perl/DBI), other DBD modules' documentation (DBD-Oracle is probably the most complete), the comp.lang.perl.modules newsgroup and the dbi-users mailing list (http://www.isc.org/dbi-lists.html).

AUTHORS

DBI/DBD was developed by Tim Bunce, <Tim.Bunce@ig.co.uk>, who also developed the DBD::Oracle.

H.Merijn Brand, <h.m.brand@hccnet.nl> developed the DBD::Unify extension.