$Id: README,v 1.17 2001/08/03 20:05:59 mpeppler Exp $
	
	   DBD::Sybase  --  a Sybase DBI driver for Perl 5.

   Copyright (c) 1996 - 2001  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 BETA SOFTWARE.


This Sybase DBI driver is built using the Sybase OpenClient Client
Library (aka CT-library). 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-1.xx-tar.gz

The Sybase OpenClient libraries are of course available from Sybase.
For Linux you can get the full Sybase ASE 11.0.3.3 release for free
(this includes the server and the client libraries.)
See http://linux.sybase.com for details, or my homepage 
(http://www.mbay.net/~mpeppler).

An alternative is to use the FreeTDS reimplementation of Client Library.
See http://www.freetds.org for details.

DBD::Sybase is a reasonably complete implementation of the DBI spec, but 
there are still some features that are missing. Please see the DBD::Sybase
man page for details.

You'll notice that the release numbering has changed between this release
and the preceding. I feel that DBD::Sybase is now solid enough to warrant
a "beta" release with a target of releasing 1.00 sometime during this
winter.

I'd like to thank the folks at Morgan Stanley for their help with this 
release.

Recent changes:

Release 0.93

	Added password encryption option to connect() request (contributed
        by Tin Martone)
        Added initial nsql().
	Added ct_get_data(), ct_send_data() and friends func().
	Added ?-style placeholder support for exec proc statements.
	Changed getExtraLibs() in Makefile.PL to *not* link with -linsck
	or -ltli (this avoids problems if the $SYBASE/config/libtcl.cfg
	file has been set to load the threaded version of these
	libraries.)
        Added support for primary_key_info().
        (release 0.92 was never publicly released for various reasons)

        Bugs Fixed:
	366    ping() fails if connection has been marked dead
	364    t/fail.t bug.

Release 0.91

	Removed artificial 1024 byte limit on char/varchar datatypes in 
	result sets.

	Bug Fixes:

	213: BLOBs are returned in HEX, not binary.

Release 0.90

        Release number sequence change: I'm dropping the "alpha" qualifier
        and I expect to release 1.00 fairly soon.

	Small Makefile.PL fix for Sybase 12.0 installation directory 
	changes.
	Applied patch from Tim Ayers to allow 0x type formatting for
	binary data fetches (similar to what Sybase::CTlib and 
	Sybase::DBlib allow).
	Fixed some t/ scripts to not fail when run against MS-SQL.
	Corrected the handling of timeout events in the client
	callback.

	Bug Fixes:

	349: CS_NUMERIC bindings for ?-style placeholders fails for large 
             values.
       	345: Dynamic statement ids get re-used.
	351: prepared statements with placeholders cause handle to become 
	     unusable if *first* execute fails.
	352: ping() doesn't work right in Apache::DBI (thanks to
	     Kiriakos Georgiou)
	353: syb_quoted_identifier doesn't work.
	354: Calling fetch() after prepare() but no execute() fails with 
	     internal DBI error. This should also fix bug # 278 and 288.
	297: type_info() returns incorrect or no data.
	344: timeout doesn't work correctly.

Release 0.23

	Bug Fixes:

	331: ? marks in comments are parsed as placeholders.
	343: Errors in stored procs cause data rows from proc to be
	     thrown away.
	255: $dbh->execute does not fail it executing proc without
	     permissions.



Building:

This version attempts to find out which libraries it needs by looking
at $SYBASE/lib ($SYBASE/$SYBASE_OCS/lib for ASE 12.x installations.) 
This behaviour is experimental, and will only work
on Unix and VMS systems (ie on Win32 you still have to edit the CONFIG
file the old way), but appears to work fine on the two systems I have
access to (Sybase 11.5/Solaris 7 & Sybase 11.0.3.3/linux) and on Sybase
10.0.2.3/OpenVMS AXP 7.1. It assumes that $SYBASE is set and points to 
the Sybase installation directory that you want to use to build 
DBD::Sybase.

Start by editing the PWD file to set a valid user, password and server
for the test scripts to use.
Make sure that the SYBASE environment variable points to the Sybase
installation that you want to use for this build.

Then run 
	perl Makefile.PL
If there were warnings about missing libraries, go to the manual 
configuration, below.
Run
	make
If the make failed, go to the manual configuration, below.
Run
	make test
If this succeeds you can install the package, via
	make install
(which you probably have to run as root.)

Manual Configuration:

If the automatic configuration fails, then you will have to edit the
CONFIG file, and set the EXTRA_LIBS entry according to your OS and
Sybase release, and then run 
	perl Makefile.PL --file

The CONFIG file can be used to set certain system variables that
are needed for the build. 
	SYBASE is the root directory of your Sybase installation. DBD::Sybase
	will use $SYBASE/lib and $SYBASE/include during the build.

	EXTRA_LIBS lists any extra libraries that are required on your
	system. For example, Solaris 2.x needs -ltli. See your OS specific
	documentation supplement from Sybase to determine what is required.

	DBI_INCLUDE is the directory where DBI installed its include files.
	Makefile.PL will normally deduce this directory from perl's Config
	module, so you only need to set this if Makefile.PL fails.

	LINKTYPE. Uncomment and set to 'static' if you want to build
	DBD::Sybase statically (ie always included in a new perl binary).

Edit PWD, and set the user, password and server that you want to use for the 
'make test'.

Run perl Makefile.PL, make, make test.

If everything's fine, run "make install" to move the files to your 
installed perl library tree.


Known Problems:
===============

Solaris 2.x:
-----------
On Solaris 2.x make test will fail if LD_LIBRARY_PATH is set and has
/usr/lib or /lib before $SYBASE/lib. This is because both Solaris 2.x
and Sybase have a library called libintl.so, and if /usr/lib is placed 
before $SYBASE/lib in LD_LIBRARY_PATH the dynamic loader will search
the wrong library when loading DBD::Sybase. In general it is not
necessary to set LD_LIBRARY_PATH on Solaris, and it is only rarely
necessary to include /usr/lib or /lib in the LD_LIBRARY_PATH as those
directories will be searched by default.

Linux:
------
If the LANG or LC_ALL environment variable is set and points to an 
entry that does not exist in $SYBASE/locales/locales.dat (in the 
[linux] section) then you will get a core dump. This is an
OpenClient problem. 
See http://www.mbay.net/~mpeppler/Linux-ASE-FAQ.html#q1.14 for
additional details.


The regression tests cover the normal operations, but they are by no 
means complete, so don't necessarily believe all is fine if the
tests succeed...

NOTE: t/fail.t will *fail* on test #8 if you are connecting to 
      an 11.0.3.3 server. This is a bug in the server, and not something
      that I can do anything about, unfortunately. It's a fairly
      obscure constraint violation condition - read the code if
      you are interested.

I have a simple bug tracking database at http://www.peppler.org/cgi-bin/bug.cgi
You can use it to check for known problems, and to report new ones. Keep
in mind that peppler.org lives on the end of a K56 dialup line, so it
may be slow.

See perldoc DBD::Sybase for details about the package.

Comments, criticism, etc. welcome!

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

