$Id: README,v 1.1 1997/09/25 00:26:01 mpeppler Exp mpeppler $
	
	   DBD::Sybase  --  a Sybase DBI driver for Perl 5.

   Copyright (c) 1996, 1997  Michael Peppler

   You may distribute under the terms of either the GNU General Public
   License or the Artistic License, as specified in the Perl README file.

		WARNING: THIS IS ALPHA SOFTWARE.
		    IT IS INCOMPLETE!
		IT IS POSSIBLY UNRELIABLE!



This Sybase DBI driver is built using the Sybase OpenClient Client
Library (aka CTlibrary). You will need to have that installed before
you can do anything with this package. You will also need Tim Bunce's
DBI module, latest release. DBI is available from CPAN, in

    "CPAN"/authors/id/TIMB/DBI/DBI-0.xx-tar.gz

The Sybase OpenClient libraries are of course available from Sybase,
except for Linux where you can get a freeware, slightly out of date
version of the libraries from my homepage (http://www.mbay.net/~mpeppler).

This version of DBD::Sybase is a first attempt at a (fairly) complete
implementation of the DBI spec. There are no doubt quite a few bugs,
and certain things (such as BLOBs and parameter binding on execution
of insert/update) aren't handled right.

Building:

Edit Makefile.PL and set $SYBASE to the Sybase installation directory
on your system.
Run perl Makefile.PL, make, make test.

The regression tests are minimal at the moment so don't necessarily
believe all is fine if the tests succeed...

I still have a problem with $dbh->disconnect which produces a message
like
	disconnect(DBI::db=HASH(0x1b5fe0)) invalidates -3 active cursor(s) at t/main.t line 141.

for some reason. This will get fixed when I figure out what is wrong.


Let me repeat: this is ALPHA software - testing has been minimal!!!



So what is implemented?

Lets take the list at the bottom of DBI.pm:

$dbh = DBI->connect($data_source, $username, $auth);
$dbh = DBI->connect($data_source, $username, $auth, \%attr);

$rc  = $dbh->disconnect;

$rv  = $dbh->do($statement);
$rv  = $dbh->do($statement, \%attr);			Not supported
$rv  = $dbh->do($statement, \%attr, @bind_values);	Not supported

$sth = $dbh->prepare($statement);
$sth = $dbh->prepare($statement, \%attr);		Not supported

$rc = $sth->bind_col($col_num, \$col_variable);
$rc = $sth->bind_columns(\%attr, @list_of_refs_to_vars_to_bind);

$rv = $sth->bind_param($param_num, $bind_value);	Not supported
$rv = $sth->bind_param($param_num, $bind_value, $bind_type);	"
$rv = $sth->bind_param($param_num, $bind_value, \%attr);	"

$rv = $sth->execute;
$rv = $sth->execute(@bind_values);			Not supported

@row_ary  = $sth->fetchrow_array;
$ary_ref  = $sth->fetchrow_arrayref;
$hash_ref = $sth->fetchrow_hashref;

$rc = $sth->finish;

$rv = $sth->rows;

$rc  = $dbh->commit;
$rc  = $dbh->rollback;

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

$rc  = $h->err;
$str = $h->errstr;
$rv  = $h->state;				Not supported


$sth->{NAME}       (\@)				Yes
$sth->{NULLABLE}   (\@)				Yes
$sth->{TYPE}       (\@)				Yes
$sth->{PRECISION}  (\@)				Yes
$sth->{SCALE}      (\@)				Yes

$sth->{NUM_OF_FIELDS}  ($)			Yes
$sth->{NUM_OF_PARAMS}  ($)			Yes

---------------------------------------------------------------


Special behaviour:
==================

The Sybase API allows you to submit SQL code to the server that can
return multiple result sets. When using Sybase::CTlib, for example, this is
handled by using a nested while loop:

while($dbh->ct_results($restype) == CS_SUCCEED) {
    next unless $dbh->ct_fetchable($restype);

    while(@dat = $dbh->ct_fetch) {
       ....
    }
}

The DBI API does not (normally) handle this situation. But because
this situation can arise without the user knowing (typically when
executing a stored procedure) I have coded fetchrow() logic
so that multiple result sets can still be fetched. 

This is done via special attribute in $sth (syb_more_results) which
you should check after $sth->fetchrow() returns an empty array. If this
attribute is true, then you can call $sth->fetchrow() again to get the
next result set.

One problem with this is that the standard $sth attributes (NAME,
NULLABLE, etc) will have the values of the NEXT result set if
$sth->{syb_more_results} is true and $sth->fetchrow returns an empty
array.

Here is an example script:


use DBI;

$dbh = DBI->connect('dbi:Sybase:', 'mpeppler', '', {RaiseError => 1});

$sth = $dbh->prepare("
select log_date, log_by from BugTrack..bug_log
where id < 10
order by id
compute count(id) by id
select * from BugTrack..bug where id < 10

declare \@acc char(10)
declare \@date datetime
declare \@open_val money
declare \@open_val_t money
select \@acc='abcd', \@date='Jan 1 1997'
exec BugTrack..t_proc \@acc, \@date out, \@open_val out, \@open_val_t out
");

$sth->execute;
AGAIN:
while($dat = $sth->fetchrow_hashref) {
    foreach (keys(%$dat)) {
	print "$_: $dat->{$_} ";
    }
    print "\n";
}
if($sth->{syb_more_results}) {
    print "More data on the way...\n";
    goto AGAIN;
}

__END__

Comments, criticism, etc. welcome!

Michael
--
Michael Peppler, Data Migrations, Inc.
mpeppler@datamig.com - http://www.mbay.net/~mpeppler