Tryag File Manager
Home
-
Turbo Force
Current Path :
/
usr
/
share
/
doc
/
freetds-0.64
/
Upload File :
New :
File
Dir
//usr/share/doc/freetds-0.64/userguide.sgml
<!doctype book PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [ <!ENTITY dblibapisgml SYSTEM "../../../dblib.api.sgml"> <!ENTITY ctlibapisgml SYSTEM "../../../ctlib.api.sgml"> <!ENTITY odbcapisgml SYSTEM "../../../odbc.api.sgml"> ]> <book> <bookinfo> <date>$Date: 2006/03/12 01:31:16 $</date> <releaseinfo>$Revision: 1.96.2.2 $</releaseinfo> <title><productname>FreeTDS</productname> User Guide</title> <subtitle>A Guide to Installing, Configuring, and Running <productname>FreeTDS</productname></subtitle> <author> <firstname>Brian</firstname> <surname>Bruns</surname> </author> <author> <firstname>James</firstname> <othername>K.</othername> <surname>Lowden</surname> </author> <copyright> <year>2001</year> <year>2002</year> <year>2003</year> <year>2004</year> <year>2005</year> <year>2006</year> <holder>Brian Bruns and James K. Lowden</holder> </copyright> <legalnotice><para> Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in the section entitled <link linkend="gfdl">GNU Free Documentation License</link>.</para> </legalnotice> </bookinfo> <toc></toc> <!-- nettiquette quoting: http://www.netmeister.org/news/learn2quote.html--> <!-- ////////////////// CHAPTER /////////////////////// --> <preface id="about"><title>About this User Guide</title> <para> This User Guide describes <productname>FreeTDS</productname> 0.64. It is the product of (lots of) happy collaborative effort. Although Brian's name and mine are at the top of it, behind it are many others, who contributed thoughtful suggestions, bamboozled questions, stellar prose, and terse instructions. I don't mention this for the usual reasons (the enumeration of which I leave to you) but rather to emphasize that the purpose of our effort is to help you and those who come after you to have the easiest and most enjoyable time with <productname>FreeTDS</productname>. </para> <para> It is surprisingly hard, after a while, to remember how it can be for someone newly approaching a project to use it. What seems as obvious as a fog horn to an old hand may be much more like the fog itself to the newcomer. That can make installing and setting up new software a puzzling or frustrating experience. You may have heard, <quote>It's easy if you know how.</quote> Indeed it is, and that's our purpose here: to make it easy, by letting you know how. </para> <para> This guide is here for you, and we hope that you will be here for it, that others might benefit from your experience or inexperience. The most recent version <footnote> <para> The version you're reading is: </para> <simplelist type='vert'> <member>$Revision: 1.96.2.2 $</> <member>$Date: 2006/03/12 01:31:16 $</> <member>CVS control number $Id: userguide.sgml,v 1.96.2.2 2006/03/12 01:31:16 jklowden Exp $.</> </simplelist> </footnote> can be found on the <productname>FreeTDS</productname> <ulink url="http://www.freetds.org/userguide/">web site</ulink>, where you will also find the most up to date <ulink url="http://www.freetds.org/faq.html">FAQ</ulink>, as well as links to the anonymous and browseable CVS tree. If you find something wrong, unclear, badly put, misleading, or incorrigible, I hope you will let us know. Post your musings or rants to the mailing list (see <link linkend="contrib">Helping</link>). Patches to <filename>doc/userguide.sgml</> are especially welcome, of course. By taking the time let us know what you think, perhaps the path to enlightenment will be made a little smoother for the fellow behind you. </para> <para> A few technical notes. This guide is written in SGML DocBook format, specifications for which are found in the <ulink url="http://www.docbook.org/tdg/en/html/docbook.html">DocBook book</ulink>. It was converted to HTML with <ulink url="http://openjade.sourceforge.net">OpenJade</ulink>. The SGML text is distributed with the rest of the source code, and may be edited with your favorite or least favorite text editor. </para> <para> Enough. Let's begin. </para> <para> --jkl </para> </preface> <chapter id="what"> <title>What is <productname>FreeTDS</productname>?</title> <para> <productname>FreeTDS</productname> is an open source (or free software if you prefer) programming library, a re-implementation of the Tabular Data Stream protocol. It can be used in place of Sybase's <systemitem class="library">db-lib</systemitem> or <systemitem class="library">ct-lib</systemitem> libraries. It also includes an <systemitem class="library">ODBC library</systemitem>. It allows many open source applications such as <productname>Perl</productname> and <productname>PHP</productname> (or your own C or C++ program) to connect to Sybase or Microsoft <productname>SQL Server</productname>. </para> <para> <productname>FreeTDS</productname> is distributed in source code form, and is expected to compile on just about any operating system. That means every form of Unix® and Unix-like™ system (including notable variants such as Interix® and QNX®), as well as Win32®, VMS®, and OS X®. If it doesn't compile on your system — and you're not using MS-DOS® — it's probably considered a bug. </para> <sect1 id="tdsprotocolhist"> <title>Background: The <acronym>TDS</> Protocol and related <acronym>API</>s </title> <para> <acronym>TDS</> is a <firstterm>protocol</firstterm>, a set of rules describing how to transmit data between two computers. Like any protocol, it defines the types of messages that can be sent, and the order in which they may be sent. Protocols describe the <quote>bits on the wire</quote>, how data flow. </para> <para> In reading this manual, it may be helpful to keep in mind that a protocol is not an <acronym>API</>, although the two are related. The server recognizes and speaks a protocol; anything that can send it the correct combination of bytes in the right order can communicate with it. But programmers aren't generally in the business of sending bytes; that's the job of a library. Over the years, there have been a few libraries — each with its own <acronym>API</> — that do the work of moving SQL through a <acronym>TDS</> pipe. <systemitem class="library">ODBC</systemitem>, <systemitem class="library">db-lib</systemitem>, <systemitem class="library">ct-lib</systemitem>, and <acronym>JDBC</> have very different <acronym>API</>s, but they're all one to the server, because on the wire they speak <acronym>TDS</>. </para> <para> The <acronym>TDS</> protocol was designed and developed by Sybase Inc. for their Sybase <productname>SQL Server</productname> relational database engine in 1984. The problem Sybase faced then still exists: There was no commonly accepted application-level protocol to transfer data between a database server and its client. To encourage the use of their product, Sybase came up with a flexible pair of products called <productname>netlib</productname> and <systemitem class="library">db-lib</systemitem>. </para> <para> <productname>netlib</productname>'s job was to ferry data between the two computers. To do that, it had to deal with the underlying network protocol. Remember, in those days <acronym>TCP/IP</> was not the ubiquitous thing it is today. Besides <acronym>TCP/IP</>, <productname>netlib</productname> ran on <acronym>DECnet</>, <acronym>IPX/SPX</>, <acronym>NetBEUI</> and the like. </para> <para> <systemitem class="library">db-lib</systemitem> provided an <acronym>API</> to the client program, and communicated with the server via <productname>netlib</productname>. What <systemitem class="library">db-lib</systemitem> sent to the server took the form of a stream of bytes, a structured stream of bytes meant for tables of data, a Tabular Data Stream. </para> <para> In 1990 Sybase entered into a technology sharing agreement with Microsoft which resulted in Microsoft marketing its own <productname>SQL Server</productname>. Microsoft kept the <systemitem class="library">db-lib</systemitem> <acronym>API</> and added <systemitem class="library">ODBC</systemitem>. (Microsoft has since added other <acronym>API</>s, too.) At about the same time, Sybase introduced a more powerful <quote>successor</quote> to <systemitem class="library">db-lib</systemitem>, called <systemitem class="library">ct-lib</systemitem>, and called the pair <productname><firstterm>OpenClient</firstterm></productname>. </para> <para> <systemitem class="library">ct-lib</systemitem>, <systemitem class="library">db-lib</systemitem>, and <systemitem class="library">ODBC</systemitem> are <acronym>API</>s that — however different their programming style may be — all use <productname>netlib</productname> to communicate to the server. The language they use is <acronym>TDS</>. </para> <para> The <acronym>TDS</> protocol comes in several flavors, most of which have never been openly documented. If anything, it's probably considered to be something like a trade secret, or at least proprietary technology. The exception is TDS 5.0, used exclusively by Sybase, for which documentation is available <ulink url="http://crm.sybase.com/sybase/www/ESD/tds_spec_download.jsp">from Sybase</ulink>. </para> </sect1> <sect1 id="tdshistory"> <title>History of <acronym>TDS</> Versions</title> <para> At first, there was One Version of <acronym>TDS</> common to both vendors, but in keeping with the broad history of private ventures, they soon diverged. Each vendor has subsequently brought out different versions, and neither supports the other's flavor. That is to say, each vendor's client libraries use the latest version of <acronym>TDS</> offered by that vendor. You can't reliably use Microsoft's libraries to connect to Sybase, or Sybase's libraries to connect to Microsoft. In some cases you'll get a connection, but pretty soon you'll bump into some incompatibility. </para> <variablelist id="tab.tds.protocol.versions"> <title>Versions of the <acronym>TDS</> protocol</title> <varlistentry><term><acronym>TDS 4.2</acronym> Sybase and Microsoft</term> <listitem> <para> The version in use at the time of the Sybase/Microsoft split. </para> </listitem></varlistentry> <varlistentry><term><acronym>TDS 5.0</acronym> Sybase</term> <listitem> <para> Introduced for Sybase. Because TDS 5.0 includes negotiated capabilities through which protocol features can be expanded, we are unlikely to see a new <acronym>TDS</> version from Sybase. </para> </listitem></varlistentry> <varlistentry><term><acronym>TDS 7.0</acronym> Microsoft</term> <listitem> <para> Introduced for <productname>SQL Server 7.0</productname>. Includes support for the extended datatypes in <productname>SQL Server 7.0</productname> (such as <structname>char</structname>/<structname>varchar</structname> fields of more than 255 characters). It also includes support for Unicode. </para> </listitem></varlistentry> <varlistentry><term>TDS 8.0 Microsoft</term> <listitem> <para> Introduced for <productname>SQL Server 2000</productname>. Includes support for big integer (64-bit <structname>int</structname>) and <quote>variant</quote> datatypes. </para> </listitem></varlistentry> </variablelist> </sect1> <sect1 id="FreeTDShistory"> <title>History of <productname>FreeTDS</productname></title> <para> <productname>FreeTDS</productname> was and is developed by observation and experimentation, which is to say, by trial and error. </para> <para> In early 1997, the only option for connecting to a Sybase server from Linux or other free systems was an aging Sybase-released version of <productname>OpenClient</productname>. Unfortunately it had a few problems. The original release was a.out based, although Greg Thain did a great service in converting the library to ELF. Secondly, it included only the newer <systemitem class="library">ct-lib</systemitem> <acronym>API</>. The older <systemitem class="library">db-lib</systemitem> <acronym>API</> was missing. </para> <para> Brian Bruns, a Sybase DBA and originator of the <productname>FreeTDS</productname> project, had some <systemitem class="library">db-lib</systemitem> programs he wanted to run under Linux, and thus began the <productname>FreeTDS</productname> project. The original work focused on <systemitem class="library">db-lib</systemitem> and version 5.0 of the protocol, but quickly expanded to include a <systemitem class="library">ct-lib</systemitem> compatible layer and <acronym>TDS</> version 4.2. Later support for <systemitem class="library">ODBC</systemitem> and <acronym>TDS 7.0 and 8.0</> was added. Craig Spannring wrote a Java <acronym>JDBC</> driver which became <productname>FreeTDS/JDBC</productname>. </para> <para> As the project matured, it gained new partcipants. Frediano Ziglio greatly expanded the <systemitem class="library">ODBC</systemitem> driver, and continues to improve both it and the underlying TDS library. Bill Thompson wrote most of the present BCP system and added cursors to our <systemitem class="library">ct-lib</systemitem>. Your humble author joined the project to add documentation, and wound up as the project's maintainer. Such are the rewards for doing a good deed. </para> <para> There have been many other contributions. Please see the <filename>AUTHORS</> in the distribution for a (we hope) complete list. </para> </sect1> <sect1 id="projects"> <title>Current Projects, Language Bindings, and Alternatives</title> <sect2 id="Current"> <title>Current Projects</title> <para> <productname>FreeTDS</productname> consists of two projects. The <productname>FreeTDS</productname> C libraries and <productname>FreeTDS</productname>/ <acronym>JDBC</>. </para> <itemizedlist mark=opencircle> <listitem><para> The <productname>FreeTDS</productname> C libraries support three separate <acronym>API</>s: <systemitem class="library">db-lib</systemitem>, <systemitem class="library">ct-lib</systemitem>, and <systemitem class="library">ODBC</systemitem>. Underlying these three is libtds, which handles the low-level details of the <acronym>TDS</> protocol, such as sending, receiving, and datatype conversion. This document and the <ulink url="http://www.freetds.org/">FreeTDS</ulink> website are dedicated to these libraries. </para></listitem> <listitem><para> If Java is your game, we refer you to the <ulink url="http://sourceforge.net/projects/jtds/">jTDS</ulink> project on SourceForge. It is a fork of the <productname>FreeTDS/JDBC</productname> project, by Craig Spannring, and is a free, native 100% Java implementation of a Type 4 <acronym>JDBC</> driver. </para></listitem> </itemizedlist> </sect2> <sect2 id="Status"> <title>Status</title> <para> The <systemitem class="library">db-lib</systemitem> and <systemitem class="library">ct-lib</systemitem> <acronym>API</>s have been usable for several years. They have been successfully substituted for Sybase's own libraries in a variety of venues, including <productname>Perl</productname> and <productname>PHP</productname>. That is not to say that these drivers are complete; they're not. But they faithfully implement an important subset of their <acronym>API</>s, enough to be useful. This 0.64 version boasts support for server-side cursors in <systemitem class="library">ct-lib</systemitem>. </para> <para> In addition to the core <systemitem class="library">db-lib</systemitem> <acronym>API</>, <productname>FreeTDS</productname> includes a full implementation of <systemitem class="library">db-lib</systemitem>'s <acronym>bcp</> functions, as well as <command>freebcp</>, a replacement for Sybase's <application>bcp</application> utility. </para> <para> The <systemitem class="library">ODBC</> driver is younger, but has received much attention. The <productname>FreeTDS</productname> 0.60 ODBC driver was a vast improvement over earlier versions, and 0.61 began to comply with the ODBC 3.0 specification. The current version should be fully ODBC 3.0 compatible and contain many fixes and improvements (<systemitem class="library">ODBC</> <acronym>RPC</> parameters, descriptors and others). Any problems found in the currently implemented <acronym>API</> subset are cheerfully addressed. </para> <para> Basic <link linkend="apireference">API coverage</link> information for all libraries may be found in this manual. It is maintained in <filename>doc/api_status.txt</>, included in the source distribution. </para> <para>How big is it? <productname>FreeTDS</productname> has over 90,000 lines of C code, maintained by a handful of developers. Patches arrive irregularly, varying in size from one-liners to thousand-line monsters. Almost all are applied or used in some way. The mailing list has some 700 or so subscribers at this writing. Safe to say, <productname>FreeTDS</productname>'s success so far lies somewhere between the Beetle and the Edsel. </para> </sect2> <sect2 id="Languages"> <title>Languages besides C and Java</title> <para> You may be wondering how these libraries fit with Perl, PHP, TCL, Python, or other popular scripting languages. Most of these languages have bindings to Sybase that use either the <systemitem class="library">db-lib</systemitem> or <systemitem class="library">ct-lib</systemitem> <acronym>API</>, for which <productname>FreeTDS</productname> is intended as a drop-in replacement. For instance, Michael Peppler's <systemitem class="library">DBD::Sybase</systemitem> works very well using <productname>FreeTDS</productname> to access Sybase or Microsoft <productname>SQL Server</productname>s. <productname>PHP</productname> has options for <filename>sybase</filename> (<systemitem class="library">db-lib</systemitem>) and <filename>sybase-ct</filename> (<systemitem class="library">ct-lib</systemitem>) <acronym>API</>s. </para> <para> Not to be outdone, the folks at the <firstterm>O'Caml</> project have a binding for that language. You can read more about it on <ulink url="http://kenn.frap.net/ocaml-freetds/"> Kenn Knowles's</ulink> site; see also his <ulink url="http://www.merjis.com/developers/">ocamldbi</ulink> driver. </para> </sect2> <sect2 id="alternatives"> <title>Alternatives</title> <variablelist id="tab.alternatives"> <title>Should <productname>FreeTDS</productname> not suit your needs, some alternatives</title> <varlistentry> <term>Sybase OpenClient</term> <listitem> <para>In the time since <productname>FreeTDS</productname> was started, Sybase (as well as most major <acronym>DBMS</> vendors) has released its database for the Intel <productname><acronym>GNU</>/Linux</productname> platform. The good: it is a solid product and supports <acronym>TDS</> 4.2 and <acronym>TDS</> 5.0. The bad: it doesn't support <acronym>TDS 7.0</> or Linux/*BSD on non-Intel platforms. The ugly: Microsoft broke date handling for big endian Sybase clients.</para> <para>Depending on platform, it may cost something.</para> </listitem> </varlistentry> <varlistentry> <term><systemitem class="library">ODBC</systemitem> bridge products</term> <listitem><para>They use the <systemitem class="library">ODBC</systemitem> driver on the NT box where your <productname>SQL Server</productname> runs so you'll never have trouble with new protocols and the like. On the downside, they can be costly and may be inefficient. We know of <productname>EasySoft ODBC-ODBC Bridge</productname> from <ulink url="http://www.easysoft.com">EasySoft</ulink>, <productname>Universal Data Access Driver</productname> from <ulink url="http://www.openlinksw.com">OpenLink Software</ulink>, <productname>SequeLink</productname> from <ulink url="http://www.merant.com/">Merant</ulink>, and <Application><systemitem class="library">ODBC</systemitem> Router</Application> from <ulink url="http://www.augsoft.com/">August Software</ulink> Corporation. </para> </listitem> </varlistentry> <varlistentry> <term>Inline <systemitem class="library">ODBC</systemitem> driver</term> <listitem><para>Based on <systemitem class="library">libtds</systemitem>, this is a native <systemitem class="library">ODBC</systemitem> driver for i386 *nix. It is free in price, but comes only as a binary at the present time.</para> </listitem> </varlistentry> <varlistentry> <term>DBD::Proxy</term> <listitem><para>We have no direct experience with this Perl-only option. It has the same caveats as an <systemitem class="library">ODBC</systemitem> bridge except it's free.</para> </listitem> </varlistentry> </variablelist> </sect2> </sect1> </chapter> <!-- ////////////////// CHAPTER /////////////////////// --> <chapter id="build"> <title>Build <productname>FreeTDS</productname></title> <epigraph> <para> If you build it they will come. </para> </epigraph> <sect1 id="gnu"> <title>The <acronym>GNU</> World</title> <para> <productname>FreeTDS</productname> uses <acronym>GNU</> <application>Automake</application>, <application>Autoconf</application>, and <application>libtool</application> to increase portability. </para> <para> For many people, the preceding sentence says it all (good or bad). If you're familiar with the <acronym>GNU</> system, you can probably just download the tarball and get away with scanning the <filename>README</filename> impatiently and then following your instincts. Because everyone is a beginner once and no one is an expert at everything, we'll try to explain things in plain English where possible, and to define our terms as we go along. </para> <para> If the following nevertheless reads like gibberish, you might very well want to use something prepackaged (see <link linkend="alternatives">Alternatives</link>). If it reads like a vaguely intelligible alien script that might yield to intensive research, we've included links to some of the usual suspects at the end of this chapter. If it reads like a bad explanation of something you could explain better, please send us your version! </para> </sect1> <sect1 id="packages"> <title>What to build: Packages, Tarballs, and the <productname>CVS</productname> repository</title> <para> The latest <productname>FreeTDS</productname> package is always available from <ulink url="ftp://ibiblio.unc.edu/pub/Linux/ALPHA/freetds/freetds-release.tgz"> <citetitle>iBiblio</citetitle></ulink> and its mirrors. </para> <para> Code changes by the developers are immediately available in the <productname>CVS</productname> repository. If you've run into a problem, you may want to check out from <productname>CVS</productname> to see if it's fixed there. </para> <para> No password is needed to obtain the current CVS copy of FreeTDS; you need only have a CVS client installed on your machine. Then: <screen> <prompt>$ </prompt><userinput>cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/freetds login</userinput> <prompt>$ </prompt><userinput>cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/freetds checkout freetds</userinput> <prompt>Password: </prompt> <prompt>$ </prompt><userinput>make install</userinput> </screen> </para> <para> For those behind firewalls or otherwise unable to access <productname>CVS</productname>, nightly snapshots of <productname>CVS</productname> are rolled up into tarballs for your convenience. They can be downloaded from <ulink url="ftp://ftp.ibiblio.org/pub/Linux/ALPHA/freetds/freetds-current.tgz">ibiblio.org</ulink>. Tarballs are generated around 3am EST (GMT-5). </para> <para> In general, the <productname>CVS</productname> version works better and has more functionality than the release version. Bugs sometimes persist in the release version but are usually fixed in short order (once identified) in <productname>CVS</productname>. </para> <tip><para> As with any project of this sort, if you want to use the <productname>CVS</productname> version, it's a good idea to join the mailing list. </para></tip> </sect1> <sect1 id="config"> <title>How to build: Configure and make</title> <para> If you've built other <acronym>GNU</> projects, building <productname>FreeTDS</productname> is a fairly straightforward process. We have a terse and verbose description. </para> <Note><para> <productname>FreeTDS</productname> is known to build with <acronym>GNU</> and <acronym>BSD</> <application>make</application>. If you encounter a large number of build errors, and your operating system's <application>make</application> is not <acronym>GNU</> <application>make</application> (as is the case on most non-<acronym>GNU</>/Linux systems), you may wish to install <acronym>GNU</> <application>make</application> from <ulink url="ftp://ftp.gnu.org/gnu/make/">ftp.gnu.org</ulink>. </para></note> <sect2 id="Experts"><title>For Experts</title> <screen> <prompt>$ </prompt><userinput>./configure --prefix=/usr/local/freetds</userinput> <prompt>$ </prompt><userinput>make</userinput> <prompt>$ </prompt><userinput>su root</userinput> <prompt>Password: </prompt> <prompt>$ </prompt><userinput>make install</userinput> </screen> <para> Building from CVS is described in the file INSTALL.CVS. </para> </sect2> <sect2 id="Everyone"><title>For Everyone Else </title> <TITLEABBREV>(<productname>FreeTDS</productname> for Dummies?)</TITLEABBREV> <para> The <acronym>GNU</> development system can generate code for a wide variety of hardware architectures and operating systems, virtually all of which can run <productname>FreeTDS</> in consequence. The work of building and installing the <productname>FreeTDS</> libraries begins with the command <Command>configure</Command>, which generates the <filename>Makefile</filename> that governs how the code is compiled, linked, and installed. Once you've <quote>configured</quote> the project, <command>make</> will manage the rest of the build. </para> <sidebar><title>ODBC Preparation</title> <para>If you intend to build the <productname>FreeTDS</> ODBC driver — and want to use a Driver Manager (DM), as most people do — install the Driver Manager before configuring <productname>FreeTDS</>. <Command>configure</> will detect the the DM and use its header (<filename>.h</>) files for ODBC constants and such. If your DM is installed in an unusual directory, you may have to provide the directory name as a parameter to <Command>configure</>.</para> <para><productname>FreeTDS</> doesn't <emphasis>require</> a DM. You can build the ODBC driver without one, as long as you have the requisite header files: <filename>sql.h</>, <filename>sqlext.h</> and <filename>sqltypes.h</>. These can be taken from either the iODBC or UnixODBC distributions. Put them wherever you like (e.g., <filename>/usr/local/include</filename>). Because <productname>FreeTDS</> won't detect your (missing) DM, it won't automatically build the ODBC driver, so you'll have to tell <Command>configure</> what to do and where to look. Cf. <link linkend="withOdbcNoDM"><option>--with-odbc-nodm</></link> <option</>. </para> </sidebar> <para> The simplest form of running <Command>configure</> is: <screen> <prompt>$ </prompt><userinput>./configure</userinput> </screen> and sometimes that's enough. <Command>configure</> accepts some command-line arguments, too, and you may need to provide some, depending on what your environment looks like. </para> <para> There are a few optional arguments to <Command>configure</> that may be important to you. For a complete list, see <command>configure --help</command>. </para> <sect3><title><command>configure</> options</title> <variablelist id="tab.configure.Directories"><title>Directories and TDS version</title> <varlistentry> <term><Option>--prefix=<replaceable>PREFIX</> </Option></term> <listitem><para> install architecture-independent files in <parameter>PREFIX</>. When you run <command>make install</command>, libraries will be placed in <parameter>PREFIX</><filename>/lib</>, executables in <parameter>PREFIX</><filename>/bin</>, and so on. </para> <para>The default is <filename>/usr/local</> if this argument is not passed to <Command>configure</Command>. </para> </listitem> </varlistentry> <varlistentry> <term><Option>--sysconfdir=<replaceable>DIR</> </Option></term> <listitem><para> read-only single-machine data in <parameter>DIR</> </para> <para>The default is <replaceable>PREFIX/etc</> (<parameter>PREFIX</> being the value of <Option>--prefix=<replaceable>PREFIX</></Option>, above) if this argument is not passed to <Command>configure</Command>. </para> </listitem> </varlistentry> <varlistentry> <term><Option>--with-libiconv-prefix=<replaceable>DIR</> </Option></term> <listitem><para>Specifies the location of the iconv library to use. <Command>configure</> will search for libiconv in the usual places; use <Option>--with-libiconv-prefix</Option> if it's unsuccessful (assuming you want to use iconv, of course). Overridden by <Option>--disable-libiconv</Option>, below. </para> </listitem> </varlistentry> <varlistentry id="withOdbcNoDM"> <term><Option>--with-odbc-nodm=<replaceable>DIR</> </Option></term> <listitem><para>If you're building the ODBC driver and not using a Driver Manager, use this option to indicate the location of the <filename>.h</> files. <command>configure</> will not cause the ODBC driver to be built unless this option is used or a DM is detected/specified. </para> </listitem> </varlistentry> <varlistentry> <term><Option>--with-tdsver=<replaceable>VER</> </Option></term> <listitem><para>Specifies the default <acronym>TDS</> version. (There are a couple of ways to set the <acronym>TDS</> version at run-time. This parameter takes effect if no run-time settings are provided.) Acceptable values of <parameter>VER</> are <literal>4.2</literal>, <literal>4.6</literal>, <literal>5.0</literal>, <literal>7.0</literal>, and <literal>8.0</literal>.</para> <para>The default is <literal>5.0</literal> if this argument is not passed to <Command>configure</Command>.</para> </listitem> </varlistentry> </variablelist> <variablelist id="tab.ODBC.Driver.Managers"><title>ODBC Driver Managers</title> <varlistentry> <term><Option>--with-iodbc=<replaceable>DIR</> </Option></term> <term><Option>--with-unixodbc=<replaceable>DIR</> </Option></term> <listitem><para>Specify directory of <systemitem class="library">iODBC</systemitem> or <systemitem class="library">unixODBC</systemitem> support, and use it as the Driver Manager. As of version 0.62, the ODBC Driver Manager is detected by <command>configure</>, so use this parameter only if yours is installed in a nonstandard path. (Requires <productname>iODBC</productname> or <systemitem class="library">unixODBC</systemitem> to have already been installed.)</para> </listitem> </varlistentry> </variablelist> <variablelist id="tab.turn.off"><title>Things you can turn off</title> <varlistentry> <term><Option>--disable-odbc </Option></term> <listitem><para>Do not attempt to detect ODBC, and do not build the ODBC driver. In case you don't care about ODBC. </para> </listitem> </varlistentry> <varlistentry> <term><Option>--disable-libiconv</Option></term> <listitem><para>By default, <command>configure</> will search your system for an <systemitem class="library">iconv</systemitem> library for use with Microsoft servers (because TDS 7.0 employs Unicode). This switch prevents that search. If no <systemitem class="library">iconv</systemitem> library is used, <productname>FreeTDS</productname> relies on its built-in iconv emulation, which is capable of converting ISO-8859-1 to UCS-2, sufficient for many applications. </para> </listitem> </varlistentry> <varlistentry> <term><Option>--disable-threadsafe</Option></term> <listitem><para>Force <productname>FreeTDS</productname> not to use threadsafe versions of functions such as <function>gethostbyname_r()</> where available. Rely instead on the older and non-threadsafe ones such as <function>gethostbyname()</>. <command>configure</> tests some of these functions. If the tests are successful, <productname>FreeTDS</productname> will use threadsafe functions throughout. </para> <para>Threadsafe operation has been tested on Linux, FreeBSD, and HP-UX. It should work on Solaris, Tru64, and (reportedly) IRIX. Not expected to work on non-unixy systems. It is a good idea to enable threadsafe operation if you configure Apache with multi-threading support.</para> </listitem> </varlistentry> <varlistentry> <term><Option>--disable-debug</Option></term> <listitem><para>Debug-mode compiles are enabled by default, and will remain so at least until version 1.0. You can speed things up ever so slightly by disabling it. </para></listitem> </varlistentry> </variablelist> <variablelist id="tab.turnon"><title>Things you can turn on</title> <varlistentry> <term><Option>--enable-msdblib</Option></term> <listitem><para>Enable Microsoft behavior in the <systemitem class="library">db-lib</systemitem> <acronym>API</> where it diverges from Sybase's. (For instance, Microsoft uses different names for the members of its date structure.) Typically needed only for porting Win32 applications to Unix.</para> <para>As of version 0.63, this option specifies just the default behavior. Programs can change the default at compile time by defining MSDBLIB or SYBDBLIB (for Microsoft or Sybase behavior, respectively) .</para> </listitem> </varlistentry> <varlistentry> <term><Option>--enable-sybase-compat</Option></term> <listitem><para>Enable close compatibility with Sybase's ABI, at the expense of other features. Currently, this enables the generation of a dbopen() entry point in <systemitem class="library">db-lib</systemitem>, which may clash with the <systemitem class="library">DBM</systemitem> function with the same name. Absolutely <emphasis>not required</> for use with other free software. </para> </listitem> </varlistentry> <varlistentry> <term><Option>--enable-extra-checks</Option></term> <listitem><para>Intended for debugging purposes, enables certain internal consistency checks against problems like memory corruption and buffer exhaustion. </para></listitem> </varlistentry> <varlistentry> <term><Option>--enable-developing</Option></term> <listitem><para>Enable some code still in development. Should be used only by a developer or a brave user :) </para></listitem> </varlistentry> </variablelist> <variablelist id="tab.ssl"><title>SSL support</title> <varlistentry> <term><Option>--with-gnutls</Option></term> <listitem><para>Enable SSL using GnuTLS. Use version 1.2.3 or newer.</para> </listitem> </varlistentry> <varlistentry> <term><Option>--with-openssl=<replaceable>DIR</></Option></term> <listitem><para>Enable SSL using OpenSSL. Unlike <productname>FreeTDS</productname>, OpenSSL does not use the LGPL. Please read the <ulink url="http://www.openssl.org/source/license.html">OpenSSL license</ulink> before distributing binaries compiled with this option. </para> </listitem> </varlistentry> </variablelist> </sect3> <sect3><title><command>Make</></title> <para> Now you're ready to build. Follow these easy steps. </para> <orderedlist> <listitem><para>Download the tarball and unpack it.</para> <para>Alternatively, get the latest build from <productname>CVS</productname> <footnote> <para> <productname>CVS</productname> users will need the GNU autotools: Autoconf, Automake, and libtool. </para> </footnote> . </para></listitem> <listitem><para>Change to the <filename>freetds</filename> directory. </para></listitem> <listitem><para>run <command>./configure</> with any options you need. </para></listitem> <listitem><para><command>make; make install; make clean</command> </para></listitem> </orderedlist> <para> You normally need to be root to <command>make install</command>, unless you used the <option>--prefix</> option during configuration to install into your own directory. </para> <para> With any luck, you've built and installed the <productname>FreeTDS</productname> libraries. </para> </sect3> </sect2> </sect1> <sect1 id="osissues"> <title>OS-specific Issues</title> <sidebar> <para>If you've recently built and installed <productname>FreeTDS</productname> and noticed steps peculiar to your OS, we'll happily include your comments here. </para> <para>One thing that can be said, if it's not too obvious: check with your vendor or favorite download site. <productname>FreeTDS</productname> is routinely rolled up into OS install packages. We know of packages for <productname>Debian</productname>, <productname>Red Hat</productname>, <productname>FreeBSD</productname>, and <productname>NetBSD</productname>. The installation through the package management systems in these environments may well reduce your work to simply <command>make install</command>. </para> </sidebar> <sect2 id="Windows"><title></title> <para>The <productname>FreeTDS</productname> ODBC driver compiles under <itemizedlist> <listitem><para>VC++; <filename>.dsw</> and <filename>.dsp</> files are included in the <filename>win32</> directory. </para></listitem> <listitem><para>Dev-C++</para></listitem> <listitem><para>MingW</para></listitem> <listitem><para><application>gcc</> under <application>cygwin</>. </para></listitem> <listitem><para>The Borland Builder 6.0 compiler is also reported to work, but requires some tweaking of the <literal>#include</> statements. We would apply any patches that make this work cleanly.</para></listitem> </itemizedlist> Threadsafe operation will not be enabled. </para> <para>From the Department of Double Emulation: <productname>FreeTDS</productname> builds as a <filename>.dll</> under <productname>WINE</> and as a <filename>.a</> under <productname>Interix</>. See the mailing list archives (second half of 2003) for details. </para> </sect2> <sect2 id="VMS"><title>VMS®</title> <para><productname>FreeTDS</productname> will probably build and run on most versions of OpenVMS Alpha 7.0 and later with DEC/Compaq C 6.0 or later. Other prerequisites: <simplelist> <member><application>gunzip</></member> <member><application>vmstar</></member> <member><application>MMS</> or <application>MMK</></member> </simplelist> </para> <sect3><title>Build Instructions</title> <para>Decompress and unpack the source archive using gunzip and vmstar. If you are untarring on an ODS-5 disk, you should use the <parameter>/ODS2</> or <parameter>-o</> option to create universally VMS-friendly filenames; otherwise the build will fail to locate some files.</para> <para>Set default to the top-level source directory and run the configuration script:</para> <screen> <prompt>$</> <userinput>@[.vms]configure</userinput> </screen> <para> This creates a <filename>descrip.mms</> in the top-level source directory which you may execute by simply running MMS (if you have the Module Management System that is part of DECset) or MMK (a freeware MMS alternative available from <ulink url="http://www.madgoat.com">www.madgoat.com</ulink>).</para> <para>Further information can be found in the <filename></> in the source distribution. </para> </sect3> </sect2> <sect2 id="osx"><title>OS X®</title> <para>As of this writing ($Date: 2006/03/12 01:31:16 $), the regular distribution compiles on OS X. Releases prior to 0.63 either did not compile or required patching. </para> <sect3 id="OSX.Build.Update"> <title>Alternative build procedure</title> <para>On 11 March 2004, <email><ulink url="mailto:dimo@angelhill.net">Dmitri Fedortchenko</ulink></email> offered the following approach, using a local <command>libtool</>. It is included here as a source of clues, in case you encounter trouble. </para> <procedure id="OSX.new.libtool"> <title>Installing with libtool 1.5.2</title> <step><para>Install the latest <command>libtool</> from GNU into <filename>/usr/local</>, so as not to interfere with the Apple-original. </para></step> <step><para>Make sure <filename>/usr/local/bin</> is in your <envar>PATH</envar> and <filename>/usr/local/lib</> is in your <envar>LIBRARY_PATH</envar>. </para></step> <step><para>Go to the <productname>FreeTDS</productname> source directory and generate the <filename>Makefile</>s <screen> <prompt>$ </prompt><userinput>./configure --disable-libiconv --disable-odbc</userinput> </screen> </para></step> <step><para>Overwrite FreeTDS's <filename>libtool</> with a symbolic link to your (better) one <screen> <footnote><para> If you run <command>configure</> again, you'll need to perform this step again, because <command>libtool</> will have been regenerated in its fossilized state. </para></footnote> <prompt>$ </prompt><userinput>ln -sf /usr/local/bin/libtool</userinput> </screen></para></step> <step performance="optional"><para>To check that you've done everything correctly up to this point, <screen> <prompt>$ </prompt><userinput>./libtool --version</userinput> </screen> <command>libtool</> should report version 1.5.2 (or whatever version you downloaded, and <emphasis>not</> 1.4). </para></step> <step><para>And finally, of course <screen> <prompt>$ </prompt><userinput>make && make install</userinput> </screen> </para></step> </procedure> </sect3> </sect2> <sect2 id="AIX"><title>AIX®</title> <para> AIX® can induce linker indigestion. libtool doesn't always understand that a <filename>.a</> file can be a shared library. One solution is to build only static libraries with the <option>--disable-shared</> configure option. </para> <para> Another problem seems to be that the linker isn't asked to pull in all the requisite libraries. Cf. this helpful <ulink url="http://lists.ibiblio.org/pipermail/freetds/2004q3/016748.html">mailing list message</ulink>. </para> </sect2> <sect2 id="RPM"><title>GNU/Linux distributions that use RPMs</title> <para> You may find it convenient to make an RPM from the source distribution, in which case you'll be glad to know it is easily done: <screen> <prompt>$ </prompt><userinput>rpmbuild -ta freetds-0.63RC9.tar.gz</userinput> </screen> </para> </sect2> </sect1> </chapter> <!-- ////////////////// CHAPTER /////////////////////// --> <chapter id="install"> <title>Install <productname>FreeTDS</productname></title> <epigraph> <para> If you install it they will stay? </para> </epigraph> <para> </para> <Note><title>Confusing terminology</title> <para> <quote>Configuring</quote> and <quote>installing</quote> don't have absolute, context-free definitions. In some circles, we install a product and then configure it. In the <acronym>GNU</> world, we <command>configure</command> the package (generate the <filename>Makefile</>s), then we <command>make install</command> the package. To <emphasis>install the package</emphasis> is to copy the binaries to their appropriate run-time directories, copy the documentation to the <filename>doc</filename> directory, and maybe let the package manager know what's happened. That's generally considered part of the <phrase>build process</phrase>, covered in the last chapter. </para> <para> For lack of a better term, this chapter describes installing the <emphasis>product</emphasis>. Put more specifically, once we're done with the package manager, we still have to tell <productname>FreeTDS</productname> about your database servers, and we still have to tell your client programs about <productname>FreeTDS</productname>. </para> </Note> <sect1 id="LocalEnvironment"> <title>The local environment</title> <para> After <productname>FreeTDS</productname> has been built and installed, it still doesn't know where your servers are or what particular version of Sybase or Microsoft software each one is using. </para> <para> The purpose of this section is to explain how to describe your dataservers to <productname>FreeTDS</productname>. <productname>FreeTDS</productname> looks up your server's attributes in <filename>freetds.conf</filename>. Some of the attributes can be overridden by environment variables. </para> <para> One of the more important (and arcane) settings is the <acronym>TDS</> protocol version, described next. </para> </sect1> <sect1 id="ChoosingTdsProtocol"> <title>Choosing a <acronym>TDS</> protocol version</title> <para> The <acronym>TDS</> protocol version is probably something you'd rather not know even existed, much less something you'd have to choose. But there's not that much to it, really. Unless you run into an incompatibility, you're best off running with the highest protocol version supported by your server. That's what the vendors' own products do, which is why when you read the Sybase or Microsoft documentation you find no mention of <acronym>TDS</> versions. <table id="tab.Protocol.by.Product"> <title>Versions of the <acronym>TDS</> Protocol, by Product</title> <tgroup cols="3"> <thead> <row> <entry>Product</entry> <entry>TDS Version</entry> <entry>Comment</entry> </row> </thead> <tbody> <row> <entry>Sybase before System 10, Microsoft SQL Server 6.x</entry> <entry>4.2</entry> <entry>Still works with all products, subject to its limitations. </entry> </row> <row> <entry>Sybase System 10 and above</entry> <entry>5.0</entry> <entry>Still the most current protocol used by Sybase. </entry> </row> <row> <entry>Sybase System SQL Anywhere</entry> <entry>5.0 <emphasis>only</> </entry> <entry>Originally Watcom SQL Server, a completely separate codebase. Our best information is that SQL Anywhere first supported TDS in version 5.5.03 using the OpenServer Gateway (OSG), and native TDS 5.0 support arrived with version 6.0. </entry> </row> <row> <entry>Microsoft SQL Server 7.0</entry> <entry>7.0</entry> <entry>Includes support for the extended datatypes in <productname>SQL Server</productname> 7.0 (such as char/<structname>varchar</structname> fields of more than 255 characters), and support for Unicode.</entry> </row> <row> <entry>Microsoft SQL Server 2000</entry> <entry>8.0</entry> <entry>Include support for bigint (64 bit integers), variant and collation on all fields. <productname>FreeTDS</productname> support for 8.0 is new. Variant is not supported; collation is not widely used. Use <acronym>TDS</> 7.0 (or 4.2) if you experience problems. </entry> </row> </tbody> </tgroup> </table> </para> <para> Why downgrade your protocol? If you encounter a bug, reverting to 4.2 can help isolate it. If you're using low-bandwidth connections, 4.2 is faster than 7.0, because 7.0 transfers all character data in UCS-2 (unicode, 2 bytes/character). However TDS 4.2 has many limitations (see below). If you encounter problems, please report them to the mailing list. </para> <para> <ItemizedList><title>TDS 4.2 has limitations</title> <listitem><para><acronym>ASCII</> only, of course. </para></listitem> <listitem><para><acronym>RPC</> is not supported. </para></listitem> <listitem><para><acronym>BCP</> is not supported. </para></listitem> <listitem><para><structname>varchar</structname> fields are limited to 255 characters. If your table defines longer fields, they'll be truncated. </para></listitem> <listitem><para>dynamic queries (also called <firstterm>prepared statements</>) are not supported. </para></listitem> </ItemizedList> </para> <para> The protocol version may also affect how database servers interpret commands. For example, Microsoft SQL Server 2000 is known to behave differently with versions 4.2 and 7.0. Version 7.0 is recommended for compatibility with SQL Server tools. </para> </sect1> <sect1 id="freetdsconf"> <title>The <filename>freetds.conf</filename> file</title> <sect2 id="freetdsconfpurpose"> <title>What it does</title> <para> <productname>FreeTDS</productname> uses a configuration file <filename>freetds.conf</filename> (the name can be controlled by an environment variable). Its format is similar to Samba's modified <quote><filename>win.ini</filename></quote> format. Its foremost job is to relate <emphasis>dataserver</emphasis> names, as known to your programs <footnote> <para>In general, the dataserver name is arbitrary and local; it's used only by your client programs to tell <productname>FreeTDS</productname> which server to connect to. You can choose any name you like. </para> <para><productname>Sybase SQL Anywhere</productname> (a/k/a Sybase ASA), however, is fussy. You must use the database's name as your dataserver name. Otherwise, the server will refuse your connection. </para> </footnote> , to <emphasis>machine</emphasis> names, as known your network. That is, while your machines have names known to the network, the dataservers on your machines have names known only to your <productname>FreeTDS</productname> client programs. The configuration file can then further describe that dataserver in greater detail, as need be. </para> <para> <note><para> <productname>FreeTDS</productname> also supports an older configuration file format, known as the <filename>interfaces</filename> file. Use <filename>freetds.conf</filename> unless <filename>interfaces</filename> is needed for your situation. It is easier to read, and it is where all the new options are being added. <productname>FreeTDS</productname> looks for <filename>freetds.conf</filename> first, falling back on <filename>interfaces</filename> only if <filename>freetds.conf</filename> is not found. </para> <para> Should you need it, more information about <filename>interfaces</filename> can be found in the <link linkend="interfacesfile">Appendix</link>. </para></note> </para> </sect2> <sect2 id="freetdsconflocation"> <title>Where it goes</title> <para> The default location of <filename>freetds.conf</filename> is determined by the <literal>--sysconfdir</literal> option of <command>configure</>. If you don't specify anything, <command>configure</>'s default <literal>sysconfdir</literal> is <filename>/usr/local/etc</filename>. </para> <para> In addition, <productname>FreeTDS</productname> will look for a file <filename>.freetds.conf</filename> in the user's home directory (<filename>~/.freetds.conf</filename>). </para> <para> The actual name and location of <filename>freetds.conf</filename> may be specified by the environment variable <envar>FREETDS</envar> (or <envar>FREETDSCONF</envar>, same effect). See <link linkend="envvar">Environment Variables</link>, below. </para> <para> <productname>FreeTDS</productname> reads the user's <replaceable>${HOME}/</replaceable><filename>.freetds.conf</filename> before resorting to the system-wide <replaceable>sysconfdir/</replaceable><filename>freetds.conf</filename>. The first properly configured (i.e., a readable file with a section for the server) <filename>freetds.conf</filename> file will be the one used. </para> </sect2> <sect2 id="freetdsconfformat"> <title>What it looks like</title> <para> The <filename>freetds.conf</filename> file is composed of two types of sections: a <literal>[global]</literal> section, and one <literal>[<replaceable>dataserver</replaceable>]</literal> section for each dataserver. Settings in the <literal>[global]</literal> section affect all dataservers, but can be overridden in a <literal>[<replaceable>dataserver</replaceable>]</literal> section. For example </para> <example id="e.g.freetdsconf"> <title>A <filename>freetds.conf</filename> file example</title> <programlisting> [global] tds version = 4.2 [myserver] host = ntbox.mydomain.com port = 1433 [myserver2] host = unixbox.mydomain.com port = 4000 tds version = 5.0 </programlisting> </example> <para> In this example, the default <acronym>TDS</> version for all dataservers is set to <literal>4.2</>. It is then overridden for <literal>myserver2</literal> (a Sybase server) which uses <literal>5.0</>. </para> <para> Usually, it is sufficient to state the only server's hostname and TDS protocol. Everything else can be inferred, unless your setup (or your server's) strays from the defaults. <tip><para>Some people seem to feel safer using the IP address for the server, rather than its name. We don't recommend you do that. Use the name, and benefit from the inherent advantages. That's why DNS was invented in the first place, you know, and you normally <emphasis>should</> be able to find your server by its name. Beyond that, if you do use a number, <productname>FreeTDS</productname> will ask DNS for that number's name (a <firstterm>reverse lookup</>). A properly configured DNS will execute a reverse lookup just as fast as a forward lookup, but not every DNS is properly configured. If yours isn't, you'll wait awhile, unless you take evasive action. </para></tip> </para> <para> It bears mentioning here that prior versions of <productname>FreeTDS</productname> were quite fussy about domain logins, forcing users to make explicit per-server entries in <filename>freetds.conf</>. That is no longer the case. If the username has the form <parameter>DOMAIN\username</>, <productname>FreeTDS</productname> will automatically use a domain login. </para> <table id="tab.freetds.conf"> <title><filename>freetds.conf</filename> settings</title> <tgroup cols="4"> <thead> <row> <entry>Name</entry> <entry>Default</entry> <entry>Meaning</entry> <entry>Possible Values</entry> </row> </thead> <tbody> <row> <entry>tds version</entry> <entry><parameter>--with-tdsver</> value (<literal>5.0</> if unspecified) Overridden by <link linkend="TDSVER">TDSVER</link>. </entry> <entry>The <acronym>TDS</> protocol version to use when connecting.</entry> <entry>4.2, 5.0, 7.0, 8.0</entry> </row> <row> <entry>host</entry> <entry>none</entry> <entry>The host that the dataserver is running on.</entry> <entry>host name or IP address</entry> </row> <row> <entry>port</entry> <entrytbl cols="3"> <thead> <row> <entry>Product</entry> <entry>Version</entry> <entry>Default Port</entry> </row> </thead> <tbody> <row> <entry>Sybase <productname>SQL Server</productname></entry> <entry>prior to System 10</entry> <entry>1433</entry> </row> <row> <entry>Sybase <productname>SQL Server</productname></entry> <entry>10 and up</entry> <entry>5000</entry> </row> <row> <entry>Sybase <productname>SQL Anywhere</productname></entry> <entry>7</entry> <entry>2638</entry> </row> <row> <entry>Microsoft <productname>SQL Server</productname></entry> <entry>all</entry> <entry>1433</entry> </row> </tbody> </entrytbl> <entry> The port number that the dataserver is listening to. <emphasis>Please note:</emphasis> The "defaults" to the left are the server's default settings. <productname>FreeTDS</productname> chooses its default port based on the TDS protocol version: <literal>5000</> for <acronym>TDS</> <literal>5.0</>, and <literal>1433</> for everything else. Overridden by <link linkend="TDSPORT">TDSPORT</link>. </entry> <entry>any valid port</entry> </row> <row> <entry>initial block size</entry> <entry>512</entry> <entry>Specifies the maximum size of a protocol block. Don't mess with unless you know what you are doing.</entry> <entry>multiple of 512</entry> </row> <row> <entry>dump file</entry> <entry>none Overridden by <link linkend="TDSDUMP">TDSDUMP</link>. </entry> <entry>Specifies the location of a tds dump file and turns on logging</entry> <entry>any valid file name</entry> </row> <row> <entry>dump file append</entry> <entry>no</entry> <entry>Appends dump file instead of overwriting it. Useful for debugging when many processes are active.</entry> <entry>yes/no</entry> </row> <row> <entry>timeout</entry> <entry>none</entry> <entry>Sets period to wait for response of query before timing out.</entry> <entry>0-</entry> </row> <row> <entry>connect timeout</entry> <entry>none</entry> <entry>Sets period to wait for response from connect before timing out.</entry> <entry>0-</entry> </row> <row> <entry>emulate little endian</entry> <entry>no</entry> <entry>Forces big endian machines (Sparc, PPC, PARISC) to act as little endian to communicate with MS Servers. Set automatically for <acronym>TDS</> 7.0/8.0 on big endian hosts</entry> <entry>yes/no</entry> </row> <row> <entry id="clientcharset">client charset</entry> <entry>ISO-8859-1<footnote><para>Valid for ISO 8859-1 character set. See <link linkend="Nonwestern"><acronym>TDS</> 7.0 for Nonwestern Languages</link> for more information. </para></footnote></entry> <entry>Makes <productname>FreeTDS</productname> use iconv to convert to and from the specified character set from UCS-2 in <acronym>TDS</> 7.0/8.0. As of 0.62 FreeTDS uses iconv to convert all character data, so there's no need to match the server's charset to insert any characters the server supports.</entry> <entry>any valid iconv character set</entry> </row> <row> <entry>text size</entry> <entry>4,294,967,295</entry> <entry>default value of TEXTSIZE, in bytes. For <type>text</type> and <type>image</type> datatypes, sets the maximum width of any returned column. Cf. <command>set TEXTSIZE</> in the <acronym>T-SQL</> documentation for your server. </entry> <entry>0 to 4,294,967,295</entry> </row> <row> <entry>instance</entry> <entry>none</entry> <entry><para>Name of Microsoft SQL Server <emphasis>instance</> to connect to. The port will be detected automatically. <note><para>This requires an extra round-trip with server and may thus slightly delay making the connection.</para></note></para></entry> <entry>instance name</entry> </row> <row> <entry>debug flags</entry> <entry>0x4fff</entry> <entry>Sets granularity of logging. A set of bit that specify levels and informations. See table below for bit specification.</entry> <entry>any number even in hex or octal notation</entry> </row> </tbody> </tgroup> </table> <para>The logging capability has helped solve inumerable cases, some trivial and some very low-level bugs. Sometimes a developer needs very detailed information about one function, whereas someone else may interested only in whether or not a particular function is called, or even want to see only the SQL that was transmitted to the server. </para> <para>The log's granularity can be controlled with the <literal>debug flags</> entry. The default value (<literal>4FFF</> hex) gives a level of detail that is useful for resolving problems via the mailing list. </para> <table id="tab.freetds.conf.debugflags"> <title>Valid bitmask values for <literal>debug flags</> entry in <filename>freetds.conf</filename></title> <tgroup cols="2"> <thead> <row> <entry>Value</entry> <entry>Meaning</entry> </row> </thead> <tbody> <row> <entry>0x80</entry> <entry>function trace and info</entry> </row> <row> <entry>0x40</entry> <entry>information level 2</entry> </row> <row> <entry>0x20</entry> <entry>information level 1</entry> </row> <row> <entry>0x10</entry> <entry>network</entry> </row> <row> <entry>0x08</entry> <entry>warning</entry> </row> <row> <entry>0x04</entry> <entry>error</entry> </row> <row> <entry>0x02</entry> <entry>severe error</entry> </row> <row> <entry>0x1000</entry> <entry>show pid</entry> </row> <row> <entry>0x2000</entry> <entry>show time</entry> </row> <row> <entry>0x4000</entry> <entry>show source level info (source file and line)</entry> </row> <row> <entry>0x8000</entry> <entry>thread id (not implemented)</entry> </row> </tbody> </tgroup> </table> <para>For more about the wonder world of <productname>FreeTDS</productname>logs, see <link linkend="logging">Logging</link>.</para> <para>As of version 0.62 the following options are deprecated and supported only for backward compatibility.</para> <table id="tab.freetds.conf.deprecated"> <title>Deprecated <filename>freetds.conf</filename> settings</title> <tgroup cols="4"> <thead> <row> <entry>Name</entry> <entry>Default</entry> <entry>Meaning</entry> <entry>Possible Values</entry> </row> </thead> <tbody> <row> <entry>try server login</entry> <entry>yes</entry> <entry>Disable use of server logins when domain logins are in use. </entry> <entry>yes/no</entry> </row> <row> <entry>try domain login</entry> <entry>yes</entry> <entry>Attempt a domain login. <emphasis> Setting try domain login has the effect of disallowing server logins!</emphasis> To configure a dataserver for both server logins and domain login, disable this option and use <link linkend="domains">DOMAIN\username</> for login. </entry> <entry>yes/no</entry> </row> <row> <entry>nt domain</entry> <entry>none</entry> <entry>Specify an explicit domain. </entry> <entry>any</entry> </row> <row> <entry>cross domain login</entry> <entry>no</entry> <entry>(Experimental) If server is member of different domain, attempt to login via that domain. </entry> <entry>yes/no</entry> </row> <row> <entry>debug level</entry> <entry>99</entry> <entry>Sets granularity of logging. Higher number catches more.</entry> <entry>0-99</entry> </row> </tbody> </tgroup> </table> <para>Many settings in <filename></> can be overridden by <link linkend="envvar">environment variables</link> </para> </sect2> </sect1> <sect1 id="locales"> <title>The <filename>locales.conf</filename> file</title> <sect2 id="localespurpose"> <title>What it does</title> <para> For an English-speaking American, not much. <productname>FreeTDS</productname> originated in the United States, and uses U.S. conventions if no <filename>locales.conf</filename> is present. The <filename>locales.conf</filename> provided with the installation also reflects these conventions. </para> <important> <para><filename>locales.conf</> will probably be dropped from <productname>FreeTDS</> one day. Its only real purpose now is to control the format of date strings. The Right Way™ to deduce the appropriate default date format is from the application's locale settings, while allowing an override in <filename>freetds.conf</>. That's the direction we're headed. </para> <para>If your purpose is to affect the client charset description, use <filename>freetds.conf</> instead. </para> </important> <para> Information on locales and locale strings is easily (even too easily!) found on the Internet, or see <command>man locale</> for your system. <productname>FreeTDS</productname> will examine its environment for a <literal>LOCALE</> string. If it finds one, it will look it up in <filename>locales.conf</> to find your preferred settings. If it fails to find one, it will use its defaults. </para> </sect2> <sect2 id="localeslocation"> <title>Where it goes</title> <para> Like <filename>freetds.conf</filename>, the location of <filename>locales.conf</> is determined by the value of <option>--sysconfdir</> to <command>configure</>. The default is <literal>PREFIX/etc</>. </para> </sect2> <sect2 id="localesformat"> <title>What it looks like</title> <para> The format of <filename>locales.conf</> is similar to that of <filename>freetds.conf</filename>. There is a <literal>[default]</> section, and a section for each locale. <filename>locales.conf</> controls three settings <variablelist id="tab.locales.conf"> <varlistentry> <term><literal>date format</></term> <listitem> <para>This entry will be passed (almost) literally to <function>strftime(3)</> to convert dates to strings. </para> <para>For the most part, see you system documentation for <function>strftime(3)</> (<command>man 3 strftime</command>). You will see there though that <function>strftime(3)</> has no provision for milliseconds. The <filename>locales.conf</> format string uses <literal>%z</> for milliseconds. <note><para>If your system's <function>strftime(3)</> does employ <literal>%z</> for its own use, it will not be given that chance by <productname>FreeTDS</productname>. <productname>FreeTDS</productname> will consume the <literal>%z</> for its milliseconds needs, and will not pass it on to <function>strftime(3)</>. </para></note></para> </listitem> </varlistentry> <varlistentry> <term>language</term> <listitem> <para>The language that will be used for error/status messages from the server. A <productname>SQL Server</productname> client can specify a language for such messages at login time. <note><para><productname>FreeTDS</productname> issues a few messages of its own. Messages from the server are called <quote>messages</>; those from the client library (i.e., from <productname>FreeTDS</productname>) are called <quote>error messages</>. <productname>FreeTDS</productname>-issued messages are not affected by <filename>locales.conf</filename>. </para></note> </para> </listitem> </varlistentry> <varlistentry> <term>character set</term> <listitem> <para>Indicates to the server what character set should be used for communicating with the client. </para> </listitem> </varlistentry> </variablelist> </para> </sect2> </sect1> <sect1 id="envvar"> <title>Setting the environment variables</title> <sect2 id="Whatfor"> <title>What they're for</title> <para> You can use environment variables to <itemizedlist> <listitem><para>Advertise the location of the <productname>FreeTDS</productname> libraries to programs that want them.</para></listitem> <listitem><para>Override some of the settings in <productname>FreeTDS</productname>'s configuration file. </para></listitem> <listitem><para>Control how logging is done. </para></listitem> </itemizedlist> This section covers the first two items. For information about environment variables that control logging, see <link linkend="logging">Logging</link> </para> <para> In a typical system, no environment variables need be used. They're sometimes handy for testing, for instance setting <envar>TDSVER</> to check if a connection problem is due to using the wrong protocol version. And they have other uses, described below. But they're just knobs, so don't feel you have to turn every one, unless you're the sort that likes turning knobs. </para> <variablelist id="tab.environment.variables"> <title>Environment Variables</title> <varlistentry> <term id="FREETDS"><envar>FREETDS</envar></term> <listitem> <para>may be used to specify the name and location of the <filename>freetds.conf</filename> file. In prior versions of <productname>FreeTDS</productname>, this variable was known as <envar>FREETDSCONF</envar>. </para> </listitem> </varlistentry> <varlistentry> <term id="TDSVER"><envar>TDSVER</envar></term> <listitem> <para>governs the version of the <acronym>TDS</> protocol used to connect to your server. For a given server, <productname>FreeTDS</productname> inspects four sources in the following order to determine which <acronym>TDS</> protocol version to use, using the first one it finds. </para> <orderedlist> <listitem><para>The value specified in <envar>TDSVER</envar> </para></listitem> <listitem><para>A <filename>freetds.conf</filename> file entry (see below) </para></listitem> <listitem><para>The <filename>interfaces</filename> file entry (see below) </para></listitem> <listitem><para>The <option>--with-tdsver</> option passed to <command>configure</command> </para></listitem> </orderedlist> </listitem> </varlistentry> <varlistentry> <term id="TDSPORT"><envar>TDSPORT</envar></term> <listitem> <para>specifies a TCP port number at which the dataserver is listening. It overrides the default port (1433 for TDS 4.2/7.0/8.0, 4000 for TDS 5.0) as well as any port specified in the <filename>freetds.conf</filename> file.</para> </listitem> </varlistentry> <varlistentry> <term id="SYBASE"><envar>SYBASE</envar></term> <listitem> <para>points to the <productname>FreeTDS</productname> run-time directory. Use of this variable originated with Sybase (the company), and many programs still rely on <envar>SYBASE</envar> to discover the location of the <quote>SYBASE</quote> libraries. </para> <para>The primary use of <envar>SYBASE</envar> is to advertise the location of the <productname>FreeTDS</productname> libraries. A secondary use is to point to the location of the <filename>interfaces</filename> file (if used, see the <link linkend="interfacesfile">Appendix</link>), which some programs examine directly. </para> </listitem> </varlistentry> <varlistentry> <term id="TDSQUERY"><envar>TDSQUERY</envar> </term> <term id="DSQUERY"><envar>DSQUERY</envar></term> <listitem> <para>provides a server name to connect to if none is specified by the application. <envar>DSQUERY</envar> is the historical Sybase name for this variable. </para> </listitem> </varlistentry> <varlistentry> <term id="TDSHOST"><envar>TDSHOST</envar></term> <listitem> <para>overrides the host specified in the <filename>freetds.conf</>.</para> </listitem> </varlistentry> <!-- <varlistentry> <term></term> <listitem> <para></para> </listitem> </varlistentry> <varlistentry> <term></term> <listitem> <para></para> </listitem> </varlistentry> --> </variablelist> </sect2> <sect2 id="Setting"> <title>Setting environment variables</title> <para> Of course, each shell is a little different. In the Bourne shell and variants such as <application>ksh</application> and <application>bash</application>, to set <envar>SYBASE</envar> and <envar>TDSVER</envar> do: <screen> <prompt>$ </prompt><userinput>export SYBASE=/usr/local/freetds</userinput> # (or your favorite directory) <prompt>$ </prompt><userinput>export TDSVER=4.2</userinput> </screen> </para> <para> In <application>csh</application>: <screen> <prompt>$ </prompt><userinput>setenv SYBASE /usr/local/freetds</userinput> <prompt>$ </prompt><userinput>setenv TDSVER 4.2</userinput> </screen> </para> </sect2> <sect2 id="Checking"> <title>Checking your work</title> <para> When you're done, you should see something very like this: <screen> <prompt>$ </prompt><userinput>ls $SYBASE</userinput> <computeroutput>etc include interfaces lib</computeroutput> </screen> </para> </sect2> </sect1> <sect1 id="Configurations"> <title>Configurations that Work</title> <para> The right combination of switches to make <productname>FreeTDS</productname> do its magic depends on <ItemizedList> <listitem><para>Sybase/Microsoft platform </para></listitem> <listitem><para>Version of the server (<productname>SQL Server</productname> 7, or whatever) </para></listitem> <listitem><para>Server CPU & OS </para></listitem> <listitem><para>Client CPU & OS </para></listitem> </ItemizedList> Most combinations work, and the list below is too small and out of date. One of these days, we'll update it. </para> <para> We asked subscribers to the <productname>FreeTDS</productname> mailing list to tell us what combinations they use. Here are the results. </para> <!-- Externally produced file: results.sgml included here --> <table id="tab.Clients.and.Servers"> <title>Combinations of <productname>FreeTDS</productname> Clients and Servers (April 2001)</title> <tgroup cols="6"> <thead> <row> <entry>Count</entry> <entry>Vendor</entry> <entry>Version</entry> <entry>Server</entry> <entry>Client</entry> <entry>TDS</entry> <entry>Tested date</entry> </row> </thead> <tbody> <row> <entry>1</entry> <entry>Microsoft </entry> <entry>2000</entry> <entry>Intel/Windows 2000 </entry> <entry>Intel/Linux</entry> <entry>7.0</entry> <entry>???</entry> </row> <row> <entry>1</entry> <entry>Microsoft </entry> <entry>2000</entry> <entry>Intel/Windows 2000 </entry> <entry>Sparc/Solaris</entry> <entry>4.2</entry> <entry>???</entry> </row> <row> <entry>1</entry> <entry>Microsoft </entry> <entry>2000</entry> <entry>Intel/Windows NT 4.0 </entry> <entry>Intel/FreeBSD</entry> <entry>7.0</entry> <entry>???</entry> </row> <row> <entry>1</entry> <entry>Microsoft </entry> <entry>2000</entry> <entry>Intel/Windows NT 4.0 </entry> <entry>Sparc/Solaris</entry> <entry>7.0</entry> <entry>???</entry> </row> <row> <entry>1</entry> <entry>Microsoft </entry> <entry>6.5</entry> <entry>Intel/Windows NT 4.0 </entry> <entry>Intel/Linux</entry> <entry>4.2</entry> <entry>???</entry> </row> <row> <entry>1</entry> <entry>Microsoft </entry> <entry>7.0</entry> <entry>Intel/Windows NT 4.0 </entry> <entry>Intel/FreeBSD</entry> <entry>4.2</entry> <entry>???</entry> </row> <row> <entry>1</entry> <entry>Microsoft </entry> <entry>7.0</entry> <entry>Intel/Windows NT 4.0 </entry> <entry>Intel/Linux</entry> <entry>4.2</entry> <entry>???</entry> </row> <row> <entry>2</entry> <entry>Microsoft </entry> <entry>7.0</entry> <entry>Intel/Windows NT 4.0 </entry> <entry>Intel/Linux</entry> <entry>7.0</entry> <entry>???</entry> </row> <row> <entry>1</entry> <entry>Microsoft </entry> <entry>7.0</entry> <entry>Intel/Windows NT 4.0 </entry> <entry>Intel/NT4</entry> <entry>4.2</entry> <entry>???</entry> </row> <row> <entry>1</entry> <entry>Microsoft </entry> <entry>7.0</entry> <entry>Intel/Windows NT 4.0 </entry> <entry>Intel/NT4</entry> <entry>7.0</entry> <entry>???</entry> </row> <row> <entry>1</entry> <entry>Microsoft </entry> <entry>7.0</entry> <entry>Intel/Windows NT 4.0 </entry> <entry>Intel/Win2000</entry> <entry>7.0</entry> <entry>???</entry> </row> <row> <entry>2</entry> <entry>Microsoft </entry> <entry>7.0</entry> <entry>Intel/Windows NT 4.0 </entry> <entry>PowerPC/Mac</entry> <entry>4.2</entry> <entry>???</entry> </row> <row> <entry>1</entry> <entry>Microsoft </entry> <entry>7.0</entry> <entry>Intel/Windows NT 4.0 </entry> <entry>Sparc/Solaris</entry> <entry>7.0</entry> <entry>???</entry> </row> <row> <entry>1</entry> <entry>Sybase </entry> <entry>11.5</entry> <entry>Sparc E300/Solaris 2.5.1 </entry> <entry>Intel/Solaris</entry> <entry>5.0</entry> <entry>???</entry> </row> <row> <entry>1</entry> <entry>Sybase ASA</entry> <entry>5.5.03 (w/OSG)</entry> <entry>Intel/Windows NT 4.0</entry> <entry>Intel/Linux</entry> <entry>5.0</entry> <entry>???</entry> </row> <row> <entry>1</entry> <entry>Microsoft</entry> <entry>7.0</entry> <entry>Intel/Windows NT 4.0</entry> <entry>Intel/Linux</entry> <entry>7.0</entry> <entry>2003-01-23</entry> </row> <row> <entry>2</entry> <entry>Microsoft</entry> <entry>2000</entry> <entry>Intel/Windows 2000</entry> <entry>Intel/Linux</entry> <entry>8.0</entry> <entry>2004-10-19</entry> </row> <row> <entry>1</entry> <entry>Microsoft</entry> <entry>7.0</entry> <entry>Intel/Windows NT 4.0</entry> <entry>PARISC/HP-UX 10.20</entry> <entry>7.0</entry> <entry>2002-12-20</entry> </row> <row> <entry>2</entry> <entry>Sybase ASE</entry> <entry>10.9.2.3</entry> <entry>Intel/Linux</entry> <entry>Intel/Linux</entry> <entry>5.0</entry> <entry>2004-10-18</entry> </row> <row> <entry>1</entry> <entry>Microsoft</entry> <entry>2000</entry> <entry>Intel/Windows 2000</entry> <entry>Intel/Linux</entry> <entry>7.0</entry> <entry>2004-10-19</entry> </row> <row> <entry>1</entry> <entry>Microsoft</entry> <entry>2000</entry> <entry>Intel/Windows 2000</entry> <entry>PARISC/HP-UX 11.00</entry> <entry>8.0</entry> <entry>2004-10-18</entry> </row> </tbody> </tgroup> </table> <!-- end of results.smgl --> <para> If you have a working configuration not listed here, please send it to <ulink url="mailto:jklowden@speakeasy.org"><productname>FreeTDS</productname> FAQ Master</ulink>. </para> </sect1> <sect1 id="ConfirmInstall"><title>Confirm the installation</title> <sect2 id="tsql"><title><application>tsql</application></title> <para> The <firstterm>tsql</> utility is provided as part of FreeTDS expressly for troubleshooting. <command>tsql</> is superficially similar to an <command>isql</>, but uses <filename>libtds</filename> directly, bypassing the client libraries (e.g., <systemitem class="library">db-lib</systemitem>). <command>tsql</> can either use or bypass the configuration files, allowing you to see if it's your dataserver that's not responding, or your configuration files that are messed up. </para> <bridgehead renderas='sect3'>Using <filename>freetds.conf</>:</bridgehead> <para> <cmdsynopsis label="Syntax synopsis for tsql"> <command>tsql</command> <arg choice='req'>-S<replaceable>server</replaceable></arg> <arg choice='req'>-U<replaceable>username</replaceable></arg> <arg choice='opt'>-P<replaceable>password</replaceable></arg> <arg choice='opt'>-C</arg> </cmdsynopsis> </para> <bridgehead renderas='sect3'>Bypassing <filename>freetds.conf</>:</bridgehead> <para> <cmdsynopsis label="Syntax synopsis for tsql"> <command>tsql</command> <arg choice='req'>-H <replaceable>hostname</replaceable></arg> <arg choice='req'>-p <replaceable>port</replaceable></arg> <arg choice='req'>-U <replaceable>username</replaceable></arg> <arg choice='opt'>-P<replaceable>password</replaceable></arg> <arg choice='opt'>-C</arg> </cmdsynopsis> </para> <example id="e.g.tsqlFail"> <title>Failing to connect with tsql</title> <screen> <prompt>$ </prompt><userinput>tsql -S <replaceable>emforester</replaceable> -U <replaceable>sa</replaceable> #only connect?</userinput> <prompt>Password: </prompt> <computeroutput> src/tds/login.c: tds_connect: 192.168.1.12:4100: Connection refused Msg 20009, Level 9, State 0, Server OpenClient, Line 0 Server is unavailable or does not exist. There was a problem connecting to the server </computeroutput> </screen> </example> <example id="e.g.tsqlservername"> <title>Connect with <command>tsql</> using a servername in <filename>freetds.conf</></title> <screen> <prompt>$ </prompt><userinput>tsql -S <replaceable>sandbox</replaceable> -U <replaceable>sa</replaceable></userinput> <prompt>Password: </prompt> <computeroutput> 1> </computeroutput> </screen> </example> <example id="e.g.tsqlhostname"> <title>Connect with <command>tsql</> using a hostname and port number</title> <screen> <prompt>$ </prompt><userinput>tsql -H <replaceable>hillary</> -p <replaceable>4100</> -U <replaceable>sa</></userinput> <prompt>Password: </prompt> <computeroutput> 1> </computeroutput> </screen> </example> <para>Another handy diagnostic feature of <command>tsql</> is that it can show you the compile-time settings of the installed version of <productname>FreeTDS</productname>: </para> <example id="e.g.tsqlShowsettings"> <title>Show compile-time settings with <command>tsql</></title> <screen> <prompt>$ </prompt><userinput>tsql -C </userinput> <prompt>Password: </prompt> <computeroutput> locale is "C" locale charset is "646" Compile-time settings (established with the "configure" script): Version: freetds v0.62.dev.20030804 MS db-lib source compatibility: no Sybase binary compatibility: unknown Thread safety: no iconv library: no TDS version: 7.0 iODBC: no unixodbc: no </computeroutput> </screen> </example> <para> For details on <command>tsql</>, see the its man page. </para> </sect2> <sect2 id="Tests"><title><application>Unit Tests</application></title> <para> The source code directory of each <productname>FreeTDS</productname> library includes a <filename>unittests</> directory. <screen> <prompt>$ </prompt><userinput>ls -d -1 src/*/unittests</userinput> <computeroutput> src/ctlib/unittests src/dblib/unittests src/odbc/unittests src/tds/unittests </computeroutput> </screen> The unit tests rely on the <filename>PWD</> file in root of the FreeTDS source tree. <filename>PWD</> holds a username, password, servername, and database to be used for the unit tests. We try to make sure to leave nothing behind: any data and objects created are either temporary or removed at the end of the test. The tests should all work, subject to disclaimers in the directory's <filename>README</>. </para> <para> To invoke the tests, edit the <filename>PWD</> file and issue the command <command>make check</command>. In order to execute all tests successfully, you must indicate a working, available dataserver in <filename>PWD</>. Some tests require permission to create stored procedures on server. </para> <para> To complete successfully, the ODBC tests require some additional setup. In your <filename>PWD</> file, add a <literal>SRV</> entry specifying the DSN entry for your <filename>odbc.ini</>. The ODBC tests all build their own <filename>odbc.ini</> and try to redirect the Driver Manager to it, however this functionality is very DM dependent and may well fail unless you have either iODBC or unixODBC. </para> <para> As of version 0.63 you may experience problems running tests under Mac OS X because the executable cannot find some library. Setting <envar>DYLD_LIBRARY_PATH</> environment variable to point to your compiler libraries usually seems to fix the problem. </para> <para> <tip><para> The <filename>PWD</> provided by <productname>FreeTDS</productname> includes usernames and passwords that probably don't exist on your server. </para></tip> </para> </sect2> </sect1> </chapter> <chapter id="PrepODBC"> <title>Preparing ODBC</title> <sect1 id="OdbcBackground"><title>Background and Terminology</title> <para> To connect to a database, a library such as <productname>FreeTDS</> needs some information about the connection. Which server, and by <emphasis>server</>, which IP address and port is do you mean? Which user is requesting the connection, and what authentication does he offer? Every database library needs a way to capture and convey that information. </para> <para> ODBC was conceived as a general interface definition, not tied to any particular database or access library. For that reason, ODBC also needs to know which driver to use with a given server. </para> <para> The original ODBC solution to this conundrum employed the <filename>odbc.ini</> file. <filename>odbc.ini</> stored information about a server, known generically as a <firstterm>Data Source Name</> (DSN). ODBC applications connected to the server by calling the function <function>SQLConnect(DSN, UID, PWD)</function>, where <replaceable>DSN</> is the Data Source Name entry in <filename>odbc.ini</>, <replaceable>UID</> is the username, and <replaceable>PWD</> the password. Any and all information about the DSN was kept in <filename>odbc.ini</>. And all was right with the world. </para> <para> The ODBC 3.0 specification introduced a new function: <function>SQLDriverConnect</>. The connection attributes are provided as a single argument, a string of concatenated name-value pairs. <function>SQLDriverConnect</> subsumed the functionality of <function>SQLConnect</>, in that the name-value pair string allowed the caller to pass — in addition the the original <literal>DSN</>, <literal>UID</>, and <literal>PWD</> — any other parameters the driver could accept. Moreover, the application can specify which driver to use. In effect, it became possible to specify the entire set of DSN properties as parameters to <function>SQLDriverConnect</>, obviating the need for <filename>odbc.ini</>. This led to the use of the so-called <firstterm>DSN-less</> configuration, a setup with no <filename>odbc.ini</>. </para> <para> But <productname>FreeTDS</> did not start out as an ODBC driver (remember db-lib and ct-lib), and has always had its own way to store server properties: <filename>freetds.conf</>. When Brian added the <productname>FreeTDS</> ODBC driver, he began by supporting the old <function>SQLConnect</>, using <filename>odbc.ini</> to describe the DSN. That choice complied with the expectations of the Driver Managers, and minimized the amount of duplicated information in the configuration files. But it can be a little confusing, too, because <filename>odbc.ini</> in effect points to <filename>freetds.conf</>. We call this configuration <firstterm>ODBC-combined</>, because it supports all three <productname>FreeTDS</> libraries. </para> <para> With version 0.60, the <productname>FreeTDS</> ODBC library started to see a fuller implementation. The driver was changed to be able to read the connection attributes directly from <filename>odbc.ini</>, rather than leaning on <filename>freetds.conf</>. For installations that don't need db-lib and ct-lib, this <firstterm>ODBC-only</> setup is simpler. </para> <para> More recently, <function>SQLDriverConnect</> was added to <productname>FreeTDS</>. As described above, this function allows the application to specify connection attributes with reference to either, or neither, configuration file. It's your choice. In making that choice, keep the following terms clear in your mind: </para> <variablelist><title>Important <productname>FreeTDS</> ODBC terms</title> <varlistentry> <term><literal>SERVERNAME</></term> <listitem> <para>specifies the <literal>[<replaceable>dataserver</>]</literal> entry in <filename>freetds.conf</>. </para> </listitem> </varlistentry> <varlistentry> <term><literal>SERVER</></term> <listitem> <para>specifies the real server i.e., the TCP/IP name of the machine hosting the database server. </para> </listitem> </varlistentry> <varlistentry> <term><literal>DSN</></term> <term><literal>Driver</></term> <listitem> <para>In your connection string, you can decide to use a DSN entry in <filename>odbc.ini</> using the <literal>DSN</> attribute, or to specify the driver you want with the <literal>Driver</> attribute.</para> </listitem> </varlistentry> </variablelist> <para> In sum, <productname>FreeTDS</productname> supports three ODBC three choices: </para> <variablelist id="tab.ODBC.configuration.choices"><title>ODBC configuration choices</title> <varlistentry> <term>DSN-less</term> <listitem> <para><emphasis>No</> connection information is specified in <filename>odbc.ini</>. Advantageous if you're using more of <productname>FreeTDS</> than just the ODBC driver. </para> </listitem> </varlistentry> <varlistentry> <term>ODBC-only</term> <listitem> <para><emphasis>All</> connection information is specified in <filename>odbc.ini</>, without the need for <filename>freetds.conf</>. This is the <quote>traditional</> ODBC setup. </para> </listitem> </varlistentry> <varlistentry> <term>ODBC-combined</term> <listitem> <para>Connection information maintained in <filename>freetds.conf</>. <filename>odbc.ini</> contains DSN entries that refer to dataserver names in <filename>freetds.conf</>. </para> </listitem> </varlistentry> </variablelist> </sect1> <sect1 id="OdbcConnAttr"><title>Connection attributes</title> <para> The following table defines all possible ODBC connection attributes for the <productname>FreeTDS</> ODBC driver. Which ones you'll need depends on how you set yourself up. They may appear in your connection string, or in <filename>odbc.ini</>, as indicated in the final column. </para> <para> <table id="tab.Connection.attributes"><title>Connection attributes</title> <tgroup cols="4"> <thead> <row> <entry>Name</entry> <entry>Meaning</entry> <entry>Possible Values</entry> <entry>Default</entry> <entry>In <filename>odbc.ini</></entry> </row> </thead> <tbody> <row> <entry><literal>DSN</></entry> <entry>Use DSN. <productname>FreeTDS</> will search <filename>odbc.ini</> for entry. It lets you specify a connection like <function>SQLConnect</>, but using <function>SQLDriverConnect</>. Do not use <literal>Servername</> and <literal>DSN</> together. Can be specified only in a connection string, not in <filename>odbc.ini</>. </entry> <entry>A valid DSN entry</entry> <entry>none</entry> <entry>no</entry> </row> <row> <entry><literal>Servername</></entry> <entry>A <filename>freetds.conf</> servername, not a hostname as known to DNS. If you want to use ODBC-only configuration, use <literal>Server</> instead.</entry> <entry>A valid <filename>freetds.conf</> server section</entry> <entry>none</entry> <entry>yes</entry> </row> <row> <entry><literal>Server</></entry> <entry>Hostname of a server. Used in an ODBC-only configuration. As of version 0.64 you can specify a Microsoft SQL Server instance in the form of <literal>server\instance</literal>. This isn't <emphasis>required</> to connect to an instance, and is in fact slightly slower to set up the conncection, because it entails an extra round trip to the server. To avoid that, ask to your administrator for the port number of each instance, and create separate server entries for each one. </entry> <entry>A server name or (ip) address</entry> <entry>none</entry> <entry>yes</entry> </row> <row> <entry><literal>Port</></entry> <entry>The TCP port where the dataserver is listening. </entry> <entry>Any TCP port</entry> <entry>Depends on the TDS version specified with <command>configure</></entry> <entry>yes</entry> </row> <row> <entry><literal>UID</></entry> <entry>Can be specified only for a DSN-less connection. (For security reasons, do not store username/password in a configuration file). To use domain authentication, specify the domain using the format <replaceable>domain\password</replaceable>.</entry> <entry>Any valid username</entry> <entry>none</entry> <entry>no</entry> </row> <row> <entry><literal>PWD</></entry> <entry>Can be specified only for a DSN-less connection. (For security reasons, do not store username/password in a configuration file). Clear text password (use domain password for domain authentication).</entry> <entry>Any</entry> <entry>empty</entry> <entry>no</entry> </row> <row> <entry><literal>TDS_Version</></entry> <entry>TDS protocol version to use (e.g., 5.0, 7.0).</entry> <entry>Any valid protocol version</entry> <entry>Depends on the TDS version specified with <command>configure</></entry> <entry>yes</entry> </row> <row> <entry><literal>APP</></entry> <entry>Application name. Identifies the connecting application to the server. </entry> <entry>Free form text, up to 30 characters. </entry> <entry>none</entry> <entry>yes</entry> </row> <row> <entry><literal>WSID</></entry> <entry>Name of the local computer, sent to server. Can be specified only for a DSN-less connection.</entry> <entry>Any</entry> <entry>Computer name</entry> <entry>no</entry> </row> <row> <entry><literal>LANGUAGE</></entry> <entry>(Human) language the server should use for error messages.</entry> <entry>Any</entry> <entry>us_english</entry> <entry>yes</entry> </row> <row> <entry><literal>Address</></entry> <entry>IP address of the dataserver. Useful if you want to specify a server by address, rather than by name. The format is <replaceable>ip,port</> or simply <replaceable>ip</> in standard dotted-decimal notation. </entry> <entry>Any</entry> <entry>none</entry> <entry>yes</entry> </row> <row> <entry><literal>Database</></entry> <entry>Specify which database you want to access. If database do not exists or you haven't permission to access it, the connection will fail.</entry> <entry>Any</entry> <entry>none</entry> <entry>yes</entry> </row> <row> <entry><literal>TextSize</></entry> <entry>Maximum size returned from server for blobs.</entry> <entry>Any</entry> <entry>DB dependent</entry> <entry>yes</entry> </row> <row> <entry><literal>PacketSize</></entry> <entry>Size of packets to server. Some users saw some performance gain by increasing this value. Normally you shouldn't set it. </entry> <entry>Any</entry> <entry>DB dependent</entry> <entry>yes</entry> </row> </tbody> </tgroup> </table> </para> </sect1> <sect1 id="dsnless"><title>DSN-less configuration</title> <para> In a DSN-less configuration, the <filename>odbc.ini</filename> file is not consulted for server connection properties. To connect to a dataserver, your application may refer to a dataserver entry in <filename>freetds.conf</>, or explicitly specify the dataserver's hostname (bypassing <filename>freetds.conf</>). <example id="e.g.SampleDSNless"><title>Sample files for a DSN-less configuration</title> <para>The <filename>odbcinst.ini</filename> is quite brief: </para> <blockquote> <programlisting> ; ; odbcinst.ini ; [FreeTDS] Driver = /usr/local/freetds/lib/libtdsodbc.so </programlisting> </blockquote> <para>The <filename>freetds.conf</> might look something like:</para> <blockquote> <programlisting> ; ; freetds.conf ; [JDBC] host = jdbc.sybase.com port = 4444 tds version = 5.0 </programlisting> </blockquote> </example> <example id="e.g.ConnectDSNless"><title>Connecting with a DSN-less configuration</title> <programlisting> /* * application call */ const char servername[] = "JDBC"; <footnote><para>refers to the <literal>[JDBC]</> entry in <filename>freetds.conf</>.</para></footnote> sprintf(tmp, "DRIVER=FreeTDS<footnote><para>refers to the <literal>[FreeTDS]</> entry in <filename>odbcinst.ini</>.</para></footnote>;SERVERNAME=%s;UID=%s;PWD=%s;DATABASE=%s;", servername, username, password, dbname); res = SQLDriverConnect(Connection, NULL, (SQLCHAR *) tmp, SQL_NTS, (SQLCHAR *) tmp, sizeof(tmp), &len, SQL_DRIVER_NOPROMPT); if (!SQL_SUCCEEDED(res)) { printf("Unable to open data source (ret=%d)\n", res); exit(1); } </programlisting> </example> You can even establish a connection without reference to either <filename>odbc.ini</filename> or <filename>freetd.conf</filename>. <example id="e.g.ConnectDSNlessnoconf"><title>Connecting with a DSN-less configuration that does not use <filename>freetds.conf</filename></title> <programlisting> /* * application call */ const char servername[] = "jdbc.sybase.com"; <footnote><para>refers to the real server name.</para></footnote> sprintf(tmp, "DRIVER=FreeTDS<footnote><para>refers to the <literal>[FreeTDS]</> entry in <filename>odbcinst.ini</>.</para></footnote>;SERVER=%s;UID=%s;PWD=%s;DATABASE=%s;TDS_Version=5.0;Port=4444;", servername, username, password, dbname); res = SQLDriverConnect(Connection, NULL, (SQLCHAR *) tmp, SQL_NTS, (SQLCHAR *) tmp, sizeof(tmp), &len, SQL_DRIVER_NOPROMPT); if (!SQL_SUCCEEDED(res)) { printf("Unable to open data source (ret=%d)\n", res); exit(1); } </programlisting> </example> </para> </sect1> <sect1 id="odbcinionly"><title>ODBC-only configuration</title> <para> An ODBC-only configuration relies solely on <filename>odbc.ini</> for server properties. Other <productname>FreeTDS</productname> drivers don't know about <filename>odbc.ini</>. <example id="e.g.SampleODBConly"><title>Sample ODBC-only <filename>odbc.ini</filename> file</title> <programlisting> [ODBC Data Sources]<footnote><para>Several DSNs might be listed here. In this example, we have only one, <quote>JDBC</>. It matches the <literal>[JDBC]</> entry later in the file. </para></footnote> JDBC = Sybase JDBC Server [JDBC] Driver = /usr/local/freetds/lib/libtdsodbc.so Description = Sybase JDBC Server Trace = No Server = jdbc.sybase.com Database = pubs2 Port = 4444 TDS_Version = 5.0 [Default] Driver = /usr/local/freetds/lib/libtdsodbc.so </programlisting> </example> </para> </sect1> <sect1 id="odbcombo"><title>ODBC-combined configuration</title> <para> Like the DSN-less configuration, ODBC-combined keeps server properties in <filename>freetds.conf</>. The difference is that your applications can refer to the server by its DSN. To make that possible, the DSN entry in <filename>odbc.ini</> refers to the dataserver entry in <filename>freetds.conf</>. <example id="e.g.SampleODBCcombo"><title>Sample ODBC-combined <filename>odbc.ini</filename> file</title> <programlisting> [ODBC Data Sources]<footnote><para>Several DSNs might be listed here. In this example, we have only one, <quote>JDBCdsn</>. It matches the <literal>[JDBCdsn]</> entry later in the file. </para></footnote> JDBCdsn = Sybase JDBC Server [JDBCdsn] Driver = /usr/local/freetds/lib/libtdsodbc.so Description = Sybase JDBC Server Trace = No Servername = JDBC<footnote><para>Refers to the <literal>[JDBC]</> entry in <filename>freetds.conf</>. </para></footnote> Database = pubs2 [Default] Driver = /usr/local/freetds/lib/libtdsodbc.so </programlisting> </example> <example id="e.g.samplecombofile"><title>Sample ODBC-combined <filename>freetds.conf</filename> file</title> <programlisting> ; ; freetds.conf ; [JDBC] host = jdbc.sybase.com port = 4444 tds version = 5.0 </programlisting> </example> </para> <para> With this arrangement, an application can connect to the server in two ways, via its DSN (<literal>JDBCdsn</>), or its dataserver name (<literal>JDBC</>). </para> </sect1> <sect1 id="odbcdiagnose"><title>Troubleshooting ODBC connections</title> <para> Supposing everything compiles and installs without trouble, how do you know if your ODBC setup works? Or, if you know it doesn't, what then? </para> <para> First, try to connect with <command>tsql</>. If you're intending to use <filename>freetds.conf</>, exercise it with <command>tsql -S <replaceable>servername</></command>. If not, use <command>tsql -H <replaceable>hostname</> -p <replaceable>port</></command> </para> <para> If <command>tsql</> works and <command>isql</> doesn't, you've isolated the problem to the ODBC setup. <productname>FreeTDS</productname> might have some interoperability problems, but mere connection to the database isn't one of them! If <command>tsql</> doesn't work, turn on logging with <envar>TDSDUMP</>. The log will tell you what TCP/IP name (and address) <productname>FreeTDS</> is attempting to connect to, and what version of the TDS protocol it's using. </para> <sect2 id="with.iodbc"><title>With iODBC</title> <para> <productname>iODBC</productname> comes with a sample command line query program called <command>odbctest</> that is located in the <filename>iodbc/samples</filename> directory. Using this program you can get a listing of DSNs, connect, and issue queries. It is often useful to compile a program such as this directly against the <productname>FreeTDS</productname> driver instead of using a driver manager. This makes it simpler to debug if something goes wrong. To do so, simply compile and install the <systemitem class="library">ODBC</systemitem> driver with <productname>iODBC</productname> as normal <footnote><para>When compiling directly to <productname>FreeTDS</productname> you still need the Driver Manager's header files.</para></footnote>, then compile and link the program directly: <example id="e.g.odbctest.nodm"> <title>Compile <filename>odbctest</> without a driver manager.</title> <screen> <prompt>$ </prompt><userinput>make odbctest.o</userinput> <prompt>$ </prompt><userinput>gcc -g -o odbctest odbctest.o /usr/local/freetds/lib/libtdsodbc.a</userinput> </screen> </example> The <option>-g</> is important to keep the symbol tables for debugging purposes. Now you can run <command>gdb</> or another debugger and set breakpoints on functions in the library without the driver manager getting in the way. </para> </sect2> <sect2 id="with.unixODBC"><title>With unixODBC</title> <para> Try <command>isql -v <replaceable>dsn</> <replaceable>username</> <replaceable>password</></command>, and have a look at the log. See if the right address and TDS version are being used. Adjust to taste. </para> </sect2> </sect1> </chapter> <chapter id="configs"> <title>Advanced Configurations</title> <para> This chapter details some advanced configurations that need expanded explanation. </para> <sect1 id="emulle"> <title>Big Endian Clients with Buggy <productname>SQL Server</productname>s</title> <para> Several version of Microsoft SQL server have a bug that affects big endian clients. This includes 7.0 GA and 7.0 SP1. Furthermore, <acronym>TDS</> Protocol version 7.0 is natively little endian. <productname>SQL Server 2000</productname> is also reported not to work from big endian clients without little endian emulation turned on. </para> <Note><para>If you are unfamiliar with the terms <emphasis>big endian</emphasis> and <emphasis>little endian</emphasis>, they are terms that come originally from Gullivers Travels. What they refer to in computer science is the the order in which bytes are stored by a processor. Big endian machines such as Sparc and PowerPC store the most significant byte in the first memory location of a multi-byte integer. Little endian machines such as Intel and Alpha do it the other way around. So the 16-bit number 258 would be 0x0102 on big endian and 0x0201 on little endian machines.</para></Note> <para> In this example we want to force connections to a server named <literal>mssql</literal> to emulate a little endian client. We are using protocol version 4.2 here, version 7.0 and 8.0 will automatically emulate little endian mode regardless of the <filename>freetds.conf</filename> setting. <emphasis>You shouldn't use this option, set another protocol version instead (7.0 or 8.0)</emphasis>. </para> <example id="e.g.LittleEndian"> <title>Emulate Little Endian <filename>freetds.conf</filename> setting</title> <programlisting> [mssql] host = ntbox.mydomain.com port = 1433 tds version = 4.2 emulate little endian = yes </programlisting> </example> </sect1> <sect1 id="Nonwestern"> <title><acronym>TDS</> 7.0 for Nonwestern Languages</title> <para> <acronym>TDS</> 7.0 uses 2-byte Unicode (technically, <acronym>UCS-2</>) to transfer character data between servers and clients. Included in <quote>character data</quote> are query text (i.e., <acronym>SQL</>), metadata (table names and such), and <foreignphrase>bona fide</> data of datatypes <literal>nchar</>, <literal>nvarchar</>, and <literal>ntext</>. </para> <para> Since most Unix tools and languages do not support <acronym>UCS-2</>, <productname>FreeTDS</productname> allows conversion by the client to other character sets using the <ulink url="http://www.opengroup.org/onlinepubs/7908799/xsh/iconv.html">iconv</ulink> standard. Background information on Unicode and how it affects <productname>FreeTDS</productname> can be found in the <link linkend="Unicode">appendix</link>. If no iconv library is found, or if it is explicitly disabled, <productname>FreeTDS</productname> will use its built-in iconv substitute, and will be capable of converting between only <acronym>ISO-8859-1</> and <acronym>UCS-2</>. </para> <para> To learn what character set the client is using, <productname>FreeTDS</productname> examines the <link linkend="clientcharset"><filename>freetds.conf</></link> entry. If it finds nothing there, it assumes the client is using <acronym>ISO-8859-1</>. That is generally a safe assumption for western languages such as English or French, but produces garbage for other languages. </para> <para> To list all supported iconv character sets try <command>iconv</>(1). GNU's does: </para> <screen> <prompt>$ </><userinput>iconv --list</userinput> </screen> <para> For other systems, consult your documentation (most likely <command>man iconv</command> will give you some hints). </para> <para> In this example a server named <literal>mssql</literal> will return data encoded in the GREEK character set. </para> <example id="e.g.GREEK"> <title>Configuring for GREEK <filename>freetds.conf</filename> setting</title> <programlisting> [mssql] host = ntbox.mydomain.com port = 1433 tds version = 7.0 client charset = GREEK </programlisting> </example> <para> If <productname>FreeTDS</productname> runs into a character it can not convert, its behavior varies according to the severity of the problem. On retrieving data from the server, <productname>FreeTDS</productname> substitutes an <acronym>ASCII</> '?' in the character's place, and emits a warning message stating that some characters could not be converted. On sending data to the server, <productname>FreeTDS</productname> aborts the query and emits an error message. It is well to ensure that the data contained in the database is representable in the client's character set.</para> <para> If you have a mix of character data that can not be contained in a single byte character set, you may wish to use <acronym>UTF-8</>. <acronym>UTF-8</> is a variable length unicode encoding that is compatible with <acronym>ASCII</> in the range 0 to 127. With <acronym>UTF-8</>, you are guaranteed to never have an unconvertible character.</para> <Important><para><productname>FreeTDS</productname> is not fully compatible with multi-byte character sets such as <acronym>UCS-2</>. You must use an ASCII-extension charset (e.g., UTF-8, ISO-8859-*)<footnote><para>not EBCDIC or other weird charsets</para></footnote>. Extreme care should be taken with testing applications using these encodings. Specifically, many applications do not expect the number of characters returned to exceed the column size (in bytes). On the other hand, support of <acronym>UTF-8</> and <acronym>UCS-2</> is a high priority for the developers. Patches and bug reports in this area are especially welcome. </para></Important> <para> In the following example, a server named <literal>mssql</literal> will return data encoded in the <acronym>UTF-8</> character set. </para> <example id="e.g.UTF8"> <title>Configuring for <acronym>UTF-8</> <filename>freetds.conf</filename> setting</title> <programlisting> [mssql] host = ntbox.mydomain.com port = 1433 tds version = 7.0 client charset = UTF-8 </programlisting> </example> <para> It is also worth clarifying that <acronym>TDS 7.0</> and above do not accept any specified character set during login, as 4.2 does. A <acronym>TDS 7.0</> login packet uses <acronym>UCS-2</>. </para> </sect1> <sect1 id="domains"> <title>Domain Logins</title> <Note><para>Domain logins can be used only with TDS protocol versions 7.0 and 8.0.</para></Note> <para> As mentioned in the installation chapter, <productname>Microsoft SQL Server</productname> includes the ability to use domain logins instead of standard server logins. The advantage of doing this is that the passwords are encrypted on the wire using a challenge-response protocol. <productname>FreeTDS</productname> began supporting domain logins in version 0.60. </para> <para> To use domain logins, use the <literal>'DOMAIN\username'</> syntax for the username and use the domain password. </para> <example id="e.g.domainlogin"><title>Logging in with a domain login</title> <screen> <computeroutput>$ </computeroutput><userinput>tsql -S camelot -U 'NOTTINGHAM\lancelot' -P roundtable</userinput> locale is "C" locale charset is "646" Msg 5703, Level 0, State 1, Server CPRO200, Line 0 Changed language setting to middle_english. 1> </screen> </example> <para> When <productname>FreeTDS</productname> sees the <quote><literal>\</></quote> character, it automatically chooses a domain login. </para> <Note><para>The term <firstterm>domain</> in this context is a Microsoft term. It refers to what's sometimes called an <firstterm>NT domain</firstterm>. It's unrelated to the DNS domain. DNS domains are used for name resolution. NT domains are used for authentication. Authentication is done by the domain controller, often the <firstterm>Primary Domain Controller</firstterm> (PDC). </para><para> The SQL Server machine may belong to an NT domain. <productname>FreeTDS</productname> provides an encrypted password — a domain password, known to the domain controller — that the server will ask the domain controller to verify. </para></Note> <sect2 id="domaindetails"> <title>Implementation details</title> <para> Support for domain logins in <productname>FreeTDS</productname> is limited to the TCP/IP network protocol stack. <productname>FreeTDS</productname> does not currently implement support for Named Pipe-based SQL connections — that is, connections transported over the DCE/RPC interface, which uses TCP port 139, 445, or 135 on Win32 machines depending on the type of encapsulation used for DCE/RPC itself. Supporting this would require a fairly extensive DCE/RPC library for Unix. <productname>Samba</productname> has one that is licensed under the GPL and therefore not usable by LGPL-licenced projects such as <productname>FreeTDS</productname> . </para> <para> Your domain controller must allow authentication over TCP/IP, or you will be unable to log in. One symptom of a server that requires Named Pipes for authentication is an error message such as: </para> <para> <informalexample><screen><computeroutput> Login failed for user '(null)'. Reason: Not associated with a trusted SQL Server connection. </computeroutput></screen></informalexample> </para> <para> The telltale sign being <literal>user '(null)'</>. </para> <para> If you suspect a problem along these lines, you could ask your friendly system administrator to check the following setting: <programlisting> Computer Configuration \Windows Settings \Security Settings \Local Policies \Security Options \LAN Manager Authentication Level </programlisting> The setting should be <quote><literal>Send LM & NTLM responses</></quote>. </para> <para> For a technical description of the protocol used for domain logins, see <ulink url="http://davenport.sourceforge.net/ntlm.html">http://davenport.sourceforge.net/ntlm.html</ulink> </para> </sect2> </sect1> <sect1 id="appendmode"> <title>Appending Dump Files</title> <para> When running <productname>FreeTDS</productname> with applications such as <productname>Apache</productname>/PHP it is often difficult to get a usable log file. Since each of the many httpd children opens the file at the beginning of its connection and closes it on connection close, they tend to stomp all over each other. In append mode, the log file is opened for append each time it is written to and then immediately closed. If you are experiencing problems when running under <productname>Apache</productname> (or similar application) use append mode to generate useful logs. </para> <example id="e.g.DumpAppend"> <title>Turning on Dump File Append mode in <filename>freetds.conf</filename></title> <programlisting> [mssql] host = ntbox.mydomain.com port = 1433 tds version = 7.0 dump file = /tmp/freetds.log dump file append = yes </programlisting> </example> <para> In this example, the <filename>/tmp/freetds.log</filename> file will contain log entries for all processes using the Microsoft <productname>SQL Server</productname> server, identified by pid. </para> <Important><para> Because there will be one log file being opened and closed more or less continuously, there is going to be a negative impact on performance. Also, be advised that the log file will grow quite large. </para></Important> <para> As an alternative to <productname>FreeTDS</productname> logging, you might also consider using <application>tcpdump</application> or <application>ethereal</application> to log network packets. While not as useful as a <acronym>TDS</> log, it can also help to identify problems. </para> </sect1> <sect1 id="tdspool"> <title>TDS Connection Pooling</title> <para> The <productname>FreeTDS</productname> connection pool is a server process, it acts just like a <productname>SQL Server</productname>. You can use any program to attach to it that you could use to attach to a real <productname>SQL Server</productname>. The pool in turn connects to the <productname>SQL Server</productname> and database you specify, and attempts to share these connections. See the <filename>README</filename> in the pool directory for a more detailed description of its inner workings. </para> <para> To configure the pooling server, first make sure <productname>FreeTDS</productname> has a working entry for the real <productname>SQL Server</productname> by connecting to it with <application>SQSH</application> or another program. </para> <Note><para> The <productname>FreeTDS</productname> connection pool currently only supports <acronym>TDS</> version 4.2. <emphasis>This restriction applies to both the client-to-pool and pool-to-server connections!</emphasis> </para></Note> <para> After FreeTDS has been installed, you will find an executable named <command>tdspool</command> in the <filename>/usr/local/bin</filename> directory (or whatever directory you specified if <command>configure</> was run using the <option>--with-prefix flag</>). </para> <para> Next, edit the <filename>pool.conf</filename> file in the <productname>FreeTDS</productname>'s <filename>etc</filename> directory. The <filename>pool.conf</filename> file is formatted like the <filename>freetds.conf</filename> with a section name in brackets and options for each section in key/value pairs. </para> <para> Just like the <filename>freetds.conf</filename> file there are two types of sections, a <literal>[global]</literal> section whose options affect all pools, and a section with the name of the pool for pool-specific options. The following options are supported and may appear in either section. </para> <para> <table id="tab.pool.conf"> <title>pool.conf settings</title> <tgroup cols="4"> <thead> <row> <entry>Name</entry> <entry>Default</entry> <entry>Meaning</entry> <entry>Possible Values</entry> </row> </thead> <tbody> <row> <entry>user</entry> <entry>none</entry> <entry>The username used to connect to the dataserver.</entry> <entry>Any valid user</entry> </row> <row> <entry>password</entry> <entry>none</entry> <entry>The password of the user at the dataserver.</entry> <entry>Any</entry> </row> <row> <entry>server</entry> <entry>none</entry> <entry>The alias from the freetds.conf file representing the dataserver that will be connected to.</entry> <entry>Any <emphasis>TDS 4.2</emphasis>entry in the freetds.conf file</entry> </row> <row> <entry>database</entry> <entry>User's default database</entry> <entry>The database on the dataserver to use.</entry> <entry>Any valid database</entry> </row> <row> <entry>port</entry> <entry>none</entry> <entry>Port on which tdspool will listen.</entry> <entry>Any TCP port</entry> </row> <row> <entry>min pool conn</entry> <entry>none</entry> <entry>Minimum number of open connections to maintain to the dataserver.</entry> <entry>1 or more</entry> </row> <row> <entry>max pool conn</entry> <entry>none</entry> <entry>Maximum number of open connections to open against the dataserver.</entry> <entry>1 or more</entry> </row> <row> <entry>max member age</entry> <entry>0</entry> <entry>Maximum age of idle members before connection is closed.</entry> <entry>0 (no limit) or a number of seconds</entry> </row> </tbody> </tgroup> </table> </para> <para> Now, let's put this into practice. <example id="e.g.pool.conf"> <title>pool.conf</title> <programlisting> [global] min pool conn = 5 max pool conn = 10 max member age = 120 [mypool] user = webuser password = secret database = ebiz server = fooserv max pool conn = 7 port = 5000 </programlisting> </example> The <literal>[global]</literal> section defines that we will open 5 connections against the server initially, and will increase up to 10 as demand requires. These connections will be closed after being idle for 2 minutes (120 seconds), but only until there are 5 remaining open. </para> <para> The <literal>[mypool]</literal> section defines a pool named <literal>mypool</literal> that will listen on port 5000. It will login to a <productname>SQL Server</productname> named <literal>fooserv</literal> using the user <literal>webuser</literal> and the ever so clever password of <literal>secret</literal>. Once logged in, the connections will use the database <literal>ebiz</literal> instead of webuser's default database. Also, since this <productname>SQL Server</productname> has a limited number of <acronym>CAL</>s (Client Access Licenses), we are restricting the maximum number of connections to 7, which overrides the <literal>global</literal> setting of 10. </para> <para> Now you can run <Command>tdspool</Command> with the name of the pool you are serving. <screen> <prompt>$ </prompt><userinput> tdspool mypool</userinput> </screen> </para> <para> Before your clients connect to the pool, you must edit your <filename>freetds.conf</filename> to include the host and port of the pooling server, and point your clients at it! </para> </sect1> <sect1 id="stunnel"> <title>stunnel HOWTO</title> <para> Contributed by <ulink url="mailto:bradleyb@u.washington.edu">Bradley Bell</ulink>. </para> <para> To set up freetds over stunnel between a Linux webserver and a W2k SQL server: </para> <orderedlist> <listitem> <para>Get unencrypted freetds working</para></listitem> <listitem> <para>Install openssl and stunnel on the Linux box: <ulink url="http://www.stunnel.org/">stunnel.org</ulink> </para></listitem> <listitem> <para>Download the <ulink url="http://www.stunnel.org/download/binaries.html">stunnel binary</ulink> and openssl dll's for Windows. </para></listitem> <listitem> <para>Generate stunnel.pem (complete with Diffie-Hellman parameters) for placement on the W2k box. See <ulink url="http://www.stunnel.org/faq/certs.html">instructions</ulink> in the stunnel FAQ. </para></listitem> <listitem> <para>Start stunnel on the W2k box:</para> <screen> <prompt>$ </prompt><userinput>stunnel.exe -d 61666 -r localhost:1433</userinput> </screen> <para>61666 is just an arbitrary port number. </para></listitem> <listitem> <para>Start stunnel on the Linux box: </para> <screen> <prompt>$ </prompt><userinput>stunnel -c -d 1433 -r <replaceable>win2kserver</replaceable>:61666</userinput> </screen> <para>where <replaceable>win2kserver</replaceable> is the hostname or IP address of the W2k box. </para></listitem> <listitem> <para>Set up freetds to use the tunnel. If this is your unencrypted entry in <filename>freetds.conf</filename>: </para> <example id="e.g.Unencrypted"> <title>Unencrypted entry in <filename>freetds.conf</filename></title> <programlisting> [win2kserver] host = win2kserver port = 1433 </programlisting> </example> <para> the encrypted equivalent uses: </para> <example id="e.g.Encrypted"> <title>Encrypted entry in <filename>freetds.conf</filename></title> <programlisting> [win2kserver] host = localhost port = 1433 </programlisting> </example> </listitem> </orderedlist> </sect1> </chapter> <!-- ////////////////// CHAPTER /////////////////////// --> <chapter id="software"> <title>How to get what works with it working</title> <para> The following programs are known to work to some extent with <productname>FreeTDS</productname>. Here you will find any special instructions for getting them compiled or running. </para> <sect1 id="sqsh"> <title><application>SQSH</application></title> <para> <application>SQSH</application> is a command line based query tool written by Scott Gray to replace the <command>isql</> utility that ships with <productname>Sybase ASE</productname>. It makes a great diagnostic tool for <productname>FreeTDS</productname> as well. If you are having trouble, install <application>SQSH</application> (it's easy) and try getting that to work before more complicated arrangements. <tip><sidebar><para>That advice is so good, it bears repeating. If you are having trouble, grab <application>SQSH</application> and get that to work. Not only will it help isolate the problem, it will give you a very capable tool. </para></sidebar></tip> </para> <para> <application>SQSH</application> 2.1 includes direct support for <productname>FreeTDS</productname>, so these instructions may not be necessary, but are still included just in case. </para> <para> After running <Command>configure</Command> in <application>SQSH</application>'s directory (make sure you set the Sybase environment variable first), look for the Sybase_LIBS definition in the Makefile. Change the line to match this example. <example id="e.g.SQSHmake"> <title>The <application>SQSH</application> Makefile</title> <programlisting> # # The following set of CT-LIB libraries were determined automatically # by 'configure'. For most systems configure looks up the required # libraries by looking at the name of the OS (although this doesn't # mean it got them right), however if the line below ends with the # word "Guess", then 'configure' didn't have an entry for your operating # system and it took a best guess to figure out which libraries you # need. In either case, there may be problems, so look this line over # and if it doesn't work, compare it to the libraries located in # $SYBASE/samples/ct-library. # # The listings below show suggested libraries for Operating Systems # that frequently fail to be recognized by 'configure': # # SCO: -lblk -lct -lcs -lcomn -ltcl -ltli -lnsl_s -lintl -m -lsocket # Dynix: -lblk -lct -lcs -lcomn -ltcl -ltli -lnsl -lintl -lm -lseq # SYBASE_LIBS = -lct -ldl -lm </programlisting> </example> At this point you can also enable <application>readline</application> support if you didn't specify it in the <application>configure</application> arguments. </para> <para> After that just type <command>make</command> and you are off and running. </para> <para> The <productname>FreeTDS</productname> maintainer has commit rights to the <application>sqsh</application> source tree. If you have problems getting <application>sqsh</application> to work with <productname>FreeTDS</productname>, you may wish to send your patches to the <productname>FreeTDS</productname> mailing list. </para> </sect1> <sect1 id="perl"> <title>Perl</title> <para>There are a few ways to use <productname>Perl</productname> to connect to a <productname>SQL Server</productname> using <productname>FreeTDS</productname>. </para> <sect2 id="DBD.Sybase"><title>DBD::Sybase</title> <para>The recommended choice is <systemitem class="library">DBD::Sybase</systemitem> from Michael Peppler. Despite the name it works for any Sybase or Microsoft <productname>SQL Server</productname>. <systemitem class="library">DBD::Sybase</systemitem> uses the <systemitem class="library">ct-lib</systemitem> <acronym>API</> and works well. </para> </sect2> <sect2 id="DBD.ODBC"><title>DBD::ODBC</title> <para> You may also use <systemitem class="library">DBD::ODBC</systemitem> with the <productname>FreeTDS</productname> <systemitem class="library">ODBC</systemitem> driver. You may find this attractive if you're familiar with <systemitem class="library">DBD::ODBC</systemitem>. </para> </sect2> <sect2 id="Sybperl"><title>Sybperl</title> <para> Finally, you can use <systemitem class="library">Sybperl</systemitem>. Scripts written against <systemitem class="library">Sybperl</systemitem> will not run against other databases the way DBI scripts will. However, it will be familiar ground for those who know <systemitem class="library">db-lib</systemitem>. </para> </sect2> <sect2 id="Perlmodules"><title>Building and using the Perl modules</title> <para> <example id="e.g.DBD.Sybase.build"> <title>Building <systemitem class="library">DBD::Sybase</systemitem></title> <screen> <prompt>$ </prompt><userinput>cd DBD-Sybase-0.91</userinput> <prompt>$ </prompt><userinput>export SYBASE=/usr/local/freetds</userinput> <prompt>$ </prompt><userinput>perl Makefile.PL</userinput> <prompt>$ </prompt><userinput>make</userinput> <prompt>$ </prompt><userinput>su root</userinput> <prompt>Password: </prompt> <prompt>$ </prompt><userinput>make install</userinput> </screen> </example> There will be some output about missing libraries after <userinput>perl Makefile.PL</userinput>. These are normal. </para> <para> The following example will attach to Sybase's public <acronym>JDBC</> server and run a simple query (it can be found in <filename>samples/test.pl</filename>): <example id="e.g.DBD.Sybase.Connect"><title>Connect to a server with <systemitem class="library">DBD::Sybase</systemitem></title> <programlisting> #!/usr/local/bin/perl # use DBI; my $dbh = DBI->connect("dbi:Sybase:server=JDBC", 'guest', 'sybase', {PrintError => 0}); die "Unable for connect to server $DBI::errstr" unless $dbh; my $rc; my $sth; $sth = $dbh->prepare("select \@\@servername"); if($sth->execute) { while(@dat = $sth->fetchrow) { print "@dat\n"; } } </programlisting> </example> </para> <para> <example id="e.g.DBD.ODBC.build"> <title>Building <systemitem class="library">DBD::ODBC</systemitem></title> <screen> <prompt>$ </prompt><userinput>cd DBD-ODBC-0.28</userinput> <prompt>$ </prompt><userinput>export SYBASE=/usr/local/freetds</userinput> <prompt>$ </prompt><userinput>export ODBCHOME=/usr/local</userinput> <prompt>$ </prompt><userinput>export DBI_DSN=dbi:ODBC:JDBC</userinput> <prompt>$ </prompt><userinput>export DBI_USER=guest</userinput> <prompt>$ </prompt><userinput>export DBI_PASS=sybase</userinput> <prompt>$ </prompt><userinput>perl Makefile.PL</userinput> <prompt>$ </prompt><userinput>make</userinput> <prompt>$ </prompt><userinput>su root</userinput> <prompt>Password: </prompt> <prompt>$ </prompt><userinput>make install</userinput> </screen> </example> <note><para>We used the public <acronym>JDBC</> server logins for our configuration here. You'll want to replace these with ones suitable to your environment.</para></note> </para> <para> <example id="e.g.DBD.ODBC.connect"><title>Connect to a server with <systemitem class="library">DBD::ODBC</systemitem></title> <programlisting> #!/usr/local/bin/perl # use DBI; my $dbh = DBI->connect("dbi:ODBC:JDBC", 'guest', 'sybase', {PrintError => 0}); die "Unable for connect to server $DBI::errstr" unless $dbh; my $rc; my $sth; $sth = $dbh->prepare("select \@\@servername"); if($sth->execute) { while(@dat = $sth->fetchrow) { print "@dat\n"; } } </programlisting> </example> You'll note this is the same program as for <systemitem class="library">DBD::Sybase</systemitem> with the exception of the <function>connect</function> statement, welcome to the magic of DBI! </para> </sect2> </sect1> <sect1 id="php"> <title>PHP</title> <para> There are three options for building PHP with support for <productname>FreeTDS</productname> corresponding to the three <acronym>API</>s that <productname>FreeTDS</productname> supports: <systemitem class="library">db-lib</systemitem>, <systemitem class="library">ct-lib</systemitem>, and <systemitem class="library">ODBC</systemitem>. <note><para>All these examples build the CGI version. Consult <ulink url="http://www.php.net/docs.php">PHP's documentation</ulink> for building the Apache module and including other extensions.</para></note> </para> <sect2 id="phpDblib"> <title><systemitem class="library">db-lib</systemitem></title> <para> PHP can be configured with <systemitem class="library">db-lib</systemitem> access for a "Sybase" server (which also works with Microsoft servers), or with the <emphasis>mssql</> extension, intended exclusively for Microsoft servers. At one time, some source code tweaking was required to build PHP with both <systemitem class="library">db-lib</systemitem> and DBM support, but <productname>FreeTDS</productname> has handled that automatically since version 0.53. </para> <para> <example id="e.g.PHP.dblib"><title>PHP and <systemitem class="library">db-lib</systemitem> for <quote>Sybase</></title> <para>First build <productname>FreeTDS</productname> normally.</para> <screen> <prompt>$ </prompt><userinput>./configure --prefix=/usr/local/freetds</userinput> <prompt>$ </prompt><userinput>make</userinput> <prompt>$ </prompt><userinput>su root</userinput> <prompt>Password: </prompt> <prompt>$ </prompt><userinput>make install</userinput> </screen> <para>Then build PHP with support for <quote>Sybase</quote></para> <screen> <prompt>$ </prompt><userinput>cd php</userinput> <prompt>$ </prompt><userinput>./configure --with-sybase=/usr/local/freetds</userinput> <prompt>$ </prompt><userinput>make</userinput> <prompt>$ </prompt><userinput>su root</userinput> <prompt>Password: </prompt> <prompt>$ </prompt><userinput>make install</userinput> </screen> <para>And that's it!</para> </example> </para> </sect2> <sect2 id="ctlib"> <title><systemitem class="library">ct-lib</systemitem></title> <para> Option 2 is to use the <systemitem class="library">ct-lib</systemitem> <acronym>API</>. Again here, we run into minor difficulties at build time. Applications linking with Sybase's OpenClient have to link in a handful of libraries and these libraries vary slightly from platform to platform. When creating <productname>FreeTDS</productname> it was decided that there would be only one library: <filename>libct</filename>. This saves a great deal of library naming conflicts that Sybase ran into (e.g. <filename>libtcl</filename> is used both by Sybase and the language TCL), however some applications like PHP assume that all the Sybase libraries will be present. So, some hand editing of the Makefile is necessary to remove these extra libs. Build <productname>FreeTDS</productname> just as you would for <systemitem class="library">db-lib</systemitem> in <link linkend="phpDblib"> with <systemitem class="library">db-lib</systemitem></link>, above. Then configure PHP with <systemitem class="library">ct-lib</systemitem>. <screen> <prompt>$ </prompt><userinput>cd php</userinput> <prompt>$ </prompt><userinput>./configure --with-sybase-ct=/usr/local/freetds</userinput> </screen> Now edit the <filename>Zend/Makefile</filename> looking for the <literal>libZend_la_LDFLAGS</literal> line and remove <literal>-lsybtcl -lintl -lcomn</literal> and <literal>-lcs</literal>, leaving the <literal>-lct</literal>. Then proceed to make and install PHP. <screen> <prompt>$ </prompt><userinput>make</userinput> <prompt>$ </prompt><userinput>su root</userinput> <prompt>Password: </prompt> <prompt>$ </prompt><userinput>make install</userinput> </screen> We hope an upcoming version of PHP will automatically detect the presence of <productname>FreeTDS</productname> and include only the <literal>-lct</literal> library. </para> </sect2> <sect2 id="ODBC"> <title><systemitem class="library">ODBC</systemitem></title> <para> The third and newest option is to use the <productname>FreeTDS</productname> <systemitem class="library">ODBC</systemitem> driver with PHP. First build the <productname>iODBC</productname> or <productname>unixODBC</productname> driver manager and <productname>FreeTDS</productname> as detailed <link linkend="prepodbc">in this guide</link>. Then build PHP with support for ODBC. <screen> <prompt>$ </prompt><userinput>cd php</userinput> <prompt>$ </prompt><userinput>./configure --with-iodbc=/usr/local</userinput> <prompt>$ </prompt><userinput>make</userinput> <prompt>$ </prompt><userinput>su root</userinput> <prompt>Password: </prompt> <prompt>$ </prompt><userinput>make install</userinput> </screen> Now everything should run. There is a sample PHP script in the <productname>FreeTDS</productname> samples directory called <filename>odbctest.php</filename>. </para> </sect2> </sect1> <sect1 id="SybSQL"> <title>SybSQL</title> <para> <productname>SybSQL</productname> is a <productname>Qt</productname>-based <acronym>GUI</> interface to <productname>Sybase</productname> databases that uses the <systemitem class="library">db-lib</systemitem> <acronym>API</>. </para> <para> <productname>SybSQL</productname> has a fairly basic build process that simply uses a Makefile. In order for <productname>SybSQL</productname> to find <productname>Qt</productname> and <productname>FreeTDS</productname> you need to define <envar>QTDIR</envar> and <envar>SYBASE</envar> environment variables. If you have <productname>Qt</productname> installed, you may have <envar>QTDIR</envar> defined already. To verify, type <command>echo $QTDIR</command> at the shell prompt. This example uses my own installation path of <filename>qt-2.3.1</filename> (from RedHat 7.2), YMMV. <screen> <prompt>$ </prompt><userinput>export QTDIR=/usr/lib/qt-2.3.1</userinput> <prompt>$ </prompt><userinput>export SYBASE=/usr/local</userinput> <prompt>$ </prompt><userinput>make</userinput> </screen> When finished you'll have an executable named <filename>sybsql</filename> that you can run. </para> <para> One caveat to the way in which <productname>SybSQL</productname> and <productname>FreeTDS</productname> interact is that <productname>SybSQL</productname> expects to be running under <productname>OpenClient</productname>, and makes the assumption that a valid <envar>$SYBASE</envar><filename>/interfaces</filename> file exists. Since <productname>FreeTDS</productname> has deprecated use of the <filename>interfaces</filename> file in favor of the <filename>freetds.conf</filename> config file, a slight work around is required. </para> <para> In <productname>FreeTDS</productname>'s <filename>bin</filename> directory, there is a script, <filename>conf2interfaces</filename>, to convert the <filename>freetds.conf</filename> file back into an <filename>interfaces</filename> file. Running this, you may convert your <filename>freetds.conf</filename> into a old-style <filename>interfaces</filename> file to make <productname>SybSQL</productname> happy. For instance, <screen> <prompt>$ </prompt><userinput>mkdir ~/freetds</userinput> <prompt>$ </prompt><userinput>conf2interfaces /usr/local/etc/freetds.conf > ~/freetds/interfaces</userinput> <prompt>$ </prompt><userinput>export SYBASE=~/freetds</userinput> <prompt>$ </prompt><userinput>sybsql</userinput> </screen> By defining <envar>SYBASE</envar> to the parent directory of the <filename>interfaces</filename> file, you may put it where ever you like; it does not have to be in <filename>/usr/local</filename>. When using <filename>freetds.conf</filename>, <productname>FreeTDS</productname> does not rely on the <envar>SYBASE</envar> variable for finding its own components, so it is safe to point it elsewhere. </para> </sect1> <sect1 id="Python"> <title>Python</title> <tip><para> I am not a Python user myself, so the information contained in this section is a little rough. Please contact the list for more assistance or (better yet) to improve these instructions. </para></tip> <para> Install <ulink url="http://www.python.org/sigs/distutils-sig/">distutils</ulink> if you haven't already. <screen> <prompt>$ </prompt><userinput>tar xvfz distutils-latest.tgz</userinput> <prompt>$ </prompt><userinput>cd distutils</userinput> <prompt>$ </prompt><userinput>python setup.py install</userinput> </screen> </para> <para> You can obtain the <productname>Python</productname> Sybase module <ulink url="http://object-craft.com.au/projects/sybase/download.html">here</ulink>. This example uses version 0.34, the most current at the time of this writing, please adjust accordingly if using a different version. <screen> <prompt>$ </prompt><userinput>tar xvfz sybase-0.34.tgz</userinput> <prompt>$ </prompt><userinput>cd sybase-0.34</userinput> <prompt>$ </prompt><userinput>export SYBASE=/usr/local/freetds</userinput> <prompt>$ </prompt><userinput>export CFLAGS="-DHAVE_FREETDS"</userinput> <prompt>$ </prompt><userinput>export LD_LIBRARY_PATH=/usr/local/freetds/lib:${LD_LIBRARY_PATH}</userinput> <prompt>$ </prompt><userinput>python setup.py install</userinput> </screen> Edit the example.py and fix the bottom stuff, freetds lacks the 110 symbols for version use 100 <screen> <prompt>$ </prompt><userinput>python example.py</userinput> </screen> </para> </sect1> </chapter> <!-- ////////////////// CHAPTER /////////////////////// --> <chapter id="troubleshooting"> <title>Troubleshooting</title> <epigraph> <attribution>Jason Mewes (Mall Rats)</attribution> <para>He's like motherf**king McGuiver, no he's better than McGuiver!</para> </epigraph> <sect1 id="knownissues"> <title>Known Issues</title> <sect2 id="Textfields"> <title><type>Text</type> Fields</title> <para> Questions sometimes arise over large <type>varchar</type> types (anything larger than <type>varchar(255)</type>) that became available with Microsoft <productname>SQL Server 7.0</productname>. When accessing long <type>varchar</type>s with <acronym>TDS</> protocol version 4.2 or 5.0, these fields will be truncated to 255 characters, due to limitations inherent in the protocol definition. Your best bet in that case is to convert them to <type>text</type> types. </para> <para> In Microsoft <productname>SQL Server</productname> 7.0 and later, <structname>varchar</structname> types can hold up to 8000 bytes (8000 <acronym>ASCII</> characters or 4000 Unicode characters). To move these large <structname>varchar</structname>s through <acronym>TDS</> 4.2, convert them with either a <command>CONVERT</command> as in, <screen> <userinput>SELECT mycol = convert(mycol, text) FROM mytable</userinput> </screen> or with the newer SQL92 <command>CAST</command> syntax e.g., <screen> <userinput>SELECT CAST(mycol as TEXT) FROM mytable</userinput></screen> </para> <para> A related problem is that some people have reported problems with <type>text</type> field using <acronym>TDS</> version 7.0. One known workaround is to convert long strings to <type>varchar(8000)</type> in your query text with <command>CAST( <parameter>variable_name</parameter> as <type>varchar</type>(8000) ) as <parameter>variable_name</parameter></command>. Text datatype handling is fixed in <productname>FreeTDS</productname> 0.60, except for bcp operations. </para> <para> There is also a bug (<quote>Lions and tigers and bugs! Oh, my!</quote>) in Microsoft's implementation of <type>text</type> fields. Disregardless [sic] of their documentation, you must explicitly set the value of <envar>TEXTSIZE</envar>, else the text fields will be represented to have a maximum size of 4 gigabytes or so. The usual manifestation is some sort of spurious <quote>out of memory</quote> error or segment fault. To avoid this, set <envar>TEXTSIZE</envar> to some reasonable value before querying any <type>TEXT</type> fields. For example, in <application>isql</application>: <screen> <prompt>1></prompt><userinput>set <envar>TEXTSIZE</envar> 10000</userinput> <prompt>2></prompt><userinput>go</userinput> </screen> Another way to handle control the default <envar>TEXTSIZE</envar> is to use the setting in <link linkend="freetdsconfformat"><filename>freetds.conf</filename></link>. </para> </sect2> <sect2 id="Endianism"> <title>Endianism</title> <para> If either your server or your client is a big endian system, pay careful attention to all references to endianism anywhere near <productname>FreeTDS</productname>. See the section on <link linkend="emulle">Little Endian Emulation</link> for details. </para> </sect2> <sect2 id="Datetime"> <title><type>Datetime</type> and <type>Money</type></title> <para> Big endian clients may experience difficulty with Microsoft servers. Some versions of <productname>SQL Server</productname> 7 did not handle these types on these machines correctly, according to the protocol. According to <ulink url="http://support.microsoft.com/support/kb/articles/Q254/1/23.ASP"> http://support.microsoft.com/support/kb/articles/Q254/1/23.ASP</ulink> on the Microsoft support site, it's fixed as of service pack 3. Unfortunately, there's no direct way for <productname>FreeTDS</productname> to know whether or not a service pack has been installed, and how/whether to support the buggy version is an outstanding issue. Your best bet is to apply their patch. <note><para>The Knowledge Base article states <quote>The Sybase CT-Lib client is the only known big-endian client that can connect to <productname>SQL Server</productname>.</quote> Depends on who's doing the knowing, of course. </para></note> </para> </sect2> <sect2 id="IntegratedSecurity"> <title>Microsoft's <quote>Integrated Security</quote></title> <para> <productname>FreeTDS</productname> may be unable to connect to the server. The error message that appears will be <computeroutput>"Login failed for user 'example'. Reason: Not associated with a trusted SQL Server connection"</computeroutput>. To solve this, turn on <productname>SQL Server</productname> authentication: </para> <ItemizedList> <listitem><para> Open the <emphasis><productname>SQL Server</productname> Enterprise Manager</emphasis>, </para></listitem> <listitem><para> Select the server, </para></listitem> <listitem><para> Right mouse click and choose <emphasis>Properties</emphasis>. A properties window will appear. </para></listitem> <listitem><para> Choose the <emphasis>Security</emphasis> tab. The security properties will be displayed. </para></listitem> <listitem><para> Change the <emphasis>Authentication</emphasis> field to <emphasis><productname>SQL Server</productname> and Windows</emphasis>, </para></listitem> <listitem><para> Apply the changes and try again. </para></listitem> </ItemizedList> <para> These instructions apply to Microsoft <productname>SQL Server 7</productname> and <productname>SQL Server 2000</productname>. </para> <sect3 id="Background"> <title><productname>SQL Server</productname>'s Security Model</title> <para> Microsoft supports two security models in three permutations: <ItemizedList> <listitem><para><firstterm>Windows NT Authentication Mode</>. The operating system performs authentication; users will <emphasis>not</emphasis> have explicit <productname>SQL Server</productname> accounts. </para></listitem> <listitem><para><firstterm>Standard Mode</>. <productname>SQL Server</productname> authenticates connections itself without consulting the operating system. Users of course need <productname>SQL Server</productname> accounts to log in. </para></listitem> <listitem><para><firstterm>Mixed Mode</> Combines the above two. </para></listitem> </ItemizedList> For normal operation, you need either Standard or Mixed mode. </para> <para> <quote>Windows NT Authentication</quote>, often called <quote>integrated security</quote>, relies on Microsoft's <emphasis>domain login</emphasis>. In it, a user's network security attributes are established at network login time. When connecting to the database server, <productname>SQL Server</productname> uses the facilities of the host operating system (<productname>Windows NT </productname> or similar) to determine the authenticated network username. <productname>SQL Server</productname> then permits or denies login access based on that network username alone, without requiring a separate login name and password. </para> <Note><para> The <productname>FreeTDS</productname> supports integrated security mode. If you have <productname>SQL Server</productname> running in integrated (domain) mode along with a Windows PDC, and wish to try it, see <link linkend="domains">Domain Logins</link> in the <link linkend="configs">Advanced Configurations</link> chapter. </para></Note> <para> <productname>FreeTDS</productname> supports the traditional database security model, which Microsoft terms <quote>SQL Server Authentication</quote> but is frequently known as <quote>standard security</quote>. Username+Password pairs have to be passed to the server explicitly. </para> <para> Mixed Mode allows users to connect using either authentication method. Users who connect through a <productname>Windows NT</productname> account can make use of trusted connections in either Windows NT Authentication Mode or Mixed Mode. After successful connection to <productname>SQL Server</productname>, the security mechanism is the same for both modes. </para> </sect3> </sect2> </sect1> <sect1 id="serverthere"> <title>Is the server there?</title> <sect2 id="serverthere.ping"> <title>Start with <command>ping</></title> <para> First <command>ping</> the host to make sure you can talk to the machine the server resides on. <example id="e.g.troubleshooting.ping"> <title>Finding the server's host</title> <screen> <prompt>$ </prompt><userinput>ping -c1 <replaceable>myhost</replaceable></userinput> <computeroutput> PING myhost (127.0.0.1) from 127.0.0.1 : 56(84) bytes of data. 64 bytes from myhost (127.0.0.1): icmp_seq=0 ttl=255 time=250 usec </computeroutput> </screen> </example> A successful ping shows that your network isn't preventing you from reaching the machine hosting the server. </para> </sect2> <sect2 id="serverthere.telnet"> <title>Test with <command>telnet</></title> <para> Attempt to <command>telnet</> to the port, to verify that the dataserver is listening. <example id="e.g.troubleshooting.telnet"> <title>Finding the server</title> <screen> <prompt>$ </prompt><userinput>telnet <replaceable>myhost 1433</></userinput> <computeroutput> Trying 127.0.0.1... Connected to myhost. Escape character is '^]'. </computeroutput> </screen> </example> If you get output as above, the dataserver is listening. If you get a 'Connection Refused' message, you're talking to the wrong host, wrong port, or the dataserver is down. <footnote><para>To exit <command>telnet</>: When connected, telnet's command mode may be entered by typing the telnet <firstterm>escape character</firstterm> (initially <keysym>Ctrl</keysym>-<keysym>]</keysym>, as above). Once in command mode, <command>telnet</> may be exited with the command <command>quit</>. </para></footnote> </para> </sect2> <sect2 id="serverthere.tsql"> <title>Test with <command>tsql</></title> <para> <command>tsql</> can be run in two ways, one which uses <filename>freetds.conf</> and one which connects directly using the host and port. First attempt a connection using host and port. <example id="e.g.troubleshooting.tsql.noconf"> <title>Connecting to the server, bypassing <filename>freetds.conf</></title> <screen> <prompt>$ </prompt><userinput>cd src/apps</userinput> <prompt>$ </prompt><userinput>./tsql -H <replaceable>myhost</> -p <replaceable>1433</> -U <replaceable>user</></userinput> </screen> </example> If you receive a message of 'Login Failed.' then your connectivity is OK, but you have a authentication issue. </para> <para> If you receive a message like <screen> <computeroutput> Msg. No.: 18450 Severity: 14 State: 1 Login failed- User: loginid Reason: Not defined as a valid user of a trusted SQL Server connection </computeroutput> </screen> <productname>SQL Server</productname> is accepting only <quote>domain</quote> logins. This applies only to Microsoft <productname>SQL Server</productname> and you'll need to have your DBA verify that <quote>server logins</quote> are allowed, or use a <link linkend="domains">domain login</link>. </para> <para> Finally, if you received a prompt, then try <command>tsql</> using the dataserver name. <example id="e.g.troubleshooting.tsql"> <title>Connecting to the server using <filename>freetds.conf</></title> <screen> <prompt>$ </prompt><userinput>./tsql -S <replaceable>myserver</> -U <replaceable>user</></userinput> </screen> </example> If this fails, FreeTDS is either not finding your <filename>freetds.conf</filename> file, finding the wrong one, or there is an error in the file. </para> </sect2> </sect1> <sect1 id="Logging"> <title>Logging</title> <para> <productname>FreeTDS</productname> has quite extensive logging capabilities. These are often invaluable in setting up new configurations, when it's hard to be sure precisely what configuration information is being used, and what communication is (not) working. Often such questions can be quickly resolved by turning on logging and examining the logs. </para> <sect2 id="Environment"><title>Environment Variables that Control Logging</title> <variablelist id="tab.Logging.control.envar"> <varlistentry> <term id="TDSDUMP"><envar>TDSDUMP</envar></term> <listitem> <para>Log files can be turned on using the <envar>TDSDUMP</envar> environment variable. For instance, setting the location of a dumpfile <screen> <prompt>$ </prompt><userinput>export TDSDUMP=/tmp/freetds.log</userinput> </screen> Will generate a log file named <filename>freetds.log</filename> in the <filename>/tmp</filename> directory. </para> </listitem> </varlistentry> <varlistentry> <term><envar>TDSDUMPCONFIG</envar></term> <listitem> <para>Set <envar>TDSDUMPCONFIG</envar> to a file to write information to on how the configuration information is being obtained, e.g. from environment variables, a <filename>freetds.conf</filename> file, or <filename>interfaces</filename> file. Sometimes it's unclear what source of information <productname>FreeTDS</productname> is using to connect to a given dataserver. This variable can make that bright and clear. </para> <para>If set to the null string, the log file name will default to <filename>/tmp/tdsconfig.log.<replaceable>9999</replaceable></filename>, where <replaceable>9999</replaceable> is the pid of the process generating the log. </para> </listitem> </varlistentry> </variablelist> <tip><para> What if you were running <productname>Apache</productname>/PHP? <productname>Apache</productname> has many children. Setting the <envar>TDSDUMP</envar> variable to a null string will cause <productname>FreeTDS</productname> to open a log under every PID. <screen> <prompt>$ </prompt><userinput>export TDSDUMP=""</userinput> </screen> The log files will be named <filename>/tmp/freetds.log.<replaceable>9999</replaceable></filename>, where <replaceable>9999</replaceable> is the pid number of the process generating the log. </para></tip> <para> A couple of important notes about using the logs with <productname>FreeTDS</productname>. First, the logs tend to grow large, so trim or archive them often. Secondly, <productname>FreeTDS</productname> will record certain network packets to the log, this <emphasis>includes login packets which can contain clear text or clear text equivalent passwords.</emphasis> So, if this is a concern (most likely is) make sure that the files are not world readable, and avoid posting them to mailing lists. </para> <para> Once in a while, someone writes to the mailing list, asking why <productname>FreeTDS</productname> is so <emphasis>slow</>. It sometimes turns out that logging was left turned on. Don't you be the next victim! <productname>FreeTDS</productname> logs are meant for development and debugging, not as a system monitoring tool. </para> </sect2> <sect2 id="Logging.freetds.conf"> <title><filename>freetds.conf</filename> variables that Control Logging</title> <para> See <link linkend="tab.freetds.conf.debugflags">Valid bitmask values for <literal>debug flags</> entry in <filename>freetds.conf</filename></link> </para> </sect2> <sect2 id="Logging.odbc"> <title>Logging in ODBC land</title> <subtitle>(Tree-huggers need not worry)</subtitle> <para> Many ODBC Driver Managers have their own support for logging. How logging is controlled, however, varies widely by implementation. The ODBC log is often very helpful because it provides a log of all calls made directly by the application. </para> <variablelist> <varlistentry> <term>unixODBC</term> <listitem> <para>unixODBC supports logging via some entries in <filename>odbcinst.ini</filename>. For example: <screen> [ODBC] Trace = Yes TraceFile = /tmp/sql.log ForceTrace = Yes </screen> Will generate a log file named <filename>sql.log</filename> in the <filename>/tmp</filename> directory. </para> </listitem> </varlistentry> </variablelist> </sect2> </sect1> <sect1 id="pagenodata"> <title>"Page contains no data"</title> <para> Web browsers display this error when the underlying script didn't return any information. The error could be in any of several places, of which <productname>FreeTDS</productname> is one. To isolate the cause, turn on enough logs to see the query, and execute the query through <application>SQSH</application>. If that works, the problem lies further up the chain. If it doesn't, take a look at the <link linkend="knownissues">known issues</link> section. </para> <para> <productname>FreeTDS</productname> under PHP executing within an <productname>Apache</productname> process may abort with a segmentation fault. The evidence of this is the words "Segmentation Fault" or "Bus Error" in the <productname>Apache</productname> error log, and a "Page contains no data" warning displayed by the web browser. The unexpected termination of the process causes the connection to the client to be closed before any buffered data is sent. </para> <para> To diagnose this sort of problem, follow this procedure; </para> <itemizedlist mark=opencircle> <listitem><para>Compile PHP as a CGI binary.</para> <para>This should have been a side-effect of your build of PHP, look for an executable called php in the PHP build tree. If you are using a packaged binary, look for a php-cgi package.</para> </listitem> <listitem><para>Make a reproducer.</para> <para>Make a PHP script that reliably reproduces the segmentation fault via the web server, but with no arguments. This is so that you can execute it using the PHP binary, thus excluding the web server as the cause of the problem.</para> </listitem> <listitem><para>Reproduce on command line.</para> <para>Reproduce the segmentation fault using PHP on the command line, by activating PHP with the script as first argument. For example;</para> <screen> <prompt>% </prompt><userinput>php file.php</userinput> <prompt>Segmentation fault</prompt> <prompt>% </prompt> </screen> <para>If this doesn't reproduce the segmentation fault, then there is something about the environment that differs, so look for the differences and resolve them. Check environment variables, assumptions made by the script, the UID you are executing under, and the current working directory.</para> </listitem> <listitem><para>Reproduce using GDB.</para> <para>Now reproduce the segmentation fault using the debugger, GDB. Instead of aborting to the command line, GDB will stop executing the PHP program at the point of failure. Use the <command>bt</command> command to determine the details and context. This is called a backtrace.</para> <screen> <prompt>% </prompt><userinput>gdb php</userinput> <prompt>gdb> </prompt><userinput>run file.php</userinput> <prompt>gdb> </prompt><userinput>bt</userinput> </screen> </listitem> <listitem><para>Analyse the backtrace.</para> <para>Read the backtrace to determine what the cause of the problem is. Examine each line, assigning responsibility by component; some code is PHP, some is <productname>FreeTDS</productname>, and some may be glibc. You will need the source code for each component, and software engineering debugging skills.</para> <para>If you cannot determine the cause yourself, send the backtrace to the <link linkend="mailinglist">mailing list</link>, along with the PHP script. It helps to make the script as small as possible, but still fail. It also helps to report the version numbers of PHP, and <productname>FreeTDS</productname>.</para> </listitem> </itemizedlist> </sect1> <sect1 id="seemtooslow"> <title>Slow connection or data retrieval</title> <para> <productname>FreeTDS</productname> is <emphasis>not</> slow. We know this because we've tested it. It's measurably slower than the vendors' products for some operations, but it's not noticeably slower and it's certainly no laggard. If your experience is different, if you're waiting 30 seconds for simple operations or minutes instead of seconds for for query results, something is up with your setup. There are two likely culprits. </para> <itemizedlist mark='bullet'> <listitem> <para>Logging. If everything seems a bit sluggish, check to make sure logging is turned off. <envar>TDSDUMP</> should not be defined, and there should be no <literal>dump file</> mentioned in <filename>freetds.conf</>. You can double-check by setting <envar>TDSDUMPCONFIG</> temporarily, which will log only the startup process. </para> </listitem> <listitem> <para>DNS. If connecting to the server takes 30 seconds or 1 minute, you could do worse than to check your <filename>resolv.conf</>. Use <command>host</> or <command>nslookup</> to confirm that <productname>FreeTDS</productname> can actually resolve the name/address you provided in <filename>freetds.conf</>. Give particular attention to reverse DNS lookups, if you were forced (or thought you were forced) to identify the server by number, instead of by name, as Vint intended. You can defeat <productname>FreeTDS</productname>'s automatic reverse-DNS lookup feature by inserting <programlisting> #define NOREVERSELOOKUPS </programlisting> in <filename>src/tds/config.c</>, rebuilding, and reinstalling. <Note><para> Reverse lookup code has been removed as of version 0.62 due to wrong implementation.</para></Note> </para> </listitem> </itemizedlist> </sect1> </chapter> <chapter id="help"> <title>Getting Help</title> <epigraph> <attribution>Beatles</> <para><literallayout> Help me if you can, I'm feeling down And I do appreciate you being 'round. Help me get my feet back on the ground, Won't you please, please help me? </literallayout></para> </epigraph> <para>In the battle against frustration and wasted motion, this manual is our first defense. Our documentation is intended to make it possible for a knowlegable user to, well, <emphasis>use</> <productname>FreeTDS</productname> without further assistance. We strive to include all known features and behaviors here, so you can work quickly and anonymously, and go home before 5:00. Would that it were always thus. </para> <sect1 id="IsolateCause"><title>Isolate the cause</title> <para> Successful problem isolation will yield earliest resolution. You (believe it or not) have more information about your environment than anyone else does, and have the greatest motivation to solve your problem. The resources at your disposal will be much more useful if the problem is specific. (Sorry if this is obvious. If it is, you might be surprised how often it's not.) </para> <para> If you can demonstrate the problem with <command>tsql</> or <command>sqsh</>, you can expect a quick answer to your question, possibly even a fairly quick fix. (It has happened several times in the last few years that bug reports to small problems were fixed the same day. On a few occasions, new functions were added in a few days. Making <productname>FreeTDS</productname> useful and bugless is the goal of the project, after all.) </para> <para> <productname>FreeTDS</productname> being what it is, problems frequently arise amidst complex environments. It can be hard for both you and the list participants — who are your allies and best resource — to determine what's going wrong. If you can submit a script that they can use to try to reproduce your results, you have a much better chance of happy resolution. </para> <para> On the plus side, the list includes people with a variety of backgrounds, who frequently answer questions that aren't really about <productname>FreeTDS</productname> <foreignphrase>per se</foreignphrase>. Clear questions have sometimes even led to submitting patches to other projects. </para> </sect1> <sect1 id="MailingList"><title>The Mailing List</title> <epigraph> <attribution>3 Henry VI, I, ii, approximately</> <para><literallayout> In them I trust; for they are [hackers] Witty, courteous, liberal, full of spirit. </literallayout></para> </epigraph> <sect2 id="Archive"><title>The Archive</title> <para>The <productname>FreeTDS</productname> mailing list <ulink url="http://lists.ibiblio.org/pipermail/freetds/">archive</ulink> is a good place to start. It is searchable. It should be considered the most up to date (and least edited) source of information. </para> <para>New developments between releases tend <emphasis>not</> to be announced on the website. The website is updated only intermittently, when we post a new release or <productname>FreeTDS</productname> is somehow in the news, say. If you found a bug or need a feature, you may find it was announced/discussed/fixed by perusing the archive. </para> </sect2> <sect2 id="Asklist"> <title>Ask the list</title> <para> Many of the original authors and anyone maintaining or extending the code reads the list. The traffic tends to be bursty. It usually focuses on build problems and troubleshooting. Again, the more specific your question, the sooner you'll get a useful reply (if it comes). </para> <para> Please, do not email the authors directly. You may well be ignored because they're they type that gets a ton of mail. Anyone willing to address your question reads the list, and you don't want to offend anyone willing to help you by going about it the wrong way. </para> </sect2> </sect1> <sect1 id="askingforhelp"><title>What to include when asking for help</title> <sect2 id="Waddyagot"><title>Waddya got?</title> <para>It's important to convey your setup and configuration. <simplelist type='vert' columns='1'> <member><productname>SQL Server</productname> version</member> <member><productname>FreeTDS</productname> version (or snapshot date, if not a release)</member> <member>which client library you are using</member> <member>what language or Perl module, as appropriate, you're using</member> <member>your client OS and hardware architecture</member> </simplelist> </para> </sect2> <sect2 id="Happened"><title>What Happened?</title> <para>If you're puzzled by some interaction with the server (often the case), it's a very good idea to set <envar>TDSDUMP</> and attach the log to your message. Messages are currently limited to 75 KB attachments, and the logs are quite detailed, so make your query as short as possible. If necessary, trim the log; <command>gzip</> is also your friend here. It's always a good idea to post it on a website where people can fetch it if they're so inclined. </para> <para>Think about it this way: If you attach a log no one reads, you wasted some bandwidth. If you don't attach one and someone asks you for it, you wasted a day. Like that. </para> </sect2> <sect2 id="HelptheHelp"><title>Help the Help</title> <para>If you've found an error, weakness, misbehavior, discrepancy, call-it-what-you-will in one of the published <acronym>API</>s, it's very helpful if you write a unit test for it, and tell us what the Microsoft or Sybase behavior is. Those problems get <emphasis>fixed</>. Oftentimes, right away. Everyone who's sent us a unit test has gotten their feature in the next release. If you don't, you'll at least get an explanation. </para> <para> Moving down, Perl or PHP code provided it creates all the tables it needs and populates them will generally result in a quick fix. A stand-alone query that will run in <application>SQSH</application> also works well. Here again, it helps to attach a log. <tip><para>If you provide an SQL query in your question to the list, provide a table definition, too. Problems are often related to specific datatypes, so a table definition is an absolute must. You can run <command>sp_help <parameter>table</parameter></command> to generate one. </para></tip> </para> <para> It is very helpful if you can show an example of the problem using <command>sqsh</> or <command>tsql</> (the latter is included in with <productname>FreeTDS</productname>). Using those programs limits the scope of question to <productname>FreeTDS</productname> itself. </para> <para>If the problem is a segmentation fault or bus error, that's bad. Please obtain a backtrace and include it in your mail. See the <link linkend="pagenodata">"Page contains no data"</link> section for how to do this.</para> </sect2> </sect1> </chapter> <!-- ////////////////// CHAPTER /////////////////////// --> <chapter id="contrib"> <title>Helping</title> <epigraph> <attribution>Bertrand Russell</> <para> The time you enjoy wasting is not wasted time. </para> </epigraph> <para> <productname>FreeTDS</productname> is a cooperative, volunteer effort. Flame wars on the list are unknown and the signal to noise ratio is pretty high for its venue. Many people have contributed patches, and few have been turned away. </para> <sect1 id="Pickweakspot"> <title>Pick a weak spot and fix it.</title> <para> <ItemizedList> <listitem> <para>We don't have enough non-English speakers to test our character set conversion features. Anyone willing to participate in that way would be most welcome. </para> </listitem> <listitem> <para>Canonical examples of using the each library would be very helpful to newcomers. </para> </listitem> <listitem> <para>An isql for db-lib, odbc, Perl, and PHP would all make debugging and testing easier for everyone. </para> </listitem> </ItemizedList> </para> <sect2 id="Sendpatch"> <title>Send a patch</title> <para> Good patches are nearly always applied in short order. Patches uploaded to <ulink url="http://sourceforge.net/tracker/?group_id=33106&atid=407808">SourceForge</ulink> trigger automatic notification to the <productname>FreeTDS</productname> mailing list. </para> </sect2> <sect2 id="Correct"> <title>Correct this User Guide</title> <para> Any corrections or suggestions, be they typographical, grammatical, structural, factual, or mineral are most welcome. Please send it to <ulink url="mailto:jklowden@speakeasy.org"><productname>FreeTDS</productname> FAQ Master</ulink>, or post a message to the list. </para> <para> The User Guide is maintained in SGML DocBook format; the file in your distibution is <filename>doc/userguide.sgml</>. It is a flat ASCII file that you can edit with any text editor. You don't have to know SGML to correct or add to the User Guide, however. Just open it up, find the place you're interested in, and type away. Do a <command>diff -u <replaceable>old_version</> <replaceable>your_version</></command> and post your patch to the SourceForge site. Any errors or lackings in your markup will be graciously emended by yours truly. </para> </sect2> <sect2 id="Documentapi"> <title>Document an <acronym>API</></title> <para> We have just begun an independent reference manual to <productname>FreeTDS</productname>; the main <acronym>API</> documents are the work of the server vendors. We're using <ulink url="http://www.stack.nl/~dimitri/doxygen/">Doxygen</>, which extracts documentation directly from comments in the source code, and we're maybe 25% done. </para> <para> The <acronym>TDS</> protocol is partly documented, as are the <acronym>API</> to <filename>libtds</filename> and <systemitem class="library">db-lib</>, but much remains. </para> </sect2> <sect2 id="FAQ"> <title>Add to the FAQ</title> <para> The <productname>FreeTDS</productname> FAQ Master is <ulink url="mailto:jklowden@speakeasy.org">James Lowden</ulink>. Mail him your FAQ (and its answer) and see your name in lights. Please include "<productname>FreeTDS</productname> FAQ Master" in the subject. </para> </sect2> </sect1> <sect1 id="Advocacy"> <title>Advocacy</title> <para> Out of ten people you know, it's a fair bet 10 never heard of <productname>FreeTDS</productname> and nine don't understand the problem it solves. Lots of places have begun to use Microsoft <productname>SQL Server</productname>s in all sorts of ways, and if you adhere to the Microsoft line, there's only one way to connect to them: from a Microsoft OS. </para> <para> What can <productname>FreeTDS</productname> do that can't be done any other way? Glad you asked. <productname>FreeTDS</productname> can </para> <ItemizedList> <listitem><para>Connect to every version of either vendor's server, using the same binaries.</para></listitem> <listitem><para>Provide a <systemitem class="library">ct-lib</systemitem> interface to Microsoft <productname>SQL Server</productname>. This feature alone allows <productname>DBD::Sybase</> and <command>sqsh</>, among others, to connect to Microsoft's product. </para></listitem> <listitem><para>Provide a bcp-capable interface and command-line utility on unix-like operating systems for Microsoft <productname>SQL Server</productname>.</para></listitem> <listitem><para>Run on many more operating systems than either vendor's libraries do.</para></listitem> <listitem><para>Get fixed, instead of telling you to get stuffed.</para></listitem> <listitem><para>Amuse and inform. Also frustrate and infuriate, but we don't put that under "Advocacy". </para></listitem> </ItemizedList> <para>If more people knew, fewer would be stuck. </para> </sect1> </chapter> <!-- ////////////////// CHAPTER /////////////////////// --> <chapter id="programming"> <title>Programming</title> <para> </para> <sect1 id="TDSprotocolref"> <title>TDS protocol reference</title> <para> Can be found on <ulink url="http://www.freetds.org/tds.html">www.freetds.org</ulink> </para> </sect1> <sect1 id="APIreference"><title>API Reference Manual</title> <para> The <ulink url="../reference/index.html">reference manual</ulink> is installed as part of <productname>FreeTDS</>. It can be regenerated at any time using <productname>Doxygen</productname> with <command>cd <filename>doc</>; make doc</command>. </para> <para> The reference manual is a work in progress: only the db-lib library is completely documented, and quite minimally at that. Should you find it inadequate, you may be interested to learn it's not hard to add to, technically. <productname>Doxygen</productname> generates a manual from encoded comments in the source code. Its markup syntax is not hard to learn. You can read more about it at the <ulink url="http://www.stack.nl/~dimitri/doxygen/">Doxygen website</>. </para> <para> Basic API coverage information for the db-lib, ct-lib, and ODBC client libraries is maintained in <filename>doc/api_status.txt</>, included in the source distribution. For your convenience and enjoyment, we include that file in the following sections. In each table, we note for the function <footnote><para>Sybase and Microsoft sometimes use slightly different names for the same function. It is the intention of the <option>--enable-msdblib</> option to align <productname>FreeTDS</> with one or the other's convention.</para></footnote> the extent to which it is implemented. The <emphasis>Status</> field may be: <variablelist id="dblib.api.status"> <title>db-lib API function status domain</title> <varlistentry> <term>(blank)</term> <listitem> <para>Function is not implemented.</para> </listitem> </varlistentry> <varlistentry> <term>stub</term> <listitem> <para>Function is implemented as a stub. Some such functions return <literal>SUCCEED</> even though they have no effect, to satisfy upper layers. </para> </listitem> </varlistentry> <varlistentry> <term>Partial</term> <listitem> <para>Function is partly implemented. We haven't dealt with every possible option, for instance. </para> </listitem> </varlistentry> <varlistentry> <term>OK</term> <listitem> <para>Function is implemented. Completely, we claim. </para> </listitem> </varlistentry> </variablelist> </para> </sect1> <sect1 id="dblib.api.summary"> <title>db-lib API Implementation Summary</title> <para>Microsoft's version of db-lib is <ulink url="http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dblibc/dbc_pdc04a_6qsl.asp">online</ulink>. Sybase's is both <ulink url="http://sybooks.sybase.com/onlinebooks/group-cn/cng1251e/dblib/@Generic__BookView">online</ulink> and can be <ulink url="http://download.sybase.com/pdfdocs/cng1250j/dblib.pdf">downloaded</ulink> as a PDF file. <footnote><para>Links such as these are quite perishable. Should you find them broken, please check the <ulink url="http://www.freetds.org/userguide/dblib.api.summary.htm">FreeTDS User Guide</ulink> posted on our website. If it's out of date, please let us know, so we can correct it. Thanks. </para></footnote></para> &dblibapisgml; </sect1> <sect1 id="ctlib.api.summary"> <title>ct-lib API Implementation Summary</title> <para>Sybase ct-lib documentation can be found <ulink url="http://sybooks.sybase.com/onlinebooks/group-cn/cng1251e/ctref/@Generic__BookView">online</ulink> and in <ulink url="http://download.sybase.com/pdfdocs/cng1000e/ref.pdf">PDF</ulink> form. <footnote><para>Links such as these are quite perishable. Should you find them broken, please check the <ulink url="http://www.freetds.org/userguide/ctlib.api.summary.htm">FreeTDS User Guide</ulink> posted on our website. If it's out of date, please let us know, so we can correct it. Thanks. </para></footnote> </para> &ctlibapisgml; </sect1> <sect1 id="odbc.api.summary"> <title>ODBC API Implementation Summary</title> <para>The functions are linked to the reference page on Microsoft's website. <footnote><para>Links such as these are quite perishable. Should you find them broken, please check the <ulink url="http://www.freetds.org/userguide/odbc.api.summary.htm">FreeTDS User Guide</ulink> posted on our website. If it's out of date, please let us know, so we can correct it. Thanks. </para></footnote></para> &odbcapisgml; </sect1> <sect1 id="samplecode"> <title>Examples [future reference]</title> <para> (this isn't a reference manual) </para> <simplelist> <member>TDS</> <member><systemitem class="library">db-lib</systemitem></> <member>bcp</> <member><systemitem class="library">ct-lib</systemitem></> <member><systemitem class="library">ODBC</systemitem></> </simplelist> </sect1> </chapter> <!-- ////////////////// CHAPTER /////////////////////// --> <chapter id="acknowledgments"> <title>Acknowledgments</title> <sect1 id="Codesmyths"> <title>Codesmyths</title> <para>Many people, too many to mention, have contributed patches and located bugs. The primary names are: </para> <simplelist columns=2> <member> <ulink url="mailto:camber@ais.org">Brian Bruns</ulink> (camber@ais.org)</member> <member>Started this crazy thing</> <member> <ulink url="mailto:misa@dntis.ro">Mihai Ibanescu</ulink> (misa@dntis.ro)</member> <member><acronym>GNU</>ified the packet</> <member> <ulink url="mailto:greggj@savvis.com">Gregg Jensen</ulink> (greggj@savvis.com)</member> <member>Message handlers and extra datatype support and some sybperl stuff</> <member> <ulink url="mailto:jklowden@schemamania.org">James K. Lowden</ulink> (jklowden@schemamania.org)</member> <member>Wrote most of the documentation. Helped out here and there. </> <member> <ulink url="mailto:smurph@smcomp.com">Steve Murphree</ulink> (smurph@smcomp.com)</member> <member>Added more ODBC functionality. </> <member> <ulink url="mailto:psaar@fenar.ee">Arno Pedusaar</ulink> (psaar@fenar.ee)</member> <member>Donated his <acronym>TDS</>4.2 code to the cause</> <member> <ulink url="mailto:mark@champ.tstonramp.com">Mark Schaal</ulink> (mark@champ.tstonramp.com)</member> <member>Cleaned up message handling, more datatype support, bug fixes</> <member> <ulink url="mailto:cts@internetcds.com">Craig Spannring</ulink> (cts@internetcds.com)</member> <member>Wrote the <acronym>JDBC</> and DBI drivers</> <member> <ulink url="mailto:thompbil@exchange.uk.ml.com">Bill Thompson</ulink> (thompbil@exchange.uk.ml.com)</member> <member>Completer of the <systemitem class="library">db-lib</systemitem> bcp API and author of <application>freebcp</application>.</> <member> <ulink url="mailto:freddy77@angelfire.com">Frediano Ziglio</ulink> (freddy77@angelfire.com)</member> <member>Extended the ODBC library, and added many, many fixes and enhancements to libtds. </> </simplelist> <para> </para> </sect1> <sect1 id="Contributors"> <title>Contributors</title> <para>This user guide owes at least 100 words each to the following people. </para> <simplelist> <member>Brian Bruns</> <member>James Cameron</> <member>Allen Grace</> <member>James K. Lowden</> <member>Bill Thompson</> </simplelist> <para> </para> </sect1> </chapter> <!-- ////////////////// Appendix ////////////////// --> <Appendix id="interfacesfile"><title>The <filename>interfaces</filename> File</title> <Abstract><para>The <filename>interfaces</filename> file is retained for compatibility with Sybase environments. It is recommended that new users use the <link linkend="freetdsconf">freetds.conf</link> format instead.</para></Abstract> <sect1 id="interfacesorigin"> <title>Where it came from</title> <para> Under Sybase OpenClient there is a file called <filename>interfaces</filename> that defines servers available to the software. <productname>FreeTDS</productname> inherited this file structure with minor alterations. The <filename>interfaces</filename> remains supported for backward compatibility, and for those running in a mixed <productname>FreeTDS</productname>/Sybase environment. </para> <para> The <filename>interfaces</filename> is not read by <productname>FreeTDS</productname> unless it does not find <filename>freetds.conf</filename>. Note also that <command>make install</command> will install a skeleton <filename>freetds.conf</filename>, which you'll have to remove if you want to use <filename>interfaces</filename> instead. </para> </sect1> <sect1 id="interfaceslocation"> <title>Where it goes</title> <para> Anywhere. The <envar>SYBASE</envar> environment variable must contain the location of <filename>interfaces</filename>; that is how <productname>FreeTDS</productname> will find it. </para> </sect1> <sect1 id="interfacespurpose"> <title>What it does</title> <para> The <filename>interfaces</filename> file aliases a dataserver name to the hostname and port number of the dataserver's machine. When <productname>FreeTDS</productname> receives a request to connect to a database server, it looks up the dataserver name in <filename>interfaces</filename>. There, it finds the machine name (or address) and port number to connect to, that is, the port where the database server is listening. </para> <tip><sidebar><title>How's that again?</title> <para> The <filename>interfaces</filename> file sometimes trips people up. It seems innocuous enough, but it's also a pretty good example of <quote>it's easy if you know how</quote>. Keep in mind: </para> <itemizedlist mark=bullet> <listitem><para>The <emphasis>dataserver name</emphasis> is the name of the database server. When a database client specifies the <quote>name of the server</quote> to connect to, it's the <emphasis>dataserver name</emphasis> that is used. </para></listitem> <listitem><para>The <emphasis>host name</emphasis> is the name of the host (machine) where the database server is running. It has an IP address, and in almost any environment, you can <command>ping</command> the machine name to see if you've got it right. After it uses the <emphasis>dataserver name</emphasis> to look up the <emphasis>host name</emphasis>, <productname>FreeTDS</productname> will do the same thing <command>ping</command> does to get the IP address of the machine to connect to. </para></listitem> <listitem><para>Finally, the <emphasis>port number</emphasis> is frequently overlooked. From the network's point of view, knowing the IP address without the port number is a little like knowing the address of an apartment building without knowing the apartment number. In both cases, it will be hard to find what you came for. Make sure you <emphasis>know</emphasis> the port number, and that it's correctly entered in the <filename>interfaces</filename> file. </para></listitem> </itemizedlist> </sidebar></tip> </sect1> <sect1 id="interfacesformat"> <title>What it looks like</title> <para> The format of the <filename>interfaces</filename> file is borrowed directly from that used by Sybase on Unix platforms (<productname>Windows</productname> has a different format). Additionally, we have overloaded one of the fields to add the ability to set the protocol version. An example <filename>interfaces</filename> file looks like this. </para> <para> <example id="e.g.interfacesfile"> <title>An <filename>interfaces</filename> file example</title> <programlisting> myserver query tcp 4.2 127.0.0.1 4000 master tcp ether 127.0.0.1 4000 </programlisting> </example> </para> <para> The entry starts with the servername beginning in the first column (no whitespace preceding it). Following the servername are one or more services lines which <emphasis>must</emphasis> be indented with whitespace. <productname>FreeTDS</productname> uses only the query line, although others may be present to retain compatibility with Sybase. </para> <para> The fields in the services lines are as follows. <table id="tab.Services.Line"> <title>Services Line</title> <tgroup cols="3"> <thead> <row> <entry>Name</entry> <entry>Example</entry> <entry>Meaning</entry> </row> </thead> <tbody> <row> <entry>service</entry> <entry>query</entry> <entry>The only supported service</entry> </row> <row> <entry>transport</entry> <entry>tcp</entry> <entry>The transport protocol to use. Only tcp is supported by <productname>FreeTDS</productname>.</entry> </row> <row> <entry>physical</entry> <entry>4.2</entry> <entry>Historically this field referred the physical/datalink layer, however it appears to simply a comment field. Therefore, <productname>FreeTDS</productname> optionally uses it to specify the protocol version to connect with.</entry> </row> <row> <entry>hostname/IP</entry> <entry>127.0.0.1</entry> <entry>The hostname or IP address where the <productname>SQL Server</productname> resides.</entry> </row> <row> <entry>port</entry> <entry>4000</entry> <entry>The TCP port where the <productname>SQL Server</productname> is listening.</entry> </row> </tbody> </tgroup> </table> </para> <para> In the example above, the <literal>hostname</literal> was entered as an IP address. It needn't be; it could just as well be a name. <productname>FreeTDS</productname> can use a name rather than an address; it will just let the network (specifically, the <application>resolver</application> get the address. </para> </sect1> </Appendix> <Appendix id="AboutUnicode"><title>About Unicode, UCS-2, and UTF-8</title> <para> For better or worse, <productname>FreeTDS</productname> brings the otherwise innocent programmer into contact with the arcane business of how data are stored and transported. <productname>FreeTDS</productname> is a data communications library that of course connects to databases, which are charged with storing information in a way that is neutral to all architectures and languages. On the surface, that might not seem very complex, even worth discussing. Under the surface, things are not so simple. </para> <section id="ascii"><title><acronym>ASCII</>: What everyone knows</title> <para> The world we are all familiar with, programmingwise, is <acronym>ASCII</>. Our email (mostly), our <quote>text</quote> files, our web pages (mostly), all use <acronym>ASCII</> to represent English (or English-like) text. Perhaps because <ulink url="http://czyborra.com/charsets/iso646.html"><acronym>ASCII</></ulink> <footnote><para>czyborra.com is offline at the time of this writing (December 2003). It contained good information, so it's still included here, in case it comes back to life. </para></footnote> was standardized back in 1972 by the ISO, it seems like the <quote>natural</quote> way to store information. But let's look under the hood a little bit, and examine our assumptions. </para> <para> Our so-called <quote>text</quote> files are nothing special, nothing but a little agreement we enter into with our operating system. The only reason we can <quote>read</quote> them with <command>cat</command> or <command>vi</command> is that the operating system and its tools are in on the agreement. A file is only a stream of bytes, after all, no more <quote>text</quote> than an executable. The only thing distinguishing a <quote>text</quote> file from any other, is our understanding to treat it like one. We agree that the number 65 will represent the letter <literal>A</literal>, 66, <literal>B</literal>, and so on, 127 values in all. See <command>man ascii</command> for further details. </para> <para> The important thing to understand is that the designation of 65 for <literal>A</literal> and so on is a choice. It's an <emphasis>encoding standard</emphasis>, made necessary by the old simple fact that computers store numbers, not letters. <acronym>ASCII</> is so ubiquitous these days that it's hard sometimes to remember there was a time when it was but one of a set of competing encoding standards. Others you probably have heard of include <acronym>EBCDIC</> and the Baudot systems, but they are by no means the only historical alternatives, nor the only modern ones. </para> <section id="ASCIICompact"><title>The <acronym>ASCII</> Compact</title> <para> UNIX® and unix-like systems bought into <acronym>ASCII</> big time. Program code, filenames, string constants (and variables), configuration files, everything but everything is encoded in <acronym>ASCII</>. Practically every utility, command, and library assumes the <quote>text</> data will be <acronym>ASCII</>. At the dawn of the 21<superscript>st</> century, there is widespread recognition that <acronym>ASCII</> will no longer suffice, but the art of upgrading all the computers and computer programmers is, well, an unfinished work. </para> </section> </section> <section id="ISO8859"><title>ISO 8859: What everyone would like to forget</title> <para> <acronym>ASCII</> won, it would seem, but the race goes not to the swift. <acronym>ASCII</> has many limitations, the most egregious of which is, it's not much good for anything besides English. It encodes all the letters and punctuation (almost) of the English alphabet, but is useless for German, Russian, and Greek, to say nothing of Chinese. </para> <para> <acronym>ASCII</> assigns one byte to every character, but deals with only 7 of the 8 available bits, the range 0-127 (with the <quote>high bit</quote> always zero). Demand for computers that could display and print languages besides English — even English with em dashes and cent (¢) signs — arrived soon enough, with the Marketing Department way out in front of the propeller heads. The predictable result was an array of <quote>8-bit <acronym>ASCII</></quote> encoding standards for a wide variety of alphabets. Eventually, they were standardized (or at least enumerated and documented) by the ISO. These are what our friendly database vendors are referring to when they talk about <emphasis>character sets</emphasis>. More information on this subject can be found at <ulink url="http://www.webreference.com/dlab/books/html/39-1.html">webreference.com</ulink>. </para> <para> The upshot is, there is no uniform standard, no agreement on the meaning of a byte, particularly if that byte's value is greater than 127. Let's say your client machine sends <literal>HELLO</literal> and your database stores it as <literal>72 69 76 76 79</literal>. When another client retrieves that value, it will convert it into human-readable form by applying an encoding standard. If everything's tightly wrapped, it will use the very same encoding that your database used (and the same one you had in mind when you sent it), and that client will also see <literal>HELLO</literal>. If things are not so tightly wrapped but that client is fortunate enough to be using a similar standard to what you were using, say, ISO 8859-1, he'll still see <literal>HELLO</literal>. Most languages based on the Roman alphabet can be represented by ISO 8859-1, and are thus interchangeable. Beyond that, things get quickly messy. Greek clients, for one, are not so lucky: there are three ISO 8859 standards for Greek, all mutually incompatible. For more information, see <ulink url="http://czyborra.com/charsets/iso8859.html">ISO 8859 Alphabet Soup</ulink>. Roman Czyborra's site is very informative; take your time there if you don't want your head to spin. </para> <para> Database servers need to know what encoding standard to employ, too. It's not obvious at first, but notions like <quote>uppercase</quote> and <quote>lowercase</quote>, trailing blanks, and collation rules all depend on what letter is meant by what number. (Collation even depends on what culture is interpreting the letters.) </para> </section> <section id="Unicode"><title>Unicode: East meets West</title> <para> <acronym>ASCII</> and its 8-bit cousins are on the way out, and with them the assumption that a character can be represented by a single byte. The new kid on the block is <ulink url="http://www.unicode.org/">Unicode</ulink>, similar to but not precisely the same as ISO 10646. Unicode (despite its name) is a set of standards. The most widely implemented is the 16-bit form, called UCS-2. As you might guess, UCS-2 uses two bytes per character, allowing it to encode most characters of most languages. Because <quote>most</quote> is far from <emphasis>all</emphasis>, there are nascent 32-bit forms, too, but they are neither complete nor in common use. </para> <para> In the same sense that 7-bit <acronym>ASCII</> was extended to 8 bits, Unicode extends the most prevalent <quote>8-bit <acronym>ASCII</></quote>, <acronym>ISO 8859-1</>, to 16 and 32 bits. The first 256 values remain in Unicode as in <acronym>ISO 8859-1</>: 65 is still <literal>A</literal>, except instead of being 8 bits (0x40), it's 16 bits (0x0040). Unlike the 8-bit extensions, Unicode has a unique 1:1 map of numbers to characters, so no language context or <quote>character set</quote> name is needed to decode a Unicode string. </para> <para> UCS-2 is the system employed by Microsoft NT-based systems. Microsoft database servers store UCS-2 strings in <type>nchar</type> and <type>nvarchar</type> datatypes. Microsoft also designed version 7.0 (and up) of the <acronym>TDS</> protocol around UCS-2: all metadata (table names and such) are encoded according to UCS-2 on the wire. </para> </section> <section id="Unicodegoodbad"><title>Unicode's Pluses and Minuses</title> <para> You will read from time to time that Unicode is not perfect. Surprise, surprise: it's true. From a linguistic point of view, Unicode is incomplete; in particular, UCS-2 is demonstrably too small (!) to hold all the forms of Chinese ideographs used over the centuries. (It is, however, quite useful and widely employed in representing modern Chinese.) Of more common concern to programmers are Unicode's technical problems, or rather, Unix's technical shortcomings <foreignphrase>vis-a-vis</foreignphrase> any encoding more complex than <acronym>ISO 8859-x</>. </para> <para> The basic problem, from a programmer's perspective, is the ancient agreement Unix entered into 30 years ago, the <quote><acronym>ASCII</> Compact,</quote> alluded to earlier. Assumptions about <acronym>ASCII</> are littered throughout Unix-like systems, beginning with C's convention of representing strings as arrays of characters ending in a zero. Returning to our HELLO example earlier, C will store <literal>HELLO</literal> as <literal>72 69 76 76 79 0</literal>, in very nice <acronym>ASCII</>. Many many parts of the operating system and its associated tools and applications will recognize that as a 5-letter word because it's terminated by a null (zero). In UCS-2 Unicode, though, that same <literal>HELLO</literal> uses 2 bytes for every character and becomes <literal>72 0 69 0 76 0 76 0 79 0 0 0</literal>. Practically the whole OS will think that's a 1-letter word, <quote>H</quote>. Not a good thing. </para> <para> Even if every OS were magically rid of all <acronym>ASCII</> assumptions and C strings, there would still be the problem of Endianism. <ulink url="http://whatis.techtarget.com/definition/0,,sid9_gci211659,00.html">Technical</ulink> <ulink url="http://www.noveltheory.com/TechPapers/endian.asp">explanations</ulink> on the subject are not hard to find. The long and short of it is, given a 16-bit integer (2 bytes), different hardware architectures will store the value differently. Asked to store our friend <quote>A</quote>, (0x41), for instance, a Sparc processor will put the least significant byte at the higher address (00 41) whereas an Intel processor will put it in the lower address (41 00). Put aside the questions of left, right, and wrong; architectures are a fact of life. Endianism shows up wherever integers are stored and retrieved in heterogeneous environments. </para> <para> The Unicode folks knew about Endianism, of course, and had to address it. A Unicode bytestream is supposed to begin with a byte-order mark. Needless to say, perhaps, many don't. </para> </section> <section id="UnicodeUtf"><title>Unicode Transformation Format: UTF-8</title> <para> The presence of nulls embedded in character data and of byte order issues make straight Unicode i.e., UCS-2 or UCS-4 hard to work with in a heterogeneous environment. Too many opportunities arise for the data to be truncated or misinterpreted, and too many systems would fail even to transmit such data. In short, when 16-bit data are thrust into a multi-architecture 8-bit world, it frequently bodes ill for the data. </para> <para> To answer that problem, to make Unicode transmissible and unambiguous to most machines, several <quote>transformation formats</quote> were adopted. Their goals were generally similar: to create a generally recognized format that would unambiguously and safely convey Unicode information between machines and across the Internet. To do that, they sought to remove nulls and endianism from the data stream. The most popular one — practically the only one used — is known as UTF-8. </para> <para> UTF-8 found wide acceptance for many reasons. UTF-8 represents any Unicode character as a combination of 1-4 bytes. The number of bytes required depends on the integer value of the Unicode character, and only one byte is used to represent the old <acronym>ASCII</> range (0-127). UTF-8 does not use zero to represent any part of any character (except for the <acronym>ASCII</> NUL). In consequence, UTF-8 is efficient with respect to space, has no endianism issues, and embeds no nulls. UTF-8 strings can be treated as plain old <acronym>ASCII</> strings. These properties make UTF-8 data relatively easy for systems accustomed to processing <acronym>ASCII</> data. </para> <para> Here's a small example showing the difference between UCS-2 and UTF-8. <example id="e.g.HELLO"> <title><quote>HELLO</quote> in UCS-2 and UTF-8</title> <screen> $ <userinput>echo HELLO | iconv -f ascii -t UCS-2 | hexdump -C</userinput> 00000000 00 48 00 45 00 4c 00 4c 00 4f 00 0a |.H.E.L.L.O..| 0000000c $ <userinput>echo HELLO | iconv -f ascii -t utf-8 | hexdump -C</userinput> 00000000 48 45 4c 4c 4f 0a |HELLO.| 00000006 $ <userinput>echo HELLO | hexdump -C</userinput> 00000000 48 45 4c 4c 4f 0a |HELLO.| 00000006 </screen> </example> It is the similarity of the last two outputs that makes UTF-8 so attractive. It behaves like <acronym>ASCII</> when <acronym>ASCII</>'s all that's needed. But it lacks <acronym>ASCII</>'s limitations. </para> <para> While UTF-8 solves many technical problems, it doesn't magically transform every <acronym>ASCII</>-assuming system into a Unicode system. For example, to display Unicode data correctly — even Unicode data in UTF-8 format — the system still needs a suitable font. And it must distinguish the buffer size (and byte count) from the character count. </para> </section> <section id="UnicodeFreeTDS"><title>Unicode and FreeTDS</title> <para> Microsoft servers using TDS 7.0 and above (anything since SQL Server 6.5) transmit their data in UCS-2 format (16-bit integers). Because most applications linked to <productname>FreeTDS</productname> are not prepared to deal with UCS-2 data, <productname>FreeTDS</productname> can convert the data to something more acceptable, including <acronym>ASCII</>. To do so, it employs an <productname>iconv</productname> library. <productname>FreeTDS</productname> determines the server's encoding from the TDS protocol and information reported by the server (generally per connection, but in the case of TDS 8.0, per result set column). It discovers the client's encoding in <filename>freetds.conf</filename>. <productname>FreeTDS</productname> will happily convert and convey your data in any <emphasis>single-byte</emphasis> format that <productname>iconv</productname> can provide. In practice, this normally means some form of ISO 8859-x or UTF-8. </para> <para> At some future time, <productname>FreeTDS</productname> aims to support Unicode and other multi-byte character sets. It does not do so at the current time. </para> <para> Sybase servers, by the way, adhere to a <quote>server makes right</quote> policy: they transmit their data in whatever character set the client requested at login time. The list of available character sets is fairly short, but includes UTF-8. While <productname>FreeTDS</> <emphasis>could</> convert Sybase data streams as easily as it does Microsoft data streams, to our knowledge no one is doing so. The Sybase server can perform the conversion itself, making <productname>FreeTDS</>'s capability in this regard largely redundant and irrelevant. </para> <section id="moreinfo"><title>For further information</title> <simplelist type=vert columns=1> <member><ulink url="http://www.cl.cam.ac.uk/~mgk25/unicode.html">UTF-8 and Unicode FAQ for Unix/Linux</ulink>, by Markus Kuhn. As the man says, very comprehensive. </member> <member><ulink url="http://www.wps.com/projects/codes/">ASCII: American Standard Code for Information Infiltration</ulink>, by Tom Jennings. Everything you ever wanted know about ASCII, but didn't know whom to ask. </member> <member><ulink url="http://tronweb.super-nova.co.jp/characcodehist.html">A Brief History of Character Codes</ulink>, by Steven J. Searle. Includes useful references. </member> <member><ulink url="http://www.unicode.org/">Unicode Home Page</ulink>. </member> <!--member><ulink url=""></ulink>. </member --> </simplelist> </section> </section> </Appendix> <appendix id="gfdl"> <title>GNU Free Documentation License</title> <!-- - GNU Project - Free Software Foundation (FSF) --> <!-- LINK REV="made" HREF="mailto:webmasters@gnu.org" --> <!-- sect1> <title>GNU Free Documentation License</title --> <para>Version 1.1, March 2000</para> <blockquote id="fsf-copyright"> <para>Copyright (C) 2000 Free Software Foundation, Inc. 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.</para> </blockquote> <sect1 id="gfdl-0"> <title>PREAMBLE</title> <para>The purpose of this License is to make a manual, textbook, or other written document "free" in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others.</para> <para>This License is a kind of "copyleft", which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software.</para> <para>We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.</para> </sect1> <sect1 id="gfdl-1"> <title>APPLICABILITY AND DEFINITIONS</title> <para>This License applies to any manual or other work that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. The "Document", below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as "you".</para> <para>A "Modified Version" of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language.</para> <para>A "Secondary Section" is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (For example, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them.</para> <para>The "Invariant Sections" are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License.</para> <para>The "Cover Texts" are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License.</para> <para>A "Transparent" copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, whose contents can be viewed and edited directly and straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup has been designed to thwart or discourage subsequent modification by readers is not Transparent. A copy that is not "Transparent" is called "Opaque".</para> <para>Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML designed for human modification. Opaque formats include PostScript, PDF, proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML produced by some word processors for output purposes only.</para> <para>The "Title Page" means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, "Title Page" means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text.</para> </sect1> <sect1 id="gfdl-2"> <title>VERBATIM COPYING</title> <para>You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3.</para> <para>You may also lend copies, under the same conditions stated above, and you may publicly display copies.</para> </sect1> <sect1 id="gfdl-3"> <title>COPYING IN QUANTITY</title> <para>If you publish printed copies of the Document numbering more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects.</para> <para>If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.</para> <para>If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a publicly-accessible computer-network location containing a complete Transparent copy of the Document, free of added material, which the general network-using public has access to download anonymously at no charge using public-standard network protocols. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public.</para> <para>It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.</para> </sect1> <sect1 id="gfdl-4"> <title>MODIFICATIONS</title> <para>You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version:</para> <orderedlist numeration="upperalpha"> <listitem><para>Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission.</para> </listitem> <listitem><para>List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has less than five).</para> </listitem> <listitem><para>State on the Title page the name of the publisher of the Modified Version, as the publisher.</para> </listitem> <listitem><para>Preserve all the copyright notices of the Document.</para> </listitem> <listitem><para>Add an appropriate copyright notice for your modifications adjacent to the other copyright notices.</para> </listitem> <listitem><para>Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below.</para> </listitem> <listitem><para>Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license notice.</para> </listitem> <listitem><para>Include an unaltered copy of this License.</para> </listitem> <listitem><para>Preserve the section entitled "History", and its title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section entitled "History" in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence.</para> </listitem> <listitem><para>Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the "History" section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission.</para> </listitem> <listitem><para>In any section entitled "Acknowledgements" or "Dedications", preserve the section's title, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein.</para> </listitem> <listitem><para>Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles.</para> </listitem> <listitem><para>Delete any section entitled "Endorsements". Such a section may not be included in the Modified Version.</para> </listitem> <listitem><para>Do not retitle any existing section as "Endorsements" or to conflict in title with any Invariant Section.</para> </listitem> </orderedlist> <para>If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles.</para> <para>You may add a section entitled "Endorsements", provided it contains nothing but endorsements of your Modified Version by various parties--for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard.</para> <para>You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one.</para> <para>The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version.</para> </sect1> <sect1 id="gfdl-5"> <title>COMBINING DOCUMENTS</title> <para>You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice.</para> <para>The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work.</para> <para>In the combination, you must combine any sections entitled "History" in the various original documents, forming one section entitled "History"; likewise combine any sections entitled "Acknowledgements", and any sections entitled "Dedications". You must delete all sections entitled "Endorsements."</para> </sect1> <sect1 id="gfdl-6"> <title>COLLECTIONS OF DOCUMENTS</title> <para>You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects.</para> <para>You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.</para> </sect1> <sect1 id="gfdl-7"> <title>AGGREGATION WITH INDEPENDENT WORKS</title> <para>A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, does not as a whole count as a Modified Version of the Document, provided no compilation copyright is claimed for the compilation. Such a compilation is called an "aggregate", and this License does not apply to the other self-contained works thus compiled with the Document, on account of their being thus compiled, if they are not themselves derivative works of the Document.</para> <para>If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one quarter of the entire aggregate, the Document's Cover Texts may be placed on covers that surround only the Document within the aggregate. Otherwise they must appear on covers around the whole aggregate.</para> </sect1> <sect1 id="gfdl-8"> <title>TRANSLATION</title> <para>Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License provided that you also include the original English version of this License. In case of a disagreement between the translation and the original English version of this License, the original English version will prevail.</para> </sect1> <sect1 id="gfdl-9"> <title>TERMINATION</title> <para>You may not copy, modify, sublicense, or distribute the Document except as expressly provided for under this License. Any other attempt to copy, modify, sublicense or distribute the Document is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.</para> </sect1> <sect1 id="gfdl-10"> <title>FUTURE REVISIONS OF THIS LICENSE</title> <para>The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See <ulink url="http://www.gnu.org/copyleft/">http://www.gnu.org/copyleft/</ulink>.</para> <para>Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License "or any later version" applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation.</para> </sect1> <sect1 id="gfdl-11"> <title>How to use this License for your documents</title> <para>To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page:</para> <blockquote id="sample-copyright"><para> Copyright (c) YEAR YOUR NAME. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with the Invariant Sections being LIST THEIR TITLES, with the Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. A copy of the license is included in the section entitled "GNU Free Documentation License". </para></blockquote> <para>If you have no Invariant Sections, write "with no Invariant Sections" instead of saying which ones are invariant. If you have no Front-Cover Texts, write "no Front-Cover Texts" instead of "Front-Cover Texts being LIST"; likewise for Back-Cover Texts.</para> <para>If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.</para> </sect1> </appendix> <!-- Keep this comment at the end of the file Local variables: mode: sgml sgml-omittag:nil sgml-shorttag:t sgml-minimize-attributes:nil sgml-always-quote-attributes:t sgml-indent-step:2 sgml-parent-document: ("referenz.sgml" "appendix") sgml-exposed-tags:nil sgml-local-ecat-files:nil sgml-local-catalogs: CATALOG sgml-validate-command: "nsgmls -s referenz.sgml" ispell-skip-sgml: t End: --> </book>