$Id: README,v 1.24 2004/12/19 09:58:06 mpeppler Exp $ DBD::Sybase -- a Sybase DBI driver for Perl 5. Copyright (c) 1996-2004 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. 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-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. With FreeTDS DBD::Sybase can be used to query a MS-SQL 7 or 2000 database server from a Unix/linux host. See http://www.freetds.org for details. If you use FreeTDS please read the README.freetds file. 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. The full write-ups of the bugs that are listed below as "fixed" can be seen at http://www.peppler.org/cgi-bin/bug.cgi. Getting Help ============ If you are stuck please start by searching the Web, the appropriate mailing lists and my bug database, as it is likely that someone else will have experienced the same problem before you. Hint: Google is your friend :-) The sybperl-l mailing list is dedicated to Sybase <-> perl issues and covers both the sybperl modules (Sybase::CTlib, etc.) and DBD::Sybase. It is archived and searchable at http://www.peppler.org/archive/sybperl-l/ If after seaching you still don't find any solution then post a question (with as much detail as possible) to either dbi-users@perl.org, sybperl-l@peppler.org or freetds@lists.ibiblio.org (only use the latter if you use the FreeTDS libraries with DBD::Sybase). Recent changes: Release 1.05 BEHAVIOR CHANGE - $dbh->{LongReadLen} must now be called before $dbh->prepare(). Previously you could call this after the $dbh->prepare() but before the $sth->execute(). Install private statement handle methods for TEXT/IMAGE handling to avoid $h->func() calls, and update documentation. Implement experimental BLK API via prepare/execute loop. Change default "AutoCommit" off mode from explicit transactions to using the "chained" mode if it is available. Add $sth->syb_describe() call, taken from Sybase::CTlib's ct_describe(). Add ISO8601 date/time format for output. Fix $sth->finish() behavior when syb_flush_finish is turned on. Changed do { } while($sth->{syb_more_results}); idiom to use redo instead. Better/more consistent handling of multiple sth on a single dbh, and new test file. Bugs Fixed: 580 - Binding binary/varbinary values to placeholders sometimes fails. 575 - Fails three tests under Tru-64. 577 - perl Makefile.PL fails if umask is 0. 578 - Better warning for calling $dbh->{LongReadLen} if $dbh is busy. 572 - Minor documentation update for bind_param(). Release 1.04 Bugs Fixed: 566 - $sth->{NAME} fails right after prepare(). Release 1.03 Added linking of threaded Sybase libs if perl is built with threading turned on. Added CLONE() method. Minor changes to dbdimp.c to be thread-safe. Added t/thread.t test script. Changes to Makefile.PL to make configuration easier. Add support for Kerberos-based network login. Release 1.02 Added syb_server_version attribute. This is filled in at connect() time with the numeric version number (11.0.3.3, 12.5.1, etc) of the server that you are connected to. Bugs Fixed: 520 - t/exec.t fails on Win32. 533 - logic error in deadlock retry in nsql(). 532 - t/xblob.t test provides false positive for win32. 534 - Placeholder prepare() fails with ASE 11.0.x Release 1.01 Automatically finish() statement handles if they are re-executed before all the rows have been fetched. Added support for new tables() syntax, thanks to Stephen Wilcoxon. Added support for DATE and TIME datatypes (available in the ASE 12.5.1 release, currently undergoing beta testing). Allow user to specify a database to use for the tests instead of using "tempdb" (useful if user does not have SA privileges). Bugs Fixed: 517 - getpwnam() isn't portable. 493 - Second execute on a prepared handle fails. 487 - Add connection information to error messages. 407 - Second+ statement does not use db from "use database". Release 1.00 Removed "beta" tag! Added data_sources(). Allow "SQL_BINARY" placeholder parameters to be passed either as a hex string (with or without leading 0x), or as raw binary data. Bugs Fixed: 477 - segfault when servermsg_cb is called with a null connection 480 - Makefile.PL searches system dirs before PERL5LIB dirs when looking for DBI installation. 485 - Incorrect handling of large varbinary columns on fetches. 489 - (same as 497, see below). 492 - Can't compile on Win2k. 494 - Do not try to use the ocs.cfg file if it exists. 495 - Incorrect handling of parameters when using placeholders & stored procs. 497 - implicit type conversions with prepared statements often fail 503 - Binary placeholders with stored procedures. 506 - Default scriptName/hostname connect() params. 508 - DBD::Sybase doesn't build under Win2k. 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 12.0/Solaris 7 & Sybase 12.5/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, and will also use the value of $SYBASE_OCS if it is set. 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 may get a core dump. This is an OpenClient problem. See http://www.peppler.org/FAQ/linux.html#q1.14 for additional details. FreeTDS: -------- See the README.freetds file for details. Regression Tests: ----------------- The regression tests cover the normal operations, but can't check for all combination of data and access modes. You should always test with your own scripts/data before moving a new release into production. 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. See perldoc DBD::Sybase for details about the package. Comments, criticism, etc. welcome! Michael -- Michael Peppler mpeppler@peppler.org http://www.peppler.org/