File: userguide.xml

package info (click to toggle)
freetds 1.3.17%2Bds-2
links: PTS, VCS
area: main
in suites: bookworm
size: 9,104 kB
sloc: ansic: 98,429; sh: 5,044; xml: 4,472; sql: 1,488; makefile: 1,077; perl: 509; php: 22
file content (5580 lines) | stat: -rw-r--r-- 325,587 bytes
parent folder | download | duplicates (2)
<?xml version="1.0" encoding='UTF-8'?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
	<!ENTITY dblibapixml SYSTEM "dblib.api.xml">
	<!ENTITY ctlibapixml SYSTEM "ctlib.api.xml">
	<!ENTITY  odbcapixml SYSTEM "odbc.api.xml">
	<!ENTITY % ug.desc SYSTEM "userguide_desc.xml">
	%ug.desc;
	<!ENTITY % comment "IGNORE" >
	<!ENTITY ora "O'Reilly &amp; Associates">
	<!ENTITY freetds "<productname>FreeTDS</productname>">
	<!ENTITY dblib '<systemitem class="library">DB-Library</systemitem>'>
	<!ENTITY ctlib '<systemitem class="library">CT-Library</systemitem>'>
	<!ENTITY odbc  '<systemitem class="library">ODBC</systemitem>'> 
	<!ENTITY iODBC '<systemitem class="library">iODBC</systemitem>'>
	<!ENTITY unixODBC '<systemitem class="library">unixODBC</systemitem>'>
	<!ENTITY version "1.3">
	<!ENTITY freetdsconf "<filename>freetds.conf</filename>">
]>
<book>
<bookinfo>
	<date>&ug.date;</date>
	<title>&freetds; User Guide</title>
	<subtitle>A Guide to Installing, Configuring, and Running &freetds;</subtitle>
	<author>
		<firstname>Brian</firstname>
		<surname>Bruns</surname>
		</author>
	<author>
		<firstname>James</firstname>
		<othername>K.</othername>
		<surname>Lowden</surname>
		</author>
	<author>
		<firstname>Frediano</firstname>
		<surname>Ziglio</surname>
		</author>
	<copyright>
		<year>2001</year>
		<year>2002</year>
		<year>2003</year>
		<year>2004</year>
		<year>2005</year>
		<year>2006</year>
		<year>2007</year>
		<year>2008</year>
		<year>2009</year>
		<year>2010</year>
		<year>2011</year>
		<holder>Brian Bruns and James K. Lowden</holder>
		</copyright>
	<copyright>
		<year>2015</year>
		<year>2016</year>
		<year>2017</year>
		<year>2018</year>
		<year>2019</year>
		<holder>Frediano Ziglio</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 &freetds; &version;.  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 &freetds;.</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>&ug.date;</member>
				<member>&ug.id;</member>
				</simplelist>
			</footnote>
		can be found on the &freetds;
		<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 git repository.  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.xml</filename> 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 XML 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="https://pagure.io/xmlto">xmlto</ulink>.
		The XML 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 &freetds;?</title>
	

<para>&freetds; is re-implementation of C libraries originally marketed by Sybase and Microsoft SQL Server.  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>&freetds; provides drop-in replacements for 

<itemizedlist>
	<listitem><para>Sybase's &dblib; and &ctlib;</para></listitem>
	<listitem><para>Microsoft's &dblib; (which differs in small details from Sybase's)</para></listitem>
	<listitem><para>the &odbc; drivers from both vendors</para></listitem>
	<listitem><para>interactive SQL and BCP utilities</para></listitem>
</itemizedlist>

The <quote>TDS</quote> part of the name comes from name of the protocol used to communicate with such servers: the Tabular Data Stream.  </para>

<para>&freetds; is distributed in source code form, and is expected to compile on just about any operating system.  That means every form of Unix&reg; and Unix-like&trade; system (including notable variants such as Interix&reg; and QNX&reg;), as well as Win32&reg;, VMS&reg;, and OS X&reg;.  If it doesn't compile on your system &mdash; and you're not using MS-DOS&reg; &mdash; it's probably considered a bug.</para>

	<sect1 id="tdsprotocolhist">
		<title>Background: The <acronym>TDS</acronym> Protocol
			and related <acronym>API</acronym>s
			</title>

<para><acronym>TDS</acronym> 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</acronym>, 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 &mdash; each with its own <acronym>API</acronym> &mdash; that do the work of moving SQL through a <acronym>TDS</acronym> pipe.  &odbc;, &dblib;, and &ctlib; have very different <acronym>API</acronym>s, but they're all one to the server, because on the wire they speak <acronym>TDS</acronym>.</para>

<para>The <acronym>TDS</acronym> 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 &dblib;.</para>

<para>&dblib; provided an <acronym>API</acronym> to the client program, and communicated with the server.  What it sent to the server took the form of a 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 &dblib; <acronym>API</acronym> and added &odbc;.  (Microsoft has since added other <acronym>API</acronym>s, too.  It no longer supports its own &dblib; implementation.) At about the same time, Sybase introduced a more powerful <quote>successor</quote> to &dblib;, called &ctlib;, and called the pair <productname><firstterm>OpenClient</firstterm></productname>.</para>

<para>&ctlib;, &dblib;, and &odbc; are <acronym>API</acronym>s that &mdash; however different their programming style may be &mdash; all communicate with the server in the same way.  The language they use is <acronym>TDS</acronym>.</para>

<para>The <acronym>TDS</acronym> protocol comes in several flavors, most of which were not openly documented.  If anything, it was considered to be something like a trade secret, or at least proprietary technology.  The exception is <acronym>TDS</acronym> 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</acronym> Versions</title>
		

<para>At first, there was One Version of <acronym>TDS</acronym> 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</acronym> 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</acronym> 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</acronym> 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 7.1 Microsoft</term> 
				<term><emphasis>was</emphasis> 8.0
					<footnote><para>Earlier &freetds; documentation referred to versions 7, 8 and 9.  Microsoft subsequently published a protocol specification document denoting 7.1 and 7.2, and one finds scattered references using that scheme elsewhere, too.  For that reason, &freetds; switched to Microsoft's nomenclature.  </para></footnote>
					</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>
			
			<varlistentry>
				<term>TDS 7.2 Microsoft</term>
				<term><emphasis>was</emphasis> 9.0</term>
				<listitem><para>Introduced for <productname>SQL Server 2005</productname>.  Includes support for varchar(max), varbinary(max), xml datatypes and MARS.</para></listitem>
				</varlistentry>

			<varlistentry>
				<term>TDS 7.3 Microsoft</term>
				<listitem><para>Introduced for <productname>SQL Server 2008</productname>.  Includes support for extended date/time, table as parameters.</para></listitem>
				</varlistentry>

			<varlistentry>
				<term>TDS 7.4 Microsoft</term>
				<listitem><para>Introduced for <productname>SQL Server 2012</productname>.  Includes support for session recovery.</para></listitem>
				</varlistentry>

			</variablelist>
		</sect1>
	
	<sect1 id="FreeTDShistory">
		<title>History of &freetds;</title>

<para>&freetds; 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 <symbol>a.out</symbol>-based, although Greg Thain did a great service in converting the library to ELF.  Secondly, it included only the newer &ctlib; <acronym>API</acronym>.  The older &dblib; <acronym>API</acronym> was missing.</para>

<para>Brian Bruns, a Sybase DBA and originator of the &freetds; project, had some &dblib; programs he wanted to run under Linux, and thus began the &freetds; project. The original work focused on &dblib; and version 5.0 of the protocol, but quickly expanded to include a &ctlib; compatible layer and <acronym>TDS</acronym> version 4.2.  Later support for &odbc; and <acronym>TDS 7.0 and 7.1</acronym> was added. Craig Spannring wrote a Java  <acronym>JDBC</acronym> driver which became <productname>FreeTDS/JDBC</productname>.</para>

<para>As the project matured, it gained new participants.  Frediano Ziglio greatly expanded the &odbc; 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 &ctlib;.  James K. Lowden joined the project to add documentation, and in 2002 became its maintainer.  Such are the rewards for doing a good deed.</para>

<para>There have been many other contributions.
Please see the <filename>AUTHORS.md</filename> 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>&freetds; consists of some C libraries.</para>
<para>The &freetds; libraries support three separate <acronym>API</acronym>s: &dblib;, &ctlib;, and &odbc;.  Underlying these three is libtds, which handles the low-level details of the <acronym>TDS</acronym> 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>
			</sect2>
		<sect2 id="Status">
			<title>Status</title>

<para>The libraries are portable, mature, and stable.  They're expected to compile readily and normally do not crash or corrupt data.  Extensive logging  aids in diagnosing problems.  While they do not include every feature provided by the vendors' libraries, they do faithfully implement a useful &mdash; and widely used &mdash; subset of their <acronym>API</acronym>s.</para>

<para>The &dblib; and &ctlib; <acronym>API</acronym>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>.</para>

<para>The <systemitem class="library">ODBC</systemitem> driver should be fully ODBC 3.5 compliant.</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</filename>, included in the source distribution.</para>

<para><note><para>For Microsoft servers, &freetds; now offers the best &dblib; for any OS on the planet (including Windows!) thanks not only to the hard work of its contributors, but also to Microsoft's<footnote><para>Microsoft ceased enhancing &dblib; in 2001, advising customers to <quote>avoid using &dblib;</quote>.  For Microsoft's unmaintained product, that's good advice.  But if the &dblib; specification meets your needs, &freetds; permits you to keep using it with little loss (and some gain) of functionality. </para></footnote> strategy.   It is the only Win64 implementation of &dblib;, and the only  Win32 implementation to support modern versions of the protocol.  (SQL Server 2008 still accepts the TDS 4.2 connections that Microsoft's old library uses, but rejects BCP uploads with a spurious permission-denied message.) </para></note></para>

<para>In addition to the core &dblib; <acronym>API</acronym>, &freetds;  includes a full implementation of &dblib;'s <acronym>bcp</acronym> functions, as well as <command>freebcp</command>, a replacement for Sybase's <application>bcp</application> utility.</para>

<para>How big is it?  &freetds; has over 100,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, &freetds;'s success so far lies somewhere between the Beetle and the Edsel.</para>

<para>Who uses it?  Oh, pretty much everyone.  &freetds; users number in the tens of thousands.  It's used by large corporations, by the U.S. federal government (e.g. <ulink url="http://www.ncbi.nlm.nih.gov/books/bv.fcgi?rid=toolkit.chapter.ch_dbapi">Database Access Library</ulink> at the National Center for Biotechnology Information) and, judging by the mailing list, by many webservers running Apache and PHP.  Sybase recommends &freetds; for their EAServer product.  Microsoft recommends &freetds; to their customers who want access to Microsoft SQL Server from non-Win32 clients.  So do we.</para>
			</sect2>
		<sect2 id="Languages">
			<title>Languages besides C</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 &dblib; or &ctlib; <acronym>API</acronym>, for which &freetds; is intended as a drop-in replacement.  For instance, Michael Peppler's <systemitem class="library">DBD::Sybase</systemitem> works very well using &freetds; to access Sybase or Microsoft <productname>SQL Server</productname>s.  <productname>PHP</productname> has options for <filename>sybase</filename> (&dblib;) and <filename>sybase-ct</filename> (&ctlib;) <acronym>API</acronym>s.</para>
			</sect2>
		<sect2 id="alternatives">
			<title>Alternatives</title>
			<variablelist id="tab.alternatives">
				<title>Should &freetds; not suit your needs, some alternatives</title>
				<varlistentry>
					<term>jTDS</term>
					<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</acronym> driver.</para>
						</listitem>
					</varlistentry>
				<varlistentry>
					<term>Sybase OpenClient</term>
					<listitem>

<para>In the time since &freetds; was started, Sybase (as well as most major <acronym>DBMS</acronym> vendors) has released its database for the Intel <productname><acronym>GNU</acronym>/Linux</productname> platform.  The good: it is a solid product and supports <acronym>TDS</acronym> 4.2 and <acronym>TDS</acronym> 5.0.  The bad: it doesn't support <acronym>TDS 7.0</acronym> 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>&odbc; bridge products</term>
					<listitem><para>They use the &odbc; 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>&odbc; Router</application> from <ulink url="http://www.augsoft.com/">August Software</ulink> Corporation.</para>
						</listitem>
					</varlistentry>
				<varlistentry>
					<term>Inline &odbc; driver</term>
					<listitem><para>Based on <systemitem class="library">libtds</systemitem>, this is a native &odbc; 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 &odbc; bridge except it's free.</para>
						</listitem>
					</varlistentry>
				</variablelist>
			</sect2>
		</sect1>
	</chapter>
<!-- ////////////////// CHAPTER /////////////////////// -->

<chapter id="build">
	<title>Build &freetds;</title>
	<epigraph>

<para>If you build it they will come.</para>
		</epigraph>
	<sect1 id="gnu">
		<title>The <acronym>GNU</acronym> World</title>

<para>&freetds; uses <acronym>GNU</acronym> <application>Autoconf</application>, <application>Automake</application>, and <application>libtool</application><footnote>
		<itemizedlist spacing="compact">
			<title>Versions used for this release</title>
			<listitem><para>autoconf (GNU Autoconf) 2.69</para></listitem>
			<listitem><para>automake (GNU automake) 1.15</para></listitem>
			<listitem><para>ltmain.sh (GNU libtool) 2.4.6</para></listitem>
			</itemizedlist>
	</footnote> 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</acronym> system, you can probably just download the tarball and get away with scanning the <filename>README.md</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>git</productname> repository</title>

<para>The latest &freetds; package is always available from
			<ulink url="ftp://ftp.freetds.org/pub/freetds/stable/freetds-stable.tgz">
				<citetitle>ftp.freetds.org</citetitle></ulink>.</para>

<para>Code changes by the developers are immediately available in the <productname>git</productname> repository.  If you've run into a problem, you may want to check out from <productname>git</productname> to see if it's fixed there.</para>

<para>No password is needed to obtain the current git copy of &freetds;; you need only have a git client installed on your machine.  Then:
<screen>
	<prompt>$ </prompt><userinput>git clone https://github.com/FreeTDS/freetds.git</userinput>
	<prompt>$ </prompt></screen></para>

<para>For those behind firewalls or otherwise unable to access <productname>git</productname>, nightly snapshots of <productname>git</productname> are rolled up into tarballs for your convenience.  They can be downloaded from
			<ulink url="ftp://ftp.freetds.org/pub/freetds/current/freetds-current.tgz">ftp.freetds.org</ulink>.</para>

<para>In general, the <productname>git</productname> master branch (the basis of the current nightly snapshot) 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>git</productname> master.</para>
		<tip><para>As with any project of this sort, if you want to use the <productname>git</productname> master branch, 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</acronym> projects, building &freetds; is a fairly straightforward process. We have a terse and verbose description.</para>
		<note><para>&freetds;  is known to build with <acronym>GNU</acronym> and <acronym>BSD</acronym> <application>make</application>.  If you encounter a large number of build errors, and your operating system's <application>make</application> is not <acronym>GNU</acronym> <application>make</application> (as is the case on most non-<acronym>GNU</acronym>/Linux systems), you may wish to install <acronym>GNU</acronym> <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</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 git is described in the file <filename>INSTALL.GIT.md</filename>.</para>
			
			</sect2>
		<sect2 id="Everyone"><title>For Everyone Else </title>
			<titleabbrev>(&freetds; for Dummies?)</titleabbrev>
			

<para>The <acronym>GNU</acronym> development system can generate code for a wide variety of hardware architectures and operating systems, virtually all of which can run &freetds; in consequence.  The work of building and installing the &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</command> will manage the rest of the build.</para>
			<sidebar><title>ODBC Preparation</title>

<para>If you intend to build the &freetds; ODBC driver &mdash; and want to use a Driver Manager (DM), as most people do &mdash; install the Driver Manager before configuring &freetds;.  <command>configure</command> will detect the the DM and use its header (<filename>.h</filename>) 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</command>.</para>
				

<para>&freetds; doesn't <emphasis>require</emphasis> a DM.
You can build the ODBC driver without one, as long as you have the requisite header files: <filename>sql.h</filename>, <filename>sqlext.h</filename> and <filename>sqltypes.h</filename>.
These can be taken from either the &iODBC; or &unixODBC; distributions.
Put them wherever you like (e.g.,  <filename>/usr/local/include</filename>).
Because &freetds; won't detect your (missing) DM, it won't automatically build the ODBC driver, so you'll have to tell <command>configure</command> what to do and where to look.
Cf. <link linkend="withOdbcNoDM"><option>--with-odbc-nodm</option></link>.</para>
				</sidebar>

<para>The simplest form of running <command>configure</command> is:
<screen>
	<prompt>$ </prompt><userinput>./configure</userinput></screen>
	and sometimes that's enough.  <command>configure</command> accepts command-line arguments, too, and you may need to provide some, depending on your environment.</para>

<para>There are a few optional arguments to <command>configure</command> that may be important to you.  For a complete list, see <command>configure --help</command>.</para>
			<sect3 id="Configure.Options" xreflabel="Options to configure">
				<title><command>configure</command> options</title>
				<variablelist id="tab.configure.Directories">
					<title>Directories and TDS version</title>
					<varlistentry>
						<term><option>--prefix=<replaceable>PREFIX</replaceable>
							</option></term>
						<listitem><para>         install architecture-independent files in <parameter>PREFIX</parameter>.  When you run <command>make install</command>, libraries will be placed in <parameter>PREFIX</parameter><filename>/lib</filename>, executables in <parameter>PREFIX</parameter><filename>/bin</filename>, and so on.</para>

<para>The default is <filename>/usr/local</filename> if this argument is not passed to <command>configure</command>.</para>
							</listitem>
						</varlistentry>
					
					<varlistentry>
						<term><option>--sysconfdir=<replaceable>DIR</replaceable>
							</option></term>
						<listitem><para> read-only single-machine data in <parameter>DIR</parameter></para>

<para>The default is <replaceable>PREFIX/etc</replaceable> (<parameter>PREFIX</parameter> being the value of <option>--prefix=<replaceable>PREFIX</replaceable></option>, above) if this argument is not passed to <command>configure</command>.</para>
							</listitem>
						</varlistentry>
					
					<varlistentry>
						<term><option>--with-libiconv-prefix=<replaceable>DIR</replaceable>
							</option></term>
						<listitem><para>Specifies the location of the iconv library to use.  <command>configure</command> 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>
<para>Version 0.95 removed support for iconv which cannot convert from any encoding to any encoding. This affect potentially systems like Tru64 and HP-UX were iconv mainly convert from/to ucs2. It's recommended to use GNU libiconv in this case.</para>
							</listitem>
						</varlistentry>
					<varlistentry>
						<term><option>--with-tdsver=<replaceable>VER</replaceable>
							</option></term>
						<listitem><para>Specifies the default <acronym>TDS</acronym> version.  (There are a couple of ways to set the <acronym>TDS</acronym> version at run-time.  This parameter takes effect if no run-time settings are provided.) Acceptable values of <parameter>VER</parameter> are <literal>5.0</literal>, <literal>7.1</literal>, <literal>7.2</literal>, <literal>7.3</literal> and <literal>7.4</literal>.</para>

<para>The default is <literal>auto</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
							</option></term>
					        <term><option>--with-iodbc=<replaceable>DIR</replaceable>
							</option></term>
						<term><option>--with-unixodbc=<replaceable>DIR</replaceable>
							</option></term>
                                                <listitem>
						  <para>
						    Specify a particular ODBC driver manager and the directory in which it is installed.
						    The <option>--with-iodbc</option> form chooses &iODBC; as the driver manager, and <option>--with-unixodbc</option> specifies &unixODBC; as the driver manager.
						    The directory argument is required for <option>--with-unixodbc</option>, but may be omitted for <option>--with-iodbc</option>; pkg-config will be used to find your &iODBC; installation if the directory is omitted.
						    Typical directory arguments are <filename>/usr</filename> and <filename>/usr/local</filename>.
						  </para>
						  <para>
						    So long as either &iODBC; or &unixODBC; are installed, the build system will detect your driver manager by default.
						    As a result, these options are only needed if you wish to override the default behavior.
						  </para>
						  <para>
						    It is an error to specify both <option>--with-iodbc</option> and <option>--with-unixodbc</option>.
						  </para>
							</listitem>
						</varlistentry>
						<varlistentry id="withOdbcNoDM">
							<term><option>--with-odbc-nodm=<replaceable>DIR</replaceable>
								</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</filename> files.  <command>configure</command> will not cause the ODBC driver to be built unless this option is used or a DM is detected/specified.</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-apps
							</option></term>
						<listitem><para>Do not attempt to build applications like tsql.</para>
							</listitem>
						</varlistentry>
					<varlistentry>
						<term><option>--disable-server
							</option></term>
						<listitem><para>Do not attempt to build server stuff.</para>
							</listitem>
						</varlistentry>
					<varlistentry>
						<term><option>--disable-pool
							</option></term>
						<listitem><para>Do not attempt to build pool stuff.</para>
							</listitem>
						</varlistentry>
					<varlistentry>
						<term><option>--disable-libiconv</option></term>
						<listitem><para>By default, <command>configure</command> 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, &freetds; 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 &freetds; not to use threadsafe versions of functions such as <function>gethostbyname_r()</function> where available.  Rely instead on the older and non-threadsafe ones such as <function>gethostbyname()</function>. <command>configure</command> tests some of these functions.  If the tests are successful, &freetds; will use threadsafe functions throughout.</para>

<para>Threadsafe operation has been tested on Linux, FreeBSD, HP-UX and Windows.  It should work on Solaris, Tru64, and (reportedly) IRIX.  Not expected to work on non-unixy systems.  Should not be used if your system supports threads. Pool server and MARS won't work if disabled.</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>
					<varlistentry>
						<term><option>--disable-odbc-wide</option></term>
						<listitem><para>Disable support for wide characaters in ODBC.
</para></listitem>
						</varlistentry>
					<varlistentry>
						<term><option>--disable-sspi</option></term>
						<listitem><para>Disable SSPI support. SSPI is a Micrsoft library that allows you to use your current logged-in account for authentication.  With this option enabled (the default), &freetds; supports "trusted logins" for Win32/64, just as Microsoft's own implementations do.
</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 &dblib; <acronym>API</acronym> where it diverges from Sybase's.  Use this option if you are replacing Microsoft's libraries with &freetds;</para>

<para>This option specifies 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 &dblib;, which may clash with the <systemitem class="library">DBM</systemitem> function with the same name.  Absolutely <emphasis>not required</emphasis> for use with other free software.</para>
							</listitem>
						</varlistentry>
					
					<varlistentry>
						<term><option>--enable-krb5</option></term>
						<listitem><para>Enable Kerberos support. With Kerberos you can connect to server using your stored Kerberos ticket.  Obviously requires Kerberos be configured on the machine.
</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>

					<varlistentry>
						<term><option>--enable-odbc-wide-tests</option></term>
						<listitem><para>Compile ODBC tests to use wide characters. Test will use wide versions.
</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.</para>
							</listitem>
						</varlistentry>
					
					<varlistentry>
						<term><option>--with-openssl=<replaceable>DIR</replaceable></option></term>
						<listitem><para>Enable SSL using OpenSSL. Unlike &freetds;, 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</command></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>git</productname>
							<footnote>

<para><productname>git</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</command> 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> option during configuration to install into your own directory.</para>

<para>With any luck, you've built and installed the &freetds; libraries.</para>

<para><tip>
	<title>Two bits of advice, if you like to keep things tidy and keep track of what you did. </title>

	<para>Create a file to hold your configure options called, say, <filename>.build_options</filename>.</para>

	<para>Create a build directory for the binaries, and invoke <command>../configure $(cat ../.build_options)</command>. </para>
	
	<para>This approach lets you remove the binaries at any time and rebuild from scratch using the same options.</para>
	
	</tip></para>
				</sect3>
			</sect2>
		</sect1>
	<sect1 id="osissues">
		<title>OS-specific Issues</title>
		<sidebar>

<para>If you've recently built and installed &freetds; 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.  &freetds; 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>Win32 and Win64</title>

<para>Officially &freetds; for Windows should be compiled using CMake. CMake is able to create project files for different development systems (like Visual C++).
Install CMake on your box and point to the source directory to generate wanted files. Refer to CMake documentation on how to do it (I personally use CMake GUI passing source directory and a newly create build directory).
Once project files are created you can open them with your environment.</para>

			<sect3><title>Other ways to build under Windows&reg;</title>
				
				<itemizedlist>
					
					<listitem><para>MingW</para></listitem>
					
					</itemizedlist>
				</sect3>

			<sect3><title>Download Windows&reg; binaries</title>

<para>You can  download FreeTDS binaries for Windows from AppVeyor (the hosted CI platform used).</para>

<para>There is a .zip file available as artifact of every sucessful build.

The list of builds is at
<ulink url="https://ci.appveyor.com/project/FreeTDS/freetds/history">https://ci.appveyor.com/project/FreeTDS/freetds/history</ulink>.

You can find there builds of code in the master banch and (from time to
time) builds from the post-1.0 release fixes-only Branch-1_00 branch.
Every build matrix element generates its artifact.</para>

<para>Ramiro Morales also maintains similar builds of the Branch-0_95 branch at
<ulink url="https://github.com/ramiro/freetds/releases">https://github.com/ramiro/freetds/releases</ulink>.</para>
				</sect3>

			<sect3 id="regsvr32"><title>ODBC driver registration</title>

<para>If compiled correctly &freetds; ODBC driver supports component registration.
Although an ODBC driver is not a Windows component you can register the driver with regsvr32 utility or
you can use this feature with some installer
and register the driver as a standard component.</para>

<para>Once the ODBC driver is registered in the system you can configure it from Control Panel.</para>

				</sect3>
			</sect2>

		<sect2 id="VMS"><title>VMS&reg;</title>

<para>&freetds; 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</application></member>
					<member><application>vmstar</application></member>
					<member><application>MMS</application> or <application>MMK</application></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</parameter> or <parameter>-o</parameter>
					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>$</prompt> <userinput>@[.vms]configure</userinput></screen>
	

<para> This creates a <filename>descrip.mms</filename> 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>vms/README.vms</filename> in the source distribution.</para>
				
				</sect3>
			</sect2>
		<sect2 id="osx"><title>OS X&reg;</title>

<para>The regular distribution compiles on OS X.</para>
			
			<sect3 id="OSX.Build.LinkIssues">
				<title>Possible linker problems</title>
<para>On 18 April 2016, a problem was reported causing linker issues.
<screen>
	Undefined symbols for architecture x86_64:

	  "___strlcpy_chk", referenced from:
	      _tdsdbopen in libsybdb_64.a(dblib.o)
	      _db_env_chg in libsybdb_64.a(dblib.o)
	      _dbcolinfo in libsybdb_64.a(dblib.o)
	      _dbtablecolinfo in libsybdb_64.a(dblib.o)
	      _tds_alloc_dynamic in libsybdb_64.a(mem.o)
	      _tds7_get_instance_port in libsybdb_64.a(net.o)
	      _tds_get_locale in libsybdb_64.a(locale.o)
	      ...
</screen>
</para>
<para>
This is due to some mismatch on different project releases. To solve these issue set the target release like
<screen>	<userinput>CFLAGS="-mmacosx-version-min=10.8" ./configure
	make</userinput></screen>
or
<screen>	<userinput>export MACOSX_DEPLOYMENT_TARGET=10.8
	./configure
	make</userinput></screen>
</para>

				</sect3>
			</sect2>
		
		<sect2 id="AIX"><title>AIX&reg;</title>

<para>AIX&reg; can induce linker indigestion.  libtool doesn't always understand that a <filename>.a</filename> file
				can be a shared library.  One solution is to build only static libraries with the <option>--disable-shared</option>
				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.95.tar.bz2</userinput></screen></para>
			</sect2>
	
		</sect1>
	</chapter>

<!-- ////////////////// CHAPTER /////////////////////// -->

<chapter id="install">
	<title>Install &freetds;</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</acronym> world, we <command>configure</command> the package (generate the <filename>Makefile</filename>s), then we <command>make install</command> the package.  In the case of a library package such as &freetds; To  <emphasis>install the package</emphasis> is to copy the files the application developer will use to their canonical locations: header files to <filename>include</filename>, libraries to the <filename>lib</filename>, documentation and man pages <filename>share</filename>.  Install targets were specified during the <phrase>build process</phrase> as arguments to <command>configure</command>, 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 &freetds; about your database servers, and we still have to tell your client programs about &freetds;.</para>
		</note>
	<sect1 id="LocalEnvironment">
		<title>The local environment</title>

<para>After &freetds; 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 servernames to &freetds;.  &freetds; looks up your server's attributes in &freetdsconf;.  Some of the attributes can be overridden by environment variables.</para>

<para>One of the more important (and arcane) settings is the <acronym>TDS</acronym> protocol version, described next.</para>
		</sect1>
	<sect1 id="ChoosingTdsProtocol">
		<title>Choosing a <acronym>TDS</acronym> protocol version</title>

<para>The <acronym>TDS</acronym> 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</acronym> versions.

			<table id="tab.Protocol.by.Product">
				<title>Versions of the <acronym>TDS</acronym> 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</emphasis> </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>7.1</entry>
							<entry>Include support for <symbol>bigint</symbol> (64 bit integers), <symbol>variant</symbol> and collation on all fields. Collation is not widely used. </entry>
							</row>
						<row>
							<entry>Microsoft SQL Server 2005</entry>
							<entry>7.2</entry>
							<entry>Includes support for varchar(max), varbinary(max), xml datatypes and MARS<footnote><para><emphasis>Multiple Active Result Sets</emphasis>.</para></footnote>.</entry>
							</row>
						<row>
							<entry>Microsoft SQL Server 2008</entry>
							<entry>7.3</entry>
							<entry>Includes support for time, date, datetime2, datetimeoffset.</entry>
							</row>
						<row>
							<entry>Microsoft SQL Server 2012 or 2014</entry>
							<entry>7.4</entry>
							<entry>Includes support for session recovery.</entry>
							</row>
						</tbody>
					</tgroup>
				</table></para>

<sect2>
	<title>Choosing protocol version since &freetds; 1.1</title>

	<para>Version 1.1 improved the discovery of the protocol version.
	If you are using Microsoft SQL Server is recommended to leave the version to <userinput>auto</userinput> (the default).
	If you are using any Sybase product you could set version to 5.0 to get faster connections (although <userinput>auto</userinput> will work too).
	</para>
</sect2>

<sect2>
	<title>Choosing protocol version before &freetds; 1.1</title>

<para>
	Choosing the correct <acronym>TDS</acronym> protocol version for use with SQL Server can be confusing. Hopefully, these steps will lead you to the correct version. If you have a Sybase server, you should be able to use version 5.0, otherwise, if you have Microsoft SQL Server refer to the following section.
</para>

<para>
	<itemizedlist>
		<listitem><para>Step 1: Find out which FreeTDS version you are running. You can use the command: `tsql -C`</para></listitem>
		<listitem><para>Step 2: Find out what version of Microsoft SQL Server you are running.</para></listitem>
		<listitem><para>Step 3: Pick the lower TDS Version number out of what matches steps 1 and 2 from the table below.</para></listitem>
	</itemizedlist>

	<table id="tab.Protocol.by.SQLServerProduct">
		<title>What Version of the <acronym>TDS</acronym> Protocol Should I use with Microsoft SQL Server?</title>
		<tgroup cols="4">
			<thead>
				<row>
					<entry>FreeTDS Version</entry>
					<entry>Microsoft SQL Server Version Supported</entry>
					<entry>Highest TDS Version Supported</entry>
					<entry>Microsoft Extended Support End Date</entry>
				</row>
			</thead>
			<tbody>
				<row>
					<entry>1.00</entry>
					<entry>2016</entry>
					<entry>7.4</entry>
					<entry>July 9th, 2024</entry>
				</row>
				<row>
					<entry>1.00</entry>
					<entry>2014</entry>
					<entry>7.4</entry>
					<entry>July 9th, 2024</entry>
				</row>
				<row>
					<entry>1.00</entry>
					<entry>2012</entry>
					<entry>7.4</entry>
					<entry>July 12th, 2022</entry>
				</row>
				<row>
					<entry>0.95</entry>
					<entry>2008</entry>
					<entry>7.3</entry>
					<entry>July 9th, 2019</entry>
				</row>
				<row>
					<entry>0.91</entry>
					<entry>2005</entry>
					<entry>7.2</entry>
					<entry>April 12th, 2016</entry>
				</row>
				<row>
					<entry>0.82</entry>
					<entry>2000</entry>
					<entry>7.1</entry>
					<entry>April 9th, 2013</entry>
				</row>
				<row>
					<entry>0.64</entry>
					<entry>2000</entry>
					<entry>7.1</entry>
					<entry>April 9th, 2013</entry>
				</row>
			</tbody>
		</tgroup>
	</table>
</para>

<para>
NOTE FOR USERS WHO NEED SQL SERVER 2000 SUPPORT (VERY RARE; SQL SERVER HAS BEEN OUT OF EXTENDED SUPPORT SINCE 2013 AND SHOULD *NEVER* BE USED IN PRODUCTION):

Years ago, Microsoft didn't officially create a TDS version number until after FreeTDS was released, and it was assumed 8.0 would be the next version; it turned out to be 7.1. Because of this:

	<itemizedlist>
		<listitem><para>If you are running FreeTDS Version 0.64 or 0.82 with Microsoft SQL Server 2000, use TDS Version 8.0 instead of 7.1.</para></listitem>
		<listitem><para>If you are running FreeTDS Version 0.91 or greater with Microsoft SQL Server 2000, use TDS Version 7.1.</para></listitem>
		<listitem><para>Please note, this is ONLY if you need Microsoft SQL Server 2000 support.</para></listitem>
	</itemizedlist>
</para>

<para>For best results, use the highest version of the protocol supported by your server.  If you encounter problems, try a lower version.  If that works, though, please report it to the mailing list!
	</para>

</sect2>

<sect2>
	<title>Regarding obsolete versions</title>

	<para>In the earlier days of &freetds;, Microsoft did not release official specs for the TDS protocol.
When MSSQL 2000 (product 8.0) was released, there was semi-official indications from the Microsoft community
that the TDS protocol would be version 8.0.
So the &freetds; developers adopted that version for &freetds;.
Years later, when Microsoft started releasing official specs of the protocol, it became obvious that the TDS
versions that &freetds; had labeled 8.0 and 9.0 were actually versions 7.1 and 7.2 respectively.</para>

	<para>Version 8.0 cannot be used from &freetds; version 1.3.</para>

<para><itemizedlist>
			<title>TDS 4.2 has limitations</title>
			<listitem><para><acronym>ASCII</acronym> only, of course.</para></listitem>
			<listitem><para><acronym>RPC</acronym> is not supported.</para></listitem>
			<listitem><para><acronym>BCP</acronym> 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</firstterm>) 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 Microsoft SQL Server tools.</para>

</sect2>
		</sect1>
	<sect1 id="name.lookup"> <title><replaceable>servername</replaceable> Lookup</title>
<!--

<para>When an application names a server to connect to, &freetds;:
<simplelist type="vert" columns="1">
<member>resolves the name to an IP address</member>
<member>chooses a port</member>
<member>connects to the port</member>
<member>chooses a version of the TDS protocol</member>
<member>sends a login packet</member>
<member>listens for an answer from the server</member>
</simplelist>
-->

<para>&freetds; converts the servername to an IP address by following the steps below, stopping when it succeeds.
			<orderedlist><title>Name lookup sequence
					<footnote><para>This description applies to &dblib; and &ctlib;.  ODBC lookup is different.</para></footnote>
					</title>
				<listitem><para>Find <replaceable>servername</replaceable> in &freetdsconf;.  If a section with that name exists, use the hostname, port, and TDS version specified therein.</para></listitem>
				<listitem><para>Attempt to convert <replaceable>servername</replaceable> to an IP address with <function>inet_addr(3)</function>.</para></listitem>
				<listitem><para>Request name-lookup from the operating system via <function>gethostbyname(3)</function> or similar.</para></listitem>
				</orderedlist>
			
			If the TDS version and port are not read from &freetdsconf;, they are derived from the compiled-in defaults and overridden by applicable environment variables.</para>
		

<para>As you can see, if most of your servers use the same TDS version and answer to the default port, then you don't need to list them all in &freetdsconf;.  You can simply compile in the right defaults &mdash; or set the <envar>TDSPORT</envar> and <envar>TDSVER</envar> environment variables &mdash; and rely on DNS for name resolution.</para>
		</sect1>
	
	<sect1 id="freetdsconf">
		<title>The &freetdsconf; file</title>
		<sect2 id="freetdsconfpurpose">
			<title>What it does</title>

<para>Just as DNS defines hostnames for  network addresses, &freetdsconf; uses a <firstterm>servername</firstterm> to define the properties of your server.  <footnote>

<para>In general, the servername is arbitrary and local; it's used only by your client programs to tell &freetds; 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.  Unless you use the <link linkend="asa.database">ASA Database</link> property, you must use the database's name as your servername.  Otherwise, the server will refuse your connection.</para>
					</footnote>
				In particular, &freetds; needs to know:
				<itemizedlist><title>Primary Server Properties</title>
					<listitem><para>Hostname or IP address of the server
</para></listitem>
					<listitem><para>Port number or Instance name (not both)
</para></listitem>
					<listitem><para><acronym>TDS</acronym> protocol version
</para></listitem>
					</itemizedlist>				</para>

<para></para>

<para><note><para>	&freetds; also supports an older configuration file format, known as the <filename>interfaces</filename> file.  Use &freetdsconf; 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.  &freetds; looks for &freetdsconf; first, falling back on <filename>interfaces</filename> only if &freetdsconf; 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 &freetdsconf; is determined by the  <literal>--sysconfdir</literal> option of <command>configure</command>.  If you don't specify anything, <command>configure</command>'s default <literal>sysconfdir</literal> is <filename>/usr/local/etc</filename>.  <command>tsql -C</command> reports the <literal>sysconfdir</literal> to let you confirm it.</para>

<para>In addition, &freetds; will look for a file <filename>.freetds.conf</filename> in the user's home directory (<envar>${HOME}</envar><filename>/.freetds.conf</filename>).</para>

<para>The actual name and location of &freetdsconf; 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>&freetds; reads the user's <replaceable>${HOME}/</replaceable><filename>.freetds.conf</filename> before resorting to the system-wide <replaceable>sysconfdir/</replaceable>&freetdsconf;.  The file used is the first one that is readable and contains a section for the server.</para>
			</sect2>
		<sect2 id="freetdsconfformat">
			<title>What it looks like</title>

<para><tip><para> The following information is also provided in the &freetdsconf; manual page, cf. <command>man freetds.conf</command>.</para></tip></para>

<para>The &freetdsconf; file format is similar to that of Samba's modified <quote><filename>win.ini</filename></quote>.  It
				is composed of two types of sections: one <literal>[global]</literal> section,  and a <literal>[<replaceable>servername</replaceable>]</literal> section for each servername.  Settings in the <literal>[global]</literal> section affect all servernames, but can be overridden in a <literal>[<replaceable>servername</replaceable>]</literal> section.  For example</para>
			<example id="e.g.freetdsconf">
				<title>A &freetdsconf; file example</title>
				<programlisting>
					[global]
					tds version = auto
					
					[myserver]
					host = ntbox.mydomain.com
					port = 1433
					
					[myserver2]
					host = unixbox.mydomain.com
					port = 4000
					tds version = 5.0
					
					[myserver3]
					host = instancebox.mydomain.com
					instance = foo
					</programlisting>
				</example>

<para>In this example, the default  <acronym>TDS</acronym> version for all servernames is set to <literal>auto</literal>.  It is then overridden for <literal>myserver2</literal> (a Sybase server) which uses <literal>5.0</literal>.</para>

<para>Usually, it is sufficient to state just the server's hostname and TDS protocol version.  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.</para></tip></para>

<para>It bears mentioning here that prior versions of &freetds; were quite fussy about domain logins, forcing users to make explicit per-server entries in &freetdsconf;.  That is no longer the case.  If the username has the form <parameter>DOMAIN\username</parameter>, &freetds; will automatically use a domain login.</para>
			<table id="tab.freetds.conf">
				<title>&freetdsconf; settings</title>
				<tgroup cols="4">
					<thead>
						<row>
							<entry>Name</entry>
							<entry>Possible Values</entry>
							<entry>Default</entry>
							<entry>Meaning</entry>
							</row>
						</thead>
					<tbody>
						<row>
							<entry><literal>tds version</literal></entry>
							<entry>4.2, 5.0, 7.0, 7.1, 7.2, 7.3, 7.4, <literal>auto</literal></entry>
							<entry><parameter>--with-tdsver</parameter> value (<literal>auto</literal> if unspecified)
								Overridden by <link  linkend="TDSVER">TDSVER</link>.</entry>
							<entry>The <acronym>TDS</acronym> protocol version to use when connecting.  <quote><literal>auto</literal></quote> tells &freetds; to use an autodetection (trial-and-error) algorithm to choose the protocol version. </entry>
							</row>
						<row>
							<entry><literal>host</literal></entry>
							<entry>host name or IP address</entry>
							<entry>none</entry>
							<entry>The host that the servername is running on.</entry>
							</row>
						<row>
							<entry><literal>port</literal></entry>
							<entry>any valid port</entry>
							<entrytbl cols="3">
								<thead>
									<colspec colname= 'prd' colsep='0' rowsep='0'/>
									<colspec colname= 'ver' colsep='0' rowsep='0'/>
									<colspec colname= 'def' colsep='0' rowsep='0'/>
									<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 servername is listening to.
								<emphasis>Please note:</emphasis>
								The "defaults" to the left are the server's default settings.   &freetds; chooses its default port based on the TDS protocol version: <literal>5000</literal> for <acronym>TDS</acronym> <literal>5.0</literal>, and <literal>1433</literal> for everything else.  Mutually exclusive with <emphasis>instance</emphasis>, below.
								Overridden by <link  linkend="TDSPORT">TDSPORT</link>. </entry>
							</row>
						
						<row>
							<entry><literal>instance</literal></entry>
							<entry>instance name</entry>
							<entry>none</entry>
							<entry><para>Name of Microsoft SQL Server <emphasis>instance</emphasis> to connect to. The port will be detected automatically.  Mutually exclusive with <emphasis>port</emphasis>, above.  Requires UDP connection to port 1434 on the server.</para></entry>
							</row>
						
						<row>
							<entry id="asa.database"><literal>ASA database</literal></entry>
							<entry>valid database name</entry>
							<entry>servername [<replaceable>section</replaceable>] name</entry>
							<entry>Specifies the name of the default database when connecting to an ASA server.  A TDS 5.0 login packet has a field called <literal>lservname</literal>.   For most TDS servers, <literal>lservname</literal> is a user-defined string with no inherent meaning.  ASA servers, however, requires that <literal>lservname</literal>  contain a valid database name, and sets that as the default database for the connection. &freetds; normally fills <literal>lservname</literal>  with the [<replaceable>section</replaceable>] text..   This entry instead sets the database name independently of the [<replaceable>section</replaceable>] name.   </entry>
							</row>

						<row>
							<entry><literal>database</literal></entry>
							<entry>valid database name</entry>
							<entry>none</entry>
							<entry>Specifies the name of the default database.
This is the name of the database container in the server you are connecting to.</entry>
							</row>
						
						<row>
							<entry><literal>initial block size</literal></entry>
							<entry>multiple of 512</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>
							</row>
						
						<row>
							<entry><literal>dump file</literal></entry>
							<entry>any valid file name</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>
							</row>
						<row>
							<entry><literal>dump file append</literal></entry>
							<entry>yes/no</entry>
							<entry>no</entry>
							<entry>Appends dump file instead of overwriting it.  Useful for debugging when many processes are active.</entry>
							</row>
						<row>
							<entry><literal>timeout</literal></entry>
							<entry>0-</entry>
							<entry>none</entry>
							<entry>Sets period to wait for response of query before timing out.</entry>
							</row>
						<row>
							<entry><literal>connect timeout</literal></entry>
							<entry>0-</entry>
							<entry>none</entry>
							<entry>Sets period to wait for response from connect before timing out.</entry>
							</row>
						<row>
							<entry><literal>emulate little endian</literal></entry>
							<entry>yes/no</entry>
							<entry>yes</entry>
							<entry>Forces big endian machines (Sparc, PPC, PARISC, MIPS) to act as little endian to communicate with server.
								Ignored, always use little endian at protocol level.</entry>
							</row>
						<row>
							<entry id="clientcharset"><literal>client charset</literal></entry>
							<entry>any valid iconv character set</entry>
							<entry>ISO-8859-1<footnote><para>Valid for ISO 8859-1 character set.  See <link linkend="Localization">Localization and <acronym>TDS</acronym> 7.0</link> for more information.</para></footnote></entry>
							<entry>Makes &freetds; use iconv to convert to and from the specified character set from UCS-2 in <acronym>TDS</acronym> 7.0 or above.
								&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>
							</row>
						<row>
							<entry><literal>text size</literal></entry>
							<entry>0 to 4,294,967,295</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</command> in the <acronym>T-SQL</acronym> documentation for your server.  </entry>
							</row>
						<row>
							<entry><literal>debug flags</literal></entry>
							<entry>Any number even in hex or octal notation</entry>
							<entry>0x4fff</entry>
							<entry>Sets granularity of logging. A bitmask. See table below for specification.</entry>
							</row>
						<row>
							<entry><literal>encryption</literal></entry>
							<entry>off/request/require</entry>
							<entry>request (if tds version &gt; 7.1 otherwise off)</entry>
							<entry>Specify if encryption is desired. Supported for Microsoft servers. <symbol>off</symbol> disables encryption; <symbol>request</symbol> means use if available; <symbol>require</symbol> means create and allow encrypted connections only.</entry>
							</row>
						<row>
							<entry><literal>enable gssapi delegation</literal></entry>
							<entry>on/off</entry>
							<entry>off</entry>
							<entry>Enable delegation flag using Kerberos.</entry>
							</row>
						<row>
							<entry><literal>realm</literal></entry>
							<entry>any</entry>
							<entry>default Kerberos realm</entry>
							<entry>Specify Kerberos realm.</entry>
							</row>
						<row>
							<entry><literal>SPN</literal></entry>
							<entry>any</entry>
							<entry>MSSQLSvc/fqdn:port</entry>
							<entry>Specify Kerberos SPN.</entry>
							</row>
						<row>
							<entry><literal>mutual authentication</literal></entry>
							<entry>on/off</entry>
							<entry>off</entry>
							<entry>Enable mutual authentication flag using Kerberos.
								Always enabled for TDS 7.0 or above.</entry>
							</row>
						<row>
							<entry><literal>use ntlmv2</literal></entry>
							<entry>yes/no</entry>
							<entry>yes</entry>
							<entry>Use NTLMv2.  An alternative to the <literal>UseNTLMv2</literal> option in <filename>odbc.ini</filename>.  </entry>
							</row>
						<row>
							<entry><literal>use lanman</literal></entry>
							<entry>yes/no</entry>
							<entry>no</entry>
							<entry>Use LAN MANAGER for NTLM.  This is a very old encryption.  Should not be enabled unless you have a really old server.</entry>
							</row>
						<row>
							<entry><literal>use utf-16</literal></entry>
							<entry>yes/no</entry>
							<entry>no</entry>
							<entry>Instead of using UCS-2 for database wide character encoding use UTF-16.  Newer Windows versions use this encoding instead of UCS-2. This could result in some issues if clients assume that a character is always 2 bytes.</entry>
							</row>
						<row>
							<entry><literal>ca file</literal></entry>
							<entry>any filename or <literal>system</literal></entry>
							<entry>none</entry>
							<entry>File that hold root certificates (in PEM format) to verify server certificate, used during an encrypted connection.
If not specify or empty any certificate will be accepted from server.
If you specify <literal>system</literal> &freetds; will use system wide certificate list.
If a certiticate is not installed server can generate a self signed certificate, in this case is useful to disable certificate validation (which is the default).
Note that is not possible to specify a directory as usually database servers does not use a certificate signed by a public global certification authority.
</entry>
							</row>
						<row>
							<entry><literal>crl file</literal></entry>
							<entry>any filename</entry>
							<entry>none</entry>
							<entry>File that hold certificate revocation list. Only used if <literal>ca file</literal> is also specified.
</entry>
							</row>
						<row>
							<entry><literal>check certificate hostname</literal></entry>
							<entry>yes/no</entry>
							<entry>yes</entry>
							<entry>Check is the hostname is valid in the certificate. Only used if <literal>ca file</literal> is also specified.
</entry>
							</row>
						<row>
							<entry><literal>read-only intent</literal></entry>
							<entry>yes/no</entry>
							<entry>no</entry>
							<entry>Tell server we only intent to do read-only queries.
This is supported from MSSQL 2012.
</entry>
							</row>
						<row>
							<entry><literal>enable tls v1</literal></entry>
							<entry>yes/no</entry>
							<entry>yes</entry>
							<entry>Enable or disable TLS version 1.0. Useful to increase security. Not too recent Windows version (like Windows 2008) does not enable higher versions by default so be aware.</entry>
							</row>
						</tbody>
					</tgroup>
				</table>
			<sect3> <title>Overrides</title>

<para>Many settings in &freetdsconf; can be overridden by <link linkend="envvar">environment variables</link>.</para>

<para>The servername can also be decorated adding the port or instance name using <link linkend="PortOverride">port override syntax</link>.</para>
				</sect3>
			<sect3> <title>Controlling log details</title>
				<abstract><para>The logging capability has helped solve innumerable 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> </abstract>
				

<para>The log's granularity can be controlled with the <literal>debug flags</literal> entry. The default value (<literal>4FFF</literal> 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</literal> entry in &freetdsconf;</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 wonderful world of &freetds; logs, see <link linkend="logging">Logging</link>.</para>
				</sect3>
			
			<sect3><title>Deprecated options</title>

<para>The following options have long been deprecated.</para>
				
				<itemizedlist id="lst.freetds.conf.deprecated" spacing="compact">
					<title>Deprecated &freetdsconf; settings</title>
					<listitem><para><symbol>try server login</symbol></para></listitem>
					<listitem><para><symbol>try domain login </symbol></para></listitem>
					<listitem><para><symbol>nt domain </symbol></para></listitem>
					<listitem><para><symbol>cross domain login </symbol></para></listitem>
					<listitem><para><symbol>debug level </symbol></para></listitem>
					</itemizedlist>
				</sect3>
			
			</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.  &freetds;  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</filename> will probably be dropped from &freetds; one day.  Its only real purpose now is to control the format of date strings.  The Right Way&trade; to deduce the appropriate default date format is from the application's locale settings, while allowing an override in &freetdsconf;.  That's the direction we're headed.</para>

<para>If your purpose is to affect the client charset description, use &freetdsconf; instead.</para>
				</important>

<para>Information on locales and locale strings is easily (even too easily!) found on the Internet, or see <command>man locale</command> for your system.  &freetds; will examine its environment for a <literal>LOCALE</literal> string.  If it finds one, it will look it up in <filename>locales.conf</filename> 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 &freetdsconf;, the location of <filename>locales.conf</filename> is determined by the value of <option>--sysconfdir</option> to <command>configure</command>.  The default is <literal>PREFIX/etc</literal>.</para>
			</sect2>
		<sect2 id="localesformat">
			<title>What it looks like</title>

<para>The format of <filename>locales.conf</filename> is similar to that of &freetdsconf;.  There is a <literal>[default]</literal> section, and a section for each locale.
				
				<filename>locales.conf</filename> controls three settings
				<variablelist id="tab.locales.conf">
					<varlistentry>
						<term><literal>date format</literal></term>
						<listitem>

<para>This entry will be passed (almost) literally to <function>strftime(3)</function> to convert dates to strings.</para>

<para>For the most part, see you system documentation for <function>strftime(3)</function> (<command>man 3 strftime</command>).  You will see there though that <function>strftime(3)</function> has no provision for milliseconds.  The <filename>locales.conf</filename> format string uses <literal>%z</literal> for milliseconds.  <note><para>If your system's <function>strftime(3)</function> does employ <literal>%z</literal> for its own use, it will not be given that chance by &freetds;.  &freetds; will consume the <literal>%z</literal> for its milliseconds needs, and will not pass it on to <function>strftime(3)</function>.</para></note></para>
							</listitem>
						</varlistentry>
					<varlistentry>
						<term><literal>language</literal></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>&freetds; issues a few messages of its own.  Messages from the server are called <quote>messages</quote>; those from the client library (i.e., from &freetds;) are called <quote>error messages</quote>.  &freetds;-issued messages are not affected by <filename>locales.conf</filename>.</para></note></para>
							</listitem>
						</varlistentry>
					<varlistentry>
						<term><literal>charset</literal></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>Environment variables</title>
		<sect2 id="Whatfor">
			<title>What they're for</title>

<para>You can use environment variables to
				<itemizedlist>
					<listitem><para>Override some of the settings in &freetds;'s configuration file.</para></listitem>
					<listitem><para>Advertise the location of the &freetds; libraries to programs that want them.</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</envar> 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 &freetdsconf; file.  In prior versions of &freetds; 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</acronym> protocol used to connect to your server.  For a given server, &freetds; inspects four sources in the following order to determine which <acronym>TDS</acronym> 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 &freetdsconf; 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> 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 servername is listening.  It overrides the default port (1433 for TDS 4.2/7.0/7.1/7.2/7.3/7.4, 4000 for TDS 5.0) as well as any port specified in the &freetdsconf; file.</para>
						</listitem>
					</varlistentry>
				<varlistentry>
					<term id="SYBASE"><envar>SYBASE</envar></term>
					<listitem>

<para>points to the &freetds; 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 &freetds; 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 &freetdsconf;.</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=7.4</userinput></screen></para>

<para>In <application>csh</application>:
				
<screen>
	<prompt>$ </prompt><userinput>setenv SYBASE /usr/local/freetds</userinput>
	<prompt>$ </prompt><userinput>setenv TDSVER 7.4</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="PortOverride">
		<title>Port/instance override syntax</title>
		

<para>The port to which to connect can be overridden using a &freetds; extended syntax.</para>
		

<para>A port may be appended to the servername in the form  <literal><replaceable>servername</replaceable>:<replaceable>port</replaceable></literal>.  &freetds; will attempt to connect to specified port. Please note <replaceable>port</replaceable> must be a number; a service name is not supported.</para>
		

<para>If you specify <literal><replaceable>servername</replaceable>\<replaceable>instance</replaceable></literal>
			as servername during login, &freetds; will attempt to connect to specified instance.
			Only Microsoft SQL Server instances are supported.  (This server feature was introduced with Microsoft SQL Server 2000.)</para>
		

<para>Note that other &freetdsconf; properties still apply.</para>

<para>For the technically curious: each Microsoft SQL Server <firstterm>instance</firstterm> appears on the network as a server listening at a port.
The old way &mdash; and it still works &mdash; is to designate each instance in &freetdsconf; as a separate server.
The new <quote>named instance</quote> notation, if we can call it that, instead uses the server to discover the port.
The library sends a UDP packet containing the instance name to the server at a <emphasis>well known port</emphasis>, port 1434.
The server responds with a port number.
&freetds; then uses that number to connect in the usual way.</para>
		</sect1>
	
	<sect1 id="ConfirmInstall" xreflabel="Confirm the installation">
		<title>Confirm the installation</title>
		

<para>We want to make sure that when your application requests a connection to your server, it actually works.  In detail, we want to know:
			<itemizedlist>
				<listitem><para>&freetds; can find and read &freetdsconf;</para></listitem>
				<listitem><para><replaceable>servername</replaceable> exists in &freetdsconf;</para></listitem>
				<listitem><para>a <replaceable>host</replaceable> property exists for <replaceable>servername</replaceable></para></listitem>
				<listitem><para><replaceable>host</replaceable> can be resolved to a network address</para></listitem>
				<listitem><para>the server is listening to the <replaceable>port</replaceable> or named <replaceable>instance</replaceable></para></listitem>
				<listitem><para>the user can log in to the server</para></listitem>
<!-- listitem><para></para></listitem -->
				</itemizedlist>
						
			Each of the above can be confirmed independently with tsql.  Once you're sure you can connect and log in, you can run the unit tests to see if the software works as promised.</para>
		
		<sect2 id="tsql"><title><application>tsql</application></title>
			

<para>The <firstterm>tsql</firstterm> utility is provided as part of &freetds; expressly for troubleshooting.  <command>tsql</command> is superficially similar to an <command>isql</command>, but uses <filename>libtds</filename> directly, bypassing the client libraries (e.g., &dblib;).  It can also  report where it looks for &freetdsconf; and other compile-time settings (with <command>tsql -C</command>).</para>
			<example id="e.g.tsqlShowsettings">
				<title>Show compile-time settings with <command>tsql</command></title>
<screen>
	<prompt>$ </prompt><userinput>tsql -C </userinput>
	<prompt>Password: </prompt>
	<computeroutput>Compile-time settings (established with the "configure" script)
                        	    Version: freetds v&version;
        	     freetds.conf directory: /usr/local/etc
	     MS db-lib source compatibility: no
        	Sybase binary compatibility: no
                	      Thread safety: yes
                	      iconv library: yes
                        	TDS version: auto
                        	      iODBC: no
                        	   unixodbc: no
        	      SSPI "trusted" logins: no
                        	    Keberos: no
                                    OpenSSL: yes
                                     GnuTLS: no
                                       MARS: yes </computeroutput></screen>
	</example>
	

<para>For details on the use of <command>tsql</command>, consult its man page.</para>
			
			<sect3 id="tsql.freetds.conf"><title><replaceable>servername</replaceable> Lookup</title>

<para>If all goes well, the first time you fire up <command>tsql</command> it connects and you can issue your first query.  More often, though, the result is less joyous.  Listed below for your troubleshooting pleasure are a variety of <replaceable>servername</replaceable> lookup failures and their corresponding messages.</para>

<para>When <replaceable>servername</replaceable> cannot be converted to an address, up to two messages may result.  Successful conversion (by any means) never produces an error message.
					
					<example id="e.g.notfound">
						<title>Failure to find <replaceable>servername</replaceable> in &freetdsconf;</title>
<screen>
	<prompt>$ </prompt><userinput>tsql -S <replaceable>nobox</replaceable> -U <replaceable>sa</replaceable> </userinput>
	<prompt>Password: </prompt>
	<computeroutput>locale is "C"
	locale charset is "646"
	Password:
	Error 20012 (severity 2):
	Server name not found in configuration files.
	Error 20013 (severity 2):
	Unknown host machine name.
	There was a problem connecting to the server
	</computeroutput>
	<prompt>$ </prompt><userinput>host nobox</userinput>
	<computeroutput>Host not found.</computeroutput></screen>
	</example>
	
					In the above case message 20012 indicates <literal>nobox</literal> was not found in &freetdsconf;.  The library then treated <literal>nobox</literal> as a network hostname but found it also not to be valid per DNS, leading to message 20013.</para>
				

<para>If <replaceable>servername</replaceable> is found in the configuration files, but refers to an invalid hostname, only message 20013 is returned.
					
					<example id="e.g.badname">
						<title>Failure to resolve hostname for <replaceable>servername</replaceable></title>
<screen>
	<prompt>$ </prompt><userinput>tsql -S <replaceable>nonesuch</replaceable> -U <replaceable>sa</replaceable>   </userinput>
	<prompt>Password: </prompt>
	<computeroutput>locale is "C"
	locale charset is "646"
	Error 20013 (severity 2):
	Unknown host machine name.
	There was a problem connecting to the server</computeroutput></screen>
	</example>
	Unfortunately, the <quote>host machine name</quote> (the right side of the <literal>host</literal> line in &freetdsconf;) isn't mentioned in the error message.  Fortunately, this kind of setup problem is rarely encountered by users.</para>
	</sect3>
	<sect3 id="tsql.connect"><title>Connecting to the Server</title>

<para>If name lookup succeeds, &freetds; next attempts to connect to the server.  <emphasis>To connect</emphasis> means to form at TCP connection by calling <function>connect(2)</function>.  A valid connection must exist before any information can be exchanged with the server.  Specifically, we need a connection before we can log in.</para>

<para>A few things can go wrong at this point.  The address returned by DNS may not be that of the machine hosting the server, or indeed of <emphasis>any</emphasis> machine!  The machine may be down.  The server may not be running.  The server may be running but not listening to the port &freetds; is attempting to connect to.  In rare cases, both ends are correctly configured, but a firewall stands in the way.</para>

<para>If no server accepts the connection, no connection can be established.  It's difficult to know why, and the message is consequently vague.
					
					<example id="e.g.noconnect">
						<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>Msg 20009, Level 9, State -1, Server OpenClient, Line -1
	Unable to connect: Adaptive Server is unavailable or does not exist
	There was a problem connecting to the server</computeroutput></screen>
	</example>
	If you get message 20009, remember you haven't connected to the machine.  It's a configuration or network issue,  <emphasis>not a protocol failure</emphasis>.  Verify the server is up, has the name and IP address &freetds; is using, and is listening to the configured port.</para>

<para>Named instances provide another way for connections to fail.  You can verify the instance name and the port the server is using with <command>tsql -L</command>.
					
					<example id="e.g.instance.name">
						<title>Getting instance information with tsql</title>
<screen>
	<prompt>$ </prompt><userinput>tsql -LH <replaceable>servername</replaceable> </userinput>
	<computeroutput>locale is "C"
	locale charset is "646"
	ServerName TITAN
	InstanceName MSSQLSERVER
	IsClustered No
	Version 8.00.194
	tcp 1433
	np \\TITAN\pipe\sql\query</computeroutput></screen>
	</example>
	<replaceable>servername</replaceable> could be configured to use instance <literal>MSSQLSERVER</literal> or port <literal>1433</literal>.</para>
	

<para>After a valid connection is formed, &freetds; sends a login packet.  The TDS protocol provides no way to interrogate the server for its TDS version.  If you specify the wrong one, you'll get an error.
					
					<example id="e.g.bad.tdsver">
						<title>Using the wrong protocol for the server</title>
<screen>
	<prompt>$ </prompt><userinput>tsql -S <replaceable>servername</replaceable> </userinput>
	<prompt>Password: </prompt>
	<computeroutput>Msg 20017, Level 9, State -1, Server OpenClient, Line -1
	Unexpected EOF from the server
	Msg 20002, Level 9, State -1, Server OpenClient, Line -1
	Adaptive Server connection failed
	There was a problem connecting to the server</computeroutput></screen>
	</example>
	
					<quote>Unexpected EOF from the server</quote> seems to be a fairly common message when the wrong TDS version is used.  Note that there's no complaint about the login.</para>
				

<para>If the right TDS version is used, the server will accept the login packet and examine its contents to authenticate the user.  If there's a problem, the server will say so.  This is the first time we're receiving a message from the server.  <footnote><para>If you'd like to help the project and want to so something fairly easy but still useful, modify tsql to distinguish clearly between errors returned by the library, and those returned by the server.  Errors should be marked <quote>error</quote> and don't return <emphasis>state</emphasis> or a line number, but can contain an error code (and message) from the operating system.</para></footnote>
										
					<example id="e.g.bad.login">
						<title>Login failure</title>
<screen>
	<prompt>$ </prompt><userinput>tsql -S <replaceable>servername</replaceable> -U notme </userinput>
	<prompt>Password: </prompt>
	<computeroutput>Msg 18456, Level 14, State 1, Server [<replaceable>servername</replaceable>], Line 0
	Login failed for user 'notme'.
	Msg 20002, Level 9, State -1, Server OpenClient, Line -1
	Adaptive Server connection failed
	There was a problem connecting to the server</computeroutput></screen>
	</example></para>
	
				<bridgehead renderas='sect3'>Bypassing &freetdsconf;:</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>
					
					Keep in mind that the TDS protocol version normally comes from &freetdsconf;.  When using <command>tsql</command> this way, the library uses the compiled-in default (set by the <filename>configure</filename> script).  If that's not what you want, override it using the <envar>TDSVER</envar> environment variable.</para>
				
				<example id="e.g.tsqlhostname">
					<title>Connect with <command>tsql</command> using a hostname and port number</title>
<screen>
	<prompt>$ </prompt><userinput>TDSVER=auto tsql -H <replaceable>hillary</replaceable> -p <replaceable>4100</replaceable> -U <replaceable>sa</replaceable></userinput>
	<prompt>Password: </prompt>
	<computeroutput>1></computeroutput></screen>
	</example>
	

<para>For details on <command>tsql</command>, see the its man page.</para>
				</sect3>
			</sect2>
		<sect2 id="Tests"><title><application>Unit Tests</application></title>

<para>The source code directory of each &freetds; library includes a <filename>unittests</filename> directory.
Although the directories are named <filename>unittests</filename> they are not unit tests, most of them require a configured database to work.
				
<screen>
	<prompt>$ </prompt><userinput>ls -d -1 src/*/unittests</userinput>
	<computeroutput>src/ctlib/unittests
	src/dblib/unittests
	src/odbc/unittests
	src/replacements/unittests
	src/tds/unittests
	src/utils/unittests</computeroutput></screen>
	
The tests rely on the <filename>PWD</filename> file in root of the &freetds; source tree.
<filename>PWD</filename> 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.md</filename>.</para>

<para>To invoke the tests, edit the <filename>PWD</filename> file (you can copy from <filename>PWD.in</filename> which is a template) and issue the command <command>make check</command>.
In order to execute all tests successfully, you must indicate a working, available servername in <filename>PWD</filename>.
Some tests require permission to create stored procedures on server.
In addition, some may require that a database named <literal>freetds_test</literal> exists on the server, and the user whose credentials are used during the testing process has sufficient permissions to create and manipulate tables in this database.</para>

<para>To complete successfully, the ODBC tests require some additional setup.
In your <filename>PWD</filename> file, add a <literal>SRV</literal> entry specifying the DSN entry for your <filename>odbc.ini</filename>.
The ODBC tests all build their own <filename>odbc.ini</filename> 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><tip><para>
						The <filename>PWD</filename> provided by &freetds; includes usernames and passwords that probably don't exist on your server.
</para></tip></para>
			</sect2>
		</sect1>
	
	</chapter>
<chapter id="prepodbc" xreflabel="Preparing ODBC">
	<title>Preparing ODBC</title>
	<sect1 id="OdbcBackground"><title>Background and Terminology</title>

<para>To connect to a database server, a library such as &freetds; needs some information about the connection.  By <emphasis>server</emphasis>, 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</filename> file.  <filename>odbc.ini</filename> stored information about a server, known generically as a <firstterm>Data Source Name</firstterm> (DSN).  ODBC applications connected to the server by calling the function <function>SQLConnect(DSN, UID, PWD)</function>, where <replaceable>DSN</replaceable> is the Data Source Name entry in <filename>odbc.ini</filename>, <replaceable>UID</replaceable> is the username, and <replaceable>PWD</replaceable> the password. Any and all information about the DSN was kept in <filename>odbc.ini</filename>.  And all was right with the world.</para>

<para>The ODBC 3.0 specification introduced a new function: <function>SQLDriverConnect</function>.
			The connection attributes are provided as a single argument, a string of concatenated name-value pairs.  <function>SQLDriverConnect</function> subsumed the functionality of <function>SQLConnect</function>, in that the name-value pair string allowed the caller to pass &mdash;  in addition the the original <literal>DSN</literal>, <literal>UID</literal>, and <literal>PWD</literal> &mdash; 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</function>, obviating the need for <filename>odbc.ini</filename>.  This led to the use of the so-called <firstterm>DSN-less</firstterm> configuration, a setup with no <filename>odbc.ini</filename>.</para>

<para>But &freetds; did not start out as an ODBC driver (remember &dblib; and &ctlib;), and has always had its own way to store server properties: &freetdsconf;.  When Brian added the &freetds; ODBC driver, he began by supporting the old <function>SQLConnect</function>, using <filename>odbc.ini</filename> 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</filename> in effect points to &freetdsconf;.  We call this configuration <firstterm>ODBC-combined</firstterm>, because it supports all three &freetds; libraries.</para>

<para>As progress on the the &freetds; ODBC library progressed, the driver was made able to read the connection attributes directly from <filename>odbc.ini</filename>, rather than leaning on &freetdsconf;.  For installations that don't need &dblib; and &ctlib;, this <firstterm>ODBC-only</firstterm> setup is simpler.</para>

<para>More recently, <function>SQLDriverConnect</function> was added to &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 &freetds; ODBC terms</title>
			<varlistentry>
				<term><literal>SERVERNAME</literal></term>
				<listitem>

<para>specifies the <literal>[<replaceable>servername</replaceable>]</literal> entry in &freetdsconf;.</para>
					</listitem>
				</varlistentry>
			<varlistentry>
				<term><literal>SERVER</literal></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</literal></term>
				<term><literal>Driver</literal></term>
				<listitem>

<para>In your connection string, you can decide to use a DSN entry in <filename>odbc.ini</filename> using the <literal>DSN</literal> attribute, or to specify the driver you want with the <literal>Driver</literal> attribute.</para>
					</listitem>
				</varlistentry>
			</variablelist>
		

<para>In sum, &freetds; supports three ODBC choices:</para>
				
		<variablelist id="tab.ODBC.configuration.choices"><title>ODBC configuration choices</title>
			<varlistentry>
				<term>DSN-less</term>
				<listitem>

<para><emphasis>No</emphasis> connection information is specified in <filename>odbc.ini</filename>.  Advantageous if you're using more of &freetds; than just the ODBC driver.</para>
					</listitem>
				</varlistentry>
			<varlistentry>
				<term>ODBC-only</term>
				<listitem>

<para><emphasis>All</emphasis> connection information
						is specified in <filename>odbc.ini</filename>, without the need for &freetdsconf;.  This is the <quote>traditional</quote> ODBC setup.</para>
					</listitem>
				</varlistentry>
			<varlistentry>
				<term>ODBC-combined</term>
				<listitem>

<para>Connection information maintained in &freetdsconf;.  <filename>odbc.ini</filename> contains DSN entries that refer to servernames in &freetdsconf;.</para>
					</listitem>
				</varlistentry>
			</variablelist>

<para><tip><title>Library or Driver?</title>
<para>What's a <emphasis>library</emphasis> and what's a <emphasis>driver</emphasis>?  Technically, they're the same thing: bodies of subroutines whose names are exported to a linker (static or runtime).  By convention, a <quote>library</quote> is used directly by an application, whose programmer will require documentation and header files.  A <quote>driver</quote>, by contrast, is defined by a binary API and is used in some kind of framework, hence <emphasis>printer driver</emphasis> and <emphasis>video driver</emphasis>.  </para>

<para>An ODBC driver is a hybrid.  For the most part, an application relies on a driver manager to define manifest constants, and links to the DM's library.  But because the ODBC specification leaves behavior up to the driver, the application is forced to include the driver's header files, too, to exploit driver-specific functions.  </para></tip></para>		
		</sect1>

	<sect1 id="OdbcConnAttr">
		<title>Connection attributes</title>

<para>The following tables define all possible ODBC connection attributes for the &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</filename>.</para>
		

<para><table id="tab.Connection.attributes.stringonly"><title>Connection attributes used only in connection strings</title>
				<tgroup cols="4">
					<thead>
						<row>
							<entry>Name</entry>
							<entry>Possible Values</entry>
							<entry>Default</entry>
							<entry>Meaning</entry>
							</row>
						</thead>
					<tbody>
						<row>
							<entry><literal>DSN</literal></entry>
							<entry>A valid DSN entry</entry>
							<entry>none</entry>
							<entry>The <literal>DSN</literal> to which &freetds; should connect. &freetds; will search <filename>odbc.ini</filename> for entry.  It lets you specify a connection as for <function>SQLConnect</function>, but using <function>SQLDriverConnect</function>.   Do not use <literal>Servername</literal> and <literal>DSN</literal> together. </entry>
							</row>
						<row>
							<entry><literal>UID</literal></entry>
							<entry>Any valid username</entry>
							<entry>none</entry>
							<entry>The username to be used when connecting.  To use domain authentication, specify the domain using the format  <replaceable>domain\username</replaceable>.</entry>
							</row>
						<row>
							<entry><literal>PWD</literal></entry>
							<entry>Any</entry>
							<entry>empty</entry>
							<entry>The password to be used when connecting. </entry>
							</row>
						<row>
							<entry><literal>WSID</literal></entry>
							<entry>Any</entry>
							<entry>Computer name</entry>
							<entry>The name of the local computer, sent to server.   Can be specified only for a DSN-less connection.</entry>
							</row>
						</tbody>
					</tgroup>
				</table>
			
			<table id="tab.Connection.attributes.freetds.conf"><title>Connection attributes that may appear in <filename>odbc.ini</filename></title>
				<tgroup cols="4">
					<thead>
						<row>
							<entry>Name</entry>
							<entry>Possible Values</entry>
							<entry>Default</entry>
							<entry>Meaning</entry>
							</row>
						</thead>
					<tbody>
						<row>
							<entry><literal>Servername</literal></entry>
							<entry>A valid &freetdsconf; server section</entry>
							<entry>none</entry>
							<entry>A &freetdsconf; servername, not a hostname as known to DNS. If you want to use ODBC-only configuration, use  <literal>Server</literal> instead.</entry>
							</row>
						<row>
							<entry><literal>Server</literal></entry>
							<entry>A server name or (ip) address</entry>
							<entry>none</entry>
							<entry>Hostname of a server. Used in an ODBC-only configuration. To specify a Microsoft SQL Server instance, use the form <literal>server\instance</literal>.  </entry>
							</row>
						<row>
							<entry><literal>Port</literal></entry>
							<entry>Any TCP port</entry>
							<entry>Depends on the TDS version specified with <command>configure</command></entry>
							<entry>The TCP port  where the servername is listening.  </entry>
							</row>
						<row>
							<entry><literal>TDS_Version</literal></entry>
							<entry>Any valid protocol version</entry>
							<entry>Depends on the TDS version specified with <command>configure</command></entry>
							<entry>TDS protocol version to use (e.g., 5.0, 7.0).</entry>
							</row>
						<row>
							<entry><literal>ClientCharset</literal> or <literal>Client_Charset</literal></entry>
							<entry>A name recognized by the iconv library linked to &freetds;.  Corresponds to <literal>client charset</literal> in &freetdsconf;.
								<literal>Client_Charset</literal> is for compatibility with <productname>NCBI C++ ToolKit</productname>.</entry>
							<entry>ISO 8859-1</entry>
							<entry>Character set (encoding) used by the client.</entry>
							</row>
						<row>
							<entry><literal>APP</literal></entry>
							<entry>Free form text, up to 30 characters.  </entry>
							<entry>none</entry>
							<entry>Application name.  Identifies the connecting application to the server.  </entry>
							</row>
						<row>
							<entry><literal>Language</literal></entry>
							<entry>Any</entry>
							<entry>us_english</entry>
							<entry>(Human) language the server should use for error messages.</entry>
							</row>
						<row>
							<entry><literal>Address</literal></entry>
							<entry>Any</entry>
							<entry>none</entry>
							<entry>IP address of the servername.  Useful if you want to specify a server by address,  rather than by name.  The format is <replaceable>ip,port</replaceable>  or simply <replaceable>ip</replaceable> in standard dotted-decimal notation.   </entry>
							</row>
						<row>
							<entry><literal>Database</literal></entry>
							<entry>Any</entry>
							<entry>none</entry>
							<entry>Specify which database you want to access.  If the database does not exist or the user lacks permission to access it,  the connection will fail.</entry>
							</row>
						<row>
							<entry><literal>TextSize</literal></entry>
							<entry>Any</entry>
							<entry>Server-dependent</entry>
							<entry>Maximum size returned from server for blobs.</entry>
							</row>
						<row>
							<entry><literal>PacketSize</literal></entry>
							<entry>Any</entry>
							<entry>Server-dependent</entry>
							<entry>Size of packets to server.  Some users saw some performance gain by increasing this value.  Normally you shouldn't set it.  </entry>
							</row>
						<row>
							<entry><literal>Trusted_Connection</literal></entry>
							<entry>Yes/No</entry>
							<entry>No</entry>
							<entry>Use your current account instead of <literal>UID</literal>/<literal>PWD</literal> attributes.  This option require SSPI or Kerberos and supersedes any <literal>UID</literal>/<literal>PWD</literal> attributes passed from the application.</entry>
							</row>
						<row>
							<entry><literal>Encryption</literal></entry>
							<entry>off/request/require</entry>
							<entry>off</entry>
							<entry>Specify encryption. See encryption on freetds.conf</entry>
							</row>
						<row>
							<entry><literal>MARS_Connection</literal></entry>
							<entry>Yes/No</entry>
							<entry>No</entry>
							<entry>Enable MARS for this connection.</entry>
							</row>
						<row>
							<entry><literal>UseNTLMv2</literal></entry>
							<entry>Yes/No</entry>
							<entry>No</entry>
							<entry>Use NTLMv2 instead of normal NTLM. Use this option if your Windows domain have this setting.</entry>
							</row>
						<row>
							<entry><literal>REALM</literal></entry>
							<entry>Machine domain</entry>
							<entry>none</entry>
							<entry>Kerberos REALM.</entry>
							</row>
						<row>
							<entry><literal>ServerSPN</literal></entry>
							<entry>Any valid SPN</entry>
							<entry>MSSQLSvc/server FQDN:port</entry>
							<entry>Full server Kerberos SPN.</entry>
							</row>
						<row>
							<entry><literal>AttachDbFilename</literal></entry>
							<entry>server filename (mdf/sdf)</entry>
							<entry>none</entry>
							<entry>MSSQL allow to attach a database while connecting to a server.
This setting allow to do it. You should specify <literal>Database</literal> attribute to set the name of the database that will be used.</entry>
							</row>
						<row>
							<entry><literal>DumpFile</literal></entry>
							<entry>Any</entry>
							<entry></entry>
							<entry>File name where to dump logs.</entry>
							</row>
						<row>
							<entry><literal>DumpFileAppend</literal></entry>
							<entry>Yes/No</entry>
							<entry>No</entry>
							<entry></entry>
							</row>
						<row>
							<entry><literal>DumpFlags</literal></entry>
							<entry>Any</entry>
							<entry></entry>
							<entry>Debug flags. See freetds.conf entries.</entry>
							</row>
						<row>
							<entry><literal>ApplicationIntent</literal></entry>
							<entry>ReadWrite/ReadOnly</entry>
							<entry>ReadWrite</entry>
							<entry>Tell application intent. See <literal>read-only intent</literal> on freetds.conf.</entry>
							</row>
						<row>
							<entry><literal>Timeout</literal></entry>
							<entry>Integer number</entry>
							<entry></entry>
							<entry>Query timeout in seconds.</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 servername, your application may refer to a servername entry in &freetdsconf;, or explicitly specify the servername's hostname (bypassing &freetdsconf;).
			
			<example id="e.g.SampleDSNless">
				<title>Sample files for a DSN-less configuration</title>

<para>The <filename>odbcinst.ini</filename> is quite brief:</para>
<programlisting>
	;
	; odbcinst.ini
	;
	[FreeTDS]
	Driver = /usr/local/freetds/lib/libtdsodbc.so
	</programlisting>

<para>The &freetdsconf; might look something like:</para>
<programlisting>
	;
	; freetds.conf
	;
	[JDBC]
	host = jdbc.sybase.com
	port = 4444
	tds version = 5.0
	</programlisting>
				</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]</literal> entry in &freetdsconf;.</para></footnote>
	sprintf(tmp, "DRIVER=FreeTDS<footnote id="dsnOdbcinst"><para>refers to the <literal>[FreeTDS]</literal> entry in <filename>odbcinst.ini</filename>.</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), &amp;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 &freetdsconf;</title>
<programlisting>
	/*
	 * application call
	 */
	const char servername[] = "jdbc.sybase.com"; <footnote><para>refers to the real server name.</para></footnote>
	sprintf(tmp, "DRIVER=FreeTDS<footnoteref linkend="dsnOdbcinst" />;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), &amp;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</filename> for server properties.  Other &freetds; libraries don't know about <filename>odbc.ini</filename>.
			
			<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</quote>.  It matches the <literal>[JDBC]</literal> 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 &freetdsconf;.  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</filename> refers to the servername entry in &freetdsconf;.
			
			<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</quote>.  It matches the <literal>[JDBCdsn]</literal> 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]</literal> entry in  &freetdsconf;.</para></footnote>
	Database        = pubs2
	
	[Default]
	Driver          = /usr/local/freetds/lib/libtdsodbc.so
	</programlisting>
					</example>
				<example id="e.g.samplecombofile">
					<title>Sample ODBC-combined &freetdsconf; 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</literal>), or its servername (<literal>JDBC</literal>).</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</command>.  If you're intending to use &freetdsconf;, exercise it with
			<command>tsql -S <replaceable>servername</replaceable></command>.  If not, use
			<command>TDSVER=auto tsql -H <replaceable>hostname</replaceable> -p <replaceable>port</replaceable></command></para>

<para>If <command>tsql</command> works and <command>isql</command> doesn't, you've isolated the problem to the ODBC setup.  &freetds; might have some interoperability problems, but mere connection to the database isn't one of them!  If <command>tsql</command>
			doesn't work, turn on logging with <envar>TDSDUMP</envar>.  The log will tell you what TCP/IP name (and address) &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>&iODBC; comes with a sample command line query program called <command>odbctest</command>, located in the <filename>iodbc/samples</filename> directory.
Using this program you can get a listing of DSNs, connect, and issue queries.
	<tip><para>For debugging purposes, you may wish to link a program such as <command>odbctest</command> directly to &freetds; instead of to the driver manager.
<footnote><para>Why?  Once the program is started in the debugger, the driver entry points become viable breakpoints.
Because the DM loads the driver dynamically with <function>dlopen(3)</function>, no driver addresses even <emphasis>exist</emphasis> until the runtime linker loads it. </para></footnote>
To do so, compile and install the &odbc; driver with &iODBC; as normal <footnote><para>When linking directly to &freetds; you still need the Driver Manager's header files.</para></footnote>, then compile and link the program:
				
				<example id="e.g.odbctest.nodm">
					<title>Compile <filename>odbctest</filename> 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>
	
				Now you can run <command>gdb</command> or another debugger and set breakpoints on functions in the library without the driver manager getting in the way.</para></tip></para>
			</sect2>
		
		<sect2 id="with.unixODBC"><title>With unixODBC</title>
			

<para>Try <command>isql -v <replaceable>dsn</replaceable> <replaceable>username</replaceable> <replaceable>password</replaceable></command>, and have a look at the log.  See if the right address and TDS version are being used.  Adjust to taste.</para>
			<sect3 id="with.unixODBC.osql"><title>Use <command>osql</command></title>
				

<para>The <command>osql</command> utility is a Bourne shell script that checks your ODBC configuration.
If it approves, it invokes the &unixODBC; isql utility.
Cf. <command>man osql</command> for details on its use.
					
					<example id="e.g.odbcdiagnose.osql">
						<title>Use <command>osql</command> to test the ODBC setup.</title>
<screen>
	<prompt>$ </prompt><userinput>osql -S machine -U mr_ed -P hayseed</userinput>
	looking for odbc.ini and odbcinst.ini in /usr/local/etc
	reading "/usr/home/mr_ed/.odbc.ini"
	[machine] found in "/usr/home/mr_ed/.odbc.ini"
	found this section:
	[machine]
	Database = testdb
	Servername = machine
	Trace           = Yes
	TraceFile       = /tmp/unixodbc.trace

	looking for driver for DSN [machine]
	no driver mentioned for [machine] in .odbc.ini
	looking for driver for DSN [default]
	driver "FreeTDS" found for [default] in .odbc.ini
	found driver named "FreeTDS"
	FreeTDS is not a readable file
	looking for entry named [FreeTDS] in /usr/local/etc/odbcinst.ini
	driver "/usr/local/lib/libtdsodbc.so" found for [FreeTDS] in odbcinst.ini
	/usr/local/lib/libtdsodbc.so is a readable file
	Using ODBC-Combined strategy
	FreeTDS servername is "machine" (from /usr/home/mr_ed/.odbc.ini)
	looking for [machine] in /usr/home/mr_ed/.freetds.conf
	"/usr/home/mr_ed/.freetds.conf" is a readable file
	found this section:
	[machine]
	host = machine.example.com
	port = 2500
	tds version = 7.1

	machine.example.com has address 10.82.32.177

	DSN: machine
	Driver: /usr/local/lib/libtdsodbc.so
	Server's hostname: machine.example.com
	Address: 10.82.32.177

	Attempting connection as mr_ed ...
	+ exec isql machine mr_ed hayseed -v
	+---------------------------------------+
	| Connected!                            |
	|                                       |
	| sql-statement                         |
	| help [tablename]                      |
	| quit                                  |
	|                                       |
	+---------------------------------------+
	SQL></screen>
						</example></para>

<para>The reader is here advised that the <command>isql</command> that comes with many versions of &unixODBC; will truncate text and surprise in other ways without warning.
If it behaves strangely, try &freetds;'s <command>bsqlodbc</command> before you decide you've found a &freetds; bug.</para>

				</sect3>
			
			</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>Microsoft 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</acronym> Protocol version 7.0 is natively little endian.
<productname>Microsoft SQL Server 2000</productname> is also reported not to work from big endian clients without little endian emulation turned on.</para>
		<note><para>The terms <emphasis>big endian</emphasis> and <emphasis>little endian</emphasis> come originally from Gulliver's Travels.  In computer science they refer to the the integer byte-order for a processor.  Big endian processors, such as Sparc and PowerPC store the most significant byte in the first memory location of a multi-byte integer.  Little endian processors, 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 or above will automatically emulate little endian mode regardless of the &freetdsconf; setting.
			<emphasis>You shouldn't use this option, set another protocol version instead (7.0, 7.1, 7.2, 7.3 or 7.4)</emphasis>.</para>
		<example id="e.g.LittleEndian">
			<title>Emulate Little Endian &freetdsconf; setting</title>
<programlisting>
	[mssql]
	host = ntbox.mydomain.com
	port = 1433
	tds version = 4.2
	emulate little endian = yes
	</programlisting>
			</example>
		</sect1>
	<sect1 id="Localization">
		<title>Localization and <acronym>TDS</acronym> 7.0</title>

<para><acronym>TDS</acronym> 7.0 uses 2-byte Unicode (technically, <acronym>UCS-2</acronym>, recently <acronym>UTF-16</acronym>) to transfer character data between servers and clients.  Included in <quote>character data</quote> are query text (i.e., <acronym>SQL</acronym>), metadata (table names and such), and <foreignphrase>bona fide</foreignphrase> data of datatypes <literal>nchar</literal>, <literal>nvarchar</literal>, and <literal>ntext</literal>.  (Background information on Unicode and how it affects &freetds; can be found in the <link linkend="Unicode">appendix</link>.)</para>

<para>Because most Unix tools and environments do not support <acronym>UCS-2</acronym>, &freetds; provides for conversion by
the client to other character sets.
The mechanism used is determined by the <filename>configure</filename> script, which looks for a <function>iconv(3)</function> function,
an implementation of the <ulink url="http://www.opengroup.org/onlinepubs/7908799/xsh/iconv.html">iconv</ulink> standard.
If no <function>iconv</function> library is found, or if it is explicitly disabled, &freetds; will use its built-in
<function>iconv</function> substitute, and will be capable of converting among only <acronym>ISO 8859-1</acronym>, <acronym>UTF-8</acronym>,
<acronym>UCS-2</acronym>, <acronym>UTF-16</acronym> and <acronym>UTF-16</acronym>.</para>

<para>To learn what character set the client wants, &freetds; prefers the applicable <link linkend="clientcharset">&freetdsconf;</link> <literal>client charset</literal> property.  If that is not set, it parses the <envar>LANG</envar> environment variable.  In either case, the found string is passed to <function>iconv</function>(3) (or its built-in replacement).  <footnote><para>The built-in replacement expects GNU iconv names: <literal>ISO-8859-1</literal>, <literal>US-ASCII</literal>, or <literal>UTF-8</literal>.</para></footnote>.  If neither is found, <acronym>UCS-2</acronym> data are converted to <acronym>ISO 8859-1</acronym>.</para>
		

<para>To list all supported iconv character sets try <command>iconv</command>(1).  GNU's does:</para>
<screen>
	<prompt>$ </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 &freetdsconf; setting</title>
<programlisting>
	[mssql]
	host = ntbox.mydomain.com
	port = 1433
	client charset = GREEK
	</programlisting>
			</example>

<para>If &freetds; runs into a character it can not convert, its behavior varies according to the severity of the problem.  On retrieving data from the server, &freetds; substitutes an <acronym>ASCII</acronym> '?' in the character's place, and emits a warning message stating that some characters could not be converted.  On sending data to the server, &freetds; 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>.  <acronym>UTF-8</acronym> is a variable length unicode encoding that is compatible with <acronym>ASCII</acronym> in the range 0 to 127.  With <acronym>UTF-8</acronym>, you are guaranteed to never have an unconvertible character.</para>
		
		<important><para>&freetds; is not fully compatible with multi-byte character sets such as <acronym>UCS-2</acronym>.  You must use an ASCII-extension charset (e.g., UTF-8, ISO-8859-*)<footnote><para>not EBCDIC or other weird charsets</para></footnote>. Great care should be taken testing applications using these encodings. Specifically, many applications do not expect the number of characters returned to exceed the column size (in bytes).</para></important>

<para>In the following example, a server named <literal>mssql</literal> will return data encoded in the <acronym>UTF-8</acronym> character set.</para>
		<example id="e.g.UTF8">
			<title>Configuring for <acronym>UTF-8</acronym> &freetdsconf; setting</title>
<programlisting>
	[mssql]
	host = ntbox.mydomain.com
	port = 1433
	client charset = UTF-8
	</programlisting>
			</example>

<para>It is also worth clarifying that <acronym>TDS 7.0</acronym> and above do not accept any specified character set during login, as 4.2 does.  A <acronym>TDS 7.0</acronym> login packet uses <acronym>UCS-2</acronym>.</para>
		<sect2 id="localization.servernote"><title>Microsoft Server Note</title>

<para>String literals in SQL must be prefixed with 'N' unless the enclosed string can be represented in the server's <emphasis>single-byte</emphasis> character set, irrespective of the column's datatype.  For example, in the SQL statement
				
<informalexample><screen>
	INSERT INTO tablename (greeting) VALUES ('Hall&aring;')</screen></informalexample>
	
				the string is subject to somewhat surprising treatment by the server.</para>

<para>When the server parses the SQL, it extracts the data values for insertion (or update, or comparison, etc.)  Unprefixed strings are converted to the single-byte character set of the server/database.<footnote><para>The precise rules are unknown to the author.</para></footnote>   Inserted data are then of course stored in the column.  In the case of UCS-2 columns &mdash; <literal>nchar</literal>, <literal>nvarchar</literal>, and <literal>ntext</literal> &mdash; the value stored is that which results from a <emphasis>second</emphasis> conversion: from the single-byte form to the <acronym>UCS-2</acronym> form.</para>

<para>The <emphasis>only</emphasis> safe way to enclose strings in SQL text is with an 'N' prefix:
				
<informalexample><screen>
	INSERT INTO tablename (greeting) VALUES (N'Hall&aring;')</screen></informalexample>				</para>
	<bridgehead renderas='sect3'>Commentary</bridgehead>

<para>What's surprising about this?  Versions 7.0 and later of the TDS protocol use UCS-2 to send SQL text.  No matter how your local client is configured &mdash; with <acronym>UCS-2</acronym> or <acronym>ISO 8859-1</acronym> or anything else &mdash; it's converted to <acronym>UCS-2</acronym> before it's sent to the server.  And obviously arrives at the server as <acronym>UCS-2</acronym>.  If the column into which it's being inserted is also <acronym>UCS-2</acronym>, there's no need of <emphasis>any</emphasis> conversion, much less two, and <emphasis>certainly</emphasis> no need to lose information.</para>

<para>Why this happens is anyone's guess.  Here's one: it makes the datatype of the column unimportant.  Regardless of whether you use char/varchar/text or nchar/nvarchar/ntext or a mixture of the two, the arriving SQL (if na&iuml;vely written) will store exactly the same characters.</para>
			</sect2>
		</sect1>
	<sect1 id="domains">
		<title>Domain Logins</title>
		<note><para>Domain logins can be used only with TDS protocol versions 7.0 or above.</para></note>

<para>As mentioned in the installation chapter, <productname>Microsoft SQL Server</productname> includes the ability to use domain
	<footnote><para>The term <firstterm>domain</firstterm> 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 Microsoft SQL Server machine may belong to an NT domain. 
&freetds; provides an encrypted password &mdash; a domain password, known to the domain controller &mdash; that the server will ask the domain controller to verify.</para></footnote> 
logins instead of standard server logins.  Passwords are encrypted on the wire using a challenge-response protocol.  &freetds; plays nice with such logins.  </para>

<para>&freetds; supports single sign-on (connecting without prompting for a username &amp; password) or not, depending on how it was configured.  For Windows hosts (both 32- and 64-bit), if SSPI is enabled, &freetds; will log in using so-called <quote>trusted authentication</quote>.  For non-Windows hosts, enabling Kerberos provides similar functionality.  </para>

<para>When neither option is enabled, &freetds; can <emphasis>still</emphasis> log in using the domain account, but the user must supply the username &amp; password.</para>

<para>To use domain logins without SSPI or Kerberos, use the <literal>'DOMAIN\username'</literal> 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 &freetds; sees the <quote><literal>\</literal></quote> character, it automatically chooses a domain login.</para>
		
		<sect2 id="domaindetails">
			<title>Implementation details</title>

<para>Support for domain logins in &freetds; is limited to the TCP/IP network protocol stack.   &freetds; does not currently implement support for Named Pipe-based SQL connections &mdash; 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-licensed projects such as &freetds; .</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="kerberos">
		<title>Kerberos Support</title>
<para>Perhaps surprisingly, Kerberos can be used to authenticate to Microsoft SQL Servers.  
<footnote><para>It works because much of Active Directory is based on Kerberos.  <emphasis>From each according to his ability; to each according to his needs. </emphasis></para></footnote>
This affords single-signon (or, at most, <quote>double-signon</quote>) capability in non-Windows environment. </para>

<para>To take advantage of Kerberos you have to set up your machine with keytab
	<footnote><para>No, the author does not really know what he's talking about.</para></footnote> 
from your Active Directory.  You could use <ulink url="http://www.samba.org/">Samba</ulink> or configure Kerberos directly (<filename>/etc/krb5.conf</filename>).  <command>configure</command> includes options to define the location of your Kerberos installation  (cf. <xref linkend="Configure.Options"/>).  </para>

<para>By default UNIX does not initialize a Kerberos ticket with your login account. You must use <command>kinit</command> to initialize a ticket.  You could also configure Kerberos in PAM to initialize a Kerberos ticket at login time.</para>
		</sect1>
	
	<sect1 id="uothread">
		<title>Threading in unixODBC</title>

<para>&unixODBC; uses a strong thread-locking policy that causes big locks with the default configuration for &freetds;.
Performance of multi-threaded applications can be affected because every operation is serialized.
To avoid this problem, choose a threading model in <filename>odbcinst.ini</filename>.
			<example id="odbcinstthread">
				<title>Sample <filename>odbcinst.ini</filename> for threading model</title>
<programlisting>
	[FreeTDS]
	Driver = /usr/local/freetds/lib/libtdsodbc.so
	Threading = 1
	</programlisting>
				</example>
			<example id="odbcinithread">
				<title>Sample <filename>odbc.ini</filename> for threading model</title>
<programlisting>
	[Server1]
	Driver = FreeTDS
	Server = myServer1
	Port = 1433
	</programlisting>
				</example>
			You can use also a connection string e.g. <literal>DRIVER=FreeTDS;SERVER=myServer1;PORT=1433;</literal>.</para>
		</sect1>
		
	<sect1 id="appendmode">
		<title>Appending Dump Files</title>

<para>When running &freetds; 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  &freetdsconf;</title>
			<programlisting>
				[mssql]
				host = ntbox.mydomain.com
				port = 1433
				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 &freetds; logging, you might also consider using <command>tcpdump</command> or <ulink url="http://www.wireshark.org/">wireshark</ulink> to log network packets.  While not as useful as a <acronym>TDS</acronym> log, it can also help to identify problems.</para>
				
		</sect1>
	<sect1 id="tdspool">
		<title>TDS Connection Pooling</title>

<para>The Connection Pooling server swims in the <filename>src/pool</filename> directory.</para>

<para>The &freetds; connection pool is a server process; it emulates a <productname>SQL Server</productname>.  Any program that can attach to a real <productname>SQL Server</productname> may instead elect to attach to the pool server.  The pool in turn connects to the <productname>SQL Server</productname> and database you specify, and attempts to share these connections.  See the <filename>src/pool/README</filename> for a more detailed description of its inner workings.</para>

<para>To configure the pool server, first make sure &freetds; 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 &freetds; connection pool currently does not supports <acronym>TDS</acronym> version 5.0 (Sybase) and encrypted connections.
<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 was specified with the <command>configure</command> <option>--with-prefix flag</option> option).</para>

<para>Edit <filename>pool.conf</filename> in the &freetds;'s <filename>etc</filename> directory.  The <filename>pool.conf</filename> file is formatted like &freetdsconf;, with a section name in brackets and options for each section in key/value pairs.</para>

<para>Just as in &freetdsconf; 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>Possible Values</entry>
							<entry>Default</entry>
							<entry>Meaning</entry>
							</row>
						</thead>
					<tbody>
						<row>
							<entry>user</entry>
							<entry>Any valid user</entry>
							<entry>none</entry>
							<entry>The username used to connect to the pool server.</entry>
							</row>
						<row>
							<entry>password</entry>
							<entry>Any</entry>
							<entry>none</entry>
							<entry>The password of the user at the pool server.</entry>
							</row>
						<row>
							<entry>server user</entry>
							<entry>Any valid user</entry>
							<entry>user field</entry>
							<entry>The username used to connect to the servername.</entry>
							</row>
						<row>
							<entry>server password</entry>
							<entry>Any</entry>
							<entry>password field</entry>
							<entry>The password of the user at the servername.</entry>
							</row>
						<row>
							<entry>server</entry>
							<entry>Any entry in the freetds.conf file</entry>
							<entry>none</entry>
							<entry>The alias from the freetds.conf file representing the servername that will be connected to.</entry>
							</row>
						<row>
							<entry>database</entry>
							<entry>Any valid database</entry>
							<entry>User's default database</entry>
							<entry>The database on the servername to use.</entry>
							</row>
						<row>
							<entry>port</entry>
							<entry>Any TCP port</entry>
							<entry>none</entry>
							<entry>Port on which tdspool will listen.</entry>
							</row>
						<row>
							<entry>min pool conn</entry>
							<entry>0 or more</entry>
							<entry>none</entry>
							<entry>Minimum number of open connections to maintain to the servername.
							0 will cause pool server to not open any initial connection.</entry>
							</row>
						<row>
							<entry>max pool conn</entry>
							<entry>1 or more</entry>
							<entry>none</entry>
							<entry>Maximum number of open connections to open against the servername.</entry>
							</row>
						<row>
							<entry>max member age</entry>
							<entry>0 (no limit) or a number of seconds</entry>
							<entry>0</entry>
							<entry>Maximum age of idle members before connection is closed.</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</acronym>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>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 &freetdsconf; 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
					&freetdsconf;:</para>
				<example id="e.g.Unencrypted">
					<title>Unencrypted entry in &freetdsconf;</title>
<programlisting>
	[win2kserver]
	host = win2kserver
	port = 1433
	</programlisting>
					</example>

<para>   the encrypted equivalent uses:</para>
				<example id="e.g.Encrypted">
					<title>Encrypted entry in &freetdsconf;</title>
<programlisting>
	[win2kserver]
	host = localhost
	port = 1433
	</programlisting>
					</example>
				</listitem>
			</orderedlist>
		</sect1>
	</chapter>
<!-- ////////////////// CHAPTER /////////////////////// -->
<chapter id="usefreetds">
	<title>Use &freetds; </title>
	<abstract><para>&freetds;  includes several utilities.  Some are testing tools, some demonstration projects, some intended for day-to-day use.  All have man pages.</para></abstract>
	
	<sect1 id="utilities"><title>&freetds; Utilities</title>
		
		<variablelist><title>(listed alphabetically)</title>
			<varlistentry>
				<term>bsqldb</term>
				<listitem>

<para>  A non-interactive equivalent of the <symbol>isql</symbol> utility programs distributed by Sybase and Microsoft. Like them, <command>bsqldb</command> uses the command <quote>go</quote> on a line by itself as a separator between batches. The last batch need not be followed by <quote>go</quote>.</para>
					

<para><command>bsqldb</command> makes use of the &dblib; <acronym>API</acronym>. Intended for production use.</para>
					</listitem>
				</varlistentry>
			<varlistentry>
				<term>bsqlodbc</term>
				<listitem>

<para>A non-interactive equivalent of the <symbol>isql</symbol> utility programs distributed by Sybase and Microsoft. Like them, <command>bsqlodbc</command> uses the command <quote>go</quote> on a line by itself as a separator between batches. The last batch need not be followed by <quote>go</quote>.  It uses the &odbc; <acronym>API</acronym>.</para>
					

<para><command>bsqlodbc</command> is a demonstration project, but can also aid in isolating problems.  &odbc; applications typically have many layers, and it can be difficult to know if a problem arises in a layer, or in the interface between layers.  By executing a query in <command>bsqlodbc</command>, you can see if the functionality of the &odbc; driver works when used as the folks who wrote the driver thought it would be used.</para>
					</listitem>
				</varlistentry>
									
			<varlistentry>
				<term>datacopy</term>
				<listitem>

<para>A tool for migrating data between Sybase ASE and Microsoft SQL Server or vice versa.</para>
					

<para><command>datacopy</command> will move table data from one server to another without the need for intermediate files. <command>datacopy</command> is much faster and more efficient than is <command>freebcp</command> out/in.</para>

<para><command>datacopy</command> makes use of the &dblib; bcp <acronym>API</acronym>.</para>
					</listitem>
				</varlistentry>
			
			<varlistentry>
				<term>defncopy</term>
				<listitem>

<para>Replaces a similar program of the same name distributed by Sybase.</para>
					

<para><command>defncopy</command> reads the text of a stored procedure or view, and writes a script suitable for recreating the procedure or view. For tables, it reads  the output of <command>sp_help</command> and constructs a <literal>CREATE TABLE</literal> statement, complete with <literal>CREATE INDEX</literal>, too.</para>
					</listitem>
				</varlistentry>
			
			<varlistentry>
				<term>fisql</term>
				<listitem>

<para>A complete replacement of the <symbol>isql</symbol> utility programs distributed by Sybase and Microsoft. Like them, <command>fisql</command> uses the command <quote>go</quote> on a line by itself as a separator between batches.</para>
					</listitem>
				</varlistentry>
			
			<varlistentry>
				<term>freebcp</term>
				<listitem>

<para>Replicates the functionality of the <symbol>bcp</symbol> utility programs distributed by Sybase and Microsoft.</para>

<para><command>freebcp</command> makes use of the &dblib; bcp <acronym>API</acronym>.</para>

<para>The manual pages or online help for Sybase or Microsoft SQL Server can be referenced for more detailed information on bcp functionality.</para>
					</listitem>
				</varlistentry>
			
			<varlistentry>
				<term>osql</term>
				<listitem>

<para>A Bourne shell script that checks and reports on your configuration.</para>
					</listitem>
				</varlistentry>
			
			<varlistentry>
				<term>tsql</term>
				<listitem>

<para>A diagnostic tool that uses uses the lowest level &freetds; library, <symbol>libtds</symbol>, as a way to isolate potential  bugs  in  the  protocol implementation.</para>

<para><command>tsql</command> is <emphasis>not</emphasis> a replacement for a complete <symbol>isql</symbol>.</para>
					</listitem>
				</varlistentry>
			</variablelist>
		</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 &freetds;.  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</command> utility that ships with <productname>Sybase ASE</productname>.  It makes a great diagnostic tool for &freetds; 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><application>SQSH</application> is an excellent tool.  Because it uses &ctlib;, it works with &freetds;, but potentially &mdash; and with significant effort &mdash; it could be ported to ODBC and thus made useful for other server environments.  Just a thought&hellip;.</para></sidebar></tip>			</para>
		

<para><application>SQSH</application> 2.1 includes direct support for &freetds;, 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 <envar>Sybase</envar> environment variable first), look for the <literal>Sybase_LIBS</literal> definition in the <filename>Makefile</filename>.  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>
		</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 &freetds;.</para>

		<sect2 id="DBD.ODBC"><title>DBD::ODBC</title>

<para>The recommended choice is <systemitem class="library">DBD::ODBC</systemitem> with the &freetds; &odbc; driver.</para>
			</sect2>

		<sect2 id="DBD.Sybase"><title>DBD::Sybase</title>

<para>You may also use <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 &ctlib; <acronym>API</acronym> and works well. However the project has not been updated for a while.</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 &dblib;.</para>
			</sect2>
		<sect2 id="Perlmodules"><title>Building and using the Perl modules</title>

<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</acronym> 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></para>

<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</acronym> 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>

You'll note this is the same program as for <systemitem class="library">DBD::ODBC</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 &freetds; corresponding to the three <acronym>API</acronym>s that &freetds; supports: &dblib;, &ctlib;, and &odbc;.
			<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>&dblib;</title>

<para>PHP can be configured with &dblib; access for a "Sybase" server (which also works with Microsoft servers), or with the <emphasis>mssql</emphasis> extension, intended exclusively for Microsoft servers.</para>

<para><example id="e.g.PHP.dblib"><title>PHP and &dblib; for <quote>Sybase</quote></title>

<para>First build &freetds; 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>&ctlib;</title>

<para>Option 2 is to use the &ctlib; <acronym>API</acronym>.  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 &freetds; 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 &freetds; just as you would for &dblib; in
				<link linkend="phpDblib"> with &dblib;</link>, above. Then configure PHP with &ctlib;.
	<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 &freetds; and include only the <literal>-lct</literal> library.</para>
	</sect2>
	<sect2 id="ODBC">
	<title>&odbc;</title>

<para>The third and newest option is to use the &freetds; &odbc; driver with PHP.
First build the &iODBC; or &unixODBC; driver manager and &freetds; as detailed in <xref linkend="prepodbc"/>.
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 &freetds; samples directory called <filename>odbctest.php</filename>.</para>
	</sect2>
	</sect1>
	<sect1 id="Python">
		<title>Python</title>
	<sect2 id="pymssql">
	<title>pymssql</title>
<para>The <productname>pymssql</productname> module is a simple database interface to Microsoft SQL Server for <productname>Python</productname> that builds on top of &freetds; to provide a Python DB-API v2 (<ulink url="http://www.python.org/dev/peps/pep-0249/">PEP-249</ulink>) interface to Microsoft SQL Server.</para>

<para>The 2.x branch of <productname>pymssql</productname> take advantage of recent releases (0.91 and newer) of &freetds; and by doing that removes many of the limitations previously found with older &freetds; versions and the 1.x branch.</para>

<para><productname>pymssql</productname> features include:</para>

<itemizedlist>
	<listitem><para>Unicode friendly</para></listitem>
	<listitem><para>Python 3 friendly</para></listitem>
	<listitem><para>Works on most popular operating systems</para></listitem>
	<listitem><para>Written in <ulink url="http://cython.org/">Cython</ulink> for performance</para></listitem>
	<listitem><para>Includes a supported and documented low-level module (<filename>_mssql</filename>) that you can use instead of the DB-API</para></listitem>
	<listitem><para>Supports stored procedures with both return values and output parameters</para></listitem>
	<listitem><para>A comprehensive test suite</para></listitem>
</itemizedlist>

<para>Please refer to the <productname>pymssql</productname> <ulink url="http://pymssql.org">home page</ulink> where you'll find complete documentation on how to obtain, install and use it.</para>
	</sect2>
	<sect2 id="Sybase.Python.Module">
	<title>Sybase module</title>
<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.37, 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.37.tgz</userinput>
	<prompt>$ </prompt><userinput>cd sybase-0.37</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>
	</sect2>
	</sect1>
	
	<sect1 id="qt">
		<title>Qt</title>

<para><productname>To access SQL Server databases using Qt</productname> use QODBC.</para>

<para>There are some problems with wide character support on Qt because Qt assumes sizeof(SQLWCHAR) == 2.
On some DMs, though &mdash; including &iODBC;, the default on <productname>Ubuntu</productname> &mdash; sizeof(SQLWCHAR) == 4, which could lead to invalid character conversion.</para>
		</sect1>
	
	<sect1 id="uodbc">
		<title>ODBC on Unix</title>

<para>&odbc; has some issues on Unix, mainly due to lack of clean specifications.</para>
		<sect2 id="uodbc.64">
			<title>ODBC and 64-bit</title>

<para>ODBC was originally specified as 32-bit<footnote><para>In fact, the earliest versions were 16-bit.</para></footnote>.
Its evolution to 64-bit took place in the absence of a good specification which led to conflicting declarations and associated problems.
For instance, some parameters are defined as SQLINTEGER but are used for pointer offsets.
But SQLINTEGER was (and remains) 32-bit, while pointer offsets must be 64-bit.
Also row numbers and some other formerly 32-bit quantities are now 64-bit.</para>

<para>If you use &unixODBC; Frediano would recommend at least version 2.2.14. Earlier versions have issues if used on 64-bit environments.</para>
			</sect2>
		<sect2 id="uodbc.wchar">
			<title>sizeof(SQLWCHAR)</title>

<para>Under Windows <literal>sizeof(wchar_t) == sizeof(SQLWCHAR) == 2</literal> but on many Unix systems you have <literal>sizeof(wchar_t) == 4</literal>.
And some DMs decided to keep <literal>sizeof(SQLWCHAR) == 2</literal> (including &unixODBC;) while in other DM <literal>sizeof(SQLWCHAR) == sizeof(wchar_t) == 4</literal> (namely &iODBC;).
This leads to incompatible ABIs between applications and drivers.
If you compile the &freetds; ODBC driver using &iODBC; take care to ensure all drivers are compiled with the same header files.</para>

<para>Alternatively, compile &freetds; with both includes and rename the library to use two ABIs (for instance having a <filename>libtdsiodbc.so</filename> and a <filename>libtdsuodbc.so</filename>).</para>

<para>At the time of writing <productname>Ubuntu</productname> compiled Qt using &iODBC; but most packages use &unixODBC;. If you plan to use Qt with the &freetds; &odbc; driver, you should have an &iODBC;-compatible driver. Also be aware that the QODBC Qt driver has problems with &iODBC; and <literal>SQLWCHAR</literal> (see <link linkend="qt">Qt</link>). Due to these problems Frediano suggests not using this configuration (Qt database) on <productname>Ubuntu</productname> at this time.</para>
			</sect2>
		<sect2 id="uodbc.char">
			<title>Default charset</title>

<para>Character encoding is yet another trap.  ODBC makes no provision for specifying client character encoding. By default many DM converting from multi-byte to wide characters assume the client uses ISO 8859-1.  Even the &freetds; driver assumes ISO 8859-1 by default.  Also some DM have problems converting multi-byte encodings (like UTF-8), by assuming a byte can be converted to a single wide character (and vice versa). That creates problems if you use multi-byte encoding for &freetds; driver.</para>
			</sect2>
		</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="known.porting">
			<title>Porting Issues</title>

			<sect3 id="known.dates">
				<title>Date Structures and Offsets</title>

<para>Microsoft and Sybase use different &dblib; date structures <emphasis>and conventions</emphasis>.  Notably months can be in the range [0,11] or [1,12].  Pay careful attention to the results of <function>dbdatecrack()</function>.  </para>
				</sect3>
	
			<sect3 id="known.float">
				<title>Floating Point</title>

<para>Precision may surprise you if you pay attention.  Microsoft's &dblib; promotes single-precision to double in <function>dbbind()</function> by appending zeros; C promotes it to the nearest double.  &freetds; relies on the C compiler.  </para>

<para>Math libraries vary, too.  If porting an application whose output uses functions such at <function>log(3)</function>, expect differences in different implementations.  Perfectly consistent results between OSes will require the use of a single math library.  </para>
				</sect3>
		
		</sect2>
			
		<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</acronym> 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</acronym> characters or 4000 Unicode characters).  To move these large <structname>varchar</structname>s through <acronym>TDS</acronym> 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>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.
If you encounter some spurious <quote>out of memory</quote> error try to 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">&freetdsconf;</link>.
As most of the time data contained in BLOBs fields are much smaller than larger supported fields, we try to avoid considering field sizes
for BLOBs allocating memory as needed instead, so you should not have to reduce this value unless you really want the server to limit
data returned by queries.</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 &freetds;.  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>Microsoft 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 &freetds; 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>&freetds; may be unable to connect to the server.  The error message 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>Microsoft 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>

<note><para>&freetds; supports integrated security mode, too.
If you have <productname>Microsoft 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.
If you have Active Directory you can also use Kerberos, see <link linkend="kerberos">Kerberos support</link>.
</para></note>

			</sect2>
		</sect1>

	<sect1 id="serverthere">
		<title>Is the server there?</title>

		<sect2 id="serverthere.ping">
			<title>Start with <command>ping</command></title>

<para>First <command>ping</command> 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</command></title>

<para>Attempt to <command>telnet</command> to the port, to verify that the servername is listening.
				<example id="e.g.troubleshooting.telnet">
					<title>Finding the server</title>
<screen>
	<prompt>$ </prompt><userinput>telnet <replaceable>myhost 1433</replaceable></userinput>
	<computeroutput>Trying 127.0.0.1...
	Connected to myhost.
	Escape character is '^]'. </computeroutput></screen>
	</example>
If you get output as above, the servername is listening.  If you get a 'Connection Refused' message, you're talking to the wrong host, wrong port, or the servername is down.
	<footnote><para>To exit <command>telnet</command>:  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</command> may be exited with the command <command>quit</command>.
</para></footnote></para>

	</sect2>
	<sect2 id="serverthere.tsql">
		<title>Test with <command>tsql</command></title>

<para><command>tsql</command> can be run in two ways, one which uses &freetdsconf; 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 &freetdsconf;</title>
<screen>
	<prompt>$ </prompt><userinput>cd src/apps</userinput>
	<prompt>$ </prompt><userinput>TDSVER=auto ./tsql -H <replaceable>myhost</replaceable> -p <replaceable>1433</replaceable> -U <replaceable>user</replaceable></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 Microsoft SQL Server connection </computeroutput></screen>
	
	<productname>Microsoft 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</command> using the servername.
				<example id="e.g.troubleshooting.tsql">
					<title>Connecting to the server using &freetdsconf;</title>
<screen>
	<prompt>$ </prompt><userinput>./tsql -S <replaceable>myserver</replaceable> -U <replaceable>user</replaceable></userinput></screen>
	</example>
	If this fails, &freetds; is either not finding your &freetdsconf; file, finding the wrong one, or there is an error in the file.</para>
	</sect2>
	</sect1>

	<sect1 id="logging">
		<title>Logging</title>

<para>&freetds; 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.
	<tip><para> The filenames <filename>stdout</filename> and <filename>stderr</filename> are also supported.  They can be handy if you want to intersperse the log output with your application's output, or if your application opens more than one connection.  (The logfile is otherwise normally truncated each time the library connects to the server.)</para></tip></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 &freetdsconf; file, or <filename>interfaces</filename> file.  Sometimes it's unclear what source of information &freetds; is using to connect to a given servername.  This variable can make that bright and clear.</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> (and/or <envar>TDSDUMPCONFIG</envar>) variable to a null string will cause &freetds; 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 &freetds;.  First,
				the logs tend to grow large, so trim or archive them often.  Secondly,
				&freetds; 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 &freetds; is so <emphasis>slow</emphasis>.  It sometimes turns out that logging was left turned on.  Don't you be the next victim!  &freetds; logs are meant for development and debugging, not as a system monitoring tool.</para>
			</sect2>
		
		<sect2 id="Logging.freetds.conf">
			<title>&freetdsconf; variables that Control Logging</title>

<para>See <link linkend="tab.freetds.conf.debugflags">Valid bitmask values for <literal>debug flags</literal> entry in &freetdsconf;</link></para>

<para>The logfile is normally truncated each time &freetds; connects to the server.</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 &freetds; 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>&freetds; 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>Analyze 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 &freetds;, 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
					&freetds;.</para>
				
				</listitem>
			</itemizedlist>
		
		</sect1>
	<sect1 id="seemtooslow">
		<title>Slow connection or data retrieval</title>

<para>&freetds; is <emphasis>not</emphasis> 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</envar> should not be defined, and there should be no <literal>dump file</literal>  mentioned in &freetdsconf;.  You can double-check by setting <envar>TDSDUMPCONFIG</envar> 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</filename>.  Use <command>host</command> or <command>nslookup</command> to confirm that &freetds; can actually resolve the name/address you provided in &freetdsconf;.</para>
				</listitem>
			<listitem><para>Packet size.  The default packet size setting in &freetdsconf; (see <literal>initial block size</literal>) is usually fine. Slowness can potentially be due to multiple packet to use.  Under <productname><acronym>GNU</acronym>/Linux</productname> system we use an optimization to reduce network traffic; you shouldn't see much difference using this system.</para>
				</listitem>
			</itemizedlist>
				
		</sect1>
	</chapter>
	
<chapter id="help">
	<title>Getting Help</title>
	<epigraph>
		<attribution>Beatles</attribution>

<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 knowledgeable user to, well, <emphasis>use</emphasis> &freetds; 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="reconfirm.installation">
		<title>Reconfirm the installation</title>

<para>For initial setup and login problems, review <xref linkend="ConfirmInstall"/>.  Distinguish between <emphasis>network</emphasis> and <emphasis>server</emphasis> issues, between finding the server and logging into it.  The <envar>TDSDUMPCONFIG</envar> log will show how the servername is being looked up, what address &amp; port is being used, what TDS version is being used.  The <envar>TDSDUMP</envar> log will show quite clearly whether or not the server accepted the connection, and whether or not the login succeeded.  </para>

<para>Remember compiled-in defaults can be displayed with <command>tsql</command>:
<screen>
<prompt>$ </prompt><userinput>tsql -C</userinput>
<computeroutput>
Compile-time settings (established with the "configure" script)
                            Version: freetds v&version;
             freetds.conf directory: /usr/local/etc
     MS db-lib source compatibility: no
        Sybase binary compatibility: no
                      Thread safety: yes
                      iconv library: yes
                        TDS version: auto
                              iODBC: no
                           unixodbc: no
              SSPI "trusted" logins: no
                            Keberos: no
                            OpenSSL: yes
                             GnuTLS: no
                               MARS: yes </computeroutput></screen>
      
For &odbc; setup issues, the <command>osql</command> script is intended to confirm the configuration files are all sane.  If it fails to report a problem, please post a message describing the problem to the mailing list.  Thanks.  </para>

		</sect1>
	
	<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</command> or <command>sqsh</command>, 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 &freetds; useful and bugless is the goal of the project, after all.)</para>

<para>&freetds; being what it is, problems frequently arise amidst complex environments.  It can be hard for both you and the list participants &mdash; who are your allies and best resource &mdash; 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 &freetds; <foreignphrase>per se</foreignphrase>.  Clear questions have sometimes even led to submitting patches to other projects.</para>
		<sect2 id="help.otherclient"><title>Try a different client</title>

<para>&freetds; comes with its own utilities that use the various libraries.  It's a good idea to run your query through one of them &mdash; the one that uses the same API you're using &mdash; to see if it produces the same behavior you're seeing.  That helps eliminate your application (and the rest of the calling hierarchy) as a source of the problem.</para>
			</sect2>
		
		<sect2 id="help.permissions">
			<title>Check permissions</title>

<para>If your query works in <command>tsql</command> but not with Apache, make sure the account running Apache can find and read &freetdsconf;.
Also consider security settings like firewalls, SELinux/AppArmor or similars.</para>
			</sect2>
		
		</sect1>
	<sect1 id="mailinglist"><title>The Mailing List</title>
		<epigraph>
			<attribution>3 Henry VI, I, ii, approximately</attribution>

<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 &freetds; 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</emphasis> to be announced on the website.  The website is updated only intermittently, when we post a new release or &freetds; 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>&freetds; version (or snapshot date, if not a release)</member>
					<member>any options used with <command>configure</command></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="help.log"><title>Attach a logfile</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</envar> 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</command> 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>Log files are especially important if you're not programming at the C level.  Sometimes there are problems &mdash; an impedance mismatch, to coin a phrase &mdash; between &freetds; and the calling framework/language.  But if you write to the list and say <quote>Why does my <literal>PHP foo()</literal> returns an empty string?</quote>, please keep in mind that your question might as well be in Urdu to someone familiar with the C library.  Without knowing which C function was called, and with what data, it's impossible to even begin to try to answer the question.  </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="ShowYourWork"><title>Show your work</title>

<para>Great questions make the problem crystal clear to a tired developer after supper.  </para>

<para>Show what you did, and show what happened.  Throughout this User Guide, you've seen examples of screenshots; in each case the first line was the command entered, followed by the machine's response.  By showing <emphasis>verbatim</emphasis> what you did and saw, you give someone who knows what to do a chance to look over your shoulder.  <emphasis>Across the Internet!</emphasis>  How cool is that?   </para>

<para>Whether you're having a problem with your own application or with something at a higher level, you're well advised to try to reproduce it using one of the &freetds; utilities, preferably one that used the same client library you're using.  If, say, <command>bsqldb</command> works and your program doesn't, that's a clue.  By the same token, if <command>bsqldb</command> exhibits problems, too, chances are you found a bug.  Or &mdash; how to say it? &mdash; a <emphasis>missing feature</emphasis>.  It's always good to know about those.  </para>

			</sect2>
		</sect1>
	</chapter>
<!-- ////////////////// CHAPTER /////////////////////// -->
<chapter id="contrib">
	<title>Helping</title>
	<epigraph>
		<attribution>Bertrand Russell</attribution>

<para>The time you enjoy wasting is not wasted time.</para>
		</epigraph>

<para>&freetds; 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 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&amp;atid=407808">SourceForge</ulink> trigger automatic notification to the &freetds;  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 the <ulink url="mailto:freetds@lists.ibiblio.org">&freetds; mailing list</ulink>.</para>

<para>The User Guide is maintained in <acronym>XML</acronym> DocBook format; the file in your distibution is  <filename>doc/userguide.xml</filename>.  It is a flat ASCII file that you can edit with any text editor.  You don't have to know <acronym>XML</acronym> 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> <replaceable>your_version</replaceable></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</acronym></title>

<para>We have just begun an independent reference manual to &freetds;; the main <acronym>API</acronym> documents are the work of the server vendors.  We're using <ulink url="http://www.doxygen.org">Doxygen</ulink>, which extracts documentation directly from comments in the source code, and we're maybe 25% done.</para>

<para>The <acronym>TDS</acronym> protocol is partly documented, as are the <acronym>API</acronym>s to <filename>libtds</filename> and &dblib;, but much remains.</para>
			</sect2>
		<sect2 id="webmaster">
			<title>Be the Webmaster</title>

<para>The FAQ and in particular the news don't get updated often enough.  If that's your thing, drop a line to the <ulink url="mailto:freetds@lists.ibiblio.org">&freetds; mailing list</ulink>.</para>
			</sect2>
		</sect1>

	<sect1 id="Light.taper">
		<title>Light another's taper</title>

<para>Every question you answer on the mailing list will save someone time and, if done well, will actually improve your own knowledge.  The project's developers will often answer technical questions that require substantial understanding of the code or suggest a possible bug.  Setup issues, though &mdash; connecting and logging in to the server, getting Apache going &mdash; are questions many experienced users can and do answer, thereby fostering the community on which the project depends.  </para>

<para>Your experience may well be more closely aligned with the question posed than that of anyone else reading the list that day.  You may use that framework or language or OS, or have that particular server.  No one, no matter how expert in the code, has used every configuration, version, OS, compiler, etc.  Whether you simply confirm there's a problem in some particular arrangement, or say, <quote>dunno, works for me</quote>, you're adding information.  </para>

		</sect1>

	<sect1 id="Ambition">
		<title>Ambitious ideas</title>

<para>If you want to get your hands really dirty, here are some big ideas to contemplate.  </para>
		
		<sect2>
			<title><literal>libtds2</literal></title>			

<para>After many years developing &freetds;, we've learned quite a bit about the protocol and how to write database libraries.  Unfortunately, though, one of the things holding us back &mdash; and, obviously hampering the project &mdash; is the underlying utility library.</para>

<para>This wouldn't be a from-scratch effort; most of the code is already written.  What's needed is a more uniform API that better reflects the TDS protocol, and that does <emphasis>not</emphasis> attempt character set conversions immediately on receipt of the data.  </para>   
			</sect2>

		<sect2>
			<title><literal>libstddb</literal></title>			

<para>This would be a new client library modelled after <literal>stdio</literal>, a project to demonstrate what database programming should be like.  </para>
			</sect2>

		<sect2>
			<title>Server code </title>			

<para>&freetds; includes a little stub of a server, but it could be much more useful.  One idea would be to make it a front-end to SQLite, thereby creating for the first time a TDS client &amp; server pair composed entirely of free software.  </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 &freetds; 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 &freetds; do that can't be done any other way?  Glad you asked.  &freetds; can</para>
		<itemizedlist>
			<listitem><para>Connect to every version of either vendor's server, using the same binaries.</para></listitem>
			<listitem><para>Provide a &ctlib; for Microsoft <productname>SQL Server</productname>.  This feature alone allows <productname>DBD::Sybase</productname> and <command>sqsh</command>, among others, to connect to Microsoft's product.</para></listitem>
			<listitem><para>Provide a modern &dblib; for Microsoft <productname>SQL Server</productname>: Win32/64, and TDS 7+.  </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 <quote>Advocacy</quote>.</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 &freetds;.  It can be regenerated at any time using <productname>Doxygen</productname> with <command>cd <filename>doc</filename>; make doc</command>.</para>

<para>The reference manual is a work in progress: only &dblib; 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.doxygen.org">Doxygen website</ulink>.</para>

<para>Basic API coverage information for the db-lib, ct-lib, and ODBC client libraries is maintained in <filename>doc/api_status.txt</filename>, 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> option to align
					&freetds; with one or the other's convention.</para></footnote>
			the extent to which it is implemented.  The <emphasis>Status</emphasis> field may be:
			
			<variablelist id="dblib.api.status">
				<title>&dblib; 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</literal> 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>&dblib; API Implementation Summary</title>

<para>Microsoft's version of &dblib; is
			<ulink url="http://msdn.microsoft.com/en-us/library/aa936988(SQL.80).aspx">online</ulink>.
			Sybase's is both
			<ulink url="http://manuals.sybase.com/onlinebooks/group-cnarc/cng1110e/dblib/@Generic__BookTextView;pt=4602;nh=1">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>
		&dblibapixml;
		</sect1>
	
	<sect1 id="ctlib.api.summary">
		<title>ct-lib API Implementation Summary</title>

<para>Sybase ct-lib documentation can be found
			<ulink url="http://manuals.sybase.com/onlinebooks/group-cnarc/cng1110e/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>
		&ctlibapixml;
		</sect1>
	
	<sect1 id="odbc.api.summary">
		<title>ODBC API Implementation Summary</title>

<para>Microsoft's ODBC documentation is
			<ulink url="http://msdn.microsoft.com/en-us/library/ms714177.aspx">online</ulink>.</para>
		

<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>
		&odbcapixml;
		</sect1>
	
	<sect1 id="samplecode">
		<title>DB-Library for the Tenderfoot</title>
		<epigraph><attribution>Mark Twain</attribution>

<para>Few things are harder to put up with than the annoyance of a good example.</para> </epigraph>
		
		<abstract><para>Below is a complete working &dblib; program, presented as a series of examples.
				<itemizedlist><title>Features of sample code</title>
					<listitem><para>Processes command-line options to select the server, database, username, and password</para></listitem>
					<listitem><para>Remaining arguments on the command line comprise the SQL query to execute</para></listitem>
					<listitem><para>Installs error and message handlers</para></listitem>
					<listitem><para>Illustrates correct row-processing</para></listitem>
					<listitem><para>Illustrates correct error detection and handling</para></listitem>
					</itemizedlist>
				Other sample code may be found in the distribution, in the cleverly named <filename>samples</filename> directory. A complete program, heavily commented for your perusal, is <filename>apps/bsqldb.c</filename>.</para></abstract>
		

<para><important><sidebar><title>What's the big deal with errors?</title>

<para>Correct handling of errors is extremely important in database applications because they involve two systems most others don't: the network and the database server.  Both can give rise to errors that, if not detected and reported when they occur, let the application proceed blithely on until something truly mysterious happens.  In the worst case, in the absence of a properly reported error, the application may <emphasis>seem</emphasis> to have updated the data, when in fact it did not.</para>

<para>Every &dblib; application uses the network, making it subject to network failures.  Database programs also almost always have very high data integrity requirements.  It is necessary to know the row was absolutely, positively committed, once and only once, without error or exception.  Without taking great care to trap and handle all error conditions, no statement about the program's reliability can be made with confidence.</para></sidebar></important></para>
		

<para><orderedlist><title>How to Get and Build the sample code</title>
				<listitem><para>Run <filename>doc/grep_sample_code</filename> to extract the <symbol>C</symbol> code from the User Guide <symbol>XML</symbol> source.</para></listitem>
				<listitem><para>Compile</para></listitem>
				<listitem><para>Link</para></listitem>
				</orderedlist>
			
			<itemizedlist><title>Files Required to Build the Sample Code</title>
				<listitem><para><filename>sybfront.h</filename></para></listitem>
				<listitem><para><filename>sybdb.h </filename></para></listitem>
				<listitem><para><filename>libsybdb.a</filename> or <filename>libsybdb.so</filename></para></listitem>
				</itemizedlist>
			Your library's extension may vary according to your operating system.</para>
		

<para>The source code may be built with commands similar to these.  The precise options and paths depend on your particular system.  The commands below work with the GNU compiler and linker on an ELF system with dynamic linking, common on Linux and BSD systems.
			<example><title>Building the Sample Code</title>
<screen>
	<prompt>$ </prompt><userinput>../doc/grep_sample_code ../doc/userguide.xml > sample.c</userinput>
	<prompt>$ </prompt><userinput>cc -I /usr/local/include -Wl,-L/usr/local/lib -Wl,-R/usr/local/lib sample.c -lsybdb -o sample</userinput></screen>
	</example>
	where <filename>/usr/local/include</filename> and <filename>/usr/local/lib</filename> are respectively the locations of your header files and libraries.</para>
	

<para>We now proceed to the code proper.</para>
				
		<sect2 id="samplecode.include"><title>Header files</title>
			<abstract><para>We need two header files to use &dblib;.  We need a few others to deal with I/O in C, as you know.  Also declare the error and message handler functions, more about which later.</para></abstract>
			

<para><example id="e.g.samplecode.dblib.include">
					<title>Sample Code: &dblib; header files</title>
					<programlisting linenumbering="unnumbered">
<![CDATA[
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <assert.h>
#include <errno.h>
#include <unistd.h>
#include <libgen.h>
						]]>
						
#include &lt;sybfront.h&gt;	<lineannotation>/* <filename>sybfront.h</filename> always comes first */</lineannotation>
#include &lt;sybdb.h&gt;	<lineannotation>/* <filename>sybdb.h</filename> is the only other file you need */</lineannotation>

int err_handler(DBPROCESS*, int, int, int, char*, char*);
int msg_handler(DBPROCESS*, DBINT, int, int, char*, char*, char*, int);
</programlisting></example></para>
			</sect2>
		
		<sect2 id="samplecode.prolog"><title>Prolog</title>
			<abstract><para>Nothing special here.  Collect the command line parameters.  We do this with the standard <function>getopts(3)</function> function.  Cf. <command>man 3 getopts</command> for details.</para></abstract>
			

<para><example id="e.g.samplecode.dblib.prolog">
					<title>Sample Code: &dblib; prolog</title>
<programlisting linenumbering="unnumbered">
	extern char *optarg;
	extern int optind;
	
	const static char syntax[] =
		"syntax: example -S server -D db -U user -P passwd\n";
	
	struct {
		char *appname, *servername, *dbname, *username, *password;
	} options = {0,0,0,0,0};
	
	int
	main(int argc, char *argv[])
	{
		int i, ch;
		LOGINREC *login;	<co id="samplecode.init.loginrec"/>
		DBPROCESS *dbproc;	<co id="samplecode.init.dbprocess"/>
		RETCODE erc;		<co id="samplecode.init.retcode"/>

		options.appname = basename(argv[0]);

		while ((ch = getopt(argc, argv, "U:P:S:D:")) != -1) {
			switch (ch) {
			case 'S':
				options.servername = strdup(optarg);
				break;
			case 'D':
				options.dbname = strdup(optarg);
				break;
			case 'U':
				options.username = strdup(optarg);
				break;
			case 'P':
				options.password = strdup(optarg);
				break;
			case '?':
			default:
				fprintf(stderr, syntax);
				exit(1);
			}
		}

		argc -= optind;
		argv += optind;

		if (! (options.servername &amp;&amp; options.username  &amp;&amp; options.password)) {
			fprintf(stderr, syntax);
			exit(1);
		}
		</programlisting></example></para>
					<para><calloutlist><title>Prolog Notes</title>
						<callout arearefs="samplecode.init.loginrec">

	<para><symbol>LOGINREC</symbol> is a structure that describes the client.  It's passed to the server at connect time.</para></callout>
						<callout arearefs="samplecode.init.dbprocess">

	<para><symbol>DBPROCESS</symbol> is a structure that describes the connection.  It is returned by <function>dbopen()</function>.</para></callout>
						<callout arearefs="samplecode.init.retcode">

	<para><symbol>RETCODE</symbol> is the most common return code type for &dblib; functions.</para></callout>
						</calloutlist></para>
				</sect2>

			<sect2 id="samplecode.init"><title>Initialize</title>
				<abstract><para>Initialize the library.  Create and populate a <symbol>LOGINREC</symbol> record.</para></abstract>


	<para><example id="e.g.samplecode.dblib.Initialize">
						<title>Sample Code: &dblib; Initialize</title>
	<programlisting linenumbering="unnumbered">

		<co id="samplecode.init.dbinit" label="initialize"/>
		if (dbinit() == FAIL) {
			fprintf(stderr, "%s:%d: dbinit() failed\n",
			options.appname, __LINE__);
			exit(1);
		}

		<co id="samplecode.init.handlers"/>
		dberrhandle(err_handler);
		dbmsghandle(msg_handler);

		<co id="samplecode.init.login"/>
		if ((login = dblogin()) == NULL) {
			fprintf(stderr, "%s:%d: unable to allocate login structure\n",
			options.appname, __LINE__);
			exit(1);
		}

		<co id="samplecode.init.login.populate"/>
		DBSETLUSER(login, options.username);
		DBSETLPWD(login, options.password);

		</programlisting></example>
					<calloutlist><title>Initialization Notes</title>
						<callout arearefs="samplecode.init.dbinit">

	<para><emphasis>Always</emphasis> make <function>dbinit()</function> the first &dblib; call.</para></callout>
						<callout arearefs="samplecode.init.handlers">

	<para>Install the error- and mesage-handlers right away.  They're explained in more detail later.</para></callout>
						<callout arearefs="samplecode.init.login">

	<para><function>dblogin()</function> almost never fails.  But check!  No point in trying to use a null pointer.</para></callout>
						<callout arearefs="samplecode.init.login.populate">

	<para>The <symbol>LOGIN</symbol> record isn't directly accessible.  It's populated via macros like these.  There are other fields, but these two are essential. Look for <symbol>SETLsomething</symbol> in the documentation.</para></callout>
						</calloutlist></para>
				</sect2>

			<sect2 id="samplecode.connect"><title>Connect to the server</title>
				<abstract><para><function>dbopen()</function> forms a connection with the server.  We pass our <symbol>LOGINREC</symbol> pointer (which describes the client end), and the name of the server.  Then, optionally, we change to our favored database.  If that step is skipped, the user lands in his default database.</para></abstract>


	<para><example id="e.g.samplecode.dblib.Connect">
						<title>Sample Code: &dblib; Connect to the server</title>
	<programlisting>
		if ((dbproc = dbopen(login, options.servername)) == NULL) {
			fprintf(stderr, "%s:%d: unable to connect to %s as %s\n",
				options.appname, __LINE__,
				options.servername, options.username);
			exit(1);
		}

		if (options.dbname  &amp;&amp; (erc = dbuse(dbproc, options.dbname)) == FAIL) {
			fprintf(stderr, "%s:%d: unable to use to database %s\n",
				options.appname, __LINE__, options.dbname);
			exit(1);
		}

		</programlisting></example></para>
				</sect2>

			<sect2 id="samplecode.query"><title>Send a query</title>
				<abstract><para>&dblib; maintains a <firstterm>command buffer</firstterm> to hold the SQL to be sent to the server.  Two functions &mdash; <function>dbcmd()</function> and <function>dbfcmd()</function> &mdash; build up the query from strings of text. The command buffer is reset after the query is sent to the server.</para>

	<para>We left the SQL on the command line.  We fetch it now and send it to the server.</para></abstract>


	<para><example id="e.g.samplecode.dblib.send">
						<title>Sample Code: &dblib; Send a query</title>
	<programlisting>
		for (i=0; i &lt; argc; i++) {
			assert(argv[i]);
			printf("%s ", argv[i]);
			if ((erc = dbfcmd(dbproc, "%s ", argv[i])) == FAIL) {
				fprintf(stderr, "%s:%d: dbcmd() failed\n", options.appname, __LINE__);
				exit(1);	<co id="samplecode.query.dbfcmd"/>
			}
		}
		printf("\n");

		if ((erc = dbsqlexec(dbproc)) == FAIL) {
			fprintf(stderr, "%s:%d: dbsqlexec() failed\n", options.appname, __LINE__);
			exit(1);		<co id="samplecode.query.exec"/>
		}
		</programlisting></example>
					<calloutlist><title>Initialization Notes</title>
						<callout arearefs="samplecode.query.dbfcmd"><para>Failure at this juncture is rare.  The library is merely allocating memory to hold the SQL.</para></callout>
						<callout arearefs="samplecode.query.exec"><para><function>dbsqlexec()</function> waits for the server to execute the query.  Depending on the complexity of the query, that may take a while.</para></callout>
						</calloutlist>
					<function>dbsqlexec()</function> will fail if something is grossly wrong with the query, e.g. incorrect syntax or a reference to nonexistent table.  It's only the first of a few places where an error can crop up in processing the query, though.  Just because <function>dbsqlexec()</function> succeeded doesn't mean you're in the clear.</para>
				</sect2>

			<sect2 id="samplecode.results"><title>Fetch Results</title>
				<abstract><para>A query may produce zero, one, or more results.  The application normally provides buffers to &dblib; to fill, and iterates over the results a row (and column) at a time.</para></abstract>

				<bridgehead id="samplecode.results.kinds.of.results" renderas="sect3">Kinds of Results</bridgehead>


	<para><firstterm>Results</firstterm> is a special term: it means more than rows or no rows.  To <emphasis>process the results</emphasis> means to gather the data returned by the server into the application's variables.
					<table id="tab.kinds.of.results"><title>Kinds of Results</title>
						<tgroup cols='6' align='left' colsep='1' rowsep='1'>
							<colspec colname="type"/>
							<colspec colname="meta"/>
							<colspec colname="reg"/>
							<colspec colname="comp"/>
							<colspec colname="ret"/>
							<colspec colname="eg"/>
							<thead>
								<row>
									<entry>Type</entry>
									<entry>Metadata</entry>
									<entry>Regular Rows</entry>
									<entry>Compute Rows</entry>
									<entry>Return Status</entry>
									<entry>Example SQL</entry>
									</row>
								</thead>
							<tbody>
								<row>	<entry colname="type">None</entry>
									<entry colname="meta">None</entry>
									<entry colname="reg">None</entry>
									<entry colname="comp">None</entry>
									<entry colname="ret">None</entry>
									<entry colname="eg">Any <symbol>INSERT</symbol>, <symbol>UPDATE</symbol>, or <symbol>DELETE</symbol> statement </entry>
									</row>
								<row>	<entry colname="type">Empty</entry>
									<entry colname="meta">1 set</entry>
									<entry colname="reg">None</entry>
									<entry colname="comp">0 or more</entry>
									<entry colname="ret">None</entry>
									<entry colname="eg"><symbol>SELECT name FROM systypes WHERE 0 = 1</symbol></entry>
									</row>
								<row>	<entry colname="type">Simple </entry>
									<entry colname="meta">1 set </entry>
									<entry colname="reg">0 or more </entry>
									<entry colname="comp">None </entry>
									<entry colname="ret">None </entry>
									<entry colname="eg"><userinput>SELECT name FROM sysobjects</userinput> </entry>
									</row>
								<row>	<entry colname="type">Complex </entry>
									<entry colname="meta">2 or more </entry>
									<entry colname="reg">0 or more </entry>
									<entry colname="comp">1 or more </entry>
									<entry colname="ret">None </entry>
									<entry colname="eg"><userinput>SELECT name FROM sysobjects COMPUTE COUNT(name)</userinput> </entry>
									</row>
								<row>	<entry colname="type">Stored Procedure </entry>
									<entry colname="meta">0 or more </entry>
									<entry colname="reg">0 or more </entry>
									<entry colname="comp">0 or more </entry>
									<entry colname="ret">1 or more</entry>
									<entry colname="eg"><userinput>EXEC sp_help sysobjects</userinput> </entry>
									</row>
								</tbody>
							</tgroup>
						</table></para>


	<para>As the above table shows, results can comprise ordinary rows and <firstterm>compute rows</firstterm> (resulting from a <symbol>COMPUTE</symbol> clause). Stored procedures may of course contain multiple SQL statements, some of which may be <symbol>SELECT</symbol> statements and might include <symbol>COMPUTE</symbol> clauses. In addition, they generate a  <firstterm>return status</firstterm> (with a <symbol>RETURN</symbol> statement or else automatically) and perhaps <symbol>OUTPUT</symbol> parameters.</para>

				<bridgehead id="samplecode.results.metadata.and.data" renderas="sect3">Data and Metadata</bridgehead>


	<para>Observe that a row is set of columns, and each column has attributes such as type and size.  The column attributes of a row are collectively known as <firstterm>metadata</firstterm>.  The server always returns metadata before any data (even for a <symbol>SELECT</symbol> statement that produced no rows).</para>


	<para> <table id="tab.result.fetching.functions"><title>Result-fetching functions</title>
						<tgroup cols='4' align='left' colsep='1' rowsep='1'>
							<colspec colname="func"/>
							<colspec colname="type"/>
							<colspec colname="ret"/>
							<colspec colname="etc"/>
							<thead>
								<row>
									<entry>Function</entry>
									<entry>Fetches</entry>
									<entry>Returns</entry>
									<entry>Comment</entry>
									</row>
								</thead>
							<tbody>
								<row>	<entry colname="func"><function>dbresults()</function></entry>
									<entry colname="type">metadata</entry>
									<entry colname="ret"><symbol>SUCCEED</symbol>, <symbol>FAIL</symbol> or, <symbol>NO_MORE_RESULTS</symbol>.  </entry>
									<entry colname="etc"><symbol>SUCCEED</symbol> indicates just that: the query executed successfully (whew!). There may be metadata (and perhaps data) and/or stored procedure outputs available.  </entry>
									</row>
								<row>	<entry colname="func"><function>dbnextrow()</function></entry>
									<entry colname="type">data</entry>
									<entry colname="ret">	<symbol>REG_ROW</symbol>,
										<firstterm>compute_id</firstterm>,
										<symbol>NO_MORE_ROWS</symbol>,
										<symbol>BUF_FULL</symbol>,
										or <symbol>FAIL</symbol>.
										</entry>
									<entry colname="etc">Places fetched data into bound columns, if any.  </entry>
									</row>
								</tbody>
							</tgroup>
						</table></para>

				<bridgehead id="samplecode.results.binding" renderas="sect3">Binding</bridgehead>


	<para>Each time <symbol>dbresults()</symbol> returns <symbol>SUCCEED</symbol>, there is something to retrieve. &dblib; has different functions to deal with the different kinds of results.  The functions are of two kinds: those that convert the data into a form desired by the application, known as <firstterm>binding</firstterm>, and those that return the data in <quote>native</quote> form.</para>


	<para>To understand binding, it may be easiest to examine two primitive functions, <function>dbdata()</function> and <function>dbconvert()</function>.  <function>dbdata()</function> returns a pointer to the column's data.  The data to which it points are in <quote>native</quote> form, 4 bytes for an <symbol>INT</symbol>, 8 bytes for a <symbol>DATETIME</symbol> and so on.  <function>dbconvert()</function> converts between datatypes; you can hand it an integer and get back a character array (or a <symbol>C double</symbol>.  You might think of  <function>dbconvert()</function> as <function>atoi(3)</function> on steroids). <function>dbbind()</function> combines these two functions.  The application indicates in what form it would like to use each column, and the library converts them  on the fly as each row is read.</para>


	<para>To <emphasis>bind a column</emphasis> is to provide a buffer to &dblib; for it to fill, and indicate which datatype the buffer is meant to hold. <footnote><para>This is the sort of thing <symbol>C++</symbol>'s type system does so much better</para></footnote></para>


	<para>It may be well to pause here to observe the three ways a datatype is described in a &dblib; program.
					<variablelist id="list.datatypes"><title>&dblib; Datatype Descriptors</title>
						<varlistentry>
							<term>Sever Datatype</term>
							<listitem>

	<para>Describes the data as an abstract type, not representing any particular kind of storage.  <symbol>SYBREAL</symbol>, for example, doesn't imply any particular arrangement of bits; it just means <quote>a floating-point datatype corresponding to the <symbol>T-SQL REAL</symbol> type on the server.</quote> These all begin with <symbol>SYB</symbol>, e.g. <symbol>SYBINT4</symbol>.</para>
								</listitem>
							</varlistentry>
						<varlistentry>
							<term>Program Variable Datatype</term>
							<listitem>

	<para>Defines a <symbol>C</symbol> variable in a machine-independent way. Because a <symbol>C</symbol> defines its  <symbol>int</symbol> type according the CPU architecture, it may have 2, 4, 8, or some other number of bytes.  A <symbol>DBINT</symbol> on the other hand, is guaranteed to be 4 bytes and, as such, assuredly will hold any value returned by the server from a <symbol>T-SQL INT</symbol> column.  These all begin with <symbol>DB</symbol>, e.g. <symbol>DBREAL</symbol>.</para>
								</listitem>
							</varlistentry>
						<varlistentry>
							<term>Bind Type</term>
							<listitem>

	<para>Prescribes a conversion operation.  Indicates to <function>dbbind()</function> the  <emphasis>Program Variable Datatype</emphasis> defined by the target buffer.  Sybase and Microsoft call this the <quote>vartype</quote>. These all <emphasis>end</emphasis> with <symbol>BIND</symbol>, e.g. <symbol>STRINGBIND</symbol>.</para>
								</listitem>
							</varlistentry>
						</variablelist></para>


	<para>Typically it's convenient to have &dblib; convert the data into the desired form.  The function that does that is <function>dbind()</function>.  So: after fetching the metadata, and before fetching the data, we usually prepare the bound columns.</para>

				<bridgehead id="samplecode.results.fetching.data" renderas="sect3">Fetching Data</bridgehead>


	<para> <table id="tab.data.fetching.functions"><title>Data-fetching functions</title>
						<tgroup cols='5' align='left' colsep='1' rowsep='1'>
							<colspec colname="type"/>
							<colspec colname="reg"/>
							<colspec colname="comp"/>
							<colspec colname="ret"/>
							<colspec colname="out"/>
							<thead>
								<row>
									<entry>Type</entry>
									<entry>Regular rows</entry>
									<entry>Compute rows</entry>
									<entry>Return status</entry>
									<entry><symbol>OUTPUT</symbol> parameters</entry>
									</row>
								</thead>
							<tbody>
								<row>	<entry colname="type">Meta </entry>
									<entry colname="reg"><function>dbnumcols()</function> </entry>
									<entry colname="comp">	<function>dbnumcompute()</function>,
										<function>dbnumalts()</function>,
										<function>dbaltop()</function>,
										<function>dbbylist()</function> </entry>
									<entry colname="ret"><function>dbhasretstatus()</function> </entry>
									<entry colname="out"><function>dbnumrets()</function> </entry>
									</row>
								<row>	<entry colname="type">Binding </entry>
									<entry colname="reg"><function>dbbind()</function>, <function>dbnullbind()</function> </entry>
									<entry colname="comp">	<function>dbaltbind()</function>,
										<function>dbanullbind()</function> </entry>
									<entry colname="ret"><function>dbretstatus()</function> </entry>
									<entry colname="out">none </entry>
									</row>
								<row>	<entry colname="type">Native </entry>
									<entry colname="reg"><function>dbdatlen()</function>, <function>dbdata()</function> </entry>
									<entry colname="comp">	<function>dbadlen()</function>,
										<function>dbalttype()</function>,
										<function>dbaltutype()</function>,
										<function>dbaltlen()</function>,
										<function>dbadata()</function> </entry>
									<entry colname="ret">none </entry>
									<entry colname="out">	<function>dbretdata()</function>,
										<function>dbretlen()</function>,
										<function>dbretname()</function>,
										<function>dbrettype()</function> </entry>
									</row>
								</tbody>
							</tgroup>
						</table></para>


	<para>The paradigm may now perhaps be clear:  Query, fetch results, bind columns, fetch regular rows, fetch compute rows, fetch stored procedure outputs.  Repeat as necessary.</para>


	<para> <table id="tab.putting.it.all.together"><title>Putting it all together </title>
						<tgroup cols='4' align='left' colsep='1' rowsep='1'>
							<colspec colname="step"/>
							<colspec colname="func"/>
							<colspec colname="once"/>
							<colspec colname="freq"/>
							<thead>
								<row>	<entry>Step </entry>
									<entry>Function </entry>
									<entry>Once Per </entry>
									<entry>Many Times Per </entry>
									</row>
								</thead>
							<tbody>
								<row>	<entry colname="step">Query </entry>
									<entry colname="func"><function>dbsqlexec()</function> </entry>
									<entry colname="once">Query</entry>
									<entry colname="freq">Program</entry>
									</row>
								<row>	<entry colname="step">Fetch metadata </entry>
									<entry colname="func"><function>dbresults()</function> </entry>
									<entry colname="once">SQL statement </entry>
									<entry colname="freq">Query </entry>
									</row>
								<row>	<entry colname="step">Prepare variables </entry>
									<entry colname="func"><function>dbbind()</function> </entry>
									<entry colname="once">Column</entry>
									<entry colname="freq">Statement</entry>
									</row>
								<row>	<entry colname="step">Fetch regular data </entry>
									<entry colname="func"><function>dbnextrow()</function> </entry>
									<entry colname="once">Row </entry>
									<entry colname="freq">Statement </entry>
									</row>
								<row>	<entry colname="step">Fetch compute data </entry>
									<entry colname="func"><function>dbnextrow()</function>  </entry>
									<entry colname="once">Compute column </entry>
									<entry colname="freq">Statement </entry>
									</row>
								<row>	<entry colname="step">Fetch output parameters </entry>
									<entry colname="func"><function>dbretdata()</function> </entry>
									<entry colname="once">output parameter </entry>
									<entry colname="freq">Stored procedure </entry>
									</row>
								<row>	<entry colname="step">Fetch return status </entry>
									<entry colname="func"><function>dbretstatus()</function> </entry>
									<entry colname="once">Stored procedure </entry>
									<entry colname="freq">Program </entry>
									</row>
								</tbody>
							</tgroup>
						</table></para>


	<para><important><title>Fetch All Rows!</title>
						<sidebar><para>&dblib; doesn't insist every column &mdash; or even any column &mdash; be bound or otherwise retrieved into the application's variables.  There is, however, one absolutely <emphasis>crucial, inflexible, unalterable</emphasis> requirement: the application must <emphasis>process all rows produced by the query</emphasis>.  Before the <symbol>DBPROCESS</symbol> can be used for another query, the application must either fetch all rows, or cancel the results and receive an acknowledgement from the server. Cancelling is beyond the scope of this document, so for now  <emphasis> fetch all rows</emphasis>.</para></sidebar></important></para>


	<para>Now, at last, some sample code that fetches data.  In the interest of simplicity, we don't bind anything except regular rows.</para>


	<para><example id="e.g.samplecode.dblib.fetch">
						<title>Sample Code: &dblib; Fetch Results</title>
	<programlisting>
		while ((erc = dbresults(dbproc)) != NO_MORE_RESULTS) {
			struct COL 						<co id="samplecode.results.dbresults"/>
			{
				char *name;
				char *buffer;
				int type, size, status;
			} *columns, *pcol;
			int ncols;
			int row_code;

			if (erc == FAIL) {
				fprintf(stderr, "%s:%d: dbresults failed\n",
				options.appname, __LINE__);
				exit(1);
			}

			ncols = dbnumcols(dbproc);

			if ((columns = calloc(ncols, sizeof(struct COL))) == NULL) {
				perror(NULL);
				exit(1);
			}

			/*
			 * Read metadata and bind.
			 */
			for (pcol = columns; pcol - columns &lt; ncols; pcol++) {
				int c = pcol - columns + 1;

				pcol->name = dbcolname(dbproc, c);		<co id="samplecode.results.c"/>
				pcol->type = dbcoltype(dbproc, c);
				pcol->size = dbcollen(dbproc, c);

				if (SYBCHAR != pcol->type) {			<co id="samplecode.results.dbcollen"/>
					pcol->size = dbprcollen(dbproc, c);
					if (pcol->size > 255)
						pcol->size = 255;
				}

				printf("%*s ", pcol->size, pcol->name);

				if ((pcol->buffer = calloc(1, pcol->size + 1)) == NULL){
					perror(NULL);
					exit(1);
				}

				erc = dbbind(dbproc, c, NTBSTRINGBIND,	<co id="samplecode.results.dbbind"/>
				pcol->size+1, (BYTE*)pcol->buffer);
				if (erc == FAIL) {
					fprintf(stderr, "%s:%d: dbbind(%d) failed\n",
					options.appname, __LINE__, c);
					exit(1);
				}
			<![CDATA[
				erc = dbnullbind(dbproc, c, &pcol->status);]]>	<co id="samplecode.results.dbnullbind"/>
				if (erc == FAIL) {
					fprintf(stderr, "%s:%d: dbnullbind(%d) failed\n",
					options.appname, __LINE__, c);
					exit(1);
				}
			}
			printf("\n");

			/*
			 * Print the data to stdout.
			 */
			while ((row_code = dbnextrow(dbproc)) != NO_MORE_ROWS){	<co id="samplecode.results.dbnextrow"/>
				switch (row_code) {
				case REG_ROW:
					for (pcol=columns; pcol - columns &lt; ncols; pcol++) {
						char *buffer = pcol->status == -1?
						"NULL" : pcol->buffer;
						printf("%*s ", pcol->size, buffer);
					}
					printf("\n");
					break;

				case BUF_FULL:
					assert(row_code != BUF_FULL);
					break;

				case FAIL:
					fprintf(stderr, "%s:%d: dbresults failed\n",
					options.appname, __LINE__);
					exit(1);
					break;

				default: 					<co id="samplecode.results.computeid"/>
					printf("Data for computeid %d ignored\n", row_code);
				}

			}

			/* free metadata and data buffers */
			for (pcol=columns; pcol - columns &lt; ncols; pcol++) {
				free(pcol->buffer);
			}
			free(columns);

			/*
			 * Get row count, if available.
			 */
			if (DBCOUNT(dbproc) > -1)
				fprintf(stderr, "%d rows affected\n", DBCOUNT(dbproc));

			/*
			 * Check return status
			 */
			if (dbhasretstat(dbproc) == TRUE) {
				printf("Procedure returned %d\n", dbretstatus(dbproc));
			}
		}

		dbclose(dbproc);
		dbexit();
		exit(0);
	}
	</programlisting></example>
				<calloutlist id="co.fetching"><title>Data-fetching Notes</title>
					<callout arearefs="samplecode.results.dbresults"><para>As soon as <function>dbresults()</function> reports <symbol>SUCCESS</symbol>, the row's metadata are available.</para></callout>
					<callout arearefs="samplecode.results.c"><para>&dblib; columns start with 1.</para></callout>
					<callout arearefs="samplecode.results.dbcollen"><para><function>dbcollen()</function> returns the sizeof the native data (e.g. 4 bytes for a T-SQL <symbol>INT</symbol>).  We'll use <function>dbbind()</function> to convert everything to strings.  If the column is <symbol>[VAR]CHAR</symbol>, we want the column's defined size, otherwise we want its maximum size when represented as a string.</para></callout>
					<callout arearefs="samplecode.results.dbbind"><para><symbol>NTBSTRINGBIND</symbol> null-terminates the character array for us.  <quote>NTB</quote> might perhaps stand for <quote>null terminating byte</quote>.</para></callout>
					<callout arearefs="samplecode.results.dbnullbind"><para>A zero-length string is not a NULL!  <function>dbnullbind()</function> arranges for the passed buffer to be set to -1 whenever that column is NULL for a particular row.</para></callout>
					<callout arearefs="samplecode.results.dbnextrow"><para>Each time <function>dbnextrow()</function> returns <symbol>REG_ROW</symbol>, it has filled the bound buffers with the converted values for the row.</para></callout>
					<callout arearefs="samplecode.results.computeid"><para>Computed rows are left as an exercise to the reader.</para></callout>
					</calloutlist></para>
			</sect2>
		
		<sect2 id="samplecode.errors"><title>Messages and Errors</title>
			<abstract><para>Errors may originate on the server or in the library itself.  The former are known as <firstterm>messages</firstterm> (because they are: they arrive as messages from the server); the latter are termed <firstterm>errors</firstterm>.  Their handling is a little intimidating.  It requires writing and installing a callback function (whose parameters are predefined by &dblib;), and thinking about how to handle different types of errors.</para></abstract>
			
			<variablelist><title>Kinds of Errors</title>
				<varlistentry>
					<term>Messages</term>
					<listitem>

<para><emphasis>Messages</emphasis> arise because the server has something to say.  <footnote><para>Just one more way in which databases differ from files.</para></footnote>.  They usually describe some problem encountered executing the SQL.  Perhaps the SQL refers to a nonexistent object or attempted to violate a constraint.  But they can also be benign, indicating for instance merely that the default database has changed.</para>
						</listitem>
					</varlistentry>
				<varlistentry>
					<term>Errors</term>
					<listitem>

<para><emphasis>Errors</emphasis> arise either because the application has misused &dblib; in some way &mdash; say, passed a NULL <symbol>DBPROCESS</symbol> pointer or tried to issue a query while results were pending &mdash; or because some trouble cropped up in communicating with the server (couldn't find it, say, or didn't hear back from it).</para>
						</listitem>
					</varlistentry>
				</variablelist>

<para>Why these two require distinct handling is lost in the mists of time. But it does help to keep them distinct in your mind, especially while reading the documentation.</para>
			

<para>To have &dblib; use your handler, pass its name to the appropriate  <function>dberrhandle()</function> or <function>dbmsghandle()</function> function immediately after calling <function>dbinit()</function>.</para>
			

<para><example id="e.g.samplecode.dblib.errors">
					<title>Sample Code: &dblib; Error and Message handlers</title>
<programlisting>
	int
	msg_handler(DBPROCESS *dbproc, DBINT msgno, int msgstate, int severity,
			char *msgtext, char *srvname, char *procname, int line)
	{									<co id="samplecode.errors.msghandler.args"/>
		enum {changed_database = 5701, changed_language = 5703 };	<co id="samplecode.errors.msghandler.suppress"/>

		if (msgno == changed_database || msgno == changed_language)
			return 0;

		if (msgno > 0) {
			fprintf(stderr, "Msg %ld, Level %d, State %d\n",
					(long) msgno, severity, msgstate);

			if (strlen(srvname) > 0)
				fprintf(stderr, "Server '%s', ", srvname);
			if (strlen(procname) > 0)
				fprintf(stderr, "Procedure '%s', ", procname);
			if (line > 0)
				fprintf(stderr, "Line %d", line);

			fprintf(stderr, "\n\t");
		}
		fprintf(stderr, "%s\n", msgtext);

		if (severity > 10) {						<co id="samplecode.errors.msghandler.severity"/>
			fprintf(stderr, "%s: error: severity %d > 10, exiting\n",
			options.appname, severity);
			exit(severity);
		}

		return 0;							<co id="samplecode.errors.msghandler.return"/>
	}
	
	int
	err_handler(DBPROCESS * dbproc, int severity, int dberr, int oserr,
			char *dberrstr, char *oserrstr)
	{									<co id="samplecode.errors.errhandler.args"/>
		if (dberr) {							<co id="samplecode.errors.errhandler.msgs"/>
			fprintf(stderr, "%s: Msg %d, Level %d\n",
			options.appname, dberr, severity);
			fprintf(stderr, "%s\n\n", dberrstr);
		} else {
			fprintf(stderr, "%s: DB-LIBRARY error:\n\t", options.appname);
			fprintf(stderr, "%s\n", dberrstr);
		}
	
		return INT_CANCEL;						<co id="samplecode.errors.errhandler.return"/>
	}
	</programlisting></example>
				<note><para>Handlers are always called before the function that engendered them returns control to the application.</para></note>
				<calloutlist><title>Error Handling Notes</title>
					<callout arearefs="samplecode.errors.msghandler.args"><para>When first writing a handler, pay careful attention to the precise type of each parameter.  Only by carefully matching them will you convince a modern <symbol>C</symbol> compiler that the address of your function is of the type accepted by <function>dbmsghandle()</function>. <footnote><para>Back in K&amp;R days, that wasn't such a problem.  But there were other problems, some much worse.</para></footnote></para></callout>
					<callout arearefs="samplecode.errors.msghandler.suppress"><para>Some messages don't convey much, as though the server gets lonely sometimes.  You're not obliged to print every one.</para></callout>
					<callout arearefs="samplecode.errors.msghandler.severity"><para>Severities are defined in the <emphasis>server</emphasis> documentation, and can be set by the <symbol>T-SQL RAISERROR</symbol> statement.</para></callout>
					<callout arearefs="samplecode.errors.msghandler.return"><para>Message handlers <emphasis>always and only ever</emphasis> return zero.</para></callout>
					<callout arearefs="samplecode.errors.errhandler.args"><para>When first writing the handler, pay careful attention to the precise type of each parameter.  Only by carefully matching them will you convince a modern <symbol>C</symbol> compiler that the address of your function is of the type accepted by <function>dberrhandle()</function>. <footnote><para>If that 					advice sounds familiar, it's because it bears repeating.</para></footnote></para></callout>
					<callout arearefs="samplecode.errors.errhandler.msgs"><para>Some messages are so severe they provoke &dblib; into calling the error handler, too!  If you have both installed &mdash; and of course you do, right? &mdash; then you can skip those lacking an error number.</para></callout>
					<callout arearefs="samplecode.errors.errhandler.return"><para>While <symbol>INT_CANCEL</symbol> is the most common return code, it's not the only one.  For one thing, the error handler's return code can control how long &dblib; keeps retrying timeout errors.  See the documentation for details.</para></callout>
					</calloutlist></para>
			

<para><note><para>No matter what the error handler says or does, it can't remedy the error.  It's <emphasis>still</emphasis> an error and usually the best that can happen is that the function will return <symbol>FAIL</symbol>.  The exception is timeout conditions, when the handler can stave off failure by requesting retries.</para></note></para>
			

<para>You may be asking yourself, <quote>OK, fine, I can print the error message.  But what if I want to communicate something back to the line in my program where the error occurred?  How to do that?</quote>  First of all, remember  the calling function &mdash; that's your application &mdash; will learn of an error from the return code.  If it needs more detail, though, there are two ways to pass it.
				
				<orderedlist>
					<listitem><para>Set a global variable.</para></listitem>
					<listitem><para>Use 	<function>setuserdata()</function> and
							<function>getuserdata()</function>.</para></listitem>
					</orderedlist>
				
				<tip><para>If your application is written in <symbol>C++</symbol>, you may be tempted to use <function>throw()</function>. Don't!  Your handler is a <symbol>C</symbol> function and, more important, <emphasis>it's an extension of &dblib;</emphasis>.  You can put a <function>throw()</function> in your handler and it will compile. But when it executes, it's going to rip through &dblib;'s stack.  Your application will be unuseable at that point, if it doesn't cause a segment fault.</para></tip></para>
			
			</sect2>
		
		<sect2 id="samplecode.wrapup"><title>Last Remarks</title>

<para>We've reached the end of our &dblib; tour.  The almost 300 lines of <symbol>C</symbol> above constitute program with these features:
				<itemizedlist><title> Sample Code features</title>
					<listitem><para>Accepts command-line parameters and SQL.</para></listitem>
					<listitem><para>Checks for errors and server messages.</para></listitem>
					<listitem><para>Processes any number of results..</para></listitem>
					<listitem><para>Prints results in columns of suitable widths.</para></listitem>
					</itemizedlist>
				
				There are things it doesn't do, in the name of simplicity.
				<itemizedlist><title> Sample Code nonfeatures</title>
					<listitem><para>No BCP (bulk copy) mode</para></listitem>
					<listitem><para>No RPC (remote procedure call) mode, preventing it from  retrieving output parameters.</para></listitem>
					</itemizedlist>
				Your humble author hopes you found it worthwhile.  Happy Hacking.</para>
			</sect2>
						
		</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:brian@bruns.org">Brian Bruns</ulink> (brian@bruns.org)</member>
			<member>Started this crazy thing</member>
			<member>
				<ulink url="mailto:misa@dntis.ro">Mihai Ibanescu</ulink> (misa@dntis.ro)</member>
			<member><acronym>GNU</acronym>ified the packet</member>
			<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>
			<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>
			<member>
				<ulink url="mailto:smurph@smcomp.com">Steve Murphree</ulink> (smurph@smcomp.com)</member>
			<member>Added more ODBC functionality.  </member>
			<member>
				<ulink url="mailto:psaar@fenar.ee">Arno Pedusaar</ulink> (psaar@fenar.ee)</member>
			<member>Donated his <acronym>TDS</acronym>4.2 code to the cause</member>
			<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>
			<member>
				<ulink url="mailto:cts@internetcds.com">Craig Spannring</ulink> (cts@internetcds.com)</member>
			<member>Wrote the  <acronym>JDBC</acronym> and DBI drivers</member>
			<member>
				<ulink url="mailto:thompbil@exchange.uk.ml.com">Bill Thompson</ulink> (thompbil@exchange.uk.ml.com)</member>
			<member>Completer of the &dblib; bcp API and author of <application>freebcp</application>.</member>
			<member>
				<ulink url="mailto:freddy77@gmail.com">Frediano Ziglio</ulink> (freddy77@gmail.com)</member>
			<member>Extended the ODBC library, and added many, many fixes and enhancements to libtds.  </member>
			</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>
			<member>James Cameron</member>
			<member>Allen Grace</member>
			<member>James K. Lowden</member>
			<member>Bill Thompson</member>
			<member>Frediano Ziglio</member>
			</simplelist>

<para></para>
		</sect1>
	
	</chapter>

<!-- ////////////////// Appendix  ////////////////// -->

<appendix id="rtl">
	<title>On Linkers</title>
	<abstract><para>&freetds; is a library, obviously, its functions invoked by an application.  How the application finds the library can be mysterious.  In the interest of making &freetds; easier to use, this appendix discusses how it all works.   </para>
	<para>This appendix focusses on <emphasis>using</emphasis> &freetds; in your application.  It isn't intended to help in building &freetds;, although the background information it provides might be useful.  </para>	
	</abstract>

	<section id="rtl.define.function">
		<title>What is a C function?</title>

<para>A C function is a named bit of code.</para>

<para>A C compiler recognizes function names in source code by parsing the C language.  When it encounters a function name, it looks for a <emphasis>definition</emphasis> for the function &mdash; i.e. actual code implementing it &mdash; in the current file.  If it finds one, it creates machine instructions to push any parameters on the stack, jump to the named address, and clear the stack after the functions returns.  If it doesn't find one, it shrugs<footnote><para>You have to watch carefully.  Modern compilers shrug quickly.  </para></footnote> and adds that name to the list of names to be <firstterm>resolved</firstterm> later.  We'll get to what that means in a minute.   </para>  

<para>The compiler's job ends where the linker's begins.   
		<itemizedlist><title>Compiler's job</title>
			<listitem><para>Convert source code into object code </para></listitem>
			<listitem><para>Put in jumps to defined functions </para></listitem>
			<listitem><para>Create a list of defined functions, and their addresses </para></listitem>
			<listitem><para>Create a list of undefined functions </para></listitem>
		</itemizedlist>

The <command>nm</command> utility displays function names.  Here are the ones defined by <filename>bsqldb.c</filename> (in <filename>bsqsldb.o</filename>):

<screen><prompt>$ </prompt><userinput>nm bsqldb.o | grep -wi t</userinput>
<computeroutput>0000000000000000 T err_handler
0000000000000270 T get_login
00000000000001d0 t get_printable_size
0000000000000940 T main
00000000000000a0 T msg_handler
00000000000007d0 t next_query
00000000000006c0 t set_format_string
0000000000000080 t usage</computeroutput></screen>

GNU <command>nm</command> marks with a lower-case letter functions that are locally defined, not intended to be used outside the file.  The C programmer marked those functions <emphasis>static</emphasis>.  Note how closely the source code corresponds to the object code: 

<screen><prompt>$ </prompt><userinput>grep ^static src/bsqldb.c</userinput>
<computeroutput>static int next_query(DBPROCESS *dbproc);
static void print_results(DBPROCESS *dbproc);
static int get_printable_size(int type, int size);
static void usage(const char invoked_as[]);
static int set_format_string(struct METADATA * meta, const char separator[]);
</computeroutput></screen>

(Order doesn't matter.  It's a set, not a list.)  
    </para>

<para>Here are some functions used, but not defined, by <filename>bsqldb.o</filename>:

<screen id="bsqldb.unresolved"><prompt>$ </prompt><userinput>nm bsqldb.o | grep -w U | head</userinput>
<computeroutput>                 U __assert_fail
                 U __ctype_b_loc
                 U __errno_location
                 U __strdup
                 U __xpg_basename
                 U asprintf
                 U calloc
                 U dbaltbind
                 U dbaltcolid
                 U dbaltlen</computeroutput></screen>

Two things to note.  First, the functions defined by <filename>bsqldb.o</filename> have addresses, and undefined functions don't.  Second, <emphasis>only the name</emphasis> identifies the function.  It's been that way since about 1978, and it's one reason C libraries are so useful: to find a function, the tool need only <firstterm>resolve the name</firstterm>, i.e. convert the name into an address.  The caller (the programmer, really) has to know the function's inputs and semantics (how it behaves), but the tool's job is bone simple.  Which turns out to be quite handy.        
	</para>

<!--
To the compiler and linker, a

It has an address &mdash; a location &mdash; in the <firstterm>text</firstterm> of a module.  (<quote>Text</quote> here refers to the machine code output by the compiler.)  
-->
			</section>
	
	<section id="rtl.define.library">
		<title>What is a C library?</title>
<para>A C library is a set of named functions, for example <literal>dbinit()</literal> or <literal>SQLConnect()</literal>.  Or, for that matter, <literal>fopen(3)</literal><footnote><para>The Unix convention is to put in parentheses behind the name the section of the manual in which the function is documented.  &freetds; functions don't get numbers because they're not in the manual.  Yet.  </para></footnote>.  </para>

<para>Libraries come in two flavors: <firstterm>static</firstterm> and <firstterm>dynamic</firstterm>.  </para>

		<section id="rtl.define.library.static">
			<title>Static libraries</title>
<para>Static libraries (also known as <firstterm>archives</firstterm>) have been around as long as C itself.  Like a <literal>.zip</literal> file, they're just a bag of object files &mdash; containing functions, of course &mdash; with a table of contents in front giving the address of each name<footnote><para>Or, depending on how you look at it, the name of each address.</para></footnote>.  Static libraries are created from object files using a <firstterm>librarian</firstterm> utility of some kind.  One such programs is <command>ar</command>, for <emphasis>archive</emphasis>.  </para>

<para>Static libraries are part of the build environment.  Functions in static libraries are joined to a program's main module by a <firstterm>static linker</firstterm> at build time to produce an executable program.  The executable incorporates the libraries' object code into its own body, making it completely self-sufficient.  </para>
		</section>

		<section id="rtl.define.library.dynamic">
			<title>Dynamic libraries</title>

<para>Dynamic libraries are the new kid on the block, as these things go, arriving on the Unix scene circa 1985.   Like a static library, a dynamic library is a collection of functions with a table of contents.  They are referenced at build time to give the executatble information about how they will eventually be used, but they aren't <emphasis>used</emphasis> until run time.  </para>

<para>Dynamic libraries are part of the run-time environment.  When a program is run, the run-time linker finds the dynamic libraries needed by the program, finds the addresses of the required functions, and assembles a runable image in memory.  Missing libraries and/or missing functions &mdash; or the wrong versions of them &mdash; can lead to head-scratching and other amusing behavior.  </para>

<para>In Windows&reg; dynamic libraries are called <firstterm>dynamic link libraries</firstterm> (DLLs).  In Unix they're normally called <firstterm>shared objects</firstterm>.  But they're roughly the same thing.    </para>

<para><note>
	<title>What about <literal>.h</literal> files?</title>

<para>C header files include <firstterm>functional prototypes</firstterm>, declarations (not <emphasis>definitions)</emphasis> of functions.  Functional prototypes describe to the compiler each function's parameters, allowing the compiler to confirm that the function is being called correctly.  </para>

<para>Most of the functions declared in header files are implemented in libraries.  However, there's <emphasis>no mechanical or automatic relationship</emphasis> between the functional prototypes in the header files and their implementation in a library.  The <literal>.h</literal> file is maintained by hand, by the programmer, and is used to generate a library.  The header file and associated library are distributed and installed together (one hopes), but correct installation and subsequent use by the compiler &amp; linker require human beings to keep track of the pair.  Failure to do so leads to <quote>interesting</quote> development and even run-time problems, especially with libraries whose functions' parameters change from version to version. </para>

<para>For example, imagine a function <literal>f(int g)</literal> defined in library <filename>libf.so</filename> and declared in <filename>f.h</filename>.  In a later version of <filename>libf.so</filename>, the function's parameter is changed to use a pointer, <literal>f(int *p)</literal>, and <filename>f.h</filename> is likewise updated.  Possible errors that cannot be prevented by the linker include: 

<orderedlist>
	<listitem><para>An old program could use the new library.  Probably the integer it passes will be interpreted as an out-of-bounds address, resulting in a segmentation violation.   </para></listitem>
	
	<listitem><para>A new program could use the old library, passing an address that the library interprets as an integer.  Hillarity ensues.  </para></listitem> 
	
	<listitem><para>Existing source code could be compiled using the old header file but linked to the new library.  If you've never done that, give it time.   </para></listitem>
	</orderedlist>

These errors are possible because C functions are identified to the linker <emphasis>by name only</emphasis>.  On the upside, that makes the tools simple and easy to implement and, by the same token, simplifies the use of C libraries by other languages.  The downside is that the work of ensuring that the right libraries are used becomes an administrative task instead of a technical one.   </para></note></para>

			</section>
		</section>
	<section id="linker.library.check">
		<title>Checking if a Library Provides a Function</title>

<para>A linker, any linker, knits together object files (some of which may be in libraries) such that every function needed by the program has a definition.  If the linker fails to locate a definition for even one function, it will fail and the program will not run.  </para>

<para>Returning to <link linkend="bsqldb.unresolved"><filename>bsqldb.o</filename></link>, we can use <command>nm</command> to see which functions are unresolved, and determine whether or not a particular library contains them.  We'll ignore the symbols that start with an underscore, marking them per the C standard as being provided by the implementation<footnote><para>Why and how leading underscores enter into this discussion is just one more example of arcane historical practices one needs to know to master the subject.  For our purposes, though, it's enough to know that <quote>implementation-provided</quote> functions like these &mdash; functions provided by the C standard library &mdash; often have an underscored prepended.  </para></footnote>, and focus on the last five in this abbreviated list.  

 <variablelist>
 	<title>Some unresolved functions in <filename>bsqldb.o</filename></title>
	<varlistentry>
		<term><function>asprintf</function></term>
		<term><function>basename</function></term>
		<listitem>
			<para>Normally provided by the standard C library, but if not by &freetds;'s replacements library: 
<screen><prompt>$ </prompt><userinput>nm /usr/lib/libc.a | grep -w T | grep -E 'asprintf|basename'
</userinput>
<computeroutput>0000000000000000 T _basename
0000000000000000 T _asprintf</computeroutput>
</screen>
			</para>
			</listitem>
		</varlistentry>	
	<varlistentry>
		<term><function>calloc</function></term>
		<listitem>
			<para>Provided by the standard C library:
<screen><prompt>$ </prompt><userinput>nm /usr/lib/libc.a | grep -w T | grep calloc </userinput>
<computeroutput>0000000000004240 T calloc</computeroutput>
</screen>
			</para>
			</listitem>
		</varlistentry>	
	<varlistentry>
		<term><function>dbaltbind</function></term>
		<term><function>dbaltcolid</function></term>
		<listitem>
			<para>Provided by &dblib;:
<screen><prompt>$ </prompt><userinput>nm libsybdb.a | grep -Ew 'dbaltbind|dbaltcolid'</userinput>
<computeroutput>0000000000007140 T dbaltbind
0000000000003590 T dbaltcolid</computeroutput>
</screen>
			</para>
			</listitem>
		</varlistentry>	
	</variablelist>

Although these examples refer to static libraries, <command>nm</command> works just as well with dynamic libraries, too.  
</para>

<para>There are other tools besides <command>nm</command>.  Windows&reg;, for instance, has <command>dumpbin</command>, and the GNU bintools include <command>objdump</command>.  </para>
		</section>

	<section id="linker.how">
		<title>How Dost Thy Linker Link? </title>

<para>Now at last we come to how the linker performs its magic.  Once again the discussion divides between static and dynamic linking.  </para>

		<section>
			<title>Static Linker</title>

<para>Static linking happens at build time.  Object files are collected together; a distinct list of all function names is created, and the linker is tasked with finding a definition for each one.  </para>

<para>Different linkers have different command-line options to support OS-specific features.  This document isn't intended to teach how to use any particular linker.  Our task here is to understand the principles involved, so that you can apply them to your particular situation.  </para>

<para>The static linker needs three kinds of information:
<orderedlist><title>Static linker inputs</title>
	<listitem><para>Object modules to be linked, including libraries </para></listitem>
	<listitem><para>Locations of libraries </para></listitem>
	<listitem><para>Search order </para></listitem>
</orderedlist></para>

			<section>
				<title>Knitting together the object modules</title>
<para>The static linker merges your object files into one executable.  Your project's object files may refer freely (usually) to each other's functions, and the linker will match them up.  It will catenate them together, compute every function's offset from the start of the executable, and replace every function reference with the actual address needed for the executable it's constructing.  For library functions, definitions are copied from the library and appended to the output file (executable).  The placeholder addresses left by the compiler are similarly replaced by offsets.  </para>
				</section>

			<section>
				<title>Specifying libraries</title>
<para></para>
<para>An application programmer using &freetds; will need to mention the name fo the &freetds; library being used.  Failure to do so will provoke the dread <firstterm>undefined reference</firstterm> linker error: 

<example><title>Missing library name</title>
<screen><prompt>$ </prompt><userinput>gcc -o bsqldb bsqldb.o  </userinput>
<computeroutput>bsqldb.o: In function `get_login':
../../../src/apps/bsqldb.c:816: undefined reference to `dblogin'
../../../src/apps/bsqldb.c:823: undefined reference to `dbsetlname'
../../../src/apps/bsqldb.c:874: undefined reference to `dbsetlname'
../../../src/apps/bsqldb.c:884: undefined reference to `dbsetlname'
../../../src/apps/bsqldb.c:889: undefined reference to `dbsetlname'
&hellip;</computeroutput>
</screen>
</example>
</para>
				</section>

			<section>
				<title>Finding libraries</title>

<para>Specifying the library is necessary but may be insufficient.  The linker may need to be told where to look for the library.  This is often the case for the application programmer using &freetds; because the &freetds; libraries may be installed in a location not on the linker's default search path.  Linkers are usually pretty blunt about missing libraries: 

<example><title>Library not found</title>
<screen><prompt>$ </prompt><userinput>gcc -o bsqldb bsqldb.o  -l sybdb</userinput>
<computeroutput>ld: cannot find -lsybdb</computeroutput>
</screen>
</example>
</para>

<para><emphasis>Order matters</emphasis>.  Linkers tend to be fussy about library search order, some more than others.  It's good practice to tell the linker to search project libraries first, third-party libraries (e.g. iconv or kerberos) next, and finally system libraries.  </para>

				</section>
			</section>

		<section id="linker.dynamic">
			<title>Dynamic Linker</title>
<para>The dynamic linker &mdash; also known as the runtime linker &mdash; is, like the rest of dynamic linking, more complicated than its static counterpart.  Whereas it's impossible even to generate an executable with missing static function references, an executable that uses dynamic libraries depends on the runtime environment to have its references satisfied.</para>

<para>When a dynamically linked application is launched, the OS invokes the runtime linker to resolve any undefined references.  Much as the static linker does, the runtime linker consults a list of dynamic libraries along its configured search path.  The names of the libraries to search for are embedded in the executable.  Sometimes, not always, the search path is found in the executable too.  Usually any embedded path can be overridden.  </para>

			<section id="linker.dynamic.the.executable">
				<title>Information in the executable</title>

<para>Exactly what information is in the executable and how to display it depends on the format of the executable.  Different OSes use different formats and most Unix derivatives actually support at least two.  The most commonly encountered format for the &freetds; programmer is the ELF format.  In the interest of your time and mine, that's the one we'll examine here.  </para>

<para>The GNU bintool utility <command>readelf</command> displays the information in the executable that is input to the runtime linker:

<screen><prompt>$ </prompt><userinput>readelf -d src/apps/.libs/bsqldb</userinput>
<computeroutput>Dynamic section at offset 0x6028 contains 20 entries:
  Tag        Type                         Name/Value
 0x0000000000000001 (NEEDED)             Shared library: [libsybdb.so.5]
 0x0000000000000001 (NEEDED)             Shared library: [libpthread.so.0]
 0x0000000000000001 (NEEDED)             Shared library: [libc.so.12]
 0x000000000000000f (RPATH)              Library rpath: [/usr/pkg/lib:/usr/local/lib]
&hellip;</computeroutput>
</screen>
	</para>
	
<para>What is this telling us?  First, the <filename>bsqldb</filename> executable uses three shared libraries, namely <literal>sybdb</literal> for &dblib;, <literal>pthread</literal> for POSIX threads, and <literal>c</literal>, the C standard library.  The runtime linker is going to have to find those somewhere, and it's going to use only those libraries to resolve unresolved references in the executable.  </para>

<para>Second, <command>readelf</command> displays the <literal>RPATH</literal>.  The runtime linker searches for the required dynamic libraries in the directories listed in the <literal>RPATH</literal>, if extant.  </para>

<para>The <literal>RPATH</literal> is placed in the executable by the static linker.  It can be thought of as a hint from the application builder to the system administrator.  If an executable is built with an appropriate <literal>RPATH</literal>, the runtine linker will have all the information it needs to find the required libraries.   </para>
				</section>
				
			<section id="linker.dynamic.ld.so">
				<title>Information outside the executable</title>

<para><note><para>Runtime linkers differ.  The advice and observations that follow apply in many situations, but not all.  The best way to know how <emphasis>yours</emphasis> works is to consult your system's documentation.  RTFM!  </para></note></para>

<para>The NetBSD and GNU linkers both (as of this writing on machines used by the author) honor a configuration file and environment variables.  They also have compiled-in default search locations.  At a minimum, the default is <filename>/usr/lib</filename>.  Sometimes a configuration file extends this to <filename>/usr/local/lib</filename>.   </para>

<para>The primary environment variable is <envar>LD_LIBRARY_PATH</envar>.  On some systems this <emphasis>overrides</emphasis> the <literal>RPATH</literal> in the executable.  In others it doesn't.  Where ineffective, specific libraries (not their paths) can be forceably used with <envar>LD_PRELOAD</envar>.  </para>
				</section>

			<section id="linker.dynamic.ldd">
				<title>Displaying what the Runtime linker will do</title>

<para>The <command>ldd(1)</command> shows which dynamic libraries an executable requires and where, if at all, they'll be found:

<screen><prompt>$ </prompt><userinput>ldd $(command -v bsqldb)</userinput>
<computeroutput>/usr/local/bin/bsqldb:
        -lc.12 => /usr/lib/libc.so.12
        -lpthread.0 => /usr/lib/libpthread.so.0
        -lsybdb.5 => /usr/local/lib/libsybdb.so.5</computeroutput>
</screen>

Important to understand: <command>ldd</command> is <emphasis>not</emphasis> figuring out this information by itself.  It just reports the results of its interrogation of the runtime linker.  As the configuration of the runtime linker is changed, so changes the output of <command>ldd</command>.  </para>
				</section>

			<section id="linker.dynamic.win32">
				<title>A Word about Windows&reg;</title>
<para>Windows executables use PE format (derived from the older COFF format), which has no provision for an <literal>RPATH</literal>.
The runtime linker searches the <literal>PATH</literal> instead, after some built-in locations that usually include the current working directory.
Neither <command>ldd</command> nor any similar utility is included in the basic product.</para>

<para>It has been said that Unix is for <emphasis>programmers</emphasis> and Windows is for <emphasis>users</emphasis>, and perhaps that roughly describes the  intention.  But the Unix features listed above &mdash; <literal>RPATH</literal> and <command>ldd</command> &mdash; as well as a canonical filesystem hierarchy and dynamic library versioning, all promote a better <emphasis>user</emphasis> experience.  Because of them, the problem of DLL conflicts in Windows hardly exists in Unix.  Yet they are neither new nor secrect nor patented nor complicated; Microsoft could have adopted them years ago (as Apple finally did).  We therefore know that the 20-year old phenomemon known as &ldquo;DLL hell&rdquo; is not inevitable, but a <emphasis>choice</emphasis> signifying nothing so much as Microsoft's indifference to its customers.
Recently Microsoft added support to configure different search paths and other attributes based on <literal>Application Manifests</literal>
and <literal>Application Configuration Files</literal>.</para>

				</section>

			<section id="linker.dynamic.advice">
				<title>Advice for the lazy</title>

<para>To avoid tinkering with your runtime linker, embed an <literal>RPATH</literal> in your executable commensurate with its intended runtime environment.  If <command>ldd</command> doesn't show the libraries you want, or some are not found, use <command>readelf</command> to see which libraries are used and the <literal>RPATH</literal>.  Relink with a better <literal>RPATH</literal> if needed.  </para>

<para>When testing with new libraries, use <envar>LD_PRELOAD</envar> to override the default, taking care that the semantics haven't changed.  </para>

				</section>

			</section> <!-- end linker.dynamic -->
		</section>
	<section id="linker.conclusion">
		<title>Keep in Mind</title>
<para>The compiler's job ends on the last line of each source code file.  A header file describes a function <emphasis>for the compiler</emphasis>, not the linker.  </para>

<para>The linker, static or runtime, uses only the function's name to resolve references.  Function parameters and semantics are invisible to it.  </para>

<para>The programmer and, to a lesser degree, the sysadmin direct the choice of which library to link to an executable.  A missing function will prevent execution.  A wrong function will promote wrong execution.  Don't do that.  </para>

		</section>
	</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.  &freetds; inherited this file structure with minor alterations.  The <filename>interfaces</filename> remains supported for backward compatibility, and for those running in a mixed &freetds;/Sybase environment.</para>

<para>The <filename>interfaces</filename> is not read by &freetds; unless it does not find &freetdsconf;.  Note also that <command>make install</command> will install a skeleton &freetdsconf;, 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 &freetds; will find it.
By the way before looking for <filename>$SYBASE/interfaces</filename> file FreeTDS try to open file specified programmatically (for instance by <function>dbsetifile()</function> using &dblib;) and <filename>.interfaces</filename> in your home directory.</para>
		</sect1>
	<sect1 id="interfacespurpose">
		<title>What it does</title>

<para>The <filename>interfaces</filename> file aliases a servername to the hostname and port number of the servername's machine.  When &freetds; receives a request to connect to a database server, it looks up the servername 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>servername</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>servername</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>servername</emphasis>  to look up the <emphasis>host name</emphasis>, &freetds; 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.  &freetds; 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 &freetds;.</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, &freetds; 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.  &freetds; 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, &freetds; brings the otherwise innocent programmer into contact with the arcane business of how data are stored and transported.  &freetds; 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</acronym>: What everyone knows</title>

<para>The world we are all familiar with, programmingwise, is <acronym>ASCII</acronym>.  Our email (mostly), our <quote>text</quote> files, our web pages (mostly), all use <acronym>ASCII</acronym> to represent English (or English-like) text. Perhaps because <ulink url="http://czyborra.com/charsets/iso646.html"><acronym>ASCII</acronym></ulink> 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</acronym> 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</acronym> 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</acronym> Compact</title>

<para>UNIX&reg; and unix-like systems bought into <acronym>ASCII</acronym> big time.  Program code, filenames, string constants (and variables), configuration files, everything but everything is encoded in <acronym>ASCII</acronym>.  Practically every utility, command, and library assumes the <quote>text</quote> data will be <acronym>ASCII</acronym>. At the dawn of the 21<superscript>st</superscript> century, there is widespread recognition that <acronym>ASCII</acronym> 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</acronym> won, it would seem, but the race goes not to the swift.  <acronym>ASCII</acronym> 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</acronym> 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 &mdash; even English with em dashes and cent (&cent;) signs &mdash; 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</acronym></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</acronym> 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</acronym> was extended to 8 bits, Unicode extends the most prevalent <quote>8-bit <acronym>ASCII</acronym></quote>,  <acronym>ISO 8859-1</acronym>, to 16 and 32 bits.  The first 256 values remain in Unicode as in <acronym>ISO 8859-1</acronym>: 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 was the initial system employed by Microsoft NT-based systems while recent versions moved to UTF-16.
Microsoft database servers store UCS-2/UTF-16 strings in <type>nchar</type> and <type>nvarchar</type> datatypes.
Microsoft also designed version 7.0 (and up) of the <acronym>TDS</acronym> protocol around UCS-2/UTF-16: all metadata (table names and such) are encoded according to these encoding 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</acronym>.</para>

<para>The basic problem, from a programmer's perspective, is the ancient agreement Unix entered into 30 years ago, the <quote><acronym>ASCII</acronym> Compact,</quote> alluded to earlier.  Assumptions about <acronym>ASCII</acronym> 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</acronym>.  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</acronym> 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> explanations 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 &mdash; practically the only one used &mdash; 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</acronym> range (0-127).  UTF-8 does not use zero to represent any part of any character (except for the <acronym>ASCII</acronym> 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</acronym> strings.  These properties make UTF-8 data relatively easy for systems accustomed to processing <acronym>ASCII</acronym> 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</acronym> when <acronym>ASCII</acronym>'s all that's needed.  But it lacks <acronym>ASCII</acronym>'s limitations.</para>

<para>While UTF-8 solves many technical problems, it doesn't magically transform every <acronym>ASCII</acronym>-assuming system into a Unicode system.  For example, to display Unicode data correctly &mdash; even Unicode data in UTF-8 format &mdash; 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 Microsoft SQL Server 6.5) transmit their data in UCS-2 format (16-bit integers).
Because most applications linked to &freetds; are not prepared to deal with UCS-2 data, &freetds; can convert the data to something more acceptable, including <acronym>ASCII</acronym>.
To do so, it employs an  <productname>iconv</productname>  library.
&freetds; determines the server's encoding from the TDS protocol and information reported by the server (generally per connection, but in the case of TDS 7.1, per result set column).
It discovers the client's encoding in &freetdsconf;.
&freetds; 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, &freetds; aims to support Unicode and other multi-byte character sets.
It does not do so at the current time, beside using wide functions in ODBC.</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  &freetds; <emphasis>could</emphasis> 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 &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://worldpowersystems.com/J/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>