DBD::ASAny -- an Adaptive Server Anywhere interface for Perl 5.

   Portions Copyright (c) 1994,1995,1996       Tim Bunce
   Portions Copyright (c) 1996,1998,1999,2000  Sybase Inc.

   For license information, please see license.txt included in this
   distribution.

*BEFORE* BUILDING, TESTING AND INSTALLING this you will need to:

    Build, test and install Perl 5 (at least 5.002beta2).
    It is very important to test it and install it!

    Build, test and install the DBI module (at least DBI 1.13).
    It is very important to test it and install it!

    Remember to *read* the DBI README file!


Building:
    On UNIX:
	[ Solaris, AIX, HP-UX, Linux ]

	perl Makefile.PL
	make
	make test
	make install
    
    On Win32:
	[ requires Microsoft C and ActiveState's ActivePerl (www.activestate.com) ]
	NOTE: ActivePerl 5.6.0 build 616 or later is required.

	NOTE: If you see errors related to a missing PerlCRT.DLL you
	      probably have a DBI module compiled with an older
	      ActivePerl. When I upgraded to 616 by overwriting my old
	      ActivePerl installation directory, I was unable to
	      install a new DBI module using ppm. To avoid the 'missing
	      PerlCRT.DLL' errors, either download, build and install
	      the DBI module yourself or do a full uninstall of
	      ActivePerl, delete the old ActivePerl installation tree,
	      then install a new ActivePerl and a new DBI module using
	      ppm.

	perl Makefile.PL
	nmake
	nmake test
	nmake install
    

    Do NOT hand edit the generated Makefile unless you are completely sure
    you understand the implications! Always try to make changes via the
    Makefile.PL command line and/or editing the Makefile.PL.


Notes:

0.  The ASAny DBD driver is NOT supported by Sybase technical
    support. If you have difficulties, please try to solve them
    yourself *before* you contact the author (smirnios@sybase.com). If
    you make additions, improvements or bug fixes, please let the
    author know so that the changes can be incorporated into the next
    version.

1.  The connect() method for Adaptive Server Anywhere now accepts
    connection parameters in a manner that is more consistent with
    other drivers and which should be backward compatible in almost
    all cases with previous DBD::ASAny versions. The recommended way
    of specifying a connection string for ASA is to append it to the
    end of the first connection parameter as in the following example:

	$dbh = DBI->connect( 'DBI:ASAny:UID=dba;PWD=sql;ENG=asademo', '', '' );
    
    For backward compatibility reasons, the ASA connection string that is used
    by the driver is essentially the concatenation of the first three parameters
    with the following exceptions:
	1. The 'DBI:ASAny:' prefix of the first parameter is removed (by DBI).
	2. 'ENG=' is prefixed to the first parameter if it begins with a
	   string which is not in 'LABEL=value' format.
	3. 'UID=' is prefixed to the second parameter if the string does not already
	   appear to use 'LABEL=value' format.
	4. 'PWD=' is prefixed to the third parameter if it is non-empty.
	
    Examples:
	NOTE: these do not represent the recommended way of specifying a connection
	      string for ASA! These examples are only provided to help understand
	      how the connect() method is compatible with older scripts.

	$dbh = DBI->connect( 'DBI:ASAny:asademo', 'dba', 'sql' );
	-> "ENG=asademo;UID=dba;PWD=sql"

	$dbh = DBI->connect( 'DBI:ASAny:asademo;DBF=asademo.db', 'dba', 'sql' );
	-> "ENG=asademo;DBF=asademo.db;UID=dba;PWD=sql"

	$dbh = DBI->connect( 'DBI:ASAny:', 'dba', 'sql' );
	-> "UID=dba;PWD=sql"

	$dbh = DBI->connect( 'DBI:ASAny:', 'UID=dba;PWD=sql', '' );
	-> "UID=dba;PWD=sql"

	[really old] $dbh = DBI->connect( 'asademo', 'dba', 'sql', 'ASAny' );
	-> "ENG=asademo;UID=dba;PWD=sql"

	[really old] $dbh = DBI->connect( 'DBF=asademo.db', 'UID=dba;PWD=sql', '', 'ASAny' );
	-> "DBF=asademo.db;UID=dba;PWD=sql"

2.  Before running 'make test', a copy of the asademo.db file located
    in the ASA directory should be in your current directory. There
    have been problems autostarting and autostopping engines in rapid
    succession on UNIX. If you encounter a problem autostarting the
    engine, start the engine on asademo.db before running the tests.

3.  The ASAny DBD driver should now be thread-safe; however, simple
    multi-threaded tests can easily crash perl. It is suspected that
    the current implementation of Perl threads and/or DBI in a
    threaded environment is the cause of the instability, not the
    driver.


So what is implemented?

Let's 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);                    %attr is ignored
$rv  = $dbh->do($statement, \%attr, @bind_values);      %attr is ignored

$sth = $dbh->prepare($statement);
$sth = $dbh->prepare($statement, \%attr);               %attr is ignored

$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);
$rv = $sth->bind_param($param_num, $bind_value, $bind_type);
$rv = $sth->bind_param($param_num, $bind_value, \%attr);

$rv = $sth->bind_param_inout($param_num, $bind_value);
$rv = $sth->bind_param_inout($param_num, $bind_value, $bind_type);
$rv = $sth->bind_param_inout($param_num, $bind_value, \%attr);

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

@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->{ASATYPE}    (\@)			Yes
$sth->{PRECISION}  (\@)			Yes
$sth->{SCALE}      (\@)			Yes

$sth->{NUM_OF_FIELDS}	($)		Yes
$sth->{NUM_OF_PARAMS}	($)		Yes
$sth->{CursorName}	($)		Yes
$sth->{Statement}	($)		Yes
$sth->{RowsInCache}	($)		Yes
$dbh->{LongReadLen}	($)		Yes

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

There are two examples in the 'eg' directory.
connect.pl  -> Demonstrates a simple connect.
retrieve.pl -> Demonstrates retrieving data from a table and displaying the result set.
blobs.pl    -> Demonstrates the use of blobs

For further examples, consult the test scripts located in the 't' directory.