README for FreeTDS
* to build FreeTDS read the file INSTALL,
* see also the FreeTDS Users Guide,
http://www.freetds.org/userguide/
FreeTDS is a free (open source) implementation of Sybase's db-lib,
ct-lib, and ODBC libraries. Currently, db-lib and ct-lib are most
mature. Both of these libraries have several programs known to
compile and run against them. ODBC is not quite as mature, but may
work depending on your needs.
A copy of the userguide, in sgml and html form, is included in this
distribution. It is an ordinary tarball; "make install" does not
install the html onto your system. You may wish to do this yourself.
FreeTDS builds and runs on every flavor of unix-like systems we've heard of, as
well as Win32 (with or without Cygwin), and Mac OS X. Failure to build on your
system is probably considered a bug.
Submissions of test programs (self-contained programs that demonstrate
functionality or problems) are greatly appreciated. They should
create any tables needed (since we obviously don't have access to your
database) and populate them. One possible exception is test code that
works against the pubs2 database. Unit tests for any of the libraries
is appreciated
FreeTDS is licensed under the Gnu LGPL license. See COPYING.LIB for
details.
Other files you might want to peruse:
AUTHORS Who's involved
BUGS Some things we fixed, or think we did
ChangeLog Detailed list of changes
NEWS Summary of feature changes and fixes
README This file
TODO The roadmap, such as it is
Also, doc/api_status.txt shows which functions are implemented.
************************************
** Warning regarding Sybase 12.5! **
************************************
Do Not Use FreeTDS 0.61 with TDS version 4.2 to connect to Sybase 12.5.
Please!
While we don't like to put the bad news first, neither do we want you to hurt
your server. Late in the release cycle, we found that our implementation of
TDS 4.2 gives Sybase 12.5 a bad case of heartburn. In short: it crashed the
server.
We don't know what it is about our version of TDS 4.2 that Sybase 12.5 doesn't
like, and we'll be looking closely at that question. But in the meanwhile,
until we can find the problem and fix it, please don't use that combination.
Unless you want to help us test it, that is.
FreeTDS 0.61 works fine with Sybase 12.5 if you use TDS version 5.0.
If you are using Sybase 12.5 and anything above is not clear to you, please
see the User Guide. If it is still not clear after that, please write to the
FreeTDS mailing list. We'd rather answer your questions while your server is
still running.
Thank you. We return now to your regularly scheduled README, already in
progress.
New location of installed files!
================================
With version 0.60, FreeTDS by default installed itself in the
/usr/local tree. You can of course override this location using the
--prefix parameter of the configure script.
Rationale: Although we're not very passionate on the subject, we feel the new
installation directory will be easier for new users to use, because they won't
have to make adjustments to the runtime linking behavior.
Prior to 0.60, FreeTDS installed into /usr/local/freetds. If you wish to
preserve that behavior, build 0.61 with your prefix set to the old location.
Example: ./configure --prefix=/usr/local/freetds/
If you have a version older than 0.60 installed, and want to "get with the
program" (use the new default locations), you will want to be sure that the
old configuration files are preserved, and the old binaries are removed. To
do that, follow these steps:
1) move your configuration files to the new location. Example:
cp /usr/local/freetds/etc/*.conf /usr/local/etc/
2) remove your old installation
rm -fr /usr/local/freetds
3) if you have modified your /etc/ld.so.conf file to include
/usr/local/freetds/lib, remove this and rerun "ldconfig"
4) if you have modified startup scripts for apache or similar applications
to include /usr/local/freetds/lib in the LD_LIBRARY_PATH, be sure to
remove them now.
Once you have installed FreeTDS and taken these steps, your new installation
should work at least as well as your old one. You may wish to try out "tsql" to
test things. See "man tsql" (!) for details.
Bug Submissions
---------------
If you want your bugs actually fixed in a timely manner (and who
doesn't!?), any bug submissions (to the mailing list or the bug
tracking system) should include the following.
1) a small program demonstrating the problem. This can be in C, PHP,
Perl, or simply the SQL if it is reproducible in SQSH.
2) The DDL for your table(s) from the SQL above. A lot of bugs can be
particular to one datatype and without this information it'll be
hard to determine your problem. A simple list of column names,
datatypes, and lengths would also be acceptable if you can't get or
don't know how to produce the DDL. (output from sp_help <tablename>
will do this nicely)
3) The version of FreeTDS you are running, but in general try to get
the latest snapshot or CVS version before reporting a bug.
4) The TDS protocol version. It's the --with-tdsver flag you
configured with 5.0 as the default. Many bugs are protocol
specific and you may just get a 'works for me' if you don't say
which version.
5) Your platform e.g. Redhat 7.0, Solaris 2.6, Linux 2.2.14, anything
close will do. This is especially important if you are on a big
endian platform (Power/PowerPC, Sparc, etc... ), a 64bit platform
(Alpha), or you are experiencing an bus error because of unaligned
access (Sparc mostly). 'uname -a' should produce this info.
6) The type and version of the server you are connecting to. You can
send the query 'select @@version' to get this information.
Also, be sure to check the FAQ (http://www.freetds.org/faq.html) and
mailing list archive
(http://lists.ibiblio.org/mailman/listinfo/freetds)
Notes to Developers
-------------------
The code is split into several pieces.
1) tds directory is the wire level stuff, it should be independent of
the library using it, this will allow db-lib, ct-lib, and ODBC to
sit on top.
2) db-lib directory. This is the actual db-lib code which runs on top of
tds.
3) ct-lib directory. This is the ct-lib code which runs on top of tds.
4) server directory. This will be a set of server routines basically
to impersonate a dataserver, functions like send_login_ack() etc...
5) odbc directory. ODBC implementation over tds. Uses iODBC or
unixODBC as a driver manager. You need to have one of those if you
are using the ODBC CLI.
6) unittests directories. Test harness code for ct-lib, db-lib and tds.
6) samples directories. Sample code for getting started with Perl,
PHP, etc...
7) pool directory. A connection pooling server for TDS. Useful if you
have a connection limited license. Needs some hacking to get
configured but is quite stable once configured correctly. Contact
the list if interested in how to use it.
Please look at doc/getting_started.txt for a description of what is
going on in the code.
Side note: Brian, as many free software authors, appreciates postcards from
all over. So if you live someplace neat (read: not Michigan) and want
to send one, email him (camber@ais.org) for his current snail mail
address.