README
1$Id: README,v 1.27 2011/04/25 08:59:17 mpeppler Exp $
2
3 DBD::Sybase -- a Sybase DBI driver for Perl 5.
4
5 Copyright (c) 1996-2011 Michael Peppler
6
7 You may distribute under the terms of either the GNU General Public
8 License or the Artistic License, as specified in the Perl README file.
9
10
11This Sybase DBI driver is built using the Sybase OpenClient Client
12Library (aka CT-library). You will need to have that installed before
13you can do anything with this package. You will also need Tim Bunce's
14DBI module, latest release. DBI is available from CPAN, in
15
16 "CPAN"/authors/id/TIMB/DBI-1.xx-tar.gz
17
18The Sybase OpenClient libraries are of course available from Sybase.
19See http://www.sybase.com or http://www.peppler.org for details.
20
21An alternative is to use the FreeTDS reimplementation of Client Library.
22With FreeTDS DBD::Sybase can be used to query a MS-SQL 7 or 2000
23database server from a Unix/linux host.
24See http://www.freetds.org for details.
25
26If you use FreeTDS please read the README.freetds file.
27
28DBD::Sybase is a reasonably complete implementation of the DBI spec, but
29there are still some features that are missing. Please see the DBD::Sybase
30man page for details.
31
32The full write-ups of the bugs that are listed in the CHANGES file as "fixed"
33can be seen at http://www.peppler.org/bugdb
34
35Getting Help
36============
37
38If you are stuck please start by searching the Web, the appropriate
39mailing lists and my bug database, as it is likely that someone else
40will have experienced the same problem before you. Hint: Google is
41your friend :-)
42
43The sybperl-l mailing list is dedicated to Sybase <-> perl issues and
44covers both the sybperl modules (Sybase::CTlib, etc.) and DBD::Sybase.
45It is archived and searchable at http://www.peppler.org/archive/sybperl-l/
46
47If after seaching you still don't find any solution then post a question
48(with as much detail as possible) to either dbi-users@perl.org,
49sybperl-l@peppler.org or freetds@lists.ibiblio.org (only use the
50latter if you use the FreeTDS libraries with DBD::Sybase).
51
52For recent changes please see the CHANGES file.
53
54Building:
55---------
56
57Make sure that the SYBASE environment variable points to the Sybase
58installation that you want to use for this build. The easiest way
59to do this is to source the SYBASE.sh/SYBASE.csh or SYBASE.bat file
60in the root directory of the Sybase installation you want to use.
61
62This version attempts to find out which libraries it needs by looking
63at $SYBASE/lib ($SYBASE/$SYBASE_OCS/lib for ASE 12.x installations.)
64This behaviour works on Unix and VMS systems, but on Win32 you still
65have to edit the CONFIG file the old way).
66It assumes that $SYBASE is set and points to
67the Sybase installation directory that you want to use to build
68DBD::Sybase, and will also use the value of $SYBASE_OCS if it is set.
69
70Then run
71 perl Makefile.PL
72You will be prompted to choose build options (chained mode for AutoCommit,
73threaded libraries when using a threaded perl) and for server/user/pwd
74to use for the "make test" step.
75
76If there were warnings about missing libraries, go to the manual
77configuration, below.
78
79Run
80 make
81If the make failed, go to the manual configuration, below.
82Run
83 make test
84If this succeeds you can install the package, via
85 make install
86(which you probably have to run as root.)
87
88Manual Configuration:
89---------------------
90
91If the automatic configuration fails, then you will have to edit the
92CONFIG file, and set the EXTRA_LIBS entry according to your OS and
93Sybase release, and then run
94 perl Makefile.PL --file
95
96The CONFIG file can be used to set certain system variables that
97are needed for the build.
98 SYBASE is the root directory of your Sybase installation. DBD::Sybase
99 will use $SYBASE/lib and $SYBASE/include during the build.
100
101 EXTRA_LIBS lists any extra libraries that are required on your
102 system. For example, Solaris 2.x needs -ltli. See your OS specific
103 documentation supplement from Sybase to determine what is required.
104
105 DBI_INCLUDE is the directory where DBI installed its include files.
106 Makefile.PL will normally deduce this directory from perl's Config
107 module, so you only need to set this if Makefile.PL fails.
108
109 LINKTYPE. Uncomment and set to 'static' if you want to build
110 DBD::Sybase statically (ie always included in a new perl binary).
111
112Edit PWD, and set the user, password and server that you want to use for the
113'make test'.
114
115Run perl Makefile.PL, make, make test.
116
117If everything's fine, run "make install" to move the files to your
118installed perl library tree.
119
120Automated build with no prompts:
121--------------------------------
122
123You can run Makefile.PL with command line arguments to accept defaults
124and build DBD::Sybase in an automated manner (without prompts).
125
126The syntax is:
127
128perl Makefile.PL --accept_test_defaults --chained {Y, N} --threaded_libs {Y, N}
129
130
131
132Known Problems:
133===============
134
135Solaris 2.x:
136-----------
137On Solaris 2.x make test will fail if LD_LIBRARY_PATH is set and has
138/usr/lib or /lib before $SYBASE/lib. This is because both Solaris 2.x
139and Sybase have a library called libintl.so, and if /usr/lib is placed
140before $SYBASE/lib in LD_LIBRARY_PATH the dynamic loader will search
141the wrong library when loading DBD::Sybase. In general it is not
142necessary to set LD_LIBRARY_PATH on Solaris, and it is only rarely
143necessary to include /usr/lib or /lib in the LD_LIBRARY_PATH as those
144directories will be searched by default.
145
146Linux:
147------
148If the LANG or LC_ALL environment variable is set and points to an
149entry that does not exist in $SYBASE/locales/locales.dat (in the
150[linux] section) then you may get a core dump. This is an
151OpenClient problem.
152See http://www.peppler.org/FAQ/linux.html#q1.14 for
153additional details.
154
155FreeTDS:
156--------
157
158See the README.freetds file for details.
159
160Regression Tests:
161-----------------
162
163The regression tests cover the normal operations, but can't check
164for all combination of data and access modes. You should always test
165with your own scripts/data before moving a new release into production.
166
167NOTE: t/fail.t will *fail* on test #8 if you are connecting to
168 an 11.0.3.3 server. This is a bug in the server, and not something
169 that I can do anything about, unfortunately. It's a fairly
170 obscure constraint violation condition - read the code if
171 you are interested.
172
173I have a simple bug tracking database at http://www.peppler.org/bugdb
174You can use it to check for known problems, and to report new ones.
175
176See perldoc DBD::Sybase for details about the package.
177
178Comments, criticism, etc. welcome!
179
180Michael
181--
182Michael Peppler
183mpeppler@peppler.org
184http://www.peppler.org/
185
186
README.freetds
1$Id: README.freetds,v 1.2 2003/04/03 19:07:00 mpeppler Exp $
2
3Using DBD::Sybase with FreeTDS
4==============================
5
6DBD::Sybase 1.00 or later works reasonably well with FreeTDS 0.61,
7but some capabilities are limited or not available.
8
9Build process:
10--------------
11
12FreeTDS normally installs in /usr/local, with the libraries in
13/usr/local/lib and the include files in /usr/local/include. This
14location is assumed below.
15
16To build DBD::Sybase you need to set the SYBASE environment variable
17to /usr/local. When you now run "perl Makefile.PL" you will get
18warnings for a few missing libraries:
19 Note (probably harmless): No library found for -lcs
20 Note (probably harmless): No library found for -lsybtcl
21 Note (probably harmless): No library found for -lcomn
22 Note (probably harmless): No library found for -lintl
23This is OK because FreeTDS doesn't package the functions in the
24same libraries as Sybase.
25
26The "make test" process will fail for a number of tests:
27
28Failed Test Stat Wstat Total Fail Failed List of Failed
29-------------------------------------------------------------------------------
30t/exec.t 0 139 ?? ?? % ??
31t/main.t 16 2 12.50% 13-14
32t/xblob.t 6 2 33.33% 5-6
3313 subtests skipped.
34
35This is expected.
36
37Missing Features:
38-----------------
39
40* ?-style placeholders are not supported.
41* Setting $dbh->{LongReadLen} doesn't work
42 Use $dbh->do("set textsize <value>") instead.
43* The special text/image handling functions don't work
44 (i.e. ct_fetch_data(), etc).
45* The $dbh->{syb_row_count} attribute doesn't work.
46 Use $dbh->do("set rowcount <value>") instead.
47* The $dbh->{syb_quoted_identifier} attribute doesn't work.
48 Use $dbh->do("set quoted_identifier <value>") instead.
49
50Bugs:
51-----
52
53FreeTDS 0.61 has a bug when executing queries that return 0 rows,
54which manifests itself when trying to do a fetchrow_hashref()
55after such a query with the following error:
56
57 Can't get DBI::st=HASH(0x811cfa8)->{NAME}: unrecognised attribute at...
58
59This is fixed in the 0.62-dev version of FreeTDS.
60
61
62
README.vms