Mercurial > mxe-octave
changeset 1583:a617b89f0696
upgrade package freetds to cvs
| author | Mark Brand <mabrand@mabrand.nl> |
|---|---|
| date | Mon, 14 Feb 2011 17:10:13 +0100 |
| parents | eb5def36aacb |
| children | 727f84d128a1 |
| files | src/freetds-1-fastforward.patch |
| diffstat | 1 files changed, 9552 insertions(+), 0 deletions(-) [+] |
line wrap: on
line diff
--- a/src/freetds-1-fastforward.patch Mon Feb 14 20:26:33 2011 +1100 +++ b/src/freetds-1-fastforward.patch Mon Feb 14 17:10:13 2011 +0100 @@ -165729,3 +165729,9555 @@ static const iconv_get_t iconv_gets[8] = { get_iso1, get_ascii, get_utf16le, get_utf16be, get_ucs4le, get_ucs4be, get_utf8, get_err + +commit 8a95ff50cdd242434bc0428280f4992cc69fa773 +Author: jklowden <jklowden> +Date: Sun Feb 13 01:54:37 2011 +0000 + + Add linker appendix + +diff --git a/ChangeLog b/ChangeLog +index 9a5b5ce..e0dacf2 100644 +--- a/ChangeLog ++++ b/ChangeLog +@@ -1,3 +1,6 @@ ++Sat Feb 12 20:53:19 EST 2011 JK Lowden <jklowden@freetds.org> ++ * doc/userguide.sgml Add linker appendix ++ + Fri Feb 11 14:54:17 CET 2011 Frediano Ziglio <freddy77_A_gmail_D_com> + * src/replacements/iconv.c: + - improve iconv replacement unsigned/signed declaration +@@ -3157,4 +3160,4 @@ Wed Jan 9 19:54:43 EST 2008 JK Lowden <jklowden@freetds.org> + * ChangeLog-0.82 added because of release + + $FreeTDS$ +-$Id: ChangeLog,v 1.3196 2011/02/11 13:54:43 freddy77 Exp $ ++$Id: ChangeLog,v 1.3197 2011/02/13 01:54:37 jklowden Exp $ +diff --git a/doc/userguide.sgml b/doc/userguide.sgml +index 641ef39..6316797 100644 +--- a/doc/userguide.sgml ++++ b/doc/userguide.sgml +@@ -2,240 +2,217 @@ + <!ENTITY dblibapisgml SYSTEM "../../../dblib.api.sgml"> + <!ENTITY ctlibapisgml SYSTEM "../../../ctlib.api.sgml"> + <!ENTITY odbcapisgml SYSTEM "../../../odbc.api.sgml"> ++ <!ENTITY % comment "IGNORE" > + <!ENTITY ora "O'Reilly & 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 version "0.92"> <!-- echo '0.84 + 0.5 * (1.0 - 0.84)' --> + <!ENTITY freetdsconf "<filename>freetds.conf</filename>"> + ]> + <book> +- <bookinfo> +- <date>$Date: 2011/01/25 06:18:53 $</date> +- <releaseinfo>$Revision: 1.132 $</releaseinfo> +- <title>&freetds; User Guide</title> +- <subtitle>A Guide to Installing, Configuring, and Running &freetds;</subtitle> +- <author> +- <firstname>Brian</firstname> +- <surname>Bruns</surname> ++<bookinfo> ++ <date>$Date: 2011/02/13 01:54:38 $</date> ++ <releaseinfo>$Revision: 1.133 $</releaseinfo> ++ <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> ++ <firstname>James</firstname> ++ <othername>K.</othername> ++ <surname>Lowden</surname> + </author> +- <copyright> +- <year>2001</year> +- <year>2002</year> +- <year>2003</year> +- <year>2004</year> +- <year>2005</year> +- <year>2006</year> +- <year>2007</year> +- <year>2008</year> +- <year>2009</year> +- <year>2010</year> +- <holder>Brian Bruns and James K. Lowden</holder> ++ <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> +- <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><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> ++<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>$Revision: 1.132 $</> +-<member>$Date: 2011/01/25 06:18:53 $</> +-<member>CVS control number $Id: userguide.sgml,v 1.132 2011/01/25 06:18:53 jklowden Exp $.</> +- </simplelist> ++<!-- ////////////////// 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>$Revision: 1.133 $</> ++ <member>$Date: 2011/02/13 01:54:38 $</> ++ <member>CVS control number $Id: userguide.sgml,v 1.133 2011/02/13 01:54:38 jklowden Exp $.</> ++ </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 CVS tree. If you find something wrong, unclear, badly put, misleading, or incorrigible, I hope you will let us know. Post your musings or rants to the mailing list (see <link linkend="contrib">Helping</link>). Patches to <filename>doc/userguide.sgml</> are especially welcome, of course. By taking the time let us know what you think, perhaps the path to enlightenment will be made a little smoother for the fellow behind you. +- </para> +- <para> +-A few technical notes. This guide is written in SGML DocBook format, specifications for which are found in the <ulink url="http://www.docbook.org/tdg/en/html/docbook.html">DocBook book</ulink>. It was converted to HTML with <ulink url="http://openjade.sourceforge.net">OpenJade</ulink>. +-The SGML text is distributed with the rest of the source code, and may be edited with your favorite or least favorite text editor. +- </para> +- <para> +-Enough. Let's begin. +- </para> +- <para> +- --jkl +- </para> ++ 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 CVS tree. If you find something wrong, unclear, badly put, misleading, or incorrigible, I hope you will let us know. Post your musings or rants to the mailing list (see <link linkend="contrib">Helping</link>). Patches to <filename>doc/userguide.sgml</> are especially welcome, of course. By taking the time let us know what you think, perhaps the path to enlightenment will be made a little smoother for the fellow behind you.</para> ++ ++<para>A few technical notes. This guide is written in SGML DocBook format, specifications for which are found in the <ulink url="http://www.docbook.org/tdg/en/html/docbook.html">DocBook book</ulink>. It was converted to HTML with <ulink url="http://openjade.sourceforge.net">OpenJade</ulink>. ++ The SGML text is distributed with the rest of the source code, and may be edited with your favorite or least favorite text editor.</para> ++ ++<para>Enough. Let's begin.</para> ++ ++<para>--jkl</para> + </preface> + +- <chapter id="what"> +- <title>What is &freetds;?</title> +- +- <para> +-&freetds; is an open source (or free software if you prefer) programming library, a re-implementation of the Tabular Data Stream protocol. It can be used in place of Sybase's <systemitem class="library">db-lib</systemitem> or <systemitem class="library">ct-lib</systemitem> libraries. It also includes an <systemitem class="library">ODBC library</systemitem>. It allows many open source applications such as <productname>Perl</productname> and <productname>PHP</productname> (or your own C or C++ program) to connect to Sybase or Microsoft <productname>SQL Server</productname>. +- </para> +- <para> +-&freetds; is distributed in source code form, and is expected to compile on just about any operating system. That means every form of Unix® and Unix-like™ system (including notable variants such as Interix® and QNX®), as well as Win32®, VMS®, and OS X®. If it doesn't compile on your system — and you're not using MS-DOS® — it's probably considered a bug. +- </para> +- <sect1 id="tdsprotocolhist"> +- <title>Background: The <acronym>TDS</> Protocol +- and related <acronym>API</>s ++<chapter id="what"> ++ <title>What is &freetds;?</title> ++ ++ ++<para>&freetds; is re-implementation of C libraries originally implmented by Sybase and Microsoft SQL Server. It includes drop-in replacements for ++ ++<itemizedlist> ++ <listitem><para>Sybase's <systemitem class="library">DB-Library</systemitem> or <systemitem class="library">CT-Library</systemitem></para></listitem> ++ <listitem><para>Microsoft's <systemitem class="library">DB-Library</systemitem> (which differs in small details from Sybase's)</para></listitem> ++ <listitem><para>an <systemitem class="library">ODBC library</systemitem> similar that provided by the vendors</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. ++ ++&freetds; 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; is distributed in source code form, and is expected to compile on just about any operating system. That means every form of Unix® and Unix-like™ system (including notable variants such as Interix® and QNX®), as well as Win32®, VMS®, and OS X®. If it doesn't compile on your system — and you're not using MS-DOS® — it's probably considered a bug.</para> ++ ++ <sect1 id="tdsprotocolhist"> ++ <title>Background: The <acronym>TDS</> Protocol ++ and related <acronym>API</>s + </title> +- <para> +-<acronym>TDS</> is a <firstterm>protocol</firstterm>, a set of rules describing how to transmit data between two computers. Like any protocol, it defines the types of messages that can be sent, and the order in which they may be sent. Protocols describe the <quote>bits on the wire</quote>, how data flow. +- </para> +- <para> +-In reading this manual, it may be helpful to keep in mind that a protocol is not an <acronym>API</>, although the two are related. The server recognizes and speaks a protocol; anything that can send it the correct combination of bytes in the right order can communicate with it. But programmers aren't generally in the business of sending bytes; that's the job of a library. Over the years, there have been a few libraries — each with its own <acronym>API</> — that do the work of moving SQL through a <acronym>TDS</> pipe. <systemitem class="library">ODBC</systemitem>, <systemitem class="library">db-lib</systemitem>, and <systemitem class="library">ct-lib</systemitem> have very different <acronym>API</>s, but they're all one to the server, because on the wire they speak <acronym>TDS</>. +- </para> +- <para> +-The <acronym>TDS</> protocol was designed and developed by Sybase Inc. for their Sybase <productname>SQL Server</productname> relational database engine in 1984. The problem Sybase faced then still exists: There was no commonly accepted application-level protocol to transfer data between a database server and its client. To encourage the use of their product, Sybase came up with a flexible pair of products called <productname>netlib</productname> and <systemitem class="library">db-lib</systemitem>. +- </para> +- <para> +-<productname>netlib</productname>'s job was to ferry data between the two computers. To do that, it had to deal with the underlying network protocol. Remember, in those days <acronym>TCP/IP</> was not the ubiquitous thing it is today. Besides <acronym>TCP/IP</>, <productname>netlib</productname> ran on <acronym>DECnet</>, <acronym>IPX/SPX</>, <acronym>NetBEUI</> and the like. +- </para> +- <para> +-<systemitem class="library">db-lib</systemitem> provided an <acronym>API</> to the client program, and communicated with the server via <productname>netlib</productname>. What <systemitem class="library">db-lib</systemitem> sent to the server took the form of a stream of bytes, a structured stream of bytes meant for tables of data, a Tabular Data Stream. +- </para> +- <para> +-In 1990 Sybase entered into a technology sharing agreement with Microsoft which resulted in Microsoft marketing its own <productname>SQL Server</productname>. Microsoft kept the <systemitem class="library">db-lib</systemitem> <acronym>API</> and added <systemitem class="library">ODBC</systemitem>. (Microsoft has since added other <acronym>API</>s, too.) + +-At about the same time, Sybase introduced a more powerful <quote>successor</quote> to <systemitem class="library">db-lib</systemitem>, called <systemitem class="library">ct-lib</systemitem>, and called the pair <productname><firstterm>OpenClient</firstterm></productname>. +- </para> +- <para> ++<para><acronym>TDS</> is a <firstterm>protocol</firstterm>, a set of rules describing how to transmit data between two computers. Like any protocol, it defines the types of messages that can be sent, and the order in which they may be sent. Protocols describe the <quote>bits on the wire</quote>, how data flow.</para> + +-<systemitem class="library">ct-lib</systemitem>, <systemitem class="library">db-lib</systemitem>, and <systemitem class="library">ODBC</systemitem> are <acronym>API</>s that — however different their programming style may be — all use <productname>netlib</productname> to communicate to the server. The language they use is <acronym>TDS</>. +- </para> +- <para> +-The <acronym>TDS</> protocol comes in several flavors, most of which have never +-been openly documented. If anything, it's probably considered to be something like a trade secret, or at least proprietary technology. The exception is TDS 5.0, used exclusively by Sybase, for which documentation is available <ulink url="http://crm.sybase.com/sybase/www/ESD/tds_spec_download.jsp">from Sybase</ulink>. +- </para> ++<para>In reading this manual, it may be helpful to keep in mind that a protocol is not an <acronym>API</>, although the two are related. The server recognizes and speaks a protocol; anything that can send it the correct combination of bytes in the right order can communicate with it. But programmers aren't generally in the business of sending bytes; that's the job of a library. Over the years, there have been a few libraries — each with its own <acronym>API</> — that do the work of moving SQL through a <acronym>TDS</> pipe. <systemitem class="library">ODBC</systemitem>, &dblib;, and &ctlib; have very different <acronym>API</>s, but they're all one to the server, because on the wire they speak <acronym>TDS</>.</para> ++ ++<para>The <acronym>TDS</> protocol was designed and developed by Sybase Inc. for their Sybase <productname>SQL Server</productname> relational database engine in 1984. The problem Sybase faced then still exists: There was no commonly accepted application-level protocol to transfer data between a database server and its client. To encourage the use of their product, Sybase came up with <systemitem class="library">DB-Library</systemitem>.</para> ++ ++<para><systemitem class="library">DB-Library</systemitem> provided an <acronym>API</> 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 <systemitem class="library">DB-Library</systemitem> <acronym>API</> and added <systemitem class="library">ODBC</systemitem>. (Microsoft has since added other <acronym>API</>s, too. It no longer supports its own <systemitem class="library">DB-Library</systemitem> implementation.) At about the same time, Sybase introduced a more powerful <quote>successor</quote> to <systemitem class="library">DB-Library</systemitem>, called <systemitem class="library">CT-Library</systemitem>, and called the pair <productname><firstterm>OpenClient</firstterm></productname>.</para> ++ ++<para><systemitem class="library">CT-Library</systemitem>, <systemitem class="library">DB-Library</systemitem>, and <systemitem class="library">ODBC</systemitem> are <acronym>API</>s that — however different their programming style may be — all communicate with the server in the same way. The language they use is <acronym>TDS</>.</para> ++ ++<para>The <acronym>TDS</> protocol comes in several flavors, most of which have never been openly documented. If anything, it's probably considered to be something like a trade secret, or at least proprietary technology. The exception is <acronym>TDS</> 5.0, used exclusively by Sybase, for which documentation is available <ulink url="http://crm.sybase.com/sybase/www/ESD/tds_spec_download.jsp">from Sybase</ulink>.</para> + </sect1> ++ ++ <sect1 id="tdshistory"> ++ <title>History of <acronym>TDS</> Versions</title> + +- <sect1 id="tdshistory"> +- <title>History of <acronym>TDS</> Versions</title> +- +- <para> +-At first, there was One Version of <acronym>TDS</> common to both vendors but, in keeping with the broad history of private ventures, they soon diverged. Each vendor has subsequently brought out different versions, and neither supports the other's flavor. That is to say, each vendor's client libraries use the latest version of <acronym>TDS</> offered by that vendor. You can't reliably use Microsoft's libraries to connect to Sybase, or Sybase's libraries to connect to Microsoft. In some cases you'll get a connection, but pretty soon you'll bump into some incompatibility. +- </para> +- <variablelist id="tab.tds.protocol.versions"> +- <title>Versions of the <acronym>TDS</> protocol</title> + ++<para>At first, there was One Version of <acronym>TDS</> common to both vendors but, in keeping with the broad history of private ventures, they soon diverged. Each vendor has subsequently brought out different versions, and neither supports the other's flavor. That is to say, each vendor's client libraries use the latest version of <acronym>TDS</> offered by that vendor. You can't reliably use Microsoft's libraries to connect to Sybase, or Sybase's libraries to connect to Microsoft. In some cases you'll get a connection, but pretty soon you'll bump into some incompatibility.</para> ++ <variablelist id="tab.tds.protocol.versions"> ++ <title>Versions of the <acronym>TDS</> protocol</title> ++ + <varlistentry><term><acronym>TDS 4.2</acronym> +- Sybase and Microsoft</term> +- <listitem> +- <para> +-The version in use at the time of the Sybase/Microsoft split. +- </para> +- </listitem></varlistentry> ++ Sybase and Microsoft</term> ++ <listitem> + ++<para>The version in use at the time of the Sybase/Microsoft split.</para> ++ </listitem></varlistentry> ++ + <varlistentry><term><acronym>TDS 5.0</acronym> +- Sybase</term> +- <listitem> +- <para> +-Introduced for Sybase. Because TDS 5.0 includes negotiated capabilities through which protocol features can be expanded, we are unlikely to see a new <acronym>TDS</> version from Sybase. +- </para> +- </listitem></varlistentry> ++ Sybase</term> ++ <listitem> + ++<para>Introduced for Sybase. Because TDS 5.0 includes negotiated capabilities through which protocol features can be expanded, we are unlikely to see a new <acronym>TDS</> version from Sybase.</para> ++ </listitem></varlistentry> ++ + <varlistentry><term><acronym>TDS 7.0</acronym> +- Microsoft</term> +- <listitem> +- <para> +-Introduced for <productname>SQL Server 7.0</productname>. Includes support for the extended datatypes in <productname>SQL Server 7.0</productname> (such as <structname>char</structname>/<structname>varchar</structname> fields of more than 255 characters). It also includes support for Unicode. +- </para> +- </listitem></varlistentry> ++ 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> +- <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> ++ Microsoft</term> ++ <listitem> + ++<para>Introduced for <productname>SQL Server 2000</productname>. Includes support for big integer (64-bit <structname>int</structname>) and <quote>variant</quote> datatypes.</para> ++ </listitem></varlistentry> ++ + <varlistentry><term>TDS 7.2 +- Microsoft</term> +- <listitem> +- <para> +-Introduced for <productname>SQL Server 2005</productname>. Includes support for varchar(max), varbinary(max), xml datatypes and MARS. +- </para> +- </listitem></varlistentry> ++ Microsoft</term> ++ <listitem> + ++<para>Introduced for <productname>SQL Server 2005</productname>. Includes support for varchar(max), varbinary(max), xml datatypes and MARS.</para> ++ </listitem></varlistentry> ++ + </variablelist> +- </sect1> ++ </sect1> ++ ++ <sect1 id="FreeTDShistory"> <title>History of &freetds;</title> + +- <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</>-based, although Greg Thain did a great service in converting the library to ELF. Secondly, it included only the newer <systemitem class="library">ct-lib</systemitem> <acronym>API</>. The older <systemitem class="library">db-lib</systemitem> <acronym>API</> was missing. +- </para> +- <para> +-Brian Bruns, a Sybase DBA and originator of the &freetds; project, had some <systemitem class="library">db-lib</systemitem> programs he wanted to run under Linux, and thus began the &freetds; project. The original work focused on <systemitem class="library">db-lib</systemitem> and version 5.0 of the protocol, but quickly expanded to include a <systemitem class="library">ct-lib</systemitem> compatible layer and <acronym>TDS</> version 4.2. Later support for <systemitem class="library">ODBC</systemitem> and <acronym>TDS 7.0 and 7.1</> was added. Craig Spannring wrote a Java <acronym>JDBC</> driver which became <productname>FreeTDS/JDBC</productname>. +- </para> +- <para> +-As the project matured, it gained new participants. Frediano Ziglio greatly expanded the <systemitem class="library">ODBC</systemitem> driver, and continues to improve both it and the underlying TDS library. Bill Thompson wrote most of the present BCP system and added cursors to our <systemitem class="library">ct-lib</systemitem>. Your humble author joined the project to add documentation, and wound up as the project's maintainer. Such are the rewards for doing a good deed. +- </para> +- <para> +-There have been many other contributions. Please see the <filename>AUTHORS</> in the distribution for a (we hope) complete list. +- </para> ++<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</>-based, although Greg Thain did a great service in converting the library to ELF. Secondly, it included only the newer &ctlib; <acronym>API</>. The older &dblib; <acronym>API</> 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</> version 4.2. Later support for <systemitem class="library">ODBC</systemitem> and <acronym>TDS 7.0 and 7.1</> was added. Craig Spannring wrote a Java <acronym>JDBC</> driver which became <productname>FreeTDS/JDBC</productname>.</para> ++ ++<para>As the project matured, it gained new participants. Frediano Ziglio greatly expanded the <systemitem class="library">ODBC</systemitem> driver, and continues to improve both it and the underlying TDS library. Bill Thompson wrote most of the present BCP system and added cursors to our &ctlib;. Your humble author joined the project to add documentation, and wound up as the project's maintainer. Such are the rewards for doing a good deed.</para> ++ ++<para>There have been many other contributions. Please see the <filename>AUTHORS</> in the distribution for a (we hope) complete list.</para> + </sect1> +- <sect1 id="projects"> +- <title>Current Projects, Language Bindings, and Alternatives</title> +- <sect2 id="Current"> ++ <sect1 id="projects"> ++ <title>Current Projects, Language Bindings, and Alternatives</title> ++ <sect2 id="Current"> + <title>Current Projects</title> +- <para> +-&freetds; consists of two projects. The &freetds; C libraries and &freetds;/ <acronym>JDBC</>. +- </para> ++ ++<para>&freetds; consists of two projects. The &freetds; C libraries and &freetds;/ <acronym>JDBC</>.</para> + <itemizedlist mark=opencircle> +- <listitem><para> +-The &freetds; C libraries support three separate <acronym>API</>s: <systemitem class="library">db-lib</systemitem>, <systemitem class="library">ct-lib</systemitem>, and <systemitem class="library">ODBC</systemitem>. Underlying these three is libtds, which handles the low-level details of the <acronym>TDS</> protocol, such as sending, receiving, and datatype conversion. This document and the <ulink url="http://www.freetds.org/">FreeTDS</ulink> website are dedicated to these libraries. +- </para></listitem> +- <listitem><para> +-If Java is your game, we refer you to the +-<ulink url="http://sourceforge.net/projects/jtds/">jTDS</ulink> +-project on SourceForge. It is a fork of the +-<productname>FreeTDS/JDBC</productname> project, by Craig Spannring, and is a free, native 100% Java implementation of a Type 4 <acronym>JDBC</> driver. +- </para></listitem> +- </itemizedlist> +- </sect2> ++ <listitem><para>The &freetds; C libraries support three separate <acronym>API</>s: &dblib;, &ctlib;, and <systemitem class="library">ODBC</systemitem>. Underlying these three is libtds, which handles the low-level details of the <acronym>TDS</> protocol, such as sending, receiving, and datatype conversion. This document and the <ulink url="http://www.freetds.org/">FreeTDS</ulink> website are dedicated to these libraries. ++</para></listitem> ++ <listitem><para>If Java is your game, we refer you to the ++ <ulink url="http://sourceforge.net/projects/jtds/">jTDS</ulink> ++ project on SourceForge. It is a fork of the ++ <productname>FreeTDS/JDBC</productname> project, by Craig Spannring, and is a free, native 100% Java implementation of a Type 4 <acronym>JDBC</> driver. ++</para></listitem> ++ </itemizedlist> ++ </sect2> + <sect2 id="Status"> + <title>Status</title> +- <para>The libraries are portable, mature, and stable. They're expected to compile readily and normally do not crash or corrupt data. There is a logging feature to aid in diagnosing problems. While they do not include every feature provided by the vendors' libaries, they do faithfully implement a useful — and widely used — subset of their <acronym>API</>s. +- </para> +- <para>The <systemitem class="library">db-lib</systemitem> and <systemitem class="library">ct-lib</systemitem> <acronym>API</>s have been usable for several years. They have been successfully substituted for Sybase's own libraries in a variety of venues, including <productname>Perl</productname> and <productname>PHP</productname>. +- </para> +- <para>The <systemitem class="library">ODBC</> driver should be fully ODBC 3.0 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</>, included in the source distribution. +- </para> +- <para>In addition to the core <systemitem class="library">db-lib</systemitem> <acronym>API</>, &freetds; includes a full implementation of <systemitem class="library">db-lib</systemitem>'s <acronym>bcp</> functions, as well as <command>freebcp</>, a replacement for Sybase's <application>bcp</application> utility. +- </para> +- <para>How big is it? &freetds; has over 90,000 lines of C code, maintained by a handful of developers. Patches arrive irregularly, varying in size from one-liners to thousand-line monsters. Almost all are applied or used in some way. The mailing list has some 700 or so subscribers at this writing. Safe to say, &freetds;'s success so far lies somewhere between the Beetle and the Edsel. +- </para> +- <para>Who uses it? Oh, pretty much everyone. &freetds; users almost certainly 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. Microsoft recommends &freetds; to their customers who want access to Microsoft SQL Server from non-Win32 clients. So do we. +- </para> +- </sect2> ++ ++<para>The libraries are portable, mature, and stable. They're expected to compile readily and normally do not crash or corrupt data. There is a logging feature to aid in diagnosing problems. While they do not include every feature provided by the vendors' libaries, they do faithfully implement a useful — and widely used — subset of their <acronym>API</>s.</para> ++ ++<para>The &dblib; and &ctlib; <acronym>API</>s have been usable for several years. They have been successfully substituted for Sybase's own libraries in a variety of venues, including <productname>Perl</productname> and <productname>PHP</productname>.</para> ++ ++<para>The <systemitem class="library">ODBC</> driver should be fully ODBC 3.0 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</>, included in the source distribution.</para> ++ ++<para>In addition to the core &dblib; <acronym>API</>, &freetds; includes a full implementation of &dblib;'s <acronym>bcp</> functions, as well as <command>freebcp</>, a replacement for Sybase's <application>bcp</application> utility.</para> ++ ++<para>How big is it? &freetds; has over 90,000 lines of C code, maintained by a handful of developers. Patches arrive irregularly, varying in size from one-liners to thousand-line monsters. Almost all are applied or used in some way. The mailing list has some 700 or so subscribers at this writing. Safe to say, &freetds;'s success so far lies somewhere between the Beetle and the Edsel.</para> ++ ++<para>Who uses it? Oh, pretty much everyone. &freetds; users almost certainly 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. 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 and Java</title> +- <para> +-You may be wondering how these libraries fit with Perl, PHP, TCL, Python, or other popular scripting languages. Most of these languages have bindings to Sybase that use either the <systemitem class="library">db-lib</systemitem> or <systemitem class="library">ct-lib</systemitem> <acronym>API</>, for which &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> (<systemitem class="library">db-lib</systemitem>) and <filename>sybase-ct</filename> (<systemitem class="library">ct-lib</systemitem>) <acronym>API</>s. +- </para> +- </sect2> ++ ++<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</>, 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</>s.</para> ++ </sect2> + <sect2 id="alternatives"> + <title>Alternatives</title> + <variablelist id="tab.alternatives"> +@@ -243,3291 +220,3204 @@ You may be wondering how these libraries fit with Perl, PHP, TCL, Python, or oth + <varlistentry> + <term>Sybase OpenClient</term> + <listitem> +- <para>In the time since &freetds; was started, Sybase (as well as most major <acronym>DBMS</> vendors) has released its database for the Intel <productname><acronym>GNU</>/Linux</productname> platform. The good: it is a solid product and supports <acronym>TDS</> 4.2 and <acronym>TDS</> 5.0. The bad: it doesn't support <acronym>TDS 7.0</> or Linux/*BSD on non-Intel platforms. The ugly: Microsoft broke date handling for big endian Sybase clients.</para> +- <para>Depending on platform, it may cost something.</para> +- </listitem> +- </varlistentry> ++ ++<para>In the time since &freetds; was started, Sybase (as well as most major <acronym>DBMS</> vendors) has released its database for the Intel <productname><acronym>GNU</>/Linux</productname> platform. The good: it is a solid product and supports <acronym>TDS</> 4.2 and <acronym>TDS</> 5.0. The bad: it doesn't support <acronym>TDS 7.0</> or Linux/*BSD on non-Intel platforms. The ugly: Microsoft broke date handling for big endian Sybase clients.</para> ++ ++<para>Depending on platform, it may cost something.</para> ++ </listitem> ++ </varlistentry> + <varlistentry> + <term><systemitem class="library">ODBC</systemitem> bridge products</term> +- <listitem><para>They use the <systemitem class="library">ODBC</systemitem> driver on the NT box where your <productname>SQL Server</productname> runs so you'll never have trouble with new protocols and the like. On the downside, they can be costly and may be inefficient. We know of <productname>EasySoft ODBC-ODBC Bridge</productname> from <ulink url="http://www.easysoft.com">EasySoft</ulink>, <productname>Universal Data Access Driver</productname> from <ulink url="http://www.openlinksw.com">OpenLink Software</ulink>, <productname>SequeLink</productname> from <ulink url="http://www.merant.com/">Merant</ulink>, and +-<Application><systemitem class="library">ODBC</systemitem> Router</Application> from <ulink url="http://www.augsoft.com/">August Software</ulink> Corporation. +-</para> +- </listitem> +- </varlistentry> ++ <listitem><para>They use the <systemitem class="library">ODBC</systemitem> driver on the NT box where your <productname>SQL Server</productname> runs so you'll never have trouble with new protocols and the like. On the downside, they can be costly and may be inefficient. We know of <productname>EasySoft ODBC-ODBC Bridge</productname> from <ulink url="http://www.easysoft.com">EasySoft</ulink>, <productname>Universal Data Access Driver</productname> from <ulink url="http://www.openlinksw.com">OpenLink Software</ulink>, <productname>SequeLink</productname> from <ulink url="http://www.merant.com/">Merant</ulink>, and ++ <Application><systemitem class="library">ODBC</systemitem> Router</Application> from <ulink url="http://www.augsoft.com/">August Software</ulink> Corporation.</para> ++ </listitem> ++ </varlistentry> + <varlistentry> + <term>Inline <systemitem class="library">ODBC</systemitem> driver</term> + <listitem><para>Based on <systemitem class="library">libtds</systemitem>, this is a native <systemitem class="library">ODBC</systemitem> driver for i386 *nix. It is free in price, but comes only as a binary at the present time.</para> +- </listitem> +- </varlistentry> ++ </listitem> ++ </varlistentry> + <varlistentry> + <term>DBD::Proxy</term> + <listitem><para>We have no direct experience with this Perl-only option. It has the same caveats as an <systemitem class="library">ODBC</systemitem> bridge except it's free.</para> +- </listitem> +- </varlistentry> +- </variablelist> +- </sect2> ++ </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</> World</title> +- <para> +-&freetds; uses <acronym>GNU</> <application>Automake</application>, <application>Autoconf</application>, and <application>libtool</application> to increase portability. +- </para> +- <para> +-For many people, the preceding sentence says it all (good or bad). If you're familiar with the <acronym>GNU</> system, you can probably just download the tarball and get away with scanning the <filename>README</filename> impatiently and then following your instincts. Because everyone is a beginner once and no one is an expert at everything, we'll try to explain things in plain English where possible, and to define our terms as we go along. +- </para> +- <para> +-If the following nevertheless reads like gibberish, you might very well want to use something prepackaged (see <link linkend="alternatives">Alternatives</link>). If it reads like a vaguely intelligible alien script that might yield to intensive research, we've included links to some of the usual suspects at the end of this chapter. If it reads like a bad explanation of something you could explain better, please send us your version! +- </para> +- </sect1> +- <sect1 id="packages"> +- <title>What to build: Packages, Tarballs, and the <productname>CVS</productname> repository</title> +- <para> +-The latest &freetds; package is always available from +- <ulink url="ftp://ibiblio.unc.edu/pub/Linux/ALPHA/freetds/freetds-release.tgz"> +- <citetitle>iBiblio</citetitle></ulink> +-and its mirrors. +- </para> +- <para> +-Code changes by the developers are immediately available in the <productname>CVS</productname> repository. If you've run into a problem, you may want to check out from <productname>CVS</productname> to see if it's fixed there. +- </para> +- <para> +-No password is needed to obtain the current CVS copy of FreeTDS; you need only have a CVS client installed on your machine. Then: +-<screen> +-<prompt>$ </prompt><userinput>cvs -d:pserver:anonymous@freetds.cvs.sourceforge.net:/cvsroot/freetds login</userinput> +-<prompt>$ </prompt><userinput>cvs -z3 -d:pserver:anonymous@freetds.cvs.sourceforge.net:/cvsroot/freetds checkout -P freetds</userinput> +-<prompt>Password: </prompt> +-<prompt>$ </prompt><userinput>make install</userinput> +-</screen> +- </para> +- <para> +-For those behind firewalls or otherwise unable to access <productname>CVS</productname>, nightly snapshots of <productname>CVS</productname> are rolled up into tarballs for your convenience. They can be downloaded from +- <ulink url="ftp://ftp.ibiblio.org/pub/Linux/ALPHA/freetds/freetds-current.tgz">ibiblio.org</ulink>. Tarballs are generated around 3am EST (GMT-5). +- </para> +- <para> +-In general, the <productname>CVS</productname> HEAD revision (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>CVS</productname> HEAD. +- </para> +- <tip><para> +-As with any project of this sort, if you want to use the <productname>CVS</productname> HEAD revision, it's a good idea to join the mailing list. +- </para></tip> +- </sect1> +- <sect1 id="config"> +- <title>How to build: Configure and make</title> +- <para> +-If you've built other <acronym>GNU</> projects, building &freetds; is a fairly straightforward process. We have a terse and verbose description. +- </para> +- <Note><para> +-&freetds; is known to build with <acronym>GNU</> and <acronym>BSD</> <application>make</application>. If you encounter a large number of build errors, and your operating system's <application>make</application> is not <acronym>GNU</> <application>make</application> (as is the case on most non-<acronym>GNU</>/Linux systems), you may wish to install <acronym>GNU</> <application>make</application> from <ulink url="ftp://ftp.gnu.org/gnu/make/">ftp.gnu.org</ulink>. +- </para></note> +- <sect2 id="Experts"><title>For Experts</title> +-<screen> +-<prompt>$ </prompt><userinput>./configure --prefix=/usr/local/freetds</userinput> +-<prompt>$ </prompt><userinput>make</userinput> +-<prompt>$ </prompt><userinput>su root</userinput> +-<prompt>Password: </prompt> +-<prompt>$ </prompt><userinput>make install</userinput> +-</screen> ++<!-- ////////////////// CHAPTER /////////////////////// --> + +- <para> +-Building from CVS is described in the file INSTALL.CVS. +- </para> ++<chapter id="build"> ++ <title>Build &freetds;</title> ++ <epigraph> + +- </sect2> +- <sect2 id="Everyone"><title>For Everyone Else </title> +- <TITLEABBREV>(&freetds; for Dummies?)</TITLEABBREV> +- +- <para> +-The <acronym>GNU</> development system can generate code for a wide variety of hardware architectures and operating systems, virtually all of which can run <productname>FreeTDS</> in consequence. The work of building and installing the <productname>FreeTDS</> libraries begins with the command <Command>configure</Command>, which generates the <filename>Makefile</filename> that governs how the code is compiled, linked, and installed. Once you've <quote>configured</quote> the project, <command>make</> will manage the rest of the build. +- </para> +- <sidebar><title>ODBC Preparation</title> +- <para>If you intend to build the <productname>FreeTDS</> ODBC driver — and want to use a Driver Manager (DM), as most people do — install the Driver Manager before configuring <productname>FreeTDS</>. <Command>configure</> will detect the the DM and use its header (<filename>.h</>) files for ODBC constants and such. If your DM is installed in an unusual directory, you may have to provide the directory name as a parameter to <Command>configure</>.</para> +- +- <para><productname>FreeTDS</> doesn't <emphasis>require</> a DM. You can build the ODBC driver without one, as long as you have the requisite header files: <filename>sql.h</>, <filename>sqlext.h</> and <filename>sqltypes.h</>. These can be taken from either the iODBC or UnixODBC distributions. Put them wherever you like (e.g., <filename>/usr/local/include</filename>). Because <productname>FreeTDS</> won't detect your (missing) DM, it won't automatically build the ODBC driver, so you'll have to tell <Command>configure</> what to do and where to look. Cf. <link linkend="withOdbcNoDM"><option>--with-odbc-nodm</></link>. +-</para> +- </sidebar> +- <para> +-The simplest form of running <Command>configure</> is: +-<screen> +- <prompt>$ </prompt><userinput>./configure</userinput> +-</screen> +-and sometimes that's enough. <Command>configure</> accepts some command-line arguments, too, and you may need to provide some, depending on what your environment looks like. +- </para> +- <para> +-There are a few optional arguments to <Command>configure</> that may be important to you. For a complete list, see <command>configure --help</command>. +- </para> +- <sect3><title><command>configure</> options</title> +- <variablelist id="tab.configure.Directories"><title>Directories and TDS version</title> +- <varlistentry> +- <term><Option>--prefix=<replaceable>PREFIX</> +- </Option></term> +- <listitem><para> install architecture-independent files in <parameter>PREFIX</>. When you run <command>make install</command>, libraries will be placed in <parameter>PREFIX</><filename>/lib</>, executables in <parameter>PREFIX</><filename>/bin</>, and so on. +- </para> +- <para>The default is <filename>/usr/local</> if this argument is not passed to <Command>configure</Command>. </para> +- </listitem> +- </varlistentry> ++<para>If you build it they will come.</para> ++ </epigraph> ++ <sect1 id="gnu"> ++ <title>The <acronym>GNU</> World</title> + +- <varlistentry> +- <term><Option>--sysconfdir=<replaceable>DIR</> +- </Option></term> +- <listitem><para> read-only single-machine data in <parameter>DIR</> +- </para> +- <para>The default is <replaceable>PREFIX/etc</> (<parameter>PREFIX</> being the value of <Option>--prefix=<replaceable>PREFIX</></Option>, above) if this argument is not passed to <Command>configure</Command>. </para> +- </listitem> +- </varlistentry> ++<para>&freetds; uses <acronym>GNU</> <application>Automake</application>, <application>Autoconf</application>, and <application>libtool</application> to increase portability.</para> + +- <varlistentry> +- <term><Option>--with-libiconv-prefix=<replaceable>DIR</> +- </Option></term> +- <listitem><para>Specifies the location of the iconv library to use. <Command>configure</> will search for libiconv in the usual places; use <Option>--with-libiconv-prefix</Option> if it's unsuccessful (assuming you want to use iconv, of course). Overridden by <Option>--disable-libiconv</Option>, below. </para> +- </listitem> +- </varlistentry> +- <varlistentry id="withOdbcNoDM"> +- <term><Option>--with-odbc-nodm=<replaceable>DIR</> +- </Option></term> +- <listitem><para>If you're building the ODBC driver and not using a Driver Manager, use this option to indicate the location of the <filename>.h</> files. <command>configure</> will not cause the ODBC driver to be built unless this option is used or a DM is detected/specified. </para> +- </listitem> +- </varlistentry> +- <varlistentry> +- <term><Option>--with-tdsver=<replaceable>VER</> +- </Option></term> +- <listitem><para>Specifies the default <acronym>TDS</> version. (There are a couple of ways to set the <acronym>TDS</> version at run-time. This parameter takes effect if no run-time settings are provided.) Acceptable values of <parameter>VER</> are <literal>4.2</literal>, <literal>4.6</literal>, <literal>5.0</literal>, <literal>7.0</literal>, <literal>7.1</literal> and <literal>7.2</literal>.</para> +- <para>The default is <literal>5.0</literal> if this argument is not passed to <Command>configure</Command>.</para> +- </listitem> +- </varlistentry> +- </variablelist> +- +- <variablelist id="tab.ODBC.Driver.Managers"><title>ODBC Driver Managers</title> +- <varlistentry> +- <term><Option>--with-iodbc=<replaceable>DIR</> +- </Option></term> +- <term><Option>--with-unixodbc=<replaceable>DIR</> +- </Option></term> +- <listitem><para>Specify directory of <systemitem class="library">iODBC</systemitem> or <systemitem class="library">unixODBC</systemitem> support, and use it as the Driver Manager. +- As of version 0.62, the ODBC Driver Manager is detected by <command>configure</>, so use this parameter only if yours is installed in a nonstandard path. +- (Requires <productname>iODBC</productname> or <systemitem class="library">unixODBC</systemitem> to have already been installed.)</para> +- </listitem> +- </varlistentry> +- </variablelist> +- +- <variablelist id="tab.turn.off"><title>Things you can turn off</title> +- <varlistentry> +- <term><Option>--disable-odbc +- </Option></term> +- <listitem><para>Do not attempt to detect ODBC, and do not build the ODBC driver. In case you don't care about ODBC. +- </para> +- </listitem> +- </varlistentry> +- <varlistentry> +- <term><Option>--disable-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</> 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()</> where available. Rely instead on the older and non-threadsafe ones such as <function>gethostbyname()</>. <command>configure</> tests some of these functions. If the tests are successful, &freetds; will use threadsafe functions throughout. </para> +- <para>Threadsafe operation has been tested on Linux, FreeBSD, and HP-UX. It should work on Solaris, Tru64, and (reportedly) IRIX. Not expected to work on non-unixy systems. It is a good idea to enable threadsafe operation if you configure Apache with multi-threading support.</para> +- </listitem> +- </varlistentry> +- <varlistentry> +- <term><Option>--disable-debug</Option></term> +- <listitem><para>Debug-mode compiles are enabled by default, and will remain so at least until version 1.0. You can speed things up ever so slightly by disabling it. +- </para></listitem> +- </varlistentry> +- </variablelist> +- +- <variablelist id="tab.turnon"><title>Things you can turn on</title> +- <varlistentry> +- <term><Option>--enable-msdblib</Option></term> +- <listitem><para>Enable Microsoft behavior in the <systemitem class="library">db-lib</systemitem> <acronym>API</> where it diverges from Sybase's. (For instance, Microsoft uses different names for the members of its date structure.) Typically needed only for porting Win32 applications to Unix.</para> +- <para>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> ++<para>For many people, the preceding sentence says it all (good or bad). If you're familiar with the <acronym>GNU</> system, you can probably just download the tarball and get away with scanning the <filename>README</filename> impatiently and then following your instincts. Because everyone is a beginner once and no one is an expert at everything, we'll try to explain things in plain English where possible, and to define our terms as we go along.</para> + +- <varlistentry> +- <term><Option>--enable-sybase-compat</Option></term> +- <listitem><para>Enable close compatibility with Sybase's ABI, at the expense of other features. Currently, this enables the generation of a dbopen() entry point in <systemitem class="library">db-lib</systemitem>, which may clash with the <systemitem class="library">DBM</systemitem> function with the same name. Absolutely <emphasis>not required</> for use with other free software. </para> +- </listitem> +- </varlistentry> ++<para>If the following nevertheless reads like gibberish, you might very well want to use something prepackaged (see <link linkend="alternatives">Alternatives</link>). If it reads like a vaguely intelligible alien script that might yield to intensive research, we've included links to some of the usual suspects at the end of this chapter. If it reads like a bad explanation of something you could explain better, please send us your version!</para> ++ </sect1> ++ <sect1 id="packages"> ++ <title>What to build: Packages, Tarballs, and the <productname>CVS</productname> repository</title> + +- <varlistentry> +- <term><Option>--enable-krb5</Option></term> +- <listitem><para>Enable Kerberos support. With Kerberos you can connect to server using your stored Kerberos ticket. +- This require you to configure Kerberos support on your machine. +- </para></listitem> +- </varlistentry> ++<para>The latest &freetds; package is always available from ++ <ulink url="ftp://ibiblio.unc.edu/pub/Linux/ALPHA/freetds/freetds-release.tgz"> ++ <citetitle>iBiblio</citetitle></ulink> ++ and its mirrors.</para> + +- <varlistentry> +- <term><Option>--enable-sspi</Option></term> +- <listitem><para>Enable SSPI support. SSPI is a Micrsoft library that allows you to use your current logged account for authentication. With this option enabled, FreeTDS supports "trusted logins" for Win32/64, just as Microsoft's own implmentations do. +- </para></listitem> +- </varlistentry> ++<para>Code changes by the developers are immediately available in the <productname>CVS</productname> repository. If you've run into a problem, you may want to check out from <productname>CVS</productname> to see if it's fixed there.</para> + +- <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> ++<para>No password is needed to obtain the current CVS copy of FreeTDS; you need only have a CVS client installed on your machine. Then: ++<screen> ++ <prompt>$ </prompt><userinput>cvs -d:pserver:anonymous@freetds.cvs.sourceforge.net:/cvsroot/freetds login</userinput> ++ <prompt>$ </prompt><userinput>cvs -z3 -d:pserver:anonymous@freetds.cvs.sourceforge.net:/cvsroot/freetds checkout -P freetds</userinput> ++ <prompt>Password: </prompt> ++ <prompt>$ </prompt><userinput>make install</userinput></screen></para> + +- <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> ++<para>For those behind firewalls or otherwise unable to access <productname>CVS</productname>, nightly snapshots of <productname>CVS</productname> are rolled up into tarballs for your convenience. They can be downloaded from ++ <ulink url="ftp://ftp.ibiblio.org/pub/Linux/ALPHA/freetds/freetds-current.tgz">ibiblio.org</ulink>. Tarballs are generated around 3am EST (GMT-5).</para> + +- </variablelist> +- <variablelist id="tab.ssl"><title>SSL support</title> +- <varlistentry> +- <term><Option>--with-gnutls</Option></term> +- <listitem><para>Enable SSL using GnuTLS. Use version 1.2.3 or newer.</para> +- </listitem> +- </varlistentry> ++<para>In general, the <productname>CVS</productname> HEAD revision (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>CVS</productname> HEAD.</para> ++ <tip><para>As with any project of this sort, if you want to use the <productname>CVS</productname> HEAD revision, it's a good idea to join the mailing list. ++</para></tip> ++ </sect1> ++ <sect1 id="config"> ++ <title>How to build: Configure and make</title> + +- <varlistentry> +- <term><Option>--with-openssl=<replaceable>DIR</></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> ++<para>If you've built other <acronym>GNU</> 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</> and <acronym>BSD</> <application>make</application>. If you encounter a large number of build errors, and your operating system's <application>make</application> is not <acronym>GNU</> <application>make</application> (as is the case on most non-<acronym>GNU</>/Linux systems), you may wish to install <acronym>GNU</> <application>make</application> from <ulink url="ftp://ftp.gnu.org/gnu/make/">ftp.gnu.org</ulink>. ++</para></note> ++ <sect2 id="Experts"><title>For Experts</title> ++<screen> ++ <prompt>$ </prompt><userinput>./configure --prefix=/usr/local/freetds</userinput> ++ <prompt>$ </prompt><userinput>make</userinput> ++ <prompt>$ </prompt><userinput>su root</userinput> ++ <prompt>Password: </prompt> ++ <prompt>$ </prompt><userinput>make install</userinput></screen> ++ + +- </variablelist> +- </sect3> ++<para>Building from CVS is described in the file INSTALL.CVS.</para> ++ ++ </sect2> ++ <sect2 id="Everyone"><title>For Everyone Else </title> ++ <TITLEABBREV>(&freetds; for Dummies?)</TITLEABBREV> ++ ++ ++<para>The <acronym>GNU</> development system can generate code for a wide variety of hardware architectures and operating systems, virtually all of which can run <productname>FreeTDS</> in consequence. The work of building and installing the <productname>FreeTDS</> libraries begins with the command <Command>configure</Command>, which generates the <filename>Makefile</filename> that governs how the code is compiled, linked, and installed. Once you've <quote>configured</quote> the project, <command>make</> will manage the rest of the build.</para> ++ <sidebar><title>ODBC Preparation</title> ++ ++<para>If you intend to build the <productname>FreeTDS</> ODBC driver — and want to use a Driver Manager (DM), as most people do — install the Driver Manager before configuring <productname>FreeTDS</>. <Command>configure</> will detect the the DM and use its header (<filename>.h</>) files for ODBC constants and such. If your DM is installed in an unusual directory, you may have to provide the directory name as a parameter to <Command>configure</>.</para> ++ ++ ++<para><productname>FreeTDS</> doesn't <emphasis>require</> a DM. You can build the ODBC driver without one, as long as you have the requisite header files: <filename>sql.h</>, <filename>sqlext.h</> and <filename>sqltypes.h</>. These can be taken from either the iODBC or UnixODBC distributions. Put them wherever you like (e.g., <filename>/usr/local/include</filename>). Because <productname>FreeTDS</> won't detect your (missing) DM, it won't automatically build the ODBC driver, so you'll have to tell <Command>configure</> what to do and where to look. Cf. <link linkend="withOdbcNoDM"><option>--with-odbc-nodm</></link>.</para> ++ </sidebar> ++ ++<para>The simplest form of running <Command>configure</> is: ++<screen> ++ <prompt>$ </prompt><userinput>./configure</userinput></screen> ++ and sometimes that's enough. <Command>configure</> accepts some command-line arguments, too, and you may need to provide some, depending on what your environment looks like.</para> ++ ++<para>There are a few optional arguments to <Command>configure</> that may be important to you. For a complete list, see <command>configure --help</command>.</para> ++ <sect3 id="Configure.Options" XrefLabel="Options to configure"> ++ <title><command>configure</> options</title> ++ <variablelist id="tab.configure.Directories"> ++ <title>Directories and TDS version</title> ++ <varlistentry> ++ <term><Option>--prefix=<replaceable>PREFIX</> ++ </Option></term> ++ <listitem><para> install architecture-independent files in <parameter>PREFIX</>. When you run <command>make install</command>, libraries will be placed in <parameter>PREFIX</><filename>/lib</>, executables in <parameter>PREFIX</><filename>/bin</>, and so on.</para> ++ ++<para>The default is <filename>/usr/local</> if this argument is not passed to <Command>configure</Command>.</para> ++ </listitem> ++ </varlistentry> ++ ++ <varlistentry> ++ <term><Option>--sysconfdir=<replaceable>DIR</> ++ </Option></term> ++ <listitem><para> read-only single-machine data in <parameter>DIR</></para> ++ ++<para>The default is <replaceable>PREFIX/etc</> (<parameter>PREFIX</> being the value of <Option>--prefix=<replaceable>PREFIX</></Option>, above) if this argument is not passed to <Command>configure</Command>.</para> ++ </listitem> ++ </varlistentry> ++ ++ <varlistentry> ++ <term><Option>--with-libiconv-prefix=<replaceable>DIR</> ++ </Option></term> ++ <listitem><para>Specifies the location of the iconv library to use. <Command>configure</> will search for libiconv in the usual places; use <Option>--with-libiconv-prefix</Option> if it's unsuccessful (assuming you want to use iconv, of course). Overridden by <Option>--disable-libiconv</Option>, below.</para> ++ </listitem> ++ </varlistentry> ++ <varlistentry> ++ <term><Option>--with-tdsver=<replaceable>VER</> ++ </Option></term> ++ <listitem><para>Specifies the default <acronym>TDS</> version. (There are a couple of ways to set the <acronym>TDS</> version at run-time. This parameter takes effect if no run-time settings are provided.) Acceptable values of <parameter>VER</> are <literal>4.2</literal>, <literal>4.6</literal>, <literal>5.0</literal>, <literal>7.0</literal>, <literal>7.1</literal> and <literal>7.2</literal>.</para> ++ ++<para>The default is <literal>5.0</literal> if this argument is not passed to <Command>configure</Command>.</para> ++ </listitem> ++ </varlistentry> ++ </variablelist> ++ ++ <variablelist id="tab.ODBC.Driver.Managers"><title>ODBC Driver Managers</title> ++ <varlistentry> ++ <term><Option>--with-iodbc=<replaceable>DIR</> ++ </Option></term> ++ <term><Option>--with-unixodbc=<replaceable>DIR</> ++ </Option></term> ++ <listitem><para>Specify directory of <systemitem class="library">iODBC</systemitem> or <systemitem class="library">unixODBC</systemitem> support, and use it as the Driver Manager. ++ As of version 0.62, the ODBC Driver Manager is detected by <command>configure</>, so use this parameter only if yours is installed in a nonstandard path. ++ (Requires <productname>iODBC</productname> or <systemitem class="library">unixODBC</systemitem> to have already been installed.)</para> ++ </listitem> ++ </varlistentry> ++ <varlistentry id="withOdbcNoDM"> ++ <term><Option>--with-odbc-nodm=<replaceable>DIR</> ++ </Option></term> ++ <listitem><para>If you're building the ODBC driver and not using a Driver Manager, use this option to indicate the location of the <filename>.h</> files. <command>configure</> will not cause the ODBC driver to be built unless this option is used or a DM is detected/specified.</para> ++ </listitem> ++ </varlistentry> ++ </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</> 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()</> where available. Rely instead on the older and non-threadsafe ones such as <function>gethostbyname()</>. <command>configure</> tests some of these functions. If the tests are successful, &freetds; will use threadsafe functions throughout.</para> ++ ++<para>Threadsafe operation has been tested on Linux, FreeBSD, and HP-UX. It should work on Solaris, Tru64, and (reportedly) IRIX. Not expected to work on non-unixy systems. It is a good idea to enable threadsafe operation if you configure Apache with multi-threading support.</para> ++ </listitem> ++ </varlistentry> ++ <varlistentry> ++ <term><Option>--disable-debug</Option></term> ++ <listitem><para>Debug-mode compiles are enabled by default, and will remain so at least until version 1.0. You can speed things up ever so slightly by disabling it. ++</para></listitem> ++ </varlistentry> ++ </variablelist> ++ ++ <variablelist id="tab.turnon"><title>Things you can turn on</title> ++ <varlistentry> ++ <term><Option>--enable-msdblib</Option></term> ++ <listitem><para>Enable Microsoft behavior in the &dblib; <acronym>API</> where it diverges from Sybase's. (For instance, Microsoft uses different names for the members of its date structure.) Typically needed only for porting Win32 applications to Unix.</para> ++ ++<para>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</> 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. ++ This require you to configure Kerberos support on your machine. ++</para></listitem> ++ </varlistentry> ++ ++ <varlistentry> ++ <term><Option>--enable-sspi</Option></term> ++ <listitem><para>Enable SSPI support. SSPI is a Micrsoft library that allows you to use your current logged account for authentication. With this option enabled, FreeTDS supports "trusted logins" for Win32/64, just as Microsoft's own implmentations do. ++</para></listitem> ++ </varlistentry> ++ ++ <varlistentry> ++ <term><Option>--enable-extra-checks</Option></term> ++ <listitem><para>Intended for debugging purposes, enables certain internal consistency checks against problems like memory corruption and buffer exhaustion. ++</para></listitem> ++ </varlistentry> ++ ++ <varlistentry> ++ <term><Option>--enable-developing</Option></term> ++ <listitem><para>Enable some code still in development. Should be used only by a developer or a brave user :) ++</para></listitem> ++ </varlistentry> ++ ++ </variablelist> ++ <variablelist id="tab.ssl"><title>SSL support</title> ++ <varlistentry> ++ <term><Option>--with-gnutls</Option></term> ++ <listitem><para>Enable SSL using GnuTLS. Use version 1.2.3 or newer.</para> ++ </listitem> ++ </varlistentry> ++ ++ <varlistentry> ++ <term><Option>--with-openssl=<replaceable>DIR</></Option></term> ++ <listitem><para>Enable SSL using OpenSSL. Unlike &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</></title> +- <para> +-Now you're ready to build. Follow these easy steps. +- </para> +- <orderedlist> +- <listitem><para>Download the tarball and unpack it.</para> +- <para>Alternatively, get the latest build from <productname>CVS</productname> +- <footnote> +- <para> +-<productname>CVS</productname> users will need the GNU autotools: Autoconf, Automake, and libtool. +- </para> +- </footnote> +-. +- </para></listitem> +- <listitem><para>Change to the <filename>freetds</filename> directory. +- </para></listitem> +- <listitem><para>run <command>./configure</> with any options you need. +- </para></listitem> +- <listitem><para><command>make; make install; make clean</command> +- </para></listitem> +- </orderedlist> +- <para> +-You normally need to be root to <command>make install</command>, unless you used the <option>--prefix</> option during configuration to install into your own directory. +- </para> +- <para> +-With any luck, you've built and installed the &freetds; libraries. +- </para> +- </sect3> +- </sect2> ++ ++<para>Now you're ready to build. Follow these easy steps.</para> ++ <orderedlist> ++ <listitem><para>Download the tarball and unpack it.</para> ++ ++<para>Alternatively, get the latest build from <productname>CVS</productname> ++ <footnote> ++ ++<para><productname>CVS</productname> users will need the GNU autotools: Autoconf, Automake, and libtool.</para> ++ </footnote> ++ . ++</para></listitem> ++ <listitem><para>Change to the <filename>freetds</filename> directory. ++</para></listitem> ++ <listitem><para>run <command>./configure</> with any options you need. ++</para></listitem> ++ <listitem><para><command>make; make install; make clean</command> ++</para></listitem> ++ </orderedlist> ++ ++<para>You normally need to be root to <command>make install</command>, unless you used the <option>--prefix</> option during configuration to install into your own directory.</para> ++ ++<para>With any luck, you've built and installed the &freetds; libraries.</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></title> +- <para>The &freetds; ODBC driver compiles under ++ <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> + +- <itemizedlist> + +- <listitem><para>VC++. Project files are included in the <filename>win32</> directory. See also <filename>Makefile.win32</>. </para></listitem> ++<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> + +- <listitem><para>Dev-C++</para></listitem> +- <listitem><para>MingW</para></listitem> ++ <sect2 id="Windows"><title>Win32 and Win64</title> + +- <listitem><para><application>gcc</> under <application>cygwin</>. </para></listitem> ++<para>Building for Windows using Microsoft's compiler is supported via the <filename>NMakefile</filename> included in the distribution. Set up the command-line build environment per Microsoft's instructions, and run e.g. + +- <listitem><para>The Borland Builder 6.0 compiler is also reported to work, but requires some tweaking of the <literal>#include</> statements. We would apply any patches that make this work cleanly.</para></listitem> ++<screen> ++ <prompt>$ </prompt><userinput>nmake -fNmakefile -nologo apps PLATFORM=win32 CONFIGURATION=debug</userinput></screen></para> + +- </itemizedlist> +- </para> ++<note><para>Perhaps you're shaking your head at such an <quote>old school</quote> approach. Over the years, Microsoft's proprietary project-configuration files have proved difficult to support. Every version is different, and there are a great many versions in use <quote>in the wild</quote> at any one time. As the project changes, it becomes impossible to maintain these kinds of files. </para></note> + +- <para>From the Department of Double Emulation: &freetds; builds as a <filename>.dll</> under <productname>WINE</> and as a <filename>.a</> under <productname>Interix</>. See the mailing list archives (second half of 2003) for details. </para> +- </sect2> ++ <sect3><title>Other ways to build under Windows®</title> ++ ++ <itemizedlist> ++ ++ <listitem><para>Visual Studio. Project files are included in the <filename>win32</> directory. See above note for why these might be out of date.</para></listitem> ++ ++ <listitem><para>Dev-C++</para></listitem> ++ <listitem><para>MingW</para></listitem> ++ ++ <listitem><para><application>gcc</> under <application>cygwin</>.</para></listitem> ++ ++ <listitem><para>The Borland Builder 6.0 compiler is also reported to work, but requires some tweaking of the <literal>#include</> statements. We would apply any patches that make this work cleanly.</para></listitem> ++ ++ </itemizedlist> ++<para>From the Department of Double Emulation: &freetds; builds as a <filename>.dll</> under <productname>WINE</> and as a <filename>.a</> under <productname>Interix</>. See the mailing list archives (second half of 2003) for details.</para> ++ </sect3> ++ </sect2> + <sect2 id="VMS"><title>VMS®</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</></member> +- <member><application>vmstar</></member> +- <member><application>MMS</> or <application>MMK</></member> +- </simplelist> +- </para> +- +- <sect3><title>Build Instructions</title> +- +- <para>Decompress and unpack the source archive using gunzip and vmstar. If +-you are untarring on an ODS-5 disk, you should use the <parameter>/ODS2</> or <parameter>-o</> +-option to create universally VMS-friendly filenames; otherwise the build will fail to locate some files.</para> ++<para>&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</></member> ++ <member><application>vmstar</></member> ++ <member><application>MMS</> or <application>MMK</></member> ++ </simplelist></para> ++ ++ <sect3><title>Build Instructions</title> ++ + +- <para>Set default to the top-level source directory and run the configuration +-script:</para> ++<para>Decompress and unpack the source archive using gunzip and vmstar. If ++ you are untarring on an ODS-5 disk, you should use the <parameter>/ODS2</> or <parameter>-o</> ++ option to create universally VMS-friendly filenames; otherwise the build will fail to locate some files.</para> ++ + ++<para>Set default to the top-level source directory and run the configuration ++ script:</para> ++ + <screen> +- <prompt>$</> <userinput>@[.vms]configure</userinput> +-</screen> +- +- <para> This creates a <filename>descrip.mms</> in the top-level source +-directory which you may execute by simply running MMS (if you have the Module Management System that +-is part of DECset) or MMK (a freeware MMS alternative available from <ulink +-url="http://www.madgoat.com">www.madgoat.com</ulink>).</para> ++ <prompt>$</> <userinput>@[.vms]configure</userinput></screen> ++ + +- <para>Further information can be found in the <filename></> in the source distribution. +- </para> ++<para> This creates a <filename>descrip.mms</> in the top-level source ++ directory which you may execute by simply running MMS (if you have the Module Management System that ++ is part of DECset) or MMK (a freeware MMS alternative available from <ulink ++ url="http://www.madgoat.com">www.madgoat.com</ulink>).</para> ++ + +- </sect3> +- </sect2> ++<para>Further information can be found in the <filename></> in the source distribution.</para> ++ ++ </sect3> ++ </sect2> + <sect2 id="osx"><title>OS X®</title> +- <para>As of this writing ($Date: 2011/01/25 06:18:53 $), the regular distribution compiles on OS X. Releases prior to 0.63 either did not compile or required patching. </para> +- +- <sect3 id="OSX.Build.Update"> +- <title>Alternative build procedure</title> +- <para>On 11 March 2004, <email><ulink url="mailto:dimo@angelhill.net">Dmitri Fedortchenko</ulink></email> offered the following approach, using a local <command>libtool</>. It is included here as a source of clues, in case you encounter trouble. </para> +- +-<procedure id="OSX.new.libtool"> +- <title>Installing with libtool 1.5.2</title> +- <step><para>Install the latest <command>libtool</> from GNU into <filename>/usr/local</>, so as not to interfere with the Apple-original. </para></step> +- <step><para>Make sure <filename>/usr/local/bin</> is in your <envar>PATH</envar> and <filename>/usr/local/lib</> is in your <envar>LIBRARY_PATH</envar>. </para></step> +- <step><para>Go to the &freetds; source directory and generate the <filename>Makefile</>s +- <screen> +- <prompt>$ </prompt><userinput>./configure --disable-libiconv --disable-odbc</userinput> +- </screen> +- </para></step> ++ ++<para>As of this writing ($Date: 2011/02/13 01:54:38 $), the regular distribution compiles on OS X. Releases prior to 0.63 either did not compile or required patching.</para> ++ ++<![ %comment [ ++ <!-- cf http://www.is-thought.co.uk/book/sgml-8.htm --> ++ <sect3 id="OSX.Build.Update"> ++ <title>Alternative build procedure</title> ++<para>On 11 March 2004, <email><ulink url="mailto:dimo@angelhill.net">Dmitri Fedortchenko</ulink></email> offered the following approach, using a local <command>libtool</>. It is included here as a source of clues, in case you encounter trouble.</para> ++ ++ <procedure id="OSX.new.libtool"> ++ <title>Installing with libtool 1.5.2</title> ++ <step><para>Install the latest <command>libtool</> from GNU into <filename>/usr/local</>, so as not to interfere with the Apple-original.</para></step> ++ <step><para>Make sure <filename>/usr/local/bin</> is in your <envar>PATH</envar> and <filename>/usr/local/lib</> is in your <envar>LIBRARY_PATH</envar>.</para></step> ++ <step><para>Go to the &freetds; source directory and generate the <filename>Makefile</>s ++<screen> ++ <prompt>$ </prompt><userinput>./configure --disable-libiconv --disable-odbc</userinput></screen> ++</para></step> + <step><para>Overwrite FreeTDS's <filename>libtool</> with a symbolic link to your (better) one +- <screen> +- <footnote><para> If you run <command>configure</> again, you'll need to perform this step +-again, because <command>libtool</> will have been regenerated in its fossilized state. </para></footnote> +- <prompt>$ </prompt><userinput>ln -sf /usr/local/bin/libtool</userinput> +- </screen></para></step> +- +- +- <step performance="optional"><para>To check that you've done everything correctly up to this +-point, +- <screen> +- <prompt>$ </prompt><userinput>./libtool --version</userinput> +- </screen> +- <command>libtool</> should report version 1.5.2 (or whatever version you downloaded, and <emphasis>not</> 1.4). </para></step> ++<screen> ++ <footnote><para> If you run <command>configure</> again, you'll need to perform this step ++ again, because <command>libtool</> will have been regenerated in its fossilized state.</para></footnote> ++ <prompt>$ </prompt><userinput>ln -sf /usr/local/bin/libtool</userinput></screen></para></step> ++ ++ <step performance="optional"><para>To check that you've done everything correctly up to this ++ point, ++<screen> ++ <prompt>$ </prompt><userinput>./libtool --version</userinput></screen> ++ <command>libtool</> should report version 1.5.2 (or whatever version you downloaded, and <emphasis>not</> 1.4).</para></step> + <step><para>And finally, of course +- <screen> +- <prompt>$ </prompt><userinput>make && make install</userinput> +- </screen> +- </para></step> +- +-</procedure> +- </sect3> +- </sect2> +- ++<screen> ++ <prompt>$ </prompt><userinput>make && make install</userinput></screen> ++</para></step> ++ ++ </procedure> ++ </sect3> ++]]> ++ </sect2> ++ + <sect2 id="AIX"><title>AIX®</title> +- <para> +-AIX® can induce linker indigestion. libtool doesn't always understand that a <filename>.a</> file +-can be a shared library. One solution is to build only static libraries with the <option>--disable-shared</> +-configure option. +- </para> +- <para> +-Another problem seems to be that the linker isn't asked to pull in all the requisite libraries. Cf. this helpful +-<ulink url="http://lists.ibiblio.org/pipermail/freetds/2004q3/016748.html">mailing list message</ulink>. +- </para> +- </sect2> +- +- <sect2 id="RPM"><title>GNU/Linux distributions that use RPMs</title> +- <para> +-You may find it convenient to make an RPM from the source distribution, in which case you'll be glad to +-know it is easily done: + +- <screen> +- <prompt>$ </prompt><userinput>rpmbuild -ta freetds-0.63RC9.tar.gz</userinput> +- </screen> ++<para>AIX® can induce linker indigestion. libtool doesn't always understand that a <filename>.a</> file ++ can be a shared library. One solution is to build only static libraries with the <option>--disable-shared</> ++ configure option.</para> + +- </para> +- </sect2> ++<para>Another problem seems to be that the linker isn't asked to pull in all the requisite libraries. Cf. this helpful ++ <ulink url="http://lists.ibiblio.org/pipermail/freetds/2004q3/016748.html">mailing list message</ulink>.</para> ++ </sect2> ++ ++ <sect2 id="RPM"><title>GNU/Linux distributions that use RPMs</title> + ++<para>You may find it convenient to make an RPM from the source distribution, in which case you'll be glad to ++ know it is easily done: ++ ++<screen> ++ <prompt>$ </prompt><userinput>rpmbuild -ta freetds-0.63RC9.tar.gz</userinput></screen></para> ++ </sect2> ++ + </sect1> + </chapter> +- ++ + <!-- ////////////////// CHAPTER /////////////////////// --> +- +- <chapter id="install"> +- <title>Install &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</> world, we <command>configure</command> the package (generate the <filename>Makefile</>s), then we <command>make install</command> the package. To <emphasis>install the package</emphasis> is to copy the binaries to their appropriate run-time directories, copy the documentation to the <filename>doc</filename> directory, and maybe let the package manager know what's happened. That's generally considered part of the <phrase>build process</phrase>, covered in the last chapter. +- </para> +- <para> +-For lack of a better term, this chapter describes installing the <emphasis>product</emphasis>. Put more specifically, once we're done with the package manager, we still have to tell &freetds; about your database servers, and we still have to tell your client programs about &freetds;. +- </para> +-</Note> +- <sect1 id="LocalEnvironment"> ++ ++<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</> world, we <command>configure</command> the package (generate the <filename>Makefile</>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</> protocol version, described next. +- </para> ++ ++<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</> protocol version, described next.</para> + </sect1> +- <sect1 id="ChoosingTdsProtocol"> +- <title>Choosing a <acronym>TDS</> protocol version</title> +- <para> +-The <acronym>TDS</> protocol version is probably something you'd rather not know even existed, much less something you'd have to choose. But there's not that much to it, really. Unless you run into an incompatibility, you're best off running with the highest protocol version supported by your server. That's what the vendors' own products do, which is why when you read the Sybase or Microsoft documentation you find no mention of <acronym>TDS</> versions. +-<table id="tab.Protocol.by.Product"> +-<title>Versions of the <acronym>TDS</> Protocol, by Product</title> +-<tgroup cols="3"> +-<thead> +-<row> <entry>Product</entry> +- <entry>TDS Version</entry> +- <entry>Comment</entry> +- </row> +-</thead> +-<tbody> +- <row> +- <entry>Sybase before System 10, Microsoft SQL Server 6.x</entry> +- <entry>4.2</entry> +- <entry>Still works with all products, subject to its limitations. </entry> +- </row> +- <row> +- <entry>Sybase System 10 and above</entry> +- <entry>5.0</entry> +- <entry>Still the most current protocol used by Sybase. </entry> +- </row> +- <row> +- <entry>Sybase System SQL Anywhere</entry> +- <entry>5.0 <emphasis>only</> </entry> +- <entry>Originally Watcom SQL Server, a completely separate codebase. Our best information is that SQL Anywhere first supported TDS in version 5.5.03 using the OpenServer Gateway (OSG), and native TDS 5.0 support arrived with version 6.0. </entry> +- </row> +- <row> +- <entry>Microsoft SQL Server 7.0</entry> +- <entry>7.0</entry> +- <entry>Includes support for the extended datatypes in <productname>SQL Server</productname> 7.0 (such as char/<structname>varchar</structname> fields of more than 255 characters), and support for Unicode.</entry> +- </row> +- <row> +- <entry>Microsoft SQL Server 2000</entry> +- <entry>7.1</entry> +- <entry>Include support for <symbol>bigint</> (64 bit integers), <symbol>variant</> 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</>. &freetds; does not support MARS. </para></footnote>.</entry> +- </row> +-</tbody> +-</tgroup> +-</table> +- </para> +- <para>For best results, use the highest version of hte 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> +- <para> +- <ItemizedList><title>TDS 4.2 has limitations</title> +- <listitem><para><acronym>ASCII</> only, of course. +- </para></listitem> +- <listitem><para><acronym>RPC</> is not supported. +- </para></listitem> +- <listitem><para><acronym>BCP</> is not supported. +- </para></listitem> +- <listitem><para><structname>varchar</structname> fields are limited to 255 characters. If your table defines longer fields, they'll be truncated. +- </para></listitem> ++ <sect1 id="ChoosingTdsProtocol"> ++ <title>Choosing a <acronym>TDS</> protocol version</title> ++ ++<para>The <acronym>TDS</> protocol version is probably something you'd rather not know even existed, much less something you'd have to choose. But there's not that much to it, really. Unless you run into an incompatibility, you're best off running with the highest protocol version supported by your server. That's what the vendors' own products do, which is why when you read the Sybase or Microsoft documentation you find no mention of <acronym>TDS</> versions. ++ <table id="tab.Protocol.by.Product"> ++ <title>Versions of the <acronym>TDS</> Protocol, by Product</title> ++ <tgroup cols="3"> ++ <thead> ++ <row> <entry>Product</entry> ++ <entry>TDS Version</entry> ++ <entry>Comment</entry> ++ </row> ++ </thead> ++ <tbody> ++ <row> ++ <entry>Sybase before System 10, Microsoft SQL Server 6.x</entry> ++ <entry>4.2</entry> ++ <entry>Still works with all products, subject to its limitations. </entry> ++ </row> ++ <row> ++ <entry>Sybase System 10 and above</entry> ++ <entry>5.0</entry> ++ <entry>Still the most current protocol used by Sybase. </entry> ++ </row> ++ <row> ++ <entry>Sybase System SQL Anywhere</entry> ++ <entry>5.0 <emphasis>only</> </entry> ++ <entry>Originally Watcom SQL Server, a completely separate codebase. Our best information is that SQL Anywhere first supported TDS in version 5.5.03 using the OpenServer Gateway (OSG), and native TDS 5.0 support arrived with version 6.0. </entry> ++ </row> ++ <row> ++ <entry>Microsoft SQL Server 7.0</entry> ++ <entry>7.0</entry> ++ <entry>Includes support for the extended datatypes in <productname>SQL Server</productname> 7.0 (such as char/<structname>varchar</structname> fields of more than 255 characters), and support for Unicode.</entry> ++ </row> ++ <row> ++ <entry>Microsoft SQL Server 2000</entry> ++ <entry>7.1</entry> ++ <entry>Include support for <symbol>bigint</> (64 bit integers), <symbol>variant</> 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</>. &freetds; does not support MARS.</para></footnote>.</entry> ++ </row> ++ </tbody> ++ </tgroup> ++ </table></para> ++ ++<para>For best results, use the highest version of hte 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> ++ ++<para><ItemizedList><title>TDS 4.2 has limitations</title> ++ <listitem><para><acronym>ASCII</> only, of course. ++</para></listitem> ++ <listitem><para><acronym>RPC</> is not supported. ++</para></listitem> ++ <listitem><para><acronym>BCP</> is not supported. ++</para></listitem> ++ <listitem><para><structname>varchar</structname> fields are limited to 255 characters. If your table defines longer fields, they'll be truncated. ++</para></listitem> + <listitem><para>dynamic queries (also called <firstterm>prepared statements</>) are not supported. +- </para></listitem> +- </ItemizedList> +- </para> +- +- <para> The protocol version may also affect how database servers interpret +-commands. For example, Microsoft SQL Server 2000 is known to behave differently with versions 4.2 +-and 7.0. Version 7.0 is recommended for compatibility with SQL Server tools. +- </para> +- +- ++</para></listitem> ++ </ItemizedList></para> ++ ++ ++<para> The protocol version may also affect how database servers interpret ++ commands. For example, Microsoft SQL Server 2000 is known to behave differently with versions 4.2 ++ and 7.0. Version 7.0 is recommended for compatibility with SQL Server tools.</para> ++ + </sect1> +- <sect1 id="name.lookup"> <title><replaceable>servername</> 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. ++ <sect1 id="name.lookup"> <title><replaceable>servername</> 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 db-lib and ct-lib. ODBC lookup is different. </para></footnote> +- </title> +- <listitem><para>Find <replaceable>servername</> 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</> to an IP address with <function>inet_addr(3)</>. </para></listitem> +- <listitem><para>Request name-lookup from the operating system via <function>gethostbyname(3)</> 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> ++ <footnote><para>This description applies to &dblib; and &ctlib;. ODBC lookup is different.</para></footnote> ++ </title> ++ <listitem><para>Find <replaceable>servername</> 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</> to an IP address with <function>inet_addr(3)</>.</para></listitem> ++ <listitem><para>Request name-lookup from the operating system via <function>gethostbyname(3)</> or similar.</para></listitem> ++ </orderedlist> + +- <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 — or set the <envar>TDSPORT</envar> and <envar>TDSVER</envar> environment variables — and rely on DNS for name resolution. +- </para> +- </sect1> ++ 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> ++ + +- <sect1 id="freetdsconf"> +- <title>The &freetdsconf; file</title> ++<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 — or set the <envar>TDSPORT</envar> and <envar>TDSVER</envar> environment variables — 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</> 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</> 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> ++<para>Just as DNS defines hostnames for network addresses, &freetdsconf; uses a <firstterm>servername</> 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</> 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</>. If you don't specify anything, <command>configure</>'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}</><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> ++ ++<para>The default location of &freetdsconf; is determined by the <literal>--sysconfdir</literal> option of <command>configure</>. If you don't specify anything, <command>configure</>'s default <literal>sysconfdir</literal> is <filename>/usr/local/etc</filename>. <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}</><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</>. </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 = 4.2 + +-[myserver] +- host = ntbox.mydomain.com +- port = 1433 ++<para><tip><para> The following information is also provided in the &freetdsconf; manual page, cf. <command>man freetds.conf</>.</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 = 4.2 ++ ++ [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 ++ tds version = 7.1 ++ </programlisting> ++ </example> ++ ++<para>In this example, the default <acronym>TDS</> version for all servernames is set to <literal>4.2</>. It is then overridden for <literal>myserver2</literal> (a Sybase server) which uses <literal>5.0</literal>, and <literal>myserver3</literal> (a MSSQL 2000 server) which uses <literal>7.1</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</>, &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>tds version</entry> ++ <entry>4.2, 5.0, 7.0, 7.1, 7.2, <literal>auto</></entry> ++ <entry><parameter>--with-tdsver</> value (<literal>5.0</> if unspecified) ++ Overridden by <link linkend="TDSVER">TDSVER</link>.</entry> ++ <entry>The <acronym>TDS</> protocol version to use when connecting. <quote><literal>auto</></quote> tells &freetds; to use an autodetection (trial-and-error) algorithm to choose the protocol version. </entry> ++ </row> ++ <row> ++ <entry>host</entry> ++ <entry>host name or IP address</entry> ++ <entry>none</entry> ++ <entry>The host that the servername is running on.</entry> ++ </row> ++ <row> ++ <entry>port</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</> for <acronym>TDS</> <literal>5.0</>, and <literal>1433</> for everything else. Mutually exclusive with <emphasis>instance</>, below. ++ Overridden by <link linkend="TDSPORT">TDSPORT</link>. </entry> ++ </row> ++ ++ <row> ++ <entry>instance</entry> ++ <entry>instance name</entry> ++ <entry>none</entry> ++ <entry><para>Name of Microsoft SQL Server <emphasis>instance</> to connect to. The port will be detected automatically. Mutually exclusive with <emphasis>port</>, above. Requires UDP connection to port 1434 on the server.</para></entry> ++ </row> ++ ++ <row> ++ <entry id="asa.database">ASA database</entry> ++ <entry>valid database name</entry> ++ <entry>servername [<replaceable>section</>] 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</>. For most TDS servers, <literal>lservname</> is a user-defined string with no inherent meaning. ASA servers, however, requires that <literal>lservname</> contain a valid database name, and sets that as the default database for the connection. FreeTDS normally fills <literal>lservname</> with the [<replaceable>section</>] text.. This entry instead sets the database name independently of the [<replaceable>section</>] name. </entry> ++ </row> ++ ++ <row> ++ <entry>initial block size</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>dump file</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>dump file append</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>timeout</entry> ++ <entry>0-</entry> ++ <entry>none</entry> ++ <entry>Sets period to wait for response of query before timing out.</entry> ++ </row> ++ <row> ++ <entry>connect timeout</entry> ++ <entry>0-</entry> ++ <entry>none</entry> ++ <entry>Sets period to wait for response from connect before timing out.</entry> ++ </row> ++ <row> ++ <entry>emulate little endian</entry> ++ <entry>yes/no</entry> ++ <entry>no</entry> ++ <entry>Forces big endian machines (Sparc, PPC, PARISC) to act as little endian to communicate with MS Servers. Set automatically for <acronym>TDS</> 7.0 or above on big endian hosts</entry> ++ </row> ++ <row> ++ <entry id="clientcharset">client charset</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</> 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</> 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>text size</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</> in the <acronym>T-SQL</> documentation for your server. </entry> ++ </row> ++ <row> ++ <entry>debug flags</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>encryption</entry> ++ <entry>off/request/required</entry> ++ <entry>off</entry> ++ <entry>Specify if encryption is desidered. Supported for Microsoft servers. <symbol>off</> disables encryption (only if needed); <symbol>request</> means use if available; <symbol>required</> means create and allow encrypted connections only.</entry> ++ </row> ++ <row> ++ <entry>enable gssapi delegation</entry> ++ <entry>on/off</entry> ++ <entry>off</entry> ++ <entry>Enable delegation flag using Kerberos.</entry> ++ </row> ++ </tbody> ++ </tgroup> ++ </table> ++ <sect3> <title>Overrides</> + +-[myserver2] +- host = unixbox.mydomain.com +- port = 4000 +- tds version = 5.0 ++<para>Many settings in &freetdsconf; can be overridden by <link linkend="envvar">environment variables</link>.</para> + +-[myserver3] +- host = instancebox.mydomain.com +- instance = foo +- tds version = 7.1 +-</programlisting> +-</example> +- <para> +-In this example, the default <acronym>TDS</> version for all servernames is set to <literal>4.2</>. It is then overridden for <literal>myserver2</literal> (a Sybase server) which uses <literal>5.0</literal>, and <literal>myserver3</literal> (a MSSQL 2000 server) which uses <literal>7.1</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</>, &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>tds version</entry> +- <entry>4.2, 5.0, 7.0, 7.1, 7.2, <literal>auto</></entry> +- <entry><parameter>--with-tdsver</> value (<literal>5.0</> if unspecified) +- Overridden by <link linkend="TDSVER">TDSVER</link>. +- </entry> +- <entry>The <acronym>TDS</> protocol version to use when connecting. <quote><literal>auto</></quote> tells &freetds; to use an autodetection (trial-and-error) algorithm to choose the protocol version. </entry> +- </row> +- <row> +- <entry>host</entry> +- <entry>host name or IP address</entry> +- <entry>none</entry> +- <entry>The host that the servername is running on.</entry> +- </row> +- <row> +- <entry>port</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</> for <acronym>TDS</> <literal>5.0</>, and <literal>1433</> for everything else. Mutually exclusive with <emphasis>instance</>, below. +- Overridden by <link linkend="TDSPORT">TDSPORT</link>. +- </entry> +- </row> +- +- <row> +- <entry>instance</entry> +- <entry>instance name</entry> +- <entry>none</entry> +- <entry><para>Name of Microsoft SQL Server <emphasis>instance</> to connect to. The port will be detected automatically. Mutually exclusive with <emphasis>port</>, above. Requires UDP connection to port 1434 on the server. </para></entry> +- </row> +- +- <row> +- <entry id="asa.database">ASA database</entry> +- <entry>valid database name</entry> +- <entry>servername [<replaceable>section</>] 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</>. For most TDS servers, <literal>lservname</> is a user-defined string with no inherent meaning. ASA servers, however, requires that <literal>lservname</> contain a valid database name, and sets that as the default database for the connection. FreeTDS normally fills <literal>lservname</> with the [<replaceable>section</>] text.. This entry instead sets the database name independently of the [<replaceable>section</>] name. </entry> +- </row> +- +- <row> +- <entry>initial block size</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>dump file</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>dump file append</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>timeout</entry> +- <entry>0-</entry> +- <entry>none</entry> +- <entry>Sets period to wait for response of query before timing out.</entry> +- </row> +- <row> +- <entry>connect timeout</entry> +- <entry>0-</entry> +- <entry>none</entry> +- <entry>Sets period to wait for response from connect before timing out.</entry> +- </row> +- <row> +- <entry>emulate little endian</entry> +- <entry>yes/no</entry> +- <entry>no</entry> +- <entry>Forces big endian machines (Sparc, PPC, PARISC) to act as little endian to communicate with MS Servers. Set automatically for <acronym>TDS</> 7.0 or above on big endian hosts</entry> +- </row> +- <row> +- <entry id="clientcharset">client charset</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</> 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</> 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>text size</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</> in the <acronym>T-SQL</> documentation for your server. </entry> +- </row> +- <row> +- <entry>debug flags</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>encryption</entry> +- <entry>off/request/required</entry> +- <entry>off</entry> +- <entry>Specify if encryption is desidered. Supported for Microsoft servers. <symbol>off</> disables encryption (only if needed); <symbol>request</> means use if available; <symbol>required</> means create and allow encrypted connections only.</entry> +- </row> +- <row> +- <entry>enable gssapi delegation</entry> +- <entry>on/off</entry> +- <entry>off</entry> +- <entry>Enable delegation flag using Kerberos.</entry> +- </row> +-</tbody> +-</tgroup> +-</table> +- <sect3> <title>Overrides</> +- <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> ++<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</> +- <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</> entry. The default value (<literal>4FFF</> hex) gives a level of detail that is useful for resolving problems via the mailing list. </para> +- +-<table id="tab.freetds.conf.debugflags"> +-<title>Valid bitmask values for <literal>debug flags</> entry in &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</> +- <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</> </para></listitem> +- <listitem><para><symbol>try domain login </> </para></listitem> +- <listitem><para><symbol>nt domain </> </para></listitem> +- <listitem><para><symbol>cross domain login </> </para></listitem> +- <listitem><para><symbol>debug level </> </para></listitem> +-</itemizedlist> +- </sect3> ++ <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> ++ + +- </sect2> +- </sect1> ++<para>The log's granularity can be controlled with the <literal>debug flags</> entry. The default value (<literal>4FFF</> hex) gives a level of detail that is useful for resolving problems via the mailing list.</para> ++ ++ <table id="tab.freetds.conf.debugflags"> ++ <title>Valid bitmask values for <literal>debug flags</> entry in &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</> + +- <sect1 id="locales"> +- <title>The <filename>locales.conf</filename> file</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</></para></listitem> ++ <listitem><para><symbol>try domain login </></para></listitem> ++ <listitem><para><symbol>nt domain </></para></listitem> ++ <listitem><para><symbol>cross domain login </></para></listitem> ++ <listitem><para><symbol>debug level </></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</> will probably be dropped from <productname>FreeTDS</> one day. Its only real purpose now is to control the format of date strings. The Right Way™ to deduce the appropriate default date format is from the application's locale settings, while allowing an override in &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</> for your system. &freetds; will examine its environment for a <literal>LOCALE</> string. If it finds one, it will look it up in <filename>locales.conf</> to find your preferred settings. If it fails to find one, it will use its defaults. +- </para> +- </sect2> ++ ++<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</> will probably be dropped from <productname>FreeTDS</> one day. Its only real purpose now is to control the format of date strings. The Right Way™ to deduce the appropriate default date format is from the application's locale settings, while allowing an override in &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</> for your system. &freetds; will examine its environment for a <literal>LOCALE</> string. If it finds one, it will look it up in <filename>locales.conf</> to find your preferred settings. If it fails to find one, it will use its defaults.</para> ++ </sect2> + <sect2 id="localeslocation"> + <title>Where it goes</title> +- <para> +- Like &freetdsconf;, the location of <filename>locales.conf</> is determined by the value of <option>--sysconfdir</> to <command>configure</>. The default is <literal>PREFIX/etc</>. +- </para> +- </sect2> ++ ++<para>Like &freetdsconf;, the location of <filename>locales.conf</> is determined by the value of <option>--sysconfdir</> to <command>configure</>. The default is <literal>PREFIX/etc</>.</para> ++ </sect2> + <sect2 id="localesformat"> + <title>What it looks like</title> +- <para> +-The format of <filename>locales.conf</> is similar to that of &freetdsconf;. There is a <literal>[default]</> section, and a section for each locale. +- +-<filename>locales.conf</> controls three settings +-<variablelist id="tab.locales.conf"> +- <varlistentry> +- <term><literal>date format</></term> +- <listitem> +- <para>This entry will be passed (almost) literally to <function>strftime(3)</> to convert dates to strings. </para> +- <para>For the most part, see you system documentation for <function>strftime(3)</> (<command>man 3 strftime</command>). You will see there though that <function>strftime(3)</> has no provision for milliseconds. The <filename>locales.conf</> format string uses <literal>%z</> for milliseconds. <note><para>If your system's <function>strftime(3)</> does employ <literal>%z</> for its own use, it will not be given that chance by &freetds;. &freetds; will consume the <literal>%z</> for its milliseconds needs, and will not pass it on to <function>strftime(3)</>. </para></note></para> +- </listitem> +- </varlistentry> +- <varlistentry> +- <term><literal>language</></term> +- <listitem> +- <para>The language that will be used for error/status messages from the server. A <productname>SQL Server</productname> client can specify a language for such messages at login time. <note><para>&freetds; issues a few messages of its own. Messages from the server are called <quote>messages</>; those from the client library (i.e., from &freetds;) are called <quote>error messages</>. &freetds;-issued messages are not affected by <filename>locales.conf</filename>. </para></note> +- </para> +- </listitem> +- </varlistentry> +- <varlistentry> +- <term><literal>charset</></term> +- <listitem> +- <para>Indicates to the server what character set should be used for communicating with the client.</para> +- </listitem> +- </varlistentry> +-</variablelist> +- </para> +- </sect2> ++ ++<para>The format of <filename>locales.conf</> is similar to that of &freetdsconf;. There is a <literal>[default]</> section, and a section for each locale. ++ ++ <filename>locales.conf</> controls three settings ++ <variablelist id="tab.locales.conf"> ++ <varlistentry> ++ <term><literal>date format</></term> ++ <listitem> ++ ++<para>This entry will be passed (almost) literally to <function>strftime(3)</> to convert dates to strings.</para> ++ ++<para>For the most part, see you system documentation for <function>strftime(3)</> (<command>man 3 strftime</command>). You will see there though that <function>strftime(3)</> has no provision for milliseconds. The <filename>locales.conf</> format string uses <literal>%z</> for milliseconds. <note><para>If your system's <function>strftime(3)</> does employ <literal>%z</> for its own use, it will not be given that chance by &freetds;. &freetds; will consume the <literal>%z</> for its milliseconds needs, and will not pass it on to <function>strftime(3)</>.</para></note></para> ++ </listitem> ++ </varlistentry> ++ <varlistentry> ++ <term><literal>language</></term> ++ <listitem> ++ ++<para>The language that will be used for error/status messages from the server. A <productname>SQL Server</productname> client can specify a language for such messages at login time. <note><para>&freetds; issues a few messages of its own. Messages from the server are called <quote>messages</>; those from the client library (i.e., from &freetds;) are called <quote>error messages</>. &freetds;-issued messages are not affected by <filename>locales.conf</filename>.</para></note></para> ++ </listitem> ++ </varlistentry> ++ <varlistentry> ++ <term><literal>charset</></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</> 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> + +- <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> ++<para>governs the version of the <acronym>TDS</> protocol used to connect to your server. For a given server, &freetds; inspects four sources in the following order to determine which <acronym>TDS</> protocol version to use, using the first one it finds.</para> ++ <orderedlist> ++ <listitem><para>The value specified in <envar>TDSVER</envar> ++</para></listitem> ++ <listitem><para>A &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 passed to <command>configure</command> ++</para></listitem> ++ </orderedlist> ++ </listitem> ++ </varlistentry> ++ <varlistentry> ++ <term id="TDSPORT"><envar>TDSPORT</envar></term> ++ <listitem> + +-This section covers the first two items. For information about environment variables that control logging, see <link linkend="logging">Logging</link> +- </para> +- <para> +-In a typical system, no environment variables need be used. They're sometimes handy for testing, for instance setting <envar>TDSVER</> to check if a connection problem is due to using the wrong protocol version. And they have other uses, described below. But they're just knobs, so don't feel you have to turn every one, unless you're the sort that likes turning knobs. +- </para> ++<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, 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> + +-<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</> protocol used to connect to your server. For a given server, &freetds; inspects four sources in the following order to determine which <acronym>TDS</> protocol version to use, using the first one it finds. </para> +- <orderedlist> +- <listitem><para>The value specified in <envar>TDSVER</envar> +- </para></listitem> +- <listitem><para>A &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 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, 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> ++<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> ++ + +- </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> ++<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"> ++ ++ <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: + ++<para>Of course, each shell is a little different. In the Bourne shell and variants such as <application>ksh</application> and <application>bash</application>, to set ++ <envar>SYBASE</envar> and <envar>TDSVER</envar> do: ++ + <screen> +-<prompt>$ </prompt><userinput>export SYBASE=/usr/local/freetds</userinput> # (or your favorite directory) +-<prompt>$ </prompt><userinput>export TDSVER=4.2</userinput> +-</screen> +- </para> +- <para> +-In <application>csh</application>: ++ <prompt>$ </prompt><userinput>export SYBASE=/usr/local/freetds</userinput> # (or your favorite directory) ++ <prompt>$ </prompt><userinput>export TDSVER=4.2</userinput></screen></para> + ++<para>In <application>csh</application>: ++ + <screen> +-<prompt>$ </prompt><userinput>setenv SYBASE /usr/local/freetds</userinput> +-<prompt>$ </prompt><userinput>setenv TDSVER 4.2</userinput> +-</screen> +- </para> +- </sect2> +- <sect2 id="Checking"> +- <title>Checking your work</title> +- <para> +-When you're done, you should see something very like this: ++ <prompt>$ </prompt><userinput>setenv SYBASE /usr/local/freetds</userinput> ++ <prompt>$ </prompt><userinput>setenv TDSVER 4.2</userinput></screen></para> ++ </sect2> ++ <sect2 id="Checking"> ++ <title>Checking your work</title> + ++<para>When you're done, you should see something very like this: ++ + <screen> +-<prompt>$ </prompt><userinput>ls $SYBASE</userinput> +-<computeroutput>etc include interfaces lib</computeroutput> +-</screen> +- </para> +- ++ <prompt>$ </prompt><userinput>ls $SYBASE</userinput> ++ <computeroutput>etc include interfaces lib</computeroutput></screen></para> ++ + </sect2> + </sect1> +- <sect1 id="PortOverride"> +- <title>Port override syntax</title> ++ <sect1 id="PortOverride"> ++ <title>Port override syntax</title> ++ + +- <para>The port to which to connect can be overridden using a &freetds; extended syntax. +- </para> ++<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>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> ++<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 SQL Server 2000.) +- </para> ++ Only Microsoft SQL Server instances are supported. (This server feature was introduced with SQL Server 2000.)</para> ++ + +- <para>Note that other &freetdsconf; properties still apply. +- </para> +- <para> For the technically curious: each SQL Server <firstterm>instance</> appears on the network as a server listening at a port. The old way — and it still works — is to designate each instance in &freetdsconf; as a separate server. The new <quote>named instance</> 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</>, port 1434. The server responds with a port number. &freetds; then uses that number to connect in the usual way. +- </para> ++<para>Note that other &freetdsconf; properties still apply.</para> ++ ++<para> For the technically curious: each SQL Server <firstterm>instance</> appears on the network as a server listening at a port. The old way — and it still works — is to designate each instance in &freetdsconf; as a separate server. The new <quote>named instance</> 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</>, 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> + +- <sect1 id="ConfirmInstall"><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</> exists in &freetdsconf; </para></listitem> +- <listitem><para>a <replaceable>host</> property exists for <replaceable>servername</></para></listitem> +- <listitem><para><replaceable>host</> can be resolved to a network address</para></listitem> +- <listitem><para>the server is listening to the <replaceable>port</> or named <replaceable>instance</> </para></listitem> +- <listitem><para>the user can log in to the server </para></listitem> +- <!-- listitem><para> </para></listitem --> ++ ++<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</> exists in &freetdsconf;</para></listitem> ++ <listitem><para>a <replaceable>host</> property exists for <replaceable>servername</></para></listitem> ++ <listitem><para><replaceable>host</> can be resolved to a network address</para></listitem> ++ <listitem><para>the server is listening to the <replaceable>port</> or named <replaceable>instance</></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> + +- +- 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</> utility is provided as part of FreeTDS expressly for troubleshooting. <command>tsql</> is superficially similar to an <command>isql</>, but uses <filename>libtds</filename> directly, bypassing the client libraries (e.g., <systemitem class="library">db-lib</systemitem>). It can also report where it looks for &freetdsconf; and other compile-time settings (with <command>tsql -C</>). +- </para> +-<example id="e.g.tsqlShowsettings"> +-<title>Show compile-time settings with <command>tsql</></title> ++<para>The <firstterm>tsql</> utility is provided as part of FreeTDS expressly for troubleshooting. <command>tsql</> is superficially similar to an <command>isql</>, but uses <filename>libtds</filename> directly, bypassing the client libraries (e.g., &dblib;). It can also report where it looks for &freetdsconf; and other compile-time settings (with <command>tsql -C</>).</para> ++ <example id="e.g.tsqlShowsettings"> ++ <title>Show compile-time settings with <command>tsql</></title> + <screen> +-<prompt>$ </prompt><userinput>tsql -C </userinput> +-<prompt>Password: </prompt> +-<computeroutput> +-locale is "C" +-locale charset is "646" +-Compile-time settings (established with the "configure" script): +- Version: freetds &version; +- freetds.conf directory: /usr/local/etc +- MS db-lib source compatibility: no +- Sybase binary compatibility: no +- Thread safety: yes +- iconv library: no +- TDS version: 7.0 +- iODBC: no +- unixodbc: no +-</computeroutput> +-</screen> +-</example> +- +- <para>For details on the use of <command>tsql</>, consult its man page. </para> ++ <prompt>$ </prompt><userinput>tsql -C </userinput> ++ <prompt>Password: </prompt> ++ <computeroutput> ++ locale is "C" ++ locale charset is "646" ++ Compile-time settings (established with the "configure" script): ++ Version: freetds &version; ++ freetds.conf directory: /usr/local/etc ++ MS db-lib source compatibility: no ++ Sybase binary compatibility: no ++ Thread safety: yes ++ iconv library: no ++ TDS version: 7.0 ++ iODBC: no ++ unixodbc: no ++ </computeroutput></screen> ++ </example> ++ + +- <sect3 id="tsql.freetds.conf"><title><replaceable>servername</> Lookup</title> +- <para>If all goes well, the first time you fire up <command>tsql</> 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</> lookup failures and their corresponding messages. </para> +- <para>When <replaceable>servername</> cannot be converted to an address, up to two messages may result. Successful conversion (by any means) never produces an error message. ++<para>For details on the use of <command>tsql</>, consult its man page.</para> + +-<example id="e.g.notfound"> +-<title>Failure to find <replaceable>servername</> in &freetdsconf;</title> ++ <sect3 id="tsql.freetds.conf"><title><replaceable>servername</> Lookup</title> ++ ++<para>If all goes well, the first time you fire up <command>tsql</> 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</> lookup failures and their corresponding messages.</para> ++ ++<para>When <replaceable>servername</> 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</> 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): ++ <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): ++ 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> ++ 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</> was not found in &freetdsconf;. The library then treated <literal>nobox</> as a network hostname but found it also not to be valid per DNS, leading to message 20013.</para> ++ + +-In the above case message 20012 indicates <literal>nobox</> was not found in &freetdsconf;. The library then treated <literal>nobox</> as a network hostname but found it also not to be valid per DNS, leading to message 20013. +- </para> ++<para>If <replaceable>servername</> 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</></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</> 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 <replaceable>servername</> is found in the configuration files, but refers to an invalid hostname, only message 20013 is returned. ++<para>If name lookup succeeds, &freetds; next attempts to connect to the server. <emphasis>To connect</> means to form at TCP connection by calling <function>connect(2)</>. 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> + +-<example id="e.g.badname"> +-<title>Failure to resolve hostname for <replaceable>servername</></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</> 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</> means to form at TCP connection by calling <function>connect(2)</>. 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</> 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. ++<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</> 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> + +-<example id="e.g.noconnect"> +-<title>Failing to connect with tsql</title> ++<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</>. 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</>. ++ <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</>. 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</>. ++ ++ <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</> or port <literal>1433</>.</para> + +-<example id="e.g.instance.name"> +-<title>Getting instance information with tsql</title> ++ ++<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 -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</> or port <literal>1433</>. +- </para> ++ <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>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. ++<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</> and don't return <emphasis>state</> 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> + +-<example id="e.g.bad.tdsver"> +-<title>Using the wrong protocol for the server</title> ++ <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</> this way, the library uses the compiled-in default (set by the <filename>configure</> script). If that's not what you want, override it using the <envar>TDSVER</> environment variable.</para> ++ ++ <example id="e.g.tsqlhostname"> ++ <title>Connect with <command>tsql</> using a hostname and port number</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> ++ <prompt>$ </prompt><userinput>TDSVER=7.0 tsql -H <replaceable>hillary</> -p <replaceable>4100</> -U <replaceable>sa</></userinput> ++ <prompt>Password: </prompt> ++ <computeroutput> ++ 1> ++ </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</> and don't return <emphasis>state</> or a line number, but can contain an error code (and message) from the operating system.</para></footnote> +- ++<para>For details on <command>tsql</>, see the its man page.</para> ++ </sect3> ++ </sect2> ++ <sect2 id="Tests"><title><application>Unit Tests</application></title> + +-<example id="e.g.bad.login"> +-<title>Login failure</title> ++<para>The source code directory of each &freetds; library includes a <filename>unittests</> directory. ++ + <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> ++ <prompt>$ </prompt><userinput>ls -d -1 src/*/unittests</userinput> ++ <computeroutput> ++ src/ctlib/unittests ++ src/dblib/unittests ++ src/odbc/unittests ++ src/tds/unittests ++ </computeroutput></screen> ++ ++ The unit tests rely on the <filename>PWD</> file in root of the FreeTDS source tree. ++ <filename>PWD</> holds a username, password, servername, and database to be used for the unit tests. We try to make sure to leave nothing behind: any data and objects created are either temporary or removed at the end of the test. The tests should all work, subject to disclaimers in the directory's <filename>README</>.</para> + +- <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</> this way, the library uses the compiled-in default (set by the <filename>configure</> script). If that's not what you want, override it using the <envar>TDSVER</> environment variable. +- </para> ++<para>To invoke the tests, edit the <filename>PWD</> file and issue the command <command>make check</command>. In order to execute all tests successfully, you must indicate a working, available servername in <filename>PWD</>. ++ Some tests require permission to create stored procedures on server.</para> + +-<example id="e.g.tsqlhostname"> +-<title>Connect with <command>tsql</> using a hostname and port number</title> +-<screen> +-<prompt>$ </prompt><userinput>TDSVER=7.0 tsql -H <replaceable>hillary</> -p <replaceable>4100</> -U <replaceable>sa</></userinput> +-<prompt>Password: </prompt> +-<computeroutput> +-1> +-</computeroutput> +-</screen> +-</example> ++<para>To complete successfully, the ODBC tests require some additional setup. In your <filename>PWD</> file, add a <literal>SRV</> entry specifying the DSN entry for your <filename>odbc.ini</>. The ODBC tests all build their own <filename>odbc.ini</> and try to redirect the Driver Manager to it, however this functionality is very DM dependent and may well fail unless you have either iODBC or unixODBC.</para> + ++<para><tip><para> ++ The <filename>PWD</> 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</>, 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> +-For details on <command>tsql</>, 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</> directory. ++<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> + +-<screen> +-<prompt>$ </prompt><userinput>ls -d -1 src/*/unittests</userinput> +-<computeroutput> +-src/ctlib/unittests +-src/dblib/unittests +-src/odbc/unittests +-src/tds/unittests +-</computeroutput> +-</screen> ++<para>The original ODBC solution to this conundrum employed the <filename>odbc.ini</> file. <filename>odbc.ini</> stored information about a server, known generically as a <firstterm>Data Source Name</> (DSN). ODBC applications connected to the server by calling the function <function>SQLConnect(DSN, UID, PWD)</function>, where <replaceable>DSN</> is the Data Source Name entry in <filename>odbc.ini</>, <replaceable>UID</> is the username, and <replaceable>PWD</> the password. Any and all information about the DSN was kept in <filename>odbc.ini</>. And all was right with the world.</para> + +-The unit tests rely on the <filename>PWD</> file in root of the FreeTDS source tree. +-<filename>PWD</> holds a username, password, servername, and database to be used for the unit tests. We try to make sure to leave nothing behind: any data and objects created are either temporary or removed at the end of the test. The tests should all work, subject to disclaimers in the directory's <filename>README</>. </para> +- <para> +-To invoke the tests, edit the <filename>PWD</> file and issue the command <command>make check</command>. In order to execute all tests successfully, you must indicate a working, available servername in <filename>PWD</>. +-Some tests require permission to create stored procedures on server. +- </para> +- <para> +-To complete successfully, the ODBC tests require some additional setup. In your <filename>PWD</> file, add a <literal>SRV</> entry specifying the DSN entry for your <filename>odbc.ini</>. The ODBC tests all build their own <filename>odbc.ini</> and try to redirect the Driver Manager to it, however this functionality is very DM dependent and may well fail unless you have either iODBC or unixODBC. +- </para> +- <para> +-<tip><para> +-The <filename>PWD</> provided by &freetds; includes usernames and passwords that probably don't exist on your server. +-</para></tip> +- </para> +- </sect2> +- </sect1> ++<para>The ODBC 3.0 specification introduced a new function: <function>SQLDriverConnect</>. ++ The connection attributes are provided as a single argument, a string of concatenated name-value pairs. <function>SQLDriverConnect</> subsumed the functionality of <function>SQLConnect</>, in that the name-value pair string allowed the caller to pass — in addition the the original <literal>DSN</>, <literal>UID</>, and <literal>PWD</> — any other parameters the driver could accept. Moreover, the application can specify which driver to use. In effect, it became possible to specify the entire set of DSN properties as parameters to <function>SQLDriverConnect</>, obviating the need for <filename>odbc.ini</>. This led to the use of the so-called <firstterm>DSN-less</> configuration, a setup with no <filename>odbc.ini</>.</para> ++ ++<para>But <productname>FreeTDS</> did not start out as an ODBC driver (remember &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</>, using <filename>odbc.ini</> to describe the DSN. That choice complied with the expectations of the Driver Managers, and minimized the amount of duplicated information in the configuration files. But it can be a little confusing, too, because <filename>odbc.ini</> in effect points to &freetdsconf;. We call this configuration <firstterm>ODBC-combined</>, because it supports all three <productname>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</>, rather than leaning on &freetdsconf;. For installations that don't need &dblib; and &ctlib;, this <firstterm>ODBC-only</> setup is simpler.</para> ++ ++<para>More recently, <function>SQLDriverConnect</> 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> + +- </chapter> +- <chapter id="PrepODBC"> +- <title>Preparing ODBC</title> +- <sect1 id="OdbcBackground"><title>Background and Terminology</title> +- <para> +-To connect to a database, a library such as <productname>FreeTDS</> needs some information about the connection. Which server, and by <emphasis>server</>, which IP address and port is do you mean? Which user is requesting the connection, and what authentication does he offer? Every database library needs a way to capture and convey that information. +- </para> +- <para> +-ODBC was conceived as a general interface definition, not tied to any particular database or access library. For that reason, ODBC also needs to know which driver to use with a given server. +- </para> +- <para> +-The original ODBC solution to this conundrum employed the <filename>odbc.ini</> file. <filename>odbc.ini</> stored information about a server, known generically as a <firstterm>Data Source Name</> (DSN). ODBC applications connected to the server by calling the function <function>SQLConnect(DSN, UID, PWD)</function>, where <replaceable>DSN</> is the Data Source Name entry in <filename>odbc.ini</>, <replaceable>UID</> is the username, and <replaceable>PWD</> the password. Any and all information about the DSN was kept in <filename>odbc.ini</>. And all was right with the world. +- </para> +- <para> +-The ODBC 3.0 specification introduced a new function: <function>SQLDriverConnect</>. +-The connection attributes are provided as a single argument, a string of concatenated name-value pairs. <function>SQLDriverConnect</> subsumed the functionality of <function>SQLConnect</>, in that the name-value pair string allowed the caller to pass — in addition the the original <literal>DSN</>, <literal>UID</>, and <literal>PWD</> — any other parameters the driver could accept. Moreover, the application can specify which driver to use. In effect, it became possible to specify the entire set of DSN properties as parameters to <function>SQLDriverConnect</>, obviating the need for <filename>odbc.ini</>. This led to the use of the so-called <firstterm>DSN-less</> configuration, a setup with no <filename>odbc.ini</>. +- </para> +- <para> +-But <productname>FreeTDS</> did not start out as an ODBC driver (remember db-lib and ct-lib), and has always had its own way to store server properties: &freetdsconf;. When Brian added the <productname>FreeTDS</> ODBC driver, he began by supporting the old <function>SQLConnect</>, using <filename>odbc.ini</> to describe the DSN. That choice complied with the expectations of the Driver Managers, and minimized the amount of duplicated information in the configuration files. But it can be a little confusing, too, because <filename>odbc.ini</> in effect points to &freetdsconf;. We call this configuration <firstterm>ODBC-combined</>, because it supports all three <productname>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</>, rather than leaning on &freetdsconf;. For installations that don't need db-lib and ct-lib, this <firstterm>ODBC-only</> setup is simpler. </para> +- <para> +-More recently, <function>SQLDriverConnect</> was added to <productname>FreeTDS</>. As described above, this function allows the application to specify connection attributes with reference to either, or neither, configuration file. It's your choice. In making that choice, keep the following terms clear in your mind: +- </para> ++ <variablelist><title>Important &freetds; ODBC terms</title> ++ <varlistentry> ++ <term><literal>SERVERNAME</></term> ++ <listitem> + +-<variablelist><title>Important <productname>FreeTDS</> ODBC terms</title> +- <varlistentry> +- <term><literal>SERVERNAME</></term> +- <listitem> +- <para>specifies the <literal>[<replaceable>servername</>]</literal> entry in &freetdsconf;. </para> +- </listitem> +- </varlistentry> +- <varlistentry> +- <term><literal>SERVER</></term> +- <listitem> +- <para>specifies the real server i.e., the TCP/IP name of the machine hosting the database server. </para> +- </listitem> +- </varlistentry> +- <varlistentry> +- <term><literal>DSN</></term> +- <term><literal>Driver</></term> +- <listitem> +- <para>In your connection string, you can decide to use a DSN entry in <filename>odbc.ini</> using the <literal>DSN</> attribute, or to specify the driver you want with the <literal>Driver</> attribute.</para> +- </listitem> +- </varlistentry> +-</variablelist> ++<para>specifies the <literal>[<replaceable>servername</>]</literal> entry in &freetdsconf;.</para> ++ </listitem> ++ </varlistentry> ++ <varlistentry> ++ <term><literal>SERVER</></term> ++ <listitem> + +- <para> +-In sum, &freetds; supports three ODBC three choices: +- </para> ++<para>specifies the real server i.e., the TCP/IP name of the machine hosting the database server.</para> ++ </listitem> ++ </varlistentry> ++ <varlistentry> ++ <term><literal>DSN</></term> ++ <term><literal>Driver</></term> ++ <listitem> + ++<para>In your connection string, you can decide to use a DSN entry in <filename>odbc.ini</> using the <literal>DSN</> attribute, or to specify the driver you want with the <literal>Driver</> attribute.</para> ++ </listitem> ++ </varlistentry> ++ </variablelist> ++ + +-<variablelist id="tab.ODBC.configuration.choices"><title>ODBC configuration choices</title> +- <varlistentry> +- <term>DSN-less</term> +- <listitem> +- <para><emphasis>No</> connection information is specified in <filename>odbc.ini</>. Advantageous if you're using more of <productname>FreeTDS</> than just the ODBC driver. </para> +- </listitem> +- </varlistentry> +- <varlistentry> +- <term>ODBC-only</term> +- <listitem> +- <para><emphasis>All</> connection information +-is specified in <filename>odbc.ini</>, without the need for &freetdsconf;. This is the <quote>traditional</> ODBC setup. </para> +- </listitem> +- </varlistentry> +- <varlistentry> +- <term>ODBC-combined</term> +- <listitem> +- <para>Connection information maintained in &freetdsconf;. <filename>odbc.ini</> contains DSN entries that refer to servernames in &freetdsconf;. </para> +- </listitem> +- </varlistentry> +-</variablelist> ++<para>In sum, &freetds; supports three ODBC three choices:</para> ++ ++ <variablelist id="tab.ODBC.configuration.choices"><title>ODBC configuration choices</title> ++ <varlistentry> ++ <term>DSN-less</term> ++ <listitem> ++ ++<para><emphasis>No</> connection information is specified in <filename>odbc.ini</>. Advantageous if you're using more of &freetds; than just the ODBC driver.</para> ++ </listitem> ++ </varlistentry> ++ <varlistentry> ++ <term>ODBC-only</term> ++ <listitem> ++ ++<para><emphasis>All</> connection information ++ is specified in <filename>odbc.ini</>, without the need for &freetdsconf;. This is the <quote>traditional</> ODBC setup.</para> ++ </listitem> ++ </varlistentry> ++ <varlistentry> ++ <term>ODBC-combined</term> ++ <listitem> ++ ++<para>Connection information maintained in &freetdsconf;. <filename>odbc.ini</> 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 table defines all possible ODBC connection attributes for the <productname>FreeTDS</> ODBC driver. Which ones you'll need depends on how you set yourself up. They may appear in your connection string, or in <filename>odbc.ini</>. +- </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</></entry> +- <entry>A valid DSN entry</entry> +- <entry>none</entry> +- <entry>The <literal>DSN</> to which <productname>FreeTDS</> should connect. <productname>FreeTDS</> will search <filename>odbc.ini</> for entry. It lets you specify a connection as for <function>SQLConnect</>, but using <function>SQLDriverConnect</>. Do not use <literal>Servername</> and <literal>DSN</> together. </entry> +- </row> +- <row> +- <entry><literal>UID</></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</></entry> +- <entry>Any</entry> +- <entry>empty</entry> +- <entry>The password to be used when connecting. </entry> +- </row> +- <row> +- <entry><literal>WSID</></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</></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</></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</> instead.</entry> +- </row> +- <row> +- <entry><literal>Server</></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</></entry> +- <entry>Any TCP port</entry> +- <entry>Depends on the TDS version specified with <command>configure</></entry> +- <entry>The TCP port where the servername is listening. </entry> +- </row> +- <row> +- <entry><literal>TDS_Version</></entry> +- <entry>Any valid protocol version</entry> +- <entry>Depends on the TDS version specified with <command>configure</></entry> +- <entry>TDS protocol version to use (e.g., 5.0, 7.0).</entry> +- </row> +- <row> +- <entry><literal>ClientCharset</></entry> +- <entry>A name recognized by the iconv library linked to FreeTDS. +- This correspond to <literal>client charset</> in &freetdsconf;.</entry> +- <entry>ISO8859-1</entry> +- <entry>Character set (encoding) used by the client.</entry> +- </row> +- <row> +- <entry><literal>APP</></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</></entry> +- <entry>Any</entry> +- <entry>us_english</entry> +- <entry>(Human) language the server should use for error messages.</entry> +- </row> +- <row> +- <entry><literal>Address</></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</> or simply <replaceable>ip</> in standard dotted-decimal notation. </entry> +- </row> +- <row> +- <entry><literal>Database</></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</></entry> +- <entry>Any</entry> +- <entry>DB dependent</entry> +- <entry>Maximum size returned from server for blobs.</entry> +- </row> +- <row> +- <entry><literal>PacketSize</></entry> +- <entry>Any</entry> +- <entry>DB 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</></entry> +- <entry>Yes/No</entry> +- <entry>No</entry> +- <entry>Use your current account instead of <literal>UID</>/<literal>PWD</> attributes. +- This option require SSPI or Kerberos. This superceed <literal>UID</>/<literal>PWD</> attributes.</entry> +- </row> +-</tbody> +-</tgroup> +-</table> +-</para> ++ <sect1 id="OdbcConnAttr"> ++ <title>Connection attributes</title> ++ ++<para>The following table defines all possible ODBC connection attributes for the <productname>FreeTDS</> ODBC driver. Which ones you'll need depends on how you set yourself up. They may appear in your connection string, or in <filename>odbc.ini</>.</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</></entry> ++ <entry>A valid DSN entry</entry> ++ <entry>none</entry> ++ <entry>The <literal>DSN</> to which <productname>FreeTDS</> should connect. <productname>FreeTDS</> will search <filename>odbc.ini</> for entry. It lets you specify a connection as for <function>SQLConnect</>, but using <function>SQLDriverConnect</>. Do not use <literal>Servername</> and <literal>DSN</> together. </entry> ++ </row> ++ <row> ++ <entry><literal>UID</></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</></entry> ++ <entry>Any</entry> ++ <entry>empty</entry> ++ <entry>The password to be used when connecting. </entry> ++ </row> ++ <row> ++ <entry><literal>WSID</></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</></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</></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</> instead.</entry> ++ </row> ++ <row> ++ <entry><literal>Server</></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</></entry> ++ <entry>Any TCP port</entry> ++ <entry>Depends on the TDS version specified with <command>configure</></entry> ++ <entry>The TCP port where the servername is listening. </entry> ++ </row> ++ <row> ++ <entry><literal>TDS_Version</></entry> ++ <entry>Any valid protocol version</entry> ++ <entry>Depends on the TDS version specified with <command>configure</></entry> ++ <entry>TDS protocol version to use (e.g., 5.0, 7.0).</entry> ++ </row> ++ <row> ++ <entry><literal>ClientCharset</></entry> ++ <entry>A name recognized by the iconv library linked to FreeTDS. ++ This correspond to <literal>client charset</> in &freetdsconf;.</entry> ++ <entry>ISO 8859-1</entry> ++ <entry>Character set (encoding) used by the client.</entry> ++ </row> ++ <row> ++ <entry><literal>APP</></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</></entry> ++ <entry>Any</entry> ++ <entry>us_english</entry> ++ <entry>(Human) language the server should use for error messages.</entry> ++ </row> ++ <row> ++ <entry><literal>Address</></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</> or simply <replaceable>ip</> in standard dotted-decimal notation. </entry> ++ </row> ++ <row> ++ <entry><literal>Database</></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</></entry> ++ <entry>Any</entry> ++ <entry>DB dependent</entry> ++ <entry>Maximum size returned from server for blobs.</entry> ++ </row> ++ <row> ++ <entry><literal>PacketSize</></entry> ++ <entry>Any</entry> ++ <entry>DB 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</></entry> ++ <entry>Yes/No</entry> ++ <entry>No</entry> ++ <entry>Use your current account instead of <literal>UID</>/<literal>PWD</> attributes. ++ This option require SSPI or Kerberos. This superceed <literal>UID</>/<literal>PWD</> attributes.</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> +-<blockquote> +- <programlisting> ++ <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> +-</blockquote> ++ + <para>The &freetdsconf; might look something like:</para> +-<blockquote> +- <programlisting> ++<programlisting> + ; + ; freetds.conf + ; + [JDBC] +- host = jdbc.sybase.com +- port = 4444 +- tds version = 5.0 ++ host = jdbc.sybase.com ++ port = 4444 ++ tds version = 5.0 + </programlisting> +-</blockquote> +-</example> +- +-<example id="e.g.ConnectDSNless"><title>Connecting with a DSN-less configuration</title> ++ </example> ++ ++ <example id="e.g.ConnectDSNless"> ++ <title>Connecting with a DSN-less configuration</title> + <programlisting> +-/* +- * application call +- */ +-const char servername[] = "JDBC"; <footnote><para>refers to the <literal>[JDBC]</> entry in &freetdsconf;.</para></footnote> +-sprintf(tmp, "DRIVER=FreeTDS<footnote><para>refers to the <literal>[FreeTDS]</> entry in <filename>odbcinst.ini</>.</para></footnote>;SERVERNAME=%s;UID=%s;PWD=%s;DATABASE=%s;", ++ /* ++ * application call ++ */ ++ const char servername[] = "JDBC"; <footnote><para>refers to the <literal>[JDBC]</> entry in &freetdsconf;.</para></footnote> ++ sprintf(tmp, "DRIVER=FreeTDS<footnote><para>refers to the <literal>[FreeTDS]</> entry in <filename>odbcinst.ini</>.</para></footnote>;SERVERNAME=%s;UID=%s;PWD=%s;DATABASE=%s;", + servername, username, password, dbname); +-res = SQLDriverConnect(Connection, NULL, (SQLCHAR *) tmp, SQL_NTS, +- (SQLCHAR *) tmp, sizeof(tmp), &len, SQL_DRIVER_NOPROMPT); +-if (!SQL_SUCCEEDED(res)) { ++ res = SQLDriverConnect(Connection, NULL, (SQLCHAR *) tmp, SQL_NTS, ++ (SQLCHAR *) tmp, sizeof(tmp), &len, SQL_DRIVER_NOPROMPT); ++ if (!SQL_SUCCEEDED(res)) { + printf("Unable to open data source (ret=%d)\n", res); + exit(1); +-} +-</programlisting> +-</example> +- +-You can even establish a connection without reference to either <filename>odbc.ini</filename> or <filename>freetd.conf</filename>. +- +-<example id="e.g.ConnectDSNlessnoconf"><title>Connecting with a DSN-less configuration that does not use &freetdsconf;</title> ++ } ++ </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<footnote><para>refers to the <literal>[FreeTDS]</> entry in <filename>odbcinst.ini</>.</para></footnote>;SERVER=%s;UID=%s;PWD=%s;DATABASE=%s;TDS_Version=5.0;Port=4444;", ++ /* ++ * application call ++ */ ++ const char servername[] = "jdbc.sybase.com"; <footnote><para>refers to the real server name.</para></footnote> ++ sprintf(tmp, "DRIVER=FreeTDS<footnote><para>refers to the <literal>[FreeTDS]</> entry in <filename>odbcinst.ini</>.</para></footnote>;SERVER=%s;UID=%s;PWD=%s;DATABASE=%s;TDS_Version=5.0;Port=4444;", + servername, username, password, dbname); +-res = SQLDriverConnect(Connection, NULL, (SQLCHAR *) tmp, SQL_NTS, +- (SQLCHAR *) tmp, sizeof(tmp), &len, SQL_DRIVER_NOPROMPT); +-if (!SQL_SUCCEEDED(res)) { ++ res = SQLDriverConnect(Connection, NULL, (SQLCHAR *) tmp, SQL_NTS, ++ (SQLCHAR *) tmp, sizeof(tmp), &len, SQL_DRIVER_NOPROMPT); ++ if (!SQL_SUCCEEDED(res)) { + printf("Unable to open data source (ret=%d)\n", res); + exit(1); +-} +-</programlisting> +-</example> +- +- </para> ++ } ++ </programlisting> ++ </example></para> + </sect1> +- <sect1 id="odbcinionly"><title>ODBC-only configuration</title> +- <para> +-An ODBC-only configuration relies solely on <filename>odbc.ini</> for server properties. Other &freetds; drivers don't know about <filename>odbc.ini</>. +- +-<example id="e.g.SampleODBConly"><title>Sample ODBC-only <filename>odbc.ini</filename> file</title> ++ ++ <sect1 id="odbcinionly"> ++ <title>ODBC-only configuration</title> ++ ++<para>An ODBC-only configuration relies solely on <filename>odbc.ini</> for server properties. Other &freetds; libraries don't know about <filename>odbc.ini</>. ++ ++ <example id="e.g.SampleODBConly"> ++ <title>Sample ODBC-only <filename>odbc.ini</filename> file</title> + <programlisting> +-[ODBC Data Sources]<footnote><para>Several DSNs might be listed here. In this example, we have only one, <quote>JDBC</>. It matches the <literal>[JDBC]</> entry later in the file. </para></footnote> +- JDBC = Sybase JDBC Server +- +-[JDBC] +-Driver = /usr/local/freetds/lib/libtdsodbc.so +-Description = Sybase JDBC Server +-Trace = No +-Server = jdbc.sybase.com +-Database = pubs2 +-Port = 4444 +-TDS_Version = 5.0 +- +-[Default] +-Driver = /usr/local/freetds/lib/libtdsodbc.so +-</programlisting> +-</example> +- </para> ++ [ODBC Data Sources]<footnote><para>Several DSNs might be listed here. In this example, we have only one, <quote>JDBC</>. It matches the <literal>[JDBC]</> entry later in the file.</para></footnote> ++ JDBC = Sybase JDBC Server ++ ++ [JDBC] ++ Driver = /usr/local/freetds/lib/libtdsodbc.so ++ Description = Sybase JDBC Server ++ Trace = No ++ Server = jdbc.sybase.com ++ Database = pubs2 ++ Port = 4444 ++ TDS_Version = 5.0 ++ ++ [Default] ++ Driver = /usr/local/freetds/lib/libtdsodbc.so ++ </programlisting> ++ </example></para> + </sect1> ++ ++ <sect1 id="odbcombo"><title>ODBC-combined configuration</title> + +- <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</> refers to the servername entry in &freetdsconf;. ++<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</> refers to the servername entry in &freetdsconf;. + +-<example id="e.g.SampleODBCcombo"><title>Sample ODBC-combined <filename>odbc.ini</filename> file</title> ++ <example id="e.g.SampleODBCcombo"> ++ <title>Sample ODBC-combined <filename>odbc.ini</filename> file</title> + <programlisting> +-[ODBC Data Sources]<footnote><para>Several DSNs might be listed here. In this example, we have only one, <quote>JDBCdsn</>. It matches the <literal>[JDBCdsn]</> entry later in the file. </para></footnote> +- JDBCdsn = Sybase JDBC Server +- +-[JDBCdsn] +-Driver = /usr/local/freetds/lib/libtdsodbc.so +-Description = Sybase JDBC Server +-Trace = No +-Servername = JDBC<footnote><para>Refers to the <literal>[JDBC]</> entry in &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> ++ [ODBC Data Sources]<footnote><para>Several DSNs might be listed here. In this example, we have only one, <quote>JDBCdsn</>. It matches the <literal>[JDBCdsn]</> entry later in the file.</para></footnote> ++ JDBCdsn = Sybase JDBC Server ++ ++ [JDBCdsn] ++ Driver = /usr/local/freetds/lib/libtdsodbc.so ++ Description = Sybase JDBC Server ++ Trace = No ++ Servername = JDBC<footnote><para>Refers to the <literal>[JDBC]</> entry in &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</>), or its servername (<literal>JDBC</>). +- </para> ++ ; ++ ; freetds.conf ++ ; ++ [JDBC] ++ host = jdbc.sybase.com ++ port = 4444 ++ tds version = 5.0 ++ </programlisting> ++ </example></para> ++ ++<para>With this arrangement, an application can connect to the server in two ways, via its DSN (<literal>JDBCdsn</>), or its servername (<literal>JDBC</>).</para> + </sect1> ++ ++ <sect1 id="odbcdiagnose"> ++ <title>Troubleshooting ODBC connections</title> + +- <sect1 id="odbcdiagnose"><title>Troubleshooting ODBC connections</title> ++ ++<para>Supposing everything compiles and installs without trouble, how do you know if your ODBC setup works? Or, if you know it doesn't, what then?</para> ++ ++<para>First, try to connect with <command>tsql</>. If you're intending to use &freetdsconf;, exercise it with ++ <command>tsql -S <replaceable>servername</></command>. If not, use ++ <command>TDSVER=7.0 tsql -H <replaceable>hostname</> -p <replaceable>port</></command></para> ++ ++<para>If <command>tsql</> works and <command>isql</> doesn't, you've isolated the problem to the ODBC setup. &freetds; might have some interoperability problems, but mere connection to the database isn't one of them! If <command>tsql</> ++ doesn't work, turn on logging with <envar>TDSDUMP</>. The log will tell you what TCP/IP name (and address) <productname>FreeTDS</> is attempting to connect to, and what version of the TDS protocol it's using.</para> + +- <para> +-Supposing everything compiles and installs without trouble, how do you know if your ODBC setup works? Or, if you know it doesn't, what then? +- </para> +- <para> +-First, try to connect with <command>tsql</>. If you're intending to use &freetdsconf;, exercise it with +- <command>tsql -S <replaceable>servername</></command>. If not, use +- <command>TDSVER=7.0 tsql -H <replaceable>hostname</> -p <replaceable>port</></command> +- </para> +- <para> +-If <command>tsql</> works and <command>isql</> doesn't, you've isolated the problem to the ODBC setup. &freetds; might have some interoperability problems, but mere connection to the database isn't one of them! If <command>tsql</> +-doesn't work, turn on logging with <envar>TDSDUMP</>. The log will tell you what TCP/IP name (and address) <productname>FreeTDS</> is attempting to connect to, and what version of the TDS protocol it's using. +- </para> +- +- <sect2 id="with.iodbc"><title>With iODBC</title> +- +- <para> <productname>iODBC</productname> comes with a sample command line query program called <command>odbctest</> that is located in the <filename>iodbc/samples</filename> directory. Using this program you can get a listing of DSNs, connect, and issue queries. It is often useful to compile a program such as this directly against the &freetds; driver instead of using a driver manager. This makes it simpler to debug if something goes wrong. To do so, simply compile and install the <systemitem class="library">ODBC</systemitem> driver with <productname>iODBC</productname> as normal <footnote><para>When compiling directly to &freetds; you still need the Driver Manager's header files.</para></footnote>, then compile and link the program directly: ++ <sect2 id="with.iodbc"><title>With iODBC</title> + +-<example id="e.g.odbctest.nodm"> +- <title>Compile <filename>odbctest</> without a driver manager.</title> ++<para> <productname>iODBC</productname> comes with a sample command line query program called <command>odbctest</> that is located in the <filename>iodbc/samples</filename> directory. Using this program you can get a listing of DSNs, connect, and issue queries. It is often useful to compile a program such as this directly against the &freetds; driver instead of using a driver manager. This makes it simpler to debug if something goes wrong. To do so, simply compile and install the <systemitem class="library">ODBC</systemitem> driver with <productname>iODBC</productname> as normal <footnote><para>When compiling directly to &freetds; you still need the Driver Manager's header files.</para></footnote>, then compile and link the program directly: ++ ++ <example id="e.g.odbctest.nodm"> ++ <title>Compile <filename>odbctest</> without a driver manager.</title> + <screen> +-<prompt>$ </prompt><userinput>make odbctest.o</userinput> +-<prompt>$ </prompt><userinput>gcc -g -o odbctest odbctest.o /usr/local/freetds/lib/libtdsodbc.a</userinput> +-</screen> +-</example> +- +-The <option>-g</> is important to keep the symbol tables for debugging purposes. Now you can run <command>gdb</> or another debugger and set breakpoints on functions in the library without the driver manager getting in the way. +- </para> +- </sect2> ++ <prompt>$ </prompt><userinput>make odbctest.o</userinput> ++ <prompt>$ </prompt><userinput>gcc -g -o odbctest odbctest.o /usr/local/freetds/lib/libtdsodbc.a</userinput></screen> ++ </example> ++ ++ The <option>-g</> is important to keep the symbol tables for debugging purposes. Now you can run <command>gdb</> or another debugger and set breakpoints on functions in the library without the driver manager getting in the way.</para> ++ </sect2> + + <sect2 id="with.unixODBC"><title>With unixODBC</title> +- +- <para> +-Try <command>isql -v <replaceable>dsn</> <replaceable>username</> <replaceable>password</></command>, and have a look at the log. See if the right address and TDS version are being used. Adjust to taste. +- </para> +- <sect3 id="with.unixODBC.osql"><title>Use <command>osql</></title> ++ + +- <para> +-The <command>osql</> utility is a Bourne shell script that checks your ODBC configuration. If it approves, it invokes the unixODBC isql utility. Cf. <command>man osql</> for details on its use. ++<para>Try <command>isql -v <replaceable>dsn</> <replaceable>username</> <replaceable>password</></command>, and have a look at the log. See if the right address and TDS version are being used. Adjust to taste.</para> ++ <sect3 id="with.unixODBC.osql"><title>Use <command>osql</></title> ++ + +-<example id="e.g.odbcdiagnose.osql"> +- <title>Use <command>osql</> to test the ODBC setup.</title> ++<para>The <command>osql</> utility is a Bourne shell script that checks your ODBC configuration. If it approves, it invokes the unixODBC isql utility. Cf. <command>man osql</> for details on its use. ++ ++ <example id="e.g.odbcdiagnose.osql"> ++ <title>Use <command>osql</> to test the ODBC setup.</title> + <screen> +-<prompt>$ </prompt><userinput>make odbctest.o</userinput> +- +-<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> ++ <prompt>$ </prompt><userinput>make odbctest.o</userinput> ++ ++ <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 + +- </sect3> +- +- </sect2> ++ 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> ++ ++ </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>SQL Server</productname>s</title> +- <para> +-Several version of Microsoft SQL server have a bug that affects big endian clients. This includes 7.0 GA and 7.0 SP1. Furthermore, <acronym>TDS</> Protocol version 7.0 is natively little endian. <productname>SQL Server 2000</productname> is also reported not to work from big endian clients without little endian emulation turned on. +- </para> +-<Note><para>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> ++<chapter id="configs"> ++ <title>Advanced Configurations</title> + +-<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 or 7.2)</emphasis>. +-</para> +-<example id="e.g.LittleEndian"> +-<title>Emulate Little Endian &freetdsconf; setting</title> ++<para>This chapter details some advanced configurations that need expanded explanation.</para> ++ <sect1 id="emulle"> ++ <title>Big Endian Clients with Buggy <productname>SQL Server</productname>s</title> ++ ++<para>Several version of Microsoft SQL server have a bug that affects big endian clients. This includes 7.0 GA and 7.0 SP1. Furthermore, <acronym>TDS</> Protocol version 7.0 is natively little endian. <productname>SQL Server 2000</productname> is also reported not to work from big endian clients without little endian emulation turned on.</para> ++ <Note><para>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 or 7.2)</emphasis>.</para> ++ <example id="e.g.LittleEndian"> ++ <title>Emulate Little Endian &freetdsconf; setting</title> + <programlisting> +-[mssql] ++ [mssql] + host = ntbox.mydomain.com + port = 1433 + tds version = 4.2 + emulate little endian = yes +-</programlisting> +-</example> ++ </programlisting> ++ </example> + </sect1> +- <sect1 id="Localization"> +- <title>Localization and <acronym>TDS</> 7.0</title> +- <para> +-<acronym>TDS</> 7.0 uses 2-byte Unicode (technically, <acronym>UCS-2</>) to transfer character data between servers and clients. Included in <quote>character data</quote> are query text (i.e., <acronym>SQL</>), metadata (table names and such), and <foreignphrase>bona fide</> data of datatypes <literal>nchar</>, <literal>nvarchar</>, and <literal>ntext</>. (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</>, &freetds; provides for conversion by the client to other character sets. The mechanism used is determined by the <filename>configure</> script, which looks for a <function>iconv(3)</> function, an implementation of the <ulink url="http://www.opengroup.org/onlinepubs/7908799/xsh/iconv.html">iconv</ulink> standard. If no <function>iconv</> library is found, or if it is explicitly disabled, &freetds; will use its built-in <function>iconv</> substitute, and will be capable of converting among only <acronym>ISO 8859-1</>, <acronym>UTF-8</>, and <acronym>UCS-2</>. +- </para> +- <para> +-To learn what character set the client wants, &freetds; prefers the applicable <link linkend="clientcharset">&freetdsconf;</link> <literal>client charset</> property. If that is not set, it parses the <envar>LANG</> environment variable. In either case, the found string is passed to <function>iconv</>(3) (or its built-in replacment). <footnote><para>The built-in replacement expects GNU iconv names: <literal>ISO-8859-1</>, <literal>US-ASCII</>, or <literal>UTF-8</>.</para></footnote>. If neither is found, <acronym>UCS-2</> data are converted to <acronym>ISO 8859-1</>. +- </para> ++ <sect1 id="Localization"> ++ <title>Localization and <acronym>TDS</> 7.0</title> + +- <para> +-To list all supported iconv character sets try <command>iconv</>(1). GNU's does: +- </para> ++<para><acronym>TDS</> 7.0 uses 2-byte Unicode (technically, <acronym>UCS-2</>) to transfer character data between servers and clients. Included in <quote>character data</quote> are query text (i.e., <acronym>SQL</>), metadata (table names and such), and <foreignphrase>bona fide</> data of datatypes <literal>nchar</>, <literal>nvarchar</>, and <literal>ntext</>. (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</>, &freetds; provides for conversion by the client to other character sets. The mechanism used is determined by the <filename>configure</> script, which looks for a <function>iconv(3)</> function, an implementation of the <ulink url="http://www.opengroup.org/onlinepubs/7908799/xsh/iconv.html">iconv</ulink> standard. If no <function>iconv</> library is found, or if it is explicitly disabled, &freetds; will use its built-in <function>iconv</> substitute, and will be capable of converting among only <acronym>ISO 8859-1</>, <acronym>UTF-8</>, and <acronym>UCS-2</>.</para> ++ ++<para>To learn what character set the client wants, &freetds; prefers the applicable <link linkend="clientcharset">&freetdsconf;</link> <literal>client charset</> property. If that is not set, it parses the <envar>LANG</> environment variable. In either case, the found string is passed to <function>iconv</>(3) (or its built-in replacment). <footnote><para>The built-in replacement expects GNU iconv names: <literal>ISO-8859-1</>, <literal>US-ASCII</>, or <literal>UTF-8</>.</para></footnote>. If neither is found, <acronym>UCS-2</> data are converted to <acronym>ISO 8859-1</>.</para> ++ ++ ++<para>To list all supported iconv character sets try <command>iconv</>(1). GNU's does:</para> + <screen> +-<prompt>$ </><userinput>iconv --list</userinput> +-</screen> +- <para> +-For other systems, consult your documentation (most likely <command>man iconv</command> will give you some hints). +- </para> +- <para> +-In this example a server named <literal>mssql</literal> will return data encoded in the GREEK character set. +- </para> +-<example id="e.g.GREEK"> +-<title>Configuring for GREEK &freetdsconf; setting</title> ++ <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] ++ [mssql] + host = ntbox.mydomain.com + port = 1433 + tds version = 7.0 + 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</> '?' 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> ++ </programlisting> ++ </example> + +- <para> +-If you have a mix of character data that can not be contained in a single-byte character set, you may wish to use <acronym>UTF-8</>. <acronym>UTF-8</> is a variable length unicode encoding that is compatible with <acronym>ASCII</> in the range 0 to 127. With <acronym>UTF-8</>, you are guaranteed to never have an unconvertible character.</para> ++<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</> '?' 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> ++ + +-<Important><para>&freetds; is not fully compatible with multi-byte character sets such as <acronym>UCS-2</>. You must use an ASCII-extension charset (e.g., UTF-8, ISO-8859-*)<footnote><para>not EBCDIC or other weird charsets</para></footnote>. 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</> character set. +- </para> +-<example id="e.g.UTF8"> +-<title>Configuring for <acronym>UTF-8</> &freetdsconf; setting</title> ++<para>If you have a mix of character data that can not be contained in a single-byte character set, you may wish to use <acronym>UTF-8</>. <acronym>UTF-8</> is a variable length unicode encoding that is compatible with <acronym>ASCII</> in the range 0 to 127. With <acronym>UTF-8</>, you are guaranteed to never have an unconvertible character.</para> ++ ++ <Important><para>&freetds; is not fully compatible with multi-byte character sets such as <acronym>UCS-2</>. You must use an ASCII-extension charset (e.g., UTF-8, ISO-8859-*)<footnote><para>not EBCDIC or other weird charsets</para></footnote>. 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</> character set.</para> ++ <example id="e.g.UTF8"> ++ <title>Configuring for <acronym>UTF-8</> &freetdsconf; setting</title> + <programlisting> +-[mssql] ++ [mssql] + host = ntbox.mydomain.com + port = 1433 + tds version = 7.0 + client charset = UTF-8 +-</programlisting> +-</example> +- <para> +-It is also worth clarifying that <acronym>TDS 7.0</> and above do not accept any specified character set during login, as 4.2 does. A <acronym>TDS 7.0</> login packet uses <acronym>UCS-2</>. +- </para> ++ </programlisting> ++ </example> ++ ++<para>It is also worth clarifying that <acronym>TDS 7.0</> and above do not accept any specified character set during login, as 4.2 does. A <acronym>TDS 7.0</> login packet uses <acronym>UCS-2</>.</para> + <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</> character set, irrespective of the column's datatype. For example, in the SQL statement + ++<para>String literals in SQL must be prefixed with 'N' unless the enclosed string can be represented in the server's <emphasis>single-byte</> character set, irrespective of the column's datatype. For example, in the SQL statement ++ + <informalexample><screen> +-INSERT INTO tablename (greeting) VALUES ('Hallå') +-</screen></informalexample> ++ INSERT INTO tablename (greeting) VALUES ('Hallå')</screen></informalexample> ++ ++ the string is subject to somewhat surprising treatment by the server.</para> + +-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 — <literal>nchar</>, <literal>nvarchar</>, and <literal>ntext</> — the value stored is that which results from a <emphasis>second</> conversion: from the single-byte form to the <acronym>UCS-2</> form. +- </para> +- <para> +-The <emphasis>only</> safe way to enclose strings in SQL text is with an 'N' prefix: ++<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 — <literal>nchar</>, <literal>nvarchar</>, and <literal>ntext</> — the value stored is that which results from a <emphasis>second</> conversion: from the single-byte form to the <acronym>UCS-2</> form.</para> + ++<para>The <emphasis>only</> safe way to enclose strings in SQL text is with an 'N' prefix: ++ + <informalexample><screen> +-INSERT INTO tablename (greeting) VALUES (N'Hallå') +-</screen></informalexample> ++ INSERT INTO tablename (greeting) VALUES (N'Hallå')</screen></informalexample> </para> ++ <bridgehead renderas='sect3'>Commentary</bridgehead> + +- </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 — with <acronym>UCS-2</> or <acronym>ISO 8859-1</> or anything else — it's converted to <acronym>UCS-2</> before it's sent to the server. And obviously arrives at the server as <acronym>UCS-2</>. If the column into which it's being inserted is also <acronym>UCS-2</>, there's no need of <emphasis>any</> conversion, much less two, and <emphasis>certainly</> no need to lose infomation. +- </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ïvely written) will store exactly the same characters. +- </para> +- </sect2> ++<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 — with <acronym>UCS-2</> or <acronym>ISO 8859-1</> or anything else — it's converted to <acronym>UCS-2</> before it's sent to the server. And obviously arrives at the server as <acronym>UCS-2</>. If the column into which it's being inserted is also <acronym>UCS-2</>, there's no need of <emphasis>any</> conversion, much less two, and <emphasis>certainly</> no need to lose infomation.</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ï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 logins instead of standard server logins. The advantage of doing this is that the passwords are encrypted on the wire using a challenge-response protocol. +- </para> +- <para>Domain logins may or may not support single sign-on (connecting without prompting for a password) depending on how &freetds; was configured. For Windows hosts (both 32- and 64-bit), if SSPI is enabled, &freetds; will log in using so-called "trusted authentication". For Linux (and similar) hosts, enabling Kerberos provides similar functionality. If neither option is enabled, &freetds; can <emphasis>still</> log in using the domain account, but the user must re-enter the password, as described next. +- </para> +- <para> +-To use domain logins, use the <literal>'DOMAIN\username'</> syntax for the username and use the domain password. +- </para> +-<example id="e.g.domainlogin"><title>Logging in with a domain login</title> +-<screen> +-<computeroutput>$ </computeroutput><userinput>tsql -S camelot -U 'NOTTINGHAM\lancelot' -P roundtable</userinput> +-locale is "C" +-locale charset is "646" +-Msg 5703, Level 0, State 1, Server CPRO200, Line 0 +-Changed language setting to middle_english. +-1> +-</screen> +-</example> ++ <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> +-When &freetds; sees the <quote><literal>\</></quote> character, it automatically chooses a domain login. +- </para> +-<Note><para>The term <firstterm>domain</> in this context is a Microsoft term. It refers to what's sometimes called an <firstterm>NT domain</firstterm>. It's unrelated to the DNS domain. DNS domains are used for name resolution. NT domains are used for authentication. Authentication is done by the domain controller, often the <firstterm>Primary Domain Controller</firstterm> (PDC). +- </para><para> +-The SQL Server machine may belong to an NT domain. &freetds; provides an encrypted password — a domain password, known to the domain controller — that the server will ask the domain controller to verify. </para></Note> ++<para>As mentioned in the installation chapter, <productname>Microsoft SQL Server</productname> includes the ability to use domain logins instead of standard server logins. The advantage of doing this is that the passwords are encrypted on the wire using a challenge-response protocol.</para> + ++<para>Domain logins may or may not support single sign-on (connecting without prompting for a password) depending on how &freetds; was configured. For Windows hosts (both 32- and 64-bit), if SSPI is enabled, &freetds; will log in using so-called "trusted authentication". For Linux (and similar) hosts, enabling Kerberos provides similar functionality. If neither option is enabled, &freetds; can <emphasis>still</> log in using the domain account, but the user must re-enter the password, as described next.</para> ++ ++<para>To use domain logins, use the <literal>'DOMAIN\username'</> syntax for the username and use the domain password.</para> ++ <example id="e.g.domainlogin"><title>Logging in with a domain login</title> ++<screen> ++ <computeroutput>$ </computeroutput><userinput>tsql -S camelot -U 'NOTTINGHAM\lancelot' -P roundtable</userinput> ++ locale is "C" ++ locale charset is "646" ++ Msg 5703, Level 0, State 1, Server CPRO200, Line 0 ++ Changed language setting to middle_english. ++ 1></screen> ++ </example> ++ ++ ++<para>When &freetds; sees the <quote><literal>\</></quote> character, it automatically chooses a domain login.</para> ++ <Note><para>The term <firstterm>domain</> in this context is a Microsoft term. It refers to what's sometimes called an <firstterm>NT domain</firstterm>. It's unrelated to the DNS domain. DNS domains are used for name resolution. NT domains are used for authentication. Authentication is done by the domain controller, often the <firstterm>Primary Domain Controller</firstterm> (PDC). ++</para><para>The SQL Server machine may belong to an NT domain. &freetds; provides an encrypted password — a domain password, known to the domain controller — that the server will ask the domain controller to verify.</para></Note> ++ + <sect2 id="domaindetails"> + <title>Implementation details</title> +- <para> +-Support for domain logins in &freetds; is limited to the TCP/IP network protocol stack. &freetds; does not currently implement support for Named Pipe-based SQL connections — that is, connections transported over the DCE/RPC interface, which uses TCP port 139, 445, or 135 on Win32 machines depending on the type of encapsulation used for DCE/RPC itself. Supporting this would require a fairly extensive DCE/RPC library for Unix. <productname>Samba</productname> has one that is licensed under the GPL and therefore not usable by LGPL-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> ++<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 — 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>In order to take advantage of Kerberos you have to set up your machine with keytab from your Active Directory. +- To configure your stuff you could use samba or configure directly Kerberos (<filename>/etc/krb5.conf</>). +- </para> +- <para>By default Unix do not initialize Kerberos ticket with your login account. You have to use kinit to initialize ticket. +- You could also configure Kerberos in PAM in order to initialize Kerberos ticket at login time. +- </para> ++ <sect1 id="kerberos"> ++ <title>Kerberos Support</title> ++<para>Perhaps surprisingly, Kerberos can be used to authenticate to Microsoft SQL Servers. This affords single-signon (or, at most, <quote>double-signon</quote>) capability in non-Windows environment. <footnote><para>The reason this works is that much of Active Directory is based on Kerberos. </para></footnote></para> ++ ++<para>To take advantage of Kerberos you have to set up your machine with keytab from your Active Directory. ++ To configure your stuff you could use <ulink url="http://www.samba.org/">Samba</ulink> or configure Kerberos directly (<filename>/etc/krb5.conf</>). <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 have to use <command>kinit</command> to initialize a ticket. ++ You could also configure Kerberos in PAM in order to initialize Kerberos ticket at login time.</para> + </sect1> ++ ++ <sect1 id="uothread"> ++ <title>Threading in unixODBC</title> + +- <sect1 id="uothread"> +- <title>Threading on unixODBC</title> +- <para><productname>unixODBC</> use strong thread locking policy. This cause big locks using default configurations for &freetds; which lead to performance issues using multi-thread applications (every single operation get serialized). In order to avoid this problem you have to set up threading model on <filename>odbcinst.ini</> (this configuration is supported only in this file). +-<example id="odbcinstthread"><title>Sample <filename>odbcinst.ini</> for threading model</title> ++<para><productname>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</>. ++ <example id="odbcinstthread"> ++ <title>Sample <filename>odbcinst.ini</> for threading model</title> + <programlisting> +-[FreeTDS] ++ [FreeTDS] + Driver = /usr/local/freetds/lib/libtdsodbc.so + Threading = 1 +-</programlisting> +-</example> +-<example id="odbcinithread"><title>Sample <filename>odbc.ini</> for threading model</title> ++ </programlisting> ++ </example> ++ <example id="odbcinithread"> ++ <title>Sample <filename>odbc.ini</> for threading model</title> + <programlisting> +-[Server1] ++ [Server1] + Driver = FreeTDS + Server = myServer1 + Port = 1433 + TDS_Version = 7.2 +-</programlisting> +-</example> +-You can use also a connection string like <literal>DRIVER=FreeTDS;SERVER=myServer1;PORT=1433;TDS_Version=7.2;</>. +- </para> ++ </programlisting> ++ </example> ++ You can use also a connection string e.g. <literal>DRIVER=FreeTDS;SERVER=myServer1;PORT=1433;TDS_Version=7.2;</>.</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 ++ tds version = 7.0 ++ dump file = /tmp/freetds.log ++ dump file append = yes ++ </programlisting> ++ </example> + +- <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 +- tds version = 7.0 +- dump file = /tmp/freetds.log +- dump file append = yes +-</programlisting> +-</example> +-<para> +-In this example, the <filename>/tmp/freetds.log</filename> file will contain log entries for all processes using the Microsoft <productname>SQL Server</productname> server, identified by pid. +-</para> +-<Important><para> +-Because there will be one log file being opened and closed more or less continuously, there is going to be a negative impact on performance. Also, be advised that the log file will grow quite large. ++<para>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 <application>tcpdump</application> or <application>ethereal</application> to log network packets. While not as useful as a <acronym>TDS</> log, it can also help to identify problems. +-</para> +- + ++<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</> log, it can also help to identify problems.</para> ++ + </sect1> +- <sect1 id="tdspool"> ++ <sect1 id="tdspool"> + <title>TDS Connection Pooling</title> +- <para> +-&freetds; 0.52 was the first to include a <acronym>TDS</> Connection Pooling server. It lives in the <filename>src/pool</filename> directory. +- </para> +- <para> +-The &freetds; connection pool is a server process, it acts just like a <productname>SQL Server</productname>. You can use any program to attach to it that you could use to attach to a real <productname>SQL Server</productname>. The pool in turn connects to the <productname>SQL Server</productname> and database you specify, and attempts to share these connections. See the <filename>README</filename> in the pool directory for a more detailed description of its inner workings. +- </para> +- <para> +-To configure the pooling server, first make sure &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 only supports <acronym>TDS</> version 4.2. <emphasis>This restriction applies to both the client-to-pool and pool-to-server connections!</emphasis> ++ ++<para>&freetds; 0.52 was the first to include a <acronym>TDS</> Connection Pooling server. It lives in the <filename>src/pool</filename> directory.</para> ++ ++<para>The &freetds; connection pool is a server process, it acts just like a <productname>SQL Server</productname>. You can use any program to attach to it that you could use to attach to a real <productname>SQL Server</productname>. The pool in turn connects to the <productname>SQL Server</productname> and database you specify, and attempts to share these connections. See the <filename>README</filename> in the pool directory for a more detailed description of its inner workings.</para> ++ ++<para>To configure the pooling server, first make sure &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 only supports <acronym>TDS</> version 4.2. <emphasis>This restriction applies to both the client-to-pool and pool-to-server connections!</emphasis> + </para></Note> +- <para> +-After FreeTDS has been installed, you will find an executable named <command>tdspool</command> in the <filename>/usr/local/bin</filename> directory (or whatever directory was specified with the <command>configure</> <option>--with-prefix flag</> option). +- </para> +- <para> +-Next, edit the <filename>pool.conf</filename> file in the &freetds;'s <filename>etc</filename> directory. The <filename>pool.conf</filename> file is formatted like the &freetdsconf; with a section name in brackets and options for each section in key/value pairs. +- </para> +- <para> +-Just like the &freetdsconf; file there are two types of sections, a <literal>[global]</literal> section whose options affect all pools, and a section with the name of the pool for pool-specific options. The following options are supported and may appear in either section. +- </para> +- <para> +- +-<table id="tab.pool.conf"> +-<title>pool.conf settings</title> +-<tgroup cols="4"> +-<thead> +- <row> +- <entry>Name</entry> +- <entry>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 servername.</entry> +- </row> +- <row> +- <entry>password</entry> +- <entry>Any</entry> +- <entry>none</entry> +- <entry>The password of the user at the servername.</entry> +- </row> +- <row> +- <entry>server</entry> +- <entry>Any <emphasis>TDS 4.2</emphasis> 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>1 or more</entry> +- <entry>none</entry> +- <entry>Minimum number of open connections to maintain to the servername.</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> ++ ++<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</> <option>--with-prefix flag</> option).</para> ++ ++<para>Next, edit the <filename>pool.conf</filename> file in the &freetds;'s <filename>etc</filename> directory. The <filename>pool.conf</filename> file is formatted like the &freetdsconf; with a section name in brackets and options for each section in key/value pairs.</para> ++ ++<para>Just like the &freetdsconf; file there are two types of sections, a <literal>[global]</literal> section whose options affect all pools, and a section with the name of the pool for pool-specific options. The following options are supported and may appear in either section.</para> ++ ++<para><table id="tab.pool.conf"> ++ <title>pool.conf settings</title> ++ <tgroup cols="4"> ++ <thead> ++ <row> ++ <entry>Name</entry> ++ <entry>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 servername.</entry> ++ </row> ++ <row> ++ <entry>password</entry> ++ <entry>Any</entry> ++ <entry>none</entry> ++ <entry>The password of the user at the servername.</entry> ++ </row> ++ <row> ++ <entry>server</entry> ++ <entry>Any <emphasis>TDS 4.2</emphasis> 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>1 or more</entry> ++ <entry>none</entry> ++ <entry>Minimum number of open connections to maintain to the servername.</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] ++ [global] + min pool conn = 5 + max pool conn = 10 + max member age = 120 +- +-[mypool] ++ ++ [mypool] + user = webuser + password = secret + database = ebiz + server = fooserv + max pool conn = 7 + port = 5000 +-</programlisting> +-</example> +-The <literal>[global]</literal> section defines that we will open 5 connections against the server initially, and will increase up to 10 as demand requires. These connections will be closed after being idle for 2 minutes (120 seconds), but only until there are 5 remaining open. +- </para> +- <para> +-The <literal>[mypool]</literal> section defines a pool named <literal>mypool</literal> that will listen on port 5000. It will login to a <productname>SQL Server</productname> named <literal>fooserv</literal> using the user <literal>webuser</literal> and the ever so clever password of <literal>secret</literal>. Once logged in, the connections will use the database <literal>ebiz</literal> instead of webuser's default database. Also, since this <productname>SQL Server</productname> has a limited number of <acronym>CAL</>s (Client Access Licenses), we are restricting the maximum number of connections to 7, which overrides the <literal>global</literal> setting of 10. +- </para> +- <para> +-Now you can run <Command>tdspool</Command> with the name of the pool you are serving. ++ </programlisting> ++ </example> ++ The <literal>[global]</literal> section defines that we will open 5 connections against the server initially, and will increase up to 10 as demand requires. These connections will be closed after being idle for 2 minutes (120 seconds), but only until there are 5 remaining open.</para> ++ ++<para>The <literal>[mypool]</literal> section defines a pool named <literal>mypool</literal> that will listen on port 5000. It will login to a <productname>SQL Server</productname> named <literal>fooserv</literal> using the user <literal>webuser</literal> and the ever so clever password of <literal>secret</literal>. Once logged in, the connections will use the database <literal>ebiz</literal> instead of webuser's default database. Also, since this <productname>SQL Server</productname> has a limited number of <acronym>CAL</>s (Client Access Licenses), we are restricting the maximum number of connections to 7, which overrides the <literal>global</literal> setting of 10.</para> ++ ++<para>Now you can run <Command>tdspool</Command> with the name of the pool you are serving. + <screen> +-<prompt>$ </prompt><userinput> tdspool mypool</userinput> +-</screen> +- </para> +- <para> +-Before your clients connect to the pool, you must edit your &freetdsconf; to include the host and port of the pooling server, and point your clients at it. +- </para> ++ <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> ++ ++ <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> ++ ++<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> ++ [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 ++ [win2kserver] ++ host = localhost + port = 1433 +-</programlisting> +-</example> ++ </programlisting> ++ </example> + </listitem> +- </orderedlist> ++ </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> ++<!-- ////////////////// 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</> + +- <sect1 id="utilities"><title>&freetds; Utilities</> +- + <variablelist><title>(listed alphabetically)</title> +- <varlistentry> +- <term>bsqldb</term> +- <listitem> +- <para> A non-interactive equivalent of the <symbol>isql</> utility programs distributed by Sybase and Microsoft. Like them, <command>bsqldb</> uses the command <quote>go</> on a line by itself as a separator between batches. The last batch need not be followed by <quote>go</>.</para> ++ <varlistentry> ++ <term>bsqldb</term> ++ <listitem> + +- <para><command>bsqldb</> makes use of the <symbol>db-lib</> <acronym>API</>. Intended for production use. </para> +- </listitem> +- </varlistentry> +- <varlistentry> +- <term>bsqlodbc</term> +- <listitem> +- <para>A non-interactive equivalent of the <symbol>isql</> utility programs distributed by Sybase and Microsoft. Like them, <command>bsqlodbc</> uses the command <quote>go</> on a line by itself as a separator between batches. The last batch need not be followed by <quote>go</>. It uses the <acronym>ODBC</> <acronym>API</>. </para> ++<para> A non-interactive equivalent of the <symbol>isql</> utility programs distributed by Sybase and Microsoft. Like them, <command>bsqldb</> uses the command <quote>go</> on a line by itself as a separator between batches. The last batch need not be followed by <quote>go</>.</para> ++ + +- <para><command>bsqlodbc</> is a demonstration project, but can also aid in isolating problems. <acronym>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</>, you can see if the functionality of the <acronym>ODBC</> driver works when used as the folks who wrote the driver thought it would be used. </para> +- </listitem> +- </varlistentry> ++<para><command>bsqldb</> makes use of the <symbol>db-lib</> <acronym>API</>. Intended for production use.</para> ++ </listitem> ++ </varlistentry> ++ <varlistentry> ++ <term>bsqlodbc</term> ++ <listitem> ++ ++<para>A non-interactive equivalent of the <symbol>isql</> utility programs distributed by Sybase and Microsoft. Like them, <command>bsqlodbc</> uses the command <quote>go</> on a line by itself as a separator between batches. The last batch need not be followed by <quote>go</>. It uses the <acronym>ODBC</> <acronym>API</>.</para> ++ + ++<para><command>bsqlodbc</> is a demonstration project, but can also aid in isolating problems. <acronym>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</>, you can see if the functionality of the <acronym>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 SQL Server or vice versa.</para> ++ + +- <varlistentry> +- <term>datacopy</term> +- <listitem> +- <para>A tool for migrating data between Sybase ASE and SQL Server or vice versa.</para> ++<para><command>datacopy</> will move table data from one server to another without the need for intermediate files. <command>datacopy</> is much faster and more efficient than is <command>freebcp</> out/in.</para> + +- <para><command>datacopy</> will move table data from one server to another without the need for intermediate files. <command>datacopy</> is much faster and more efficient than is <command>freebcp</> out/in.</para> + <para><command>datacopy</> makes use of the <symbol>db-lib</> bcp <acronym>API</>.</para> +- </listitem> +- </varlistentry> +- +- <varlistentry> +- <term>defncopy</term> +- <listitem> +- <para>Replaces a similar program of the same name distributed by Sybase.</para> +- +- <para><command>defncopy</> 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</> and constructs a <literal>CREATE TABLE</> statement, complete with <literal>CREATE INDEX</>, too. </para> +- </listitem> +- </varlistentry> +- +- <varlistentry> +- <term>fisql</term> +- <listitem> +- <para>A complete replacement of the <symbol>isql</> utility programs distributed by Sybase and Microsoft. Like them, <command>fisql</> uses the command <quote>go</> 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</> utility programs distributed by Sybase and Microsoft.</para> +- <para><command>freebcp</> makes use of the <symbol>db-lib</> bcp <acronym>API</>. </para> +- <para>The manual pages or online help for Sybase or 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 <productname>FreeTDS</> library, <symbol>libtds</>, as a way to isolate potential bugs in the protocol implementation. </para> +- <para><command>tsql</> is <emphasis>not</> a replacement for a complete <symbol>isql</>. </para> +- </listitem> +- </varlistentry> +- </variablelist> +- </sect1> +- </chapter> ++ </listitem> ++ </varlistentry> ++ ++ <varlistentry> ++ <term>defncopy</term> ++ <listitem> + ++<para>Replaces a similar program of the same name distributed by Sybase.</para> ++ + ++<para><command>defncopy</> 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</> and constructs a <literal>CREATE TABLE</> statement, complete with <literal>CREATE INDEX</>, too.</para> ++ </listitem> ++ </varlistentry> ++ ++ <varlistentry> ++ <term>fisql</term> ++ <listitem> + ++<para>A complete replacement of the <symbol>isql</> utility programs distributed by Sybase and Microsoft. Like them, <command>fisql</> uses the command <quote>go</> 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</> utility programs distributed by Sybase and Microsoft.</para> + +- <!-- ////////////////// 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</> 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. ++<para><command>freebcp</> makes use of the <symbol>db-lib</> bcp <acronym>API</>.</para> + +- <tip><sidebar><para>That advice is so good, it bears repeating. If you are having trouble, grab <application>SQSH</application> and get that to work. Not only will it help isolate the problem, it will give you a very capable tool. </para></sidebar></tip> ++<para>The manual pages or online help for Sybase or SQL Server can be referenced for more detailed information on bcp functionality.</para> ++ </listitem> ++ </varlistentry> ++ ++ <varlistentry> ++ <term>osql</term> ++ <listitem> + +- </para> ++<para>A Bourne shell script that checks and reports on your configuration.</para> ++ </listitem> ++ </varlistentry> ++ ++ <varlistentry> ++ <term>tsql</term> ++ <listitem> + +- <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 Sybase environment variable first), look for the Sybase_LIBS definition in the Makefile. Change the line to match this example. +-<example id="e.g.SQSHmake"> +-<title>The <application>SQSH</application> Makefile</title> +-<programlisting> +-# +-# The following set of CT-LIB libraries were determined automatically +-# by 'configure'. For most systems configure looks up the required +-# libraries by looking at the name of the OS (although this doesn't +-# mean it got them right), however if the line below ends with the +-# word "Guess", then 'configure' didn't have an entry for your operating +-# system and it took a best guess to figure out which libraries you +-# need. In either case, there may be problems, so look this line over +-# and if it doesn't work, compare it to the libraries located in +-# $SYBASE/samples/ct-library. +-# +-# The listings below show suggested libraries for Operating Systems +-# that frequently fail to be recognized by 'configure': +-# +-# SCO: -lblk -lct -lcs -lcomn -ltcl -ltli -lnsl_s -lintl -m -lsocket +-# Dynix: -lblk -lct -lcs -lcomn -ltcl -ltli -lnsl -lintl -lm -lseq +-# +-SYBASE_LIBS = -lct -ldl -lm +-</programlisting> +-</example> +-At this point you can also enable <application>readline</application> support if you didn't specify it in the <application>configure</application> arguments. +- </para> +- <para> +-After that just type <command>make</command> and you are off and running. +- </para> ++<para>A diagnostic tool that uses uses the lowest level <productname>FreeTDS</> library, <symbol>libtds</>, as a way to isolate potential bugs in the protocol implementation.</para> ++ ++<para><command>tsql</> is <emphasis>not</> a replacement for a complete <symbol>isql</>.</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> + +- <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> ++<para><application>SQSH</application> is a command line based query tool written by Scott Gray to replace the <command>isql</> utility that ships with <productname>Sybase ASE</productname>. It makes a great diagnostic tool for &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 — and with significant effort — it could be ported to ODBC and thus made useful for other server environments. Just a thought….</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.Sybase"><title>DBD::Sybase</title> +- <para>The recommended choice is <systemitem class="library">DBD::Sybase</systemitem> from Michael Peppler. Despite the name it works for any Sybase or Microsoft <productname>SQL Server</productname>. <systemitem class="library">DBD::Sybase</systemitem> uses the <systemitem class="library">ct-lib</systemitem> <acronym>API</> and works well. </para> +- </sect2> +- ++ ++<para>The recommended choice is <systemitem class="library">DBD::Sybase</systemitem> from Michael Peppler. Despite the name it works for any Sybase or Microsoft <productname>SQL Server</productname>. <systemitem class="library">DBD::Sybase</systemitem> uses the &ctlib; <acronym>API</> and works well.</para> ++ </sect2> ++ + <sect2 id="DBD.ODBC"><title>DBD::ODBC</title> +- <para> +-You may also use <systemitem class="library">DBD::ODBC</systemitem> with the &freetds; <systemitem class="library">ODBC</systemitem> driver. You may find this attractive if you're familiar with <systemitem class="library">DBD::ODBC</systemitem>. +- </para> +- </sect2> ++ ++<para>You may also use <systemitem class="library">DBD::ODBC</systemitem> with the &freetds; <systemitem class="library">ODBC</systemitem> driver. You may find this attractive if you're familiar with <systemitem class="library">DBD::ODBC</systemitem>.</para> ++ </sect2> + <sect2 id="Sybperl"><title>Sybperl</title> +- <para> +-Finally, you can use <systemitem class="library">Sybperl</systemitem>. Scripts written against <systemitem class="library">Sybperl</systemitem> will not run against other databases the way DBI scripts will. However, it will be familiar ground for those who know <systemitem class="library">db-lib</systemitem>. +- </para> +- </sect2> ++ ++<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.Sybase.build"> +- <title>Building <systemitem class="library">DBD::Sybase</systemitem></title> +-<screen> +-<prompt>$ </prompt><userinput>cd DBD-Sybase-0.91</userinput> +-<prompt>$ </prompt><userinput>export SYBASE=/usr/local/freetds</userinput> +-<prompt>$ </prompt><userinput>perl Makefile.PL</userinput> +-<prompt>$ </prompt><userinput>make</userinput> +-<prompt>$ </prompt><userinput>su root</userinput> +-<prompt>Password: </prompt> +-<prompt>$ </prompt><userinput>make install</userinput> +-</screen> +-</example> + +-There will be some output about missing libraries after <userinput>perl Makefile.PL</userinput>. These are normal. +- </para> +- <para> +-The following example will attach to Sybase's public <acronym>JDBC</> server and run a simple query (it can be found in <filename>samples/test.pl</filename>): ++<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> + +-<example id="e.g.DBD.Sybase.Connect"><title>Connect to a server with <systemitem class="library">DBD::Sybase</systemitem></title> ++<para>The following example will attach to Sybase's public <acronym>JDBC</> server and run a simple query (it can be found in <filename>samples/test.pl</filename>): ++ ++ <example id="e.g.DBD.Sybase.Connect"><title>Connect to a server with <systemitem class="library">DBD::Sybase</systemitem></title> + <programlisting> +-#!/usr/local/bin/perl +-# +-use DBI; +- +-my $dbh = DBI->connect("dbi:Sybase:server=JDBC", 'guest', 'sybase', {PrintError => 0}); +- +-die "Unable for connect to server $DBI::errstr" +- unless $dbh; +- +-my $rc; +-my $sth; ++ #!/usr/local/bin/perl ++ # ++ use DBI; ++ ++ my $dbh = DBI->connect("dbi:Sybase:server=JDBC", 'guest', 'sybase', {PrintError => 0}); ++ ++ die "Unable for connect to server $DBI::errstr" ++ unless $dbh; ++ ++ my $rc; ++ my $sth; ++ ++ $sth = $dbh->prepare("select \@\@servername"); ++ if($sth->execute) { ++ while(@dat = $sth->fetchrow) { ++ print "@dat\n"; ++ } ++ } ++ </programlisting> ++ </example></para> + +-$sth = $dbh->prepare("select \@\@servername"); +-if($sth->execute) { +- while(@dat = $sth->fetchrow) { +- print "@dat\n"; +- } +-} +-</programlisting> +-</example> +- </para> +- <para> +-<example id="e.g.DBD.ODBC.build"> +- <title>Building <systemitem class="library">DBD::ODBC</systemitem></title> ++<para><example id="e.g.DBD.ODBC.build"> ++ <title>Building <systemitem class="library">DBD::ODBC</systemitem></title> + <screen> +-<prompt>$ </prompt><userinput>cd DBD-ODBC-0.28</userinput> +-<prompt>$ </prompt><userinput>export SYBASE=/usr/local/freetds</userinput> +-<prompt>$ </prompt><userinput>export ODBCHOME=/usr/local</userinput> +-<prompt>$ </prompt><userinput>export DBI_DSN=dbi:ODBC:JDBC</userinput> +-<prompt>$ </prompt><userinput>export DBI_USER=guest</userinput> +-<prompt>$ </prompt><userinput>export DBI_PASS=sybase</userinput> +-<prompt>$ </prompt><userinput>perl Makefile.PL</userinput> +-<prompt>$ </prompt><userinput>make</userinput> +-<prompt>$ </prompt><userinput>su root</userinput> +-<prompt>Password: </prompt> +-<prompt>$ </prompt><userinput>make install</userinput> +-</screen> +-</example> +-<note><para>We used the public <acronym>JDBC</> server logins for our configuration here. You'll want to replace these with ones suitable to your environment.</para></note> +- </para> +- <para> +-<example id="e.g.DBD.ODBC.connect"><title>Connect to a server with <systemitem class="library">DBD::ODBC</systemitem></title> ++ <prompt>$ </prompt><userinput>cd DBD-ODBC-0.28</userinput> ++ <prompt>$ </prompt><userinput>export SYBASE=/usr/local/freetds</userinput> ++ <prompt>$ </prompt><userinput>export ODBCHOME=/usr/local</userinput> ++ <prompt>$ </prompt><userinput>export DBI_DSN=dbi:ODBC:JDBC</userinput> ++ <prompt>$ </prompt><userinput>export DBI_USER=guest</userinput> ++ <prompt>$ </prompt><userinput>export DBI_PASS=sybase</userinput> ++ <prompt>$ </prompt><userinput>perl Makefile.PL</userinput> ++ <prompt>$ </prompt><userinput>make</userinput> ++ <prompt>$ </prompt><userinput>su root</userinput> ++ <prompt>Password: </prompt> ++ <prompt>$ </prompt><userinput>make install</userinput></screen> ++ </example> ++ <note><para>We used the public <acronym>JDBC</> server logins for our configuration here. You'll want to replace these with ones suitable to your environment.</para></note></para> ++ ++<para><example id="e.g.DBD.ODBC.connect"> ++ <title>Connect to a server with <systemitem class="library">DBD::ODBC</systemitem></title> + <programlisting> +-#!/usr/local/bin/perl +-# +-use DBI; ++ #!/usr/local/bin/perl ++ # ++ use DBI; ++ ++ my $dbh = DBI->connect("dbi:ODBC:JDBC", 'guest', 'sybase', {PrintError => 0}); ++ ++ die "Unable for connect to server $DBI::errstr" ++ unless $dbh; ++ ++ my $rc; ++ my $sth; ++ ++ $sth = $dbh->prepare("select \@\@servername"); ++ if($sth->execute) { ++ while(@dat = $sth->fetchrow) { ++ print "@dat\n"; ++ } ++ } ++ </programlisting> ++ </example> ++ You'll note this is the same program as for <systemitem class="library">DBD::Sybase</systemitem> with the exception of the <function>connect</function> statement, welcome to the magic of DBI!</para> ++ </sect2> ++ </sect1> ++ ++ <sect1 id="php"> ++ <title>PHP</title> + +-my $dbh = DBI->connect("dbi:ODBC:JDBC", 'guest', 'sybase', {PrintError => 0}); ++<para>There are three options for building PHP with support for &freetds; corresponding to the three <acronym>API</>s that &freetds; supports: &dblib;, &ctlib;, and <systemitem class="library">ODBC</systemitem>. ++ <note><para>All these examples build the CGI version. Consult <ulink url="http://www.php.net/docs.php">PHP's documentation</ulink> for building the Apache module and including other extensions.</para></note></para> ++ <sect2 id="phpDblib"> ++ <title>&dblib;</title> + +-die "Unable for connect to server $DBI::errstr" +- unless $dbh; ++<para>PHP can be configured with &dblib; access for a "Sybase" server (which also works with Microsoft servers), or with the <emphasis>mssql</> extension, intended exclusively for Microsoft servers.</para> + +-my $rc; +-my $sth; ++<para><example id="e.g.PHP.dblib"><title>PHP and &dblib; for <quote>Sybase</></title> + +-$sth = $dbh->prepare("select \@\@servername"); +-if($sth->execute) { +- while(@dat = $sth->fetchrow) { +- print "@dat\n"; +- } +-} +-</programlisting> +-</example> +-You'll note this is the same program as for <systemitem class="library">DBD::Sybase</systemitem> with the exception of the <function>connect</function> statement, welcome to the magic of DBI! +- </para> +- </sect2> +- </sect1> +- +- <sect1 id="php"> +- <title>PHP</title> +- <para> +-There are three options for building PHP with support for &freetds; corresponding to the three <acronym>API</>s that &freetds; supports: <systemitem class="library">db-lib</systemitem>, <systemitem class="library">ct-lib</systemitem>, and <systemitem class="library">ODBC</systemitem>. +-<note><para>All these examples build the CGI version. Consult <ulink url="http://www.php.net/docs.php">PHP's documentation</ulink> for building the Apache module and including other extensions.</para></note> +- </para> +- <sect2 id="phpDblib"> +- <title><systemitem class="library">db-lib</systemitem></title> +- <para> +-PHP can be configured with <systemitem class="library">db-lib</systemitem> access for a "Sybase" server (which also works with Microsoft servers), or with the <emphasis>mssql</> extension, intended exclusively for Microsoft servers. +- </para> +- <para> +-<example id="e.g.PHP.dblib"><title>PHP and <systemitem class="library">db-lib</systemitem> for <quote>Sybase</></title> +- <para>First build &freetds; normally.</para> ++<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> ++ <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> ++ <prompt>$ </prompt><userinput>cd php</userinput> ++ <prompt>$ </prompt><userinput>./configure --with-sybase=/usr/local/freetds</userinput> ++ <prompt>$ </prompt><userinput>make</userinput> ++ <prompt>$ </prompt><userinput>su root</userinput> ++ <prompt>Password: </prompt> ++ <prompt>$ </prompt><userinput>make install</userinput></screen> ++ ++<para>And that's it!</para> ++ </example></para> ++ </sect2> + <sect2 id="ctlib"> +- <title><systemitem class="library">ct-lib</systemitem></title> +- <para> +-Option 2 is to use the <systemitem class="library">ct-lib</systemitem> <acronym>API</>. Again here, we run into minor difficulties at build time. Applications linking with Sybase's OpenClient have to link in a handful of libraries and these libraries vary slightly from platform to platform. When creating &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 <systemitem class="library">db-lib</systemitem> in +-<link linkend="phpDblib"> with <systemitem class="library">db-lib</systemitem></link>, above. Then configure PHP with <systemitem class="library">ct-lib</systemitem>. +-<screen> +-<prompt>$ </prompt><userinput>cd php</userinput> +-<prompt>$ </prompt><userinput>./configure --with-sybase-ct=/usr/local/freetds</userinput> +-</screen> +-Now edit the <filename>Zend/Makefile</filename> looking for the <literal>libZend_la_LDFLAGS</literal> line and remove <literal>-lsybtcl -lintl -lcomn</literal> and <literal>-lcs</literal>, leaving the <literal>-lct</literal>. Then proceed to make and install PHP. ++ <title>&ctlib;</title> ++ ++<para>Option 2 is to use the &ctlib; <acronym>API</>. Again here, we run into minor difficulties at build time. Applications linking with Sybase's OpenClient have to link in a handful of libraries and these libraries vary slightly from platform to platform. When creating &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><systemitem class="library">ODBC</systemitem></title> +- <para> +-The third and newest option is to use the &freetds; <systemitem class="library">ODBC</systemitem> driver with PHP. First build the <productname>iODBC</productname> or <productname>unixODBC</productname> driver manager and &freetds; as detailed <link linkend="prepodbc">in this guide</link>. Then build PHP with support for ODBC. ++ <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><systemitem class="library">ODBC</systemitem></title> ++ ++<para>The third and newest option is to use the &freetds; <systemitem class="library">ODBC</systemitem> driver with PHP. First build the <productname>iODBC</productname> or <productname>unixODBC</productname> 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="SybSQL"> +- <title>SybSQL</title> +- <para> +-<productname>SybSQL</productname> is a <productname>Qt</productname>-based <acronym>GUI</> interface to <productname>Sybase</productname> databases that uses the <systemitem class="library">db-lib</systemitem> <acronym>API</>. +- </para> +- <para> +-<productname>SybSQL</productname> has a fairly basic build process that simply uses a Makefile. In order for <productname>SybSQL</productname> to find <productname>Qt</productname> and &freetds; you need to define <envar>QTDIR</envar> and <envar>SYBASE</envar> environment variables. If you have <productname>Qt</productname> installed, you may have <envar>QTDIR</envar> defined already. To verify, type <command>echo $QTDIR</command> at the shell prompt. This example uses my own installation path of <filename>qt-2.3.1</filename> (from RedHat 7.2), YMMV. ++ <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="SybSQL"> ++ <title>SybSQL</title> ++ ++<para><productname>SybSQL</productname> is a <productname>Qt</productname>-based <acronym>GUI</> interface to <productname>Sybase</productname> databases that uses the &dblib; <acronym>API</>.</para> ++ ++<para><productname>SybSQL</productname> has a fairly basic build process that simply uses a Makefile. In order for <productname>SybSQL</productname> to find <productname>Qt</productname> and &freetds; you need to define <envar>QTDIR</envar> and <envar>SYBASE</envar> environment variables. If you have <productname>Qt</productname> installed, you may have <envar>QTDIR</envar> defined already. To verify, type <command>echo $QTDIR</command> at the shell prompt. This example uses my own installation path of <filename>qt-2.3.1</filename> (from RedHat 7.2), YMMV. + <screen> +-<prompt>$ </prompt><userinput>export QTDIR=/usr/lib/qt-2.3.1</userinput> +-<prompt>$ </prompt><userinput>export SYBASE=/usr/local</userinput> +-<prompt>$ </prompt><userinput>make</userinput> +-</screen> +-When finished you'll have an executable named <filename>sybsql</filename> that you can run. +- </para> +- <para> +-One caveat to the way in which <productname>SybSQL</productname> and &freetds; interact is that <productname>SybSQL</productname> expects to be running under <productname>OpenClient</productname>, and makes the assumption that a valid <envar>$SYBASE</envar><filename>/interfaces</filename> file exists. Since &freetds; has deprecated use of the <filename>interfaces</filename> file in favor of the &freetdsconf; config file, you may have to create a <filename>interfaces</> file just to satisfy <productname>SybSQL</productname>. +- </para> +- <para> +-By defining <envar>SYBASE</envar> to the parent directory of the <filename>interfaces</filename> file, you may put it wherever you like; it does not have to be in <filename>/usr/local</filename>. When using &freetdsconf;, &freetds; does not rely on the <envar>SYBASE</envar> variable for finding its own components, so it is safe to point it elsewhere. +- </para> ++ <prompt>$ </prompt><userinput>export QTDIR=/usr/lib/qt-2.3.1</userinput> ++ <prompt>$ </prompt><userinput>export SYBASE=/usr/local</userinput> ++ <prompt>$ </prompt><userinput>make</userinput></screen> ++ When finished you'll have an executable named <filename>sybsql</filename> that you can run.</para> ++ ++<para>One caveat to the way in which <productname>SybSQL</productname> and &freetds; interact is that <productname>SybSQL</productname> expects to be running under <productname>OpenClient</productname>, and makes the assumption that a valid <envar>$SYBASE</envar><filename>/interfaces</filename> file exists. Since &freetds; has deprecated use of the <filename>interfaces</filename> file in favor of the &freetdsconf; config file, you may have to create a <filename>interfaces</> file just to satisfy <productname>SybSQL</productname>.</para> ++ ++<para>By defining <envar>SYBASE</envar> to the parent directory of the <filename>interfaces</filename> file, you may put it wherever you like; it does not have to be in <filename>/usr/local</filename>. When using &freetdsconf;, &freetds; does not rely on the <envar>SYBASE</envar> variable for finding its own components, so it is safe to point it elsewhere.</para> + </sect1> +- <sect1 id="Python"> +- <title>Python</title> +-<tip><para> +-Your humble author is not enlightened enough to use Python, and the information contained in this section is a little rough. Please contact the list for more assistance or (better yet) to improve these instructions. +- </para></tip> +- <para> +-Install <ulink url="http://www.python.org/sigs/distutils-sig/">distutils</ulink> if you haven't already. +-<screen> +-<prompt>$ </prompt><userinput>tar xvfz distutils-latest.tgz</userinput> +-<prompt>$ </prompt><userinput>cd distutils</userinput> +-<prompt>$ </prompt><userinput>python setup.py install</userinput> +-</screen> +- </para> +- <para> +-You can obtain the <productname>Python</productname> Sybase module <ulink url="http://object-craft.com.au/projects/sybase/download.html">here</ulink>. This example uses version 0.34, the most current at the time of this writing, please adjust accordingly if using a different version. ++ <sect1 id="Python"> ++ <title>Python</title> ++ <tip><para>Your humble author is not enlightened enough to use Python, and the information contained in this section is a little rough. Please contact the list for more assistance or (better yet) to improve these instructions. ++</para></tip> ++ ++<para>Install <ulink url="http://www.python.org/sigs/distutils-sig/">distutils</ulink> if you haven't already. + <screen> +-<prompt>$ </prompt><userinput>tar xvfz sybase-0.34.tgz</userinput> +-<prompt>$ </prompt><userinput>cd sybase-0.34</userinput> +-<prompt>$ </prompt><userinput>export SYBASE=/usr/local/freetds</userinput> +-<prompt>$ </prompt><userinput>export CFLAGS="-DHAVE_FREETDS"</userinput> +-<prompt>$ </prompt><userinput>export LD_LIBRARY_PATH=/usr/local/freetds/lib:${LD_LIBRARY_PATH}</userinput> +-<prompt>$ </prompt><userinput>python setup.py install</userinput> +-</screen> +-Edit the example.py and fix the bottom stuff, FreeTDS lacks the 110 +-symbols for version use 100 ++ <prompt>$ </prompt><userinput>tar xvfz distutils-latest.tgz</userinput> ++ <prompt>$ </prompt><userinput>cd distutils</userinput> ++ <prompt>$ </prompt><userinput>python setup.py install</userinput></screen></para> ++ ++<para>You can obtain the <productname>Python</productname> Sybase module <ulink url="http://object-craft.com.au/projects/sybase/download.html">here</ulink>. This example uses version 0.34, the most current at the time of this writing, please adjust accordingly if using a different version. ++ <screen> ++ <prompt>$ </prompt><userinput>tar xvfz sybase-0.34.tgz</userinput> ++ <prompt>$ </prompt><userinput>cd sybase-0.34</userinput> ++ <prompt>$ </prompt><userinput>export SYBASE=/usr/local/freetds</userinput> ++ <prompt>$ </prompt><userinput>export CFLAGS="-DHAVE_FREETDS"</userinput> ++ <prompt>$ </prompt><userinput>export LD_LIBRARY_PATH=/usr/local/freetds/lib:${LD_LIBRARY_PATH}</userinput> ++ <prompt>$ </prompt><userinput>python setup.py install</userinput></screen> ++ Edit the example.py and fix the bottom stuff, FreeTDS lacks the 110 ++ symbols for version use 100 + <screen> +-<prompt>$ </prompt><userinput>python example.py</userinput> +-</screen> +- </para> +- </sect1> ++ <prompt>$ </prompt><userinput>python example.py</userinput></screen></para> ++ </sect1> ++ ++ <sect1 id="qt"> ++ <title>Qt</title> + +- <sect1 id="qt"> +- <title>Qt</title> +- <para><productname>Qt</> has two driver to access SQL Server databases: QTDS and QODBC. +- At the time of writing (January 2010) QTDS has a performance problem cause it does not reuse connection but do a connection for every query so use QODBC. +- </para> +- <para>There are however some problems with wide character support on Qt. Qt assume sizeof(SQLWCHAR) == 2 however using some DM (like <productname>iODBC</> using Linux which is the default setting on <productname>Ubuntu</>) which could lead to wrong characters conversion. +- </para> ++<para><productname>Qt</> has two drivers to access SQL Server databases: QTDS and QODBC. ++ At the time of writing (January 2010) QTDS has a performance problem because rather than maintaining a connection, it instead re-connects for every query. So use QODBC.</para> ++ ++<para>There are however some problems with wide character support on Qt because Qt assumes sizeof(SQLWCHAR) == 2. On some DMs, though — including <productname>iODBC</>, the default on <productname>Ubuntu</> — sizeof(SQLWCHAR) == 4, which could lead to invalid character conversion.</para> + </sect1> ++ ++ <sect1 id="uodbc"> ++ <title>ODBC on Unix</title> + +- <sect1 id="uodbc"> +- <title>ODBC on Unix</title> +- <para><productname>ODBC</> have many issues under Unix mainly due to lack of specifications. +- </para> +- <sect2 id="uodbc64"> +- <title>ODBC and 64-bit</title> +- <para>On first specifications ODBC was only 32-bit. Converting it to 64-bit there was not good specification which leads to wrong declarations and problems. For instance some SQLINTEGER are used for pointer offsets specification but SQLINTEGER was 32-bit while pointer offsets must be 64-bit. Also row numbers and other stuffs are now 64-bit. +- </para> +- <para>If you use <productname>unixODBC</> I would recommend at least version 2.2.14. Former versions have issues if used on 64-bit environments.</para> ++<para><productname>ODBC</> have many issues under Unix mainly due to lack of specifications.</para> ++ <sect2 id="uodbc64"> ++ <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-bity quantities are now 64-bit.</para> ++ ++<para>If you use <productname>unixODBC</> Frediano would recommend at least version 2.2.14. Earlier versions have issues if used on 64-bit environments.</para> + </sect2> +- <sect2 id="uodbcwchar"> +- <title>sizeof(SQLWCHAR)</title> +- <para>Under Windows you have sizeof(wchar_t) == sizeof(SQLWCHAR) == 2 but on many Unix systems you have sizeof(wchar_t) == 4. The problem is that some DM decided to keep sizeof(SQLWCHAR) == 2 (like <productname>unixODBC</>) while in other DM sizeof(SQLWCHAR) == sizeof(wchar_t) == 4 (like <productname>iODBC</>). This leads to ABI imcompatibility between applications and drivers. If you compile &freetds; ODBC driver using <productname>iODBC</> on such systems (like Linux) do not use the driver using <productname>unixODBC</> and viceversa. +- </para> +- <para>You can compile &freetds; with both includes and rename the library to use two ABI (for instance having a <filename>libtdsiodbc.so</> and a <filename>libtdsuodbc.so</>). +- </para> +- <para>As the time of writing <productname>Ubuntu</> compiled Qt using <productname>iODBC</> but mostly packages use <productname>unixODBC</>. If you plan to use Qt using &freetds; ODBC driver you should have a <productname>iODBC</> compatible driver. Also QODBC Qt driver have problems with <productname>iODBC</> and SQLWCHAR (see <link linkend="qt">Qt</link>). Due to these problems I would suggest to not use this configuration (Qt database) on <productname>Ubuntu</>. +- </para> ++ <sect2 id="uodbcwchar"> ++ <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 <productname>unixODBC</>) while in other DM <literal>sizeof(SQLWCHAR) == sizeof(wchar_t) == 4</literal> (namely <productname>iODBC</>). This leads to incompatibile ABIs between applications and drivers. If you compile the &freetds; ODBC driver using <productname>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</> and a <filename>libtdsuodbc.so</>).</para> ++ ++<para>As of the time of writing <productname>Ubuntu</> compiled Qt using <productname>iODBC</> but most packages use <productname>unixODBC</>. If you plan to use Qt with the &freetds; ODBC driver, you should have an <productname>iODBC</>-compatible driver. Also be aware that the QODBC Qt driver has problems with <productname>iODBC</> and <literal>SQLWCHAR</literal> (see <link linkend="qt">Qt</link>). Due to these problems Frediano suggests not to use this configuration (Qt database) on <productname>Ubuntu</> at this time.</para> + </sect2> +- <sect2 id="uodbcchar"> +- <title>Default charset</title> +- <para>Is not possible to specify charset under ODBC and there was not so clear specifications. For this reason by default many DM converting from multi-byte to wide characters assume ISO8859-1 charset. For this reason even &freetds; driver assume ISO8859-1 by default. Also some DM have problems converting multi-byte encodings (like UTF-8) assuming a byte get converted to a single wide character (and viceversa). This can create problems if you use multi-byte encoding for &freetds; driver. +- </para> ++ <sect2 id="uodbcchar"> ++ <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> ++<!-- ////////////////// CHAPTER /////////////////////// --> ++<chapter id="troubleshooting"> ++ <title>Troubleshooting</title> ++ <epigraph> ++ <attribution>Jason Mewes (Mall Rats)</attribution> ++ + <para>He's like motherf**king McGuiver, no he's better than McGuiver!</para> +-</epigraph> +- <sect1 id="knownissues"> +- <title>Known Issues</title> +- <sect2 id="Textfields"> +- <title><type>Text</type> Fields</title> +- <para> +-Questions sometimes arise over large <type>varchar</type> types (anything larger than <type>varchar(255)</type>) that became available with Microsoft <productname>SQL Server 7.0</productname>. When accessing long <type>varchar</type>s with <acronym>TDS</> protocol version 4.2 or 5.0, these fields will be truncated to 255 characters, due to limitations inherent in the protocol definition. Your best bet in that case is to convert them to <type>text</type> types. +- </para> +- <para> +-In Microsoft <productname>SQL Server</productname> 7.0 and later, <structname>varchar</structname> types can hold up to 8000 bytes (8000 <acronym>ASCII</> characters or 4000 Unicode characters). To move these large <structname>varchar</structname>s through <acronym>TDS</> 4.2, convert them with either a <command>CONVERT</command> as in, +-<screen> +-<userinput>SELECT mycol = convert(mycol, text) FROM mytable</userinput> </screen> +-or with the newer SQL92 <command>CAST</command> syntax e.g., +-<screen> +-<userinput>SELECT CAST(mycol as TEXT) FROM mytable</userinput></screen> +- </para> +- <para> +-A related problem is that some people have reported problems with <type>text</type> field using <acronym>TDS</> version 7.0. One known workaround is to convert long strings to <type>varchar(8000)</type> in your query text with <command>CAST( <parameter>variable_name</parameter> as <type>varchar</type>(8000) ) as <parameter>variable_name</parameter></command>. Text datatype handling is fixed in &freetds; 0.60, except for bcp operations. +- </para> +- <para> +-There is also a bug (<quote>Lions and tigers and bugs! Oh, my!</quote>) in Microsoft's implementation of <type>text</type> fields. Disregardless [sic] of their documentation, you must explicitly set the value of <envar>TEXTSIZE</envar>, else the text fields will be represented to have a maximum size of 4 gigabytes or so. The usual manifestation is some sort of spurious <quote>out of memory</quote> error or segment fault. To avoid this, set <envar>TEXTSIZE</envar> to some reasonable value before querying any <type>TEXT</type> fields. For example, in <application>isql</application>: ++ </epigraph> ++ <sect1 id="knownissues"> ++ <title>Known Issues</title> ++ <sect2 id="Textfields"> ++ <title><type>Text</type> Fields</title> ++ ++<para>Questions sometimes arise over large <type>varchar</type> types (anything larger than <type>varchar(255)</type>) that became available with Microsoft <productname>SQL Server 7.0</productname>. When accessing long <type>varchar</type>s with <acronym>TDS</> protocol version 4.2 or 5.0, these fields will be truncated to 255 characters, due to limitations inherent in the protocol definition. Your best bet in that case is to convert them to <type>text</type> types.</para> ++ ++<para>In Microsoft <productname>SQL Server</productname> 7.0 and later, <structname>varchar</structname> types can hold up to 8000 bytes (8000 <acronym>ASCII</> characters or 4000 Unicode characters). To move these large <structname>varchar</structname>s through <acronym>TDS</> 4.2, convert them with either a <command>CONVERT</command> as in, ++ <screen> ++ <userinput>SELECT mycol = convert(mycol, text) FROM mytable</userinput> </screen> ++ or with the newer SQL92 <command>CAST</command> syntax e.g., + <screen> +-<prompt>1></prompt><userinput>set <envar>TEXTSIZE</envar> 10000</userinput> +-<prompt>2></prompt><userinput>go</userinput> +-</screen> ++ <userinput>SELECT CAST(mycol as TEXT) FROM mytable</userinput></screen></para> + +-Another way to handle control the default <envar>TEXTSIZE</envar> is to use the setting in <link linkend="freetdsconfformat">&freetdsconf;</link>. +- </para> ++<para>A related problem is that some people have reported problems with <type>text</type> field using <acronym>TDS</> version 7.0. One known workaround is to convert long strings to <type>varchar(8000)</type> in your query text with <command>CAST( <parameter>variable_name</parameter> as <type>varchar</type>(8000) ) as <parameter>variable_name</parameter></command>. Text datatype handling is fixed in &freetds; 0.60, except for bcp operations.</para> ++ ++<para>There is also a bug (<quote>Lions and tigers and bugs! Oh, my!</quote>) in Microsoft's implementation of <type>text</type> fields. Disregardless [sic] of their documentation, you must explicitly set the value of <envar>TEXTSIZE</envar>, else the text fields will be represented to have a maximum size of 4 gigabytes or so. The usual manifestation is some sort of spurious <quote>out of memory</quote> error or segment fault. To avoid this, set <envar>TEXTSIZE</envar> to some reasonable value before querying any <type>TEXT</type> fields. For example, in <application>isql</application>: ++<screen> ++ <prompt>1></prompt><userinput>set <envar>TEXTSIZE</envar> 10000</userinput> ++ <prompt>2></prompt><userinput>go</userinput></screen> ++ ++ Another way to handle control the default <envar>TEXTSIZE</envar> is to use the setting in <link linkend="freetdsconfformat">&freetdsconf;</link>.</para> + </sect2> + <sect2 id="Endianism"> +- <title>Endianism</title> +- <para> +-If either your server or your client is a big endian system, pay careful attention to all references to endianism anywhere near &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>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> ++ <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="IntegratedSecurity"> +- <title>Microsoft's <quote>Integrated Security</quote></title> +- <para> +-&freetds; may be unable to connect to the server. The error message that appears will be <computeroutput>"Login failed for user 'example'. Reason: Not associated with a trusted SQL Server connection"</computeroutput>. To solve this, turn on <productname>SQL Server</productname> authentication: +-</para> ++ <sect2 id="Datetime"> ++ <title><type>Datetime</type> and <type>Money</type></title> ++ ++<para>Big endian clients may experience difficulty with Microsoft servers. Some versions of <productname>SQL Server</productname> 7 did not handle these types on these machines correctly, according to the protocol. According to ++ <ulink url="http://support.microsoft.com/support/kb/articles/Q254/1/23.ASP"> http://support.microsoft.com/support/kb/articles/Q254/1/23.ASP</ulink> on the Microsoft support site, it's fixed as of service pack 3. Unfortunately, there's no direct way for &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 that appears will be <computeroutput>"Login failed for user 'example'. Reason: Not associated with a trusted SQL Server connection"</computeroutput>. To solve this, turn on <productname>SQL Server</productname> authentication:</para> + <ItemizedList> +- <listitem><para> +-Open the <emphasis><productname>SQL Server</productname> Enterprise Manager</emphasis>, +- </para></listitem> +- <listitem><para> +-Select the server, +- </para></listitem> +- <listitem><para> +-Right mouse click and choose <emphasis>Properties</emphasis>. A properties window will appear. +- </para></listitem> +- <listitem><para> +-Choose the <emphasis>Security</emphasis> tab. The security properties will be displayed. +- </para></listitem> +- <listitem><para> +-Change the <emphasis>Authentication</emphasis> field to <emphasis><productname>SQL Server</productname> and Windows</emphasis>, +- </para></listitem> +- <listitem><para> +-Apply the changes and try again. +- </para></listitem> +- </ItemizedList> +- <para> +-These instructions apply to Microsoft <productname>SQL Server 7</productname> and <productname>SQL Server 2000</productname>. +- </para> ++ <listitem><para>Open the <emphasis><productname>SQL Server</productname> Enterprise Manager</emphasis>, ++</para></listitem> ++ <listitem><para>Select the server, ++</para></listitem> ++ <listitem><para>Right mouse click and choose <emphasis>Properties</emphasis>. A properties window will appear. ++</para></listitem> ++ <listitem><para>Choose the <emphasis>Security</emphasis> tab. The security properties will be displayed. ++</para></listitem> ++ <listitem><para>Change the <emphasis>Authentication</emphasis> field to <emphasis><productname>SQL Server</productname> and Windows</emphasis>, ++</para></listitem> ++ <listitem><para>Apply the changes and try again. ++</para></listitem> ++ </ItemizedList> ++ ++<para>These instructions apply to Microsoft <productname>SQL Server 7</productname> and <productname>SQL Server 2000</productname>.</para> + <sect3 id="Background"> + <title><productname>SQL Server</productname>'s Security Model</title> +- <para> +-Microsoft supports two security models in three permutations: + +- <ItemizedList> +- <listitem><para><firstterm>Windows NT Authentication Mode</>. The operating system performs authentication; users will <emphasis>not</emphasis> have explicit <productname>SQL Server</productname> accounts. +- </para></listitem> +- <listitem><para><firstterm>Standard Mode</>. <productname>SQL Server</productname> authenticates connections itself without consulting the operating system. Users of course need <productname>SQL Server</productname> accounts to log in. +- </para></listitem> +- <listitem><para><firstterm>Mixed Mode</> Combines the above two. +- </para></listitem> +- </ItemizedList> +-For normal operation, you need either Standard or Mixed mode. +- </para> +- <para> +-<quote>Windows NT Authentication</quote>, often called <quote>integrated security</quote>, +-relies on Microsoft's <emphasis>domain login</emphasis>. In it, a user's network security attributes are established at network login time. When connecting to the database server, <productname>SQL +-Server</productname> uses the facilities of the host operating system (<productname>Windows NT </productname> or similar) to determine the authenticated network username. +-<productname>SQL Server</productname> then permits or denies login access based on that network +-username alone, without requiring a separate login name and password. +- </para> +-<Note><para> +-The &freetds; supports integrated security mode. If you have <productname>SQL Server</productname> running in integrated (domain) mode along with a Windows PDC, and wish to try it, see <link linkend="domains">Domain Logins</link> in the <link linkend="configs">Advanced Configurations</link> chapter. If you have Active Directory you can also use Kerberos, see <link linkend="kerberos">Kerberos support</link>. ++<para>Microsoft supports two security models in three permutations: ++ ++ <ItemizedList> ++ <listitem><para><firstterm>Windows NT Authentication Mode</>. The operating system performs authentication; users will <emphasis>not</emphasis> have explicit <productname>SQL Server</productname> accounts. ++</para></listitem> ++ <listitem><para><firstterm>Standard Mode</>. <productname>SQL Server</productname> authenticates connections itself without consulting the operating system. Users of course need <productname>SQL Server</productname> accounts to log in. ++</para></listitem> ++ <listitem><para><firstterm>Mixed Mode</> Combines the above two. ++</para></listitem> ++ </ItemizedList> ++ For normal operation, you need either Standard or Mixed mode.</para> ++ ++<para><quote>Windows NT Authentication</quote>, often called <quote>integrated security</quote>, ++ relies on Microsoft's <emphasis>domain login</emphasis>. In it, a user's network security attributes are established at network login time. When connecting to the database server, <productname>SQL ++ Server</productname> uses the facilities of the host operating system (<productname>Windows NT </productname> or similar) to determine the authenticated network username. ++ <productname>SQL Server</productname> then permits or denies login access based on that network ++ username alone, without requiring a separate login name and password.</para> ++ <Note><para>The &freetds; supports integrated security mode. If you have <productname>SQL Server</productname> running in integrated (domain) mode along with a Windows PDC, and wish to try it, see <link linkend="domains">Domain Logins</link> in the <link linkend="configs">Advanced Configurations</link> chapter. If you have Active Directory you can also use Kerberos, see <link linkend="kerberos">Kerberos support</link>. + </para></Note> +- <para> +-&freetds; supports the traditional database +-security model, which Microsoft terms <quote>SQL Server +-Authentication</quote> but is frequently known as <quote>standard +-security</quote>. Username+Password pairs have to be passed to the +-server explicitly. +- </para> +- <para> +-Mixed Mode allows users to connect using either authentication +-method. Users who connect through a <productname>Windows NT</productname> account can make use +-of trusted connections in either Windows NT Authentication Mode or +-Mixed Mode. After successful connection to <productname>SQL +-Server</productname>, the security mechanism is the same for both +-modes. +- </para> +- </sect3> ++ ++<para>&freetds; supports the traditional database ++ security model, which Microsoft terms <quote>SQL Server ++ Authentication</quote> but is frequently known as <quote>standard ++ security</quote>. Username+Password pairs have to be passed to the ++ server explicitly.</para> ++ ++<para>Mixed Mode allows users to connect using either authentication ++ method. Users who connect through a <productname>Windows NT</productname> account can make use ++ of trusted connections in either Windows NT Authentication Mode or ++ Mixed Mode. After successful connection to <productname>SQL ++ Server</productname>, the security mechanism is the same for both ++ modes.</para> ++ </sect3> + </sect2> + </sect1> +- <sect1 id="serverthere"> +- <title>Is the server there?</title> +- <sect2 id="serverthere.ping"> +- <title>Start with <command>ping</></title> +- <para> +-First <command>ping</> the host to make sure you can talk to the machine the server resides on. +- +-<example id="e.g.troubleshooting.ping"> +- <title>Finding the server's host</title> ++ <sect1 id="serverthere"> ++ <title>Is the server there?</title> ++ <sect2 id="serverthere.ping"> ++ <title>Start with <command>ping</></title> ++ ++<para>First <command>ping</> the host to make sure you can talk to the machine the server resides on. ++ ++ <example id="e.g.troubleshooting.ping"> ++ <title>Finding the server's host</title> + <screen> +-<prompt>$ </prompt><userinput>ping -c1 <replaceable>myhost</replaceable></userinput> +-<computeroutput> +-PING myhost (127.0.0.1) from 127.0.0.1 : 56(84) bytes of data. +-64 bytes from myhost (127.0.0.1): icmp_seq=0 ttl=255 time=250 usec +-</computeroutput> +-</screen> +-</example> +-A successful ping shows that your network isn't preventing you from reaching the machine hosting the server. +- </para> +- </sect2> +- <sect2 id="serverthere.telnet"> +- <title>Test with <command>telnet</></title> +- <para> +-Attempt to <command>telnet</> to the port, to verify that the servername is listening. +-<example id="e.g.troubleshooting.telnet"> +- <title>Finding the server</title> ++ <prompt>$ </prompt><userinput>ping -c1 <replaceable>myhost</replaceable></userinput> ++ <computeroutput> ++ PING myhost (127.0.0.1) from 127.0.0.1 : 56(84) bytes of data. ++ 64 bytes from myhost (127.0.0.1): icmp_seq=0 ttl=255 time=250 usec ++ </computeroutput></screen> ++ </example> ++ A successful ping shows that your network isn't preventing you from reaching the machine hosting the server.</para> ++ </sect2> ++ <sect2 id="serverthere.telnet"> ++ <title>Test with <command>telnet</></title> ++ ++<para>Attempt to <command>telnet</> to the port, to verify that the servername is listening. ++ <example id="e.g.troubleshooting.telnet"> ++ <title>Finding the server</title> + <screen> +-<prompt>$ </prompt><userinput>telnet <replaceable>myhost 1433</></userinput> +-<computeroutput> +-Trying 127.0.0.1... +-Connected to myhost. +-Escape character is '^]'. +-</computeroutput> +-</screen> +-</example> +-If you get output as above, the servername is listening. If you get a 'Connection Refused' message, you're talking to the wrong host, wrong port, or the servername is down. ++ <prompt>$ </prompt><userinput>telnet <replaceable>myhost 1433</></userinput> ++ <computeroutput> ++ Trying 127.0.0.1... ++ Connected to myhost. ++ Escape character is '^]'. ++ </computeroutput></screen> ++ </example> ++ If you get output as above, the 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</>: When connected, telnet's command mode may be entered by +- typing the telnet <firstterm>escape character</firstterm> (initially <keysym>Ctrl</keysym>-<keysym>]</keysym>, as above). Once in command mode, <command>telnet</> may be exited with the command <command>quit</>. +- </para></footnote> +- </para> +- </sect2> +- <sect2 id="serverthere.tsql"> +- <title>Test with <command>tsql</></title> +- <para> +-<command>tsql</> can be run in two ways, one which uses &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> ++ typing the telnet <firstterm>escape character</firstterm> (initially <keysym>Ctrl</keysym>-<keysym>]</keysym>, as above). Once in command mode, <command>telnet</> may be exited with the command <command>quit</>. ++</para></footnote></para> ++ </sect2> ++ <sect2 id="serverthere.tsql"> ++ <title>Test with <command>tsql</></title> ++ ++<para><command>tsql</> can be run in two ways, one which uses &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=7.0 ./tsql -H <replaceable>myhost</> -p <replaceable>1433</> -U <replaceable>user</></userinput> +-</screen> +-</example> +-If you receive a message of 'Login Failed.' then your connectivity is OK, but you have a authentication issue. +-</para> +-<para> +-If you receive a message like +-<screen> +-<computeroutput> +- Msg. No.: 18450 Severity: 14 State: 1 Login failed- User: loginid Reason: Not defined as a valid user of a trusted SQL Server connection +-</computeroutput> +-</screen> +-<productname>SQL Server</productname> is accepting only <quote>domain</quote> logins. This applies only to Microsoft <productname>SQL Server</productname> and you'll need to have your DBA verify that <quote>server logins</quote> are allowed, or use a <link linkend="domains">domain login</link>. ++ <prompt>$ </prompt><userinput>cd src/apps</userinput> ++ <prompt>$ </prompt><userinput>TDSVER=7.0 ./tsql -H <replaceable>myhost</> -p <replaceable>1433</> -U <replaceable>user</></userinput></screen> ++ </example> ++ If you receive a message of 'Login Failed.' then your connectivity is OK, but you have a authentication issue.</para> + +- </para> +- <para> +-Finally, if you received a prompt, then try <command>tsql</> using the servername. +-<example id="e.g.troubleshooting.tsql"> +- <title>Connecting to the server using &freetdsconf;</title> ++<para>If you receive a message like + <screen> +-<prompt>$ </prompt><userinput>./tsql -S <replaceable>myserver</> -U <replaceable>user</></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 ++ <computeroutput> ++ Msg. No.: 18450 Severity: 14 State: 1 Login failed- User: loginid Reason: Not defined as a valid user of a trusted SQL Server connection ++ </computeroutput></screen> ++ <productname>SQL Server</productname> is accepting only <quote>domain</quote> logins. This applies only to Microsoft <productname>SQL Server</productname> and you'll need to have your DBA verify that <quote>server logins</quote> are allowed, or use a <link linkend="domains">domain login</link>. </para> ++ ++<para>Finally, if you received a prompt, then try <command>tsql</> using the servername. ++ <example id="e.g.troubleshooting.tsql"> ++ <title>Connecting to the server using &freetdsconf;</title> + <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</> and <filename>stderr</> 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 truncatated each time the library connects to the server.) </para></tip> +- </para> +- </listitem> +- </varlistentry> ++ <prompt>$ </prompt><userinput>./tsql -S <replaceable>myserver</> -U <replaceable>user</></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</> and <filename>stderr</> 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 truncatated 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> ++ <term><envar>TDSDUMPCONFIG</envar></term> ++ <listitem> + +- <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. ++<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</>. 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"> ++ <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</>. 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</> entry in &freetdsconf;</link> +- </para> +- <para>The logfile is normally truncated each time &freetds; connects to the server. +- </para> +- ++ ++<para>See <link linkend="tab.freetds.conf.debugflags">Valid bitmask values for <literal>debug flags</> 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: ++ <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> ++ [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> ++ </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> + +- <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> ++ 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> + +-<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> ++ 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> +- ++ 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> ++ <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> ++ 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> +- ++ 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> ++ <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> ++ 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> ++ 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> + +-</listitem> +-</itemizedlist> ++<para>&freetds; is <emphasis>not</> slow. We know this because we've tested it. It's measurably slower than the vendors' products for some operations, but it's not noticeably slower and it's certainly no laggard. If your experience is different, if you're waiting 30 seconds for simple operations or minutes instead of seconds for for query results, something is up with your setup. There are two likely culprits.</para> ++ ++ <itemizedlist mark='bullet'> ++ <listitem> + ++<para>Logging. If everything seems a bit sluggish, check to make sure logging is turned off. <envar>TDSDUMP</> should not be defined, and there should be no <literal>dump file</> mentioned in &freetdsconf;. You can double-check by setting <envar>TDSDUMPCONFIG</> temporarily, which will log only the startup process.</para> ++ </listitem> ++ <listitem> ++ ++<para>DNS. If connecting to the server takes 30 seconds or 1 minute, you could do worse than to check your <filename>resolv.conf</>. Use <command>host</> or <command>nslookup</> to confirm that &freetds; can actually resolve the name/address you provided in &freetdsconf;. Give particular attention to reverse DNS lookups, if you were forced (or thought you were forced) to identify the server by number, instead of by name, as Vint intended. You can defeat &freetds;'s automatic reverse-DNS lookup feature by inserting ++<programlisting> ++ #define NOREVERSELOOKUPS ++ </programlisting> ++ in <filename>src/tds/config.c</>, rebuilding, and reinstalling. ++ <Note><para> Reverse lookup code has been removed as of version 0.62 due to wrong implementation.</para></Note></para> ++ </listitem> ++ <listitem> ++ ++<para>Packet size. Check packet size setting on &freetdsconf; (see <literal>initial block size</>). Default value (no configuration) is usually fine. The slowness is due to multiple packet to use. ++ Under <productname><acronym>GNU</>/Linux</productname> system we use an optimization to reduce network traffic so you shouldn't see much difference using this system.</para> ++ </listitem> ++ </itemizedlist> ++ + </sect1> +- <sect1 id="seemtooslow"> +- <title>Slow connection or data retrieval</title> +- <para> +-&freetds; is <emphasis>not</> slow. We know this because we've tested it. It's measurably slower than the vendors' products for some operations, but it's not noticeably slower and it's certainly no laggard. If your experience is different, if you're waiting 30 seconds for simple operations or minutes instead of seconds for for query results, something is up with your setup. There are two likely culprits. +- </para> ++ </chapter> ++<chapter id="help"> ++ <title>Getting Help</title> ++ <epigraph> ++ <attribution>Beatles</> + +-<itemizedlist mark='bullet'> +- <listitem> +- <para>Logging. If everything seems a bit sluggish, check to make sure logging is turned off. <envar>TDSDUMP</> should not be defined, and there should be no <literal>dump file</> mentioned in &freetdsconf;. You can double-check by setting <envar>TDSDUMPCONFIG</> temporarily, which will log only the startup process. </para> +- </listitem> +- <listitem> +- <para>DNS. If connecting to the server takes 30 seconds or 1 minute, you could do worse than to check your <filename>resolv.conf</>. Use <command>host</> or <command>nslookup</> to confirm that &freetds; can actually resolve the name/address you provided in &freetdsconf;. Give particular attention to reverse DNS lookups, if you were forced (or thought you were forced) to identify the server by number, instead of by name, as Vint intended. You can defeat &freetds;'s automatic reverse-DNS lookup feature by inserting +- <programlisting> +- #define NOREVERSELOOKUPS +- </programlisting> +-in <filename>src/tds/config.c</>, rebuilding, and reinstalling. +-<Note><para> Reverse lookup code has been removed as of version 0.62 due to wrong implementation.</para></Note> +- </para> +- </listitem> +- <listitem> +- <para>Packet size. Check packet size setting on &freetdsconf; (see <literal>initial block size</>). Default value (no configuration) is usually fine. The slowness is due to multiple packet to use. +- Under <productname><acronym>GNU</>/Linux</productname> system we use an optimization to reduce network traffic so you shouldn't see much difference using this system. </para> +- </listitem> +-</itemizedlist> ++<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</> &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 & 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 v0.83.dev.20110124 ++ freetds.conf directory: /usr/local/etc ++ MS db-lib source compatibility: no ++ Sybase binary compatibility: no ++ Thread safety: yes ++ iconv library: no ++ TDS version: 7.0 ++ iODBC: no ++ unixodbc: no ++ SSPI "trusted" logins: no ++ Keberos: no ++ </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> +- </chapter> +- <chapter id="help"> +- <title>Getting Help</title> +-<epigraph> +-<attribution>Beatles</> +-<para><literallayout> +- Help me if you can, I'm feeling down +- And I do appreciate you being 'round. +- Help me get my feet back on the ground, +- Won't you please, please help me? +-</literallayout></para> +-</epigraph> +- <para>In the battle against frustration and wasted motion, this manual is our first defense. Our documentation is intended to make it possible for a knowledgeable user to, well, <emphasis>use</> &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="IsolateCause"><title>Isolate the cause</title> +- <para> +-Successful problem isolation will yield earliest resolution. You (believe it or not) have more information about your environment than anyone else does, and have the greatest motivation to solve your problem. The resources at your disposal will be much more useful if the problem is specific. (Sorry if this is obvious. If it is, you might be surprised how often it's not.) +- </para> +- <para> +-If you can demonstrate the problem with <command>tsql</> or <command>sqsh</>, you can expect a quick answer to your question, possibly even a fairly quick fix. (It has happened several times in the last few years that bug reports to small problems were fixed the same day. On a few occasions, new functions were added in a few days. Making &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 — who are your allies and best resource — to determine what's going wrong. If you can submit a script that they can use to try to reproduce your results, you have a much better chance of happy resolution. +- </para> +- <para> +-On the plus side, the list includes people with a variety of backgrounds, who frequently answer questions that aren't really about &freetds; <foreignphrase>per se</foreignphrase>. Clear questions have sometimes even led to submitting patches to other projects. +- </para> ++ ++ <sect1 id="IsolateCause"> ++ <title>Isolate the cause</title> ++ ++<para>Successful problem isolation will yield earliest resolution. You (believe it or not) have more information about your environment than anyone else does, and have the greatest motivation to solve your problem. The resources at your disposal will be much more useful if the problem is specific. (Sorry if this is obvious. If it is, you might be surprised how often it's not.)</para> ++ ++<para>If you can demonstrate the problem with <command>tsql</> or <command>sqsh</>, you can expect a quick answer to your question, possibly even a fairly quick fix. (It has happened several times in the last few years that bug reports to small problems were fixed the same day. On a few occasions, new functions were added in a few days. Making &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 — who are your allies and best resource — to determine what's going wrong. If you can submit a script that they can use to try to reproduce your results, you have a much better chance of happy resolution.</para> ++ ++<para>On the plus side, the list includes people with a variety of backgrounds, who frequently answer questions that aren't really about &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</> +- <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 — the one that uses the same API you're using — 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> ++ ++<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 — the one that uses the same API you're using — 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 <filename>freetds.conf</filename>. </para> ++ </sect2> + + </sect1> +- <sect1 id="MailingList"><title>The Mailing List</title> +-<epigraph> +-<attribution>3 Henry VI, I, ii, approximately</> +-<para><literallayout> +- In them I trust; for they are [hackers] +- Witty, courteous, liberal, full of spirit. +-</literallayout></para> +-</epigraph> ++ <sect1 id="MailingList"><title>The Mailing List</title> ++ <epigraph> ++ <attribution>3 Henry VI, I, ii, approximately</> + +- ++<para><literallayout> ++ In them I trust; for they are [hackers] ++ Witty, courteous, liberal, full of spirit. ++ </literallayout></para> ++ </epigraph> ++ + <sect2 id="Archive"><title>The Archive</title> + +- <para>The &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</> 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> ++ ++<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</> 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> ++ <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> ++ ++ <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>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> ++ ++<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>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</> and attach the log to your message. Messages are currently limited to 75 KB attachments, and the logs are quite detailed, so make your query as short as possible. If necessary, trim the log; <command>gzip</> is also your friend here. It's always a good idea to post it on a website where people can fetch it if they're so inclined.</para> ++ ++<para>Log files are especially important if you're not programming at the C level. Sometimes there are problems — an impedance mismatch, to coin a phrase — 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> + +- <para>If you're puzzled by some interaction with the server (often the case), it's a very good idea to set <envar>TDSDUMP</> and attach the log to your message. Messages are currently limited to 75 KB attachments, and the logs are quite detailed, so make your query as short as possible. If necessary, trim the log; <command>gzip</> is also your friend here. It's always a good idea to post it on a website where people can fetch it if they're so inclined. +- </para> +- <para>Think about it this way: If you attach a log no one reads, you wasted some bandwidth. If you don't attach one and someone asks you for it, you wasted a day. Like that. </para> +- </sect2> +- +- <sect2 id="HelptheHelp"><title>Help the Help</title> +- +- <para>If you've found an error, weakness, misbehavior, discrepancy, call-it-what-you-will in one of the published <acronym>API</>s, it's very helpful if you write a unit test for it, and tell us what the Microsoft or Sybase behavior is. Those problems get <emphasis>fixed</>. Oftentimes, right away. Everyone who's sent us a unit test has gotten their feature in the next release. If you don't, you'll at least get an explanation. +- </para> +- <para> +-Moving down, Perl or PHP code provided it creates all the tables it needs and populates them will generally result in a quick fix. A stand-alone query that will run in <application>SQSH</application> also works well. Here again, it helps to attach a log. +- <tip><para>If you provide an SQL query in your question to the list, provide a table definition, too. Problems are often related to specific datatypes, so a table definition is an absolute must. You can run <command>sp_help <parameter>table</parameter></command> to generate one. </para></tip> +- </para> +- <para> +-It is very helpful if you can show an example of the problem using <command>sqsh</> or an appropriate <link linkend="utilities">utility</>. Using those programs limits the scope of question to &freetds; itself. +- </para> +-<para>If the problem is a segmentation fault or bus error, that's bad. Please obtain a +-backtrace and include it in your mail. See the <link +-linkend="pagenodata">"Page contains no data"</link> section for how to +-do this.</para> ++ <sect2 id="ShowYourWork"><title>Show your work</title> ++ ++<para>Great questions make the problem crystal clear to a tired developer after supper. </para> + +- </sect2> ++<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 — how to say it? — 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</> +-<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> ++<!-- ////////////////// CHAPTER /////////////////////// --> ++<chapter id="contrib"> ++ <title>Helping</title> ++ <epigraph> ++ <attribution>Bertrand Russell</> + +- <ItemizedList> ++<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> ++ ++<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> ++ ++<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> ++ ++<para>An isql Perl and PHP would all make debugging and testing easier for everyone.</para> + </listitem> +- </ItemizedList> +- </para> ++ </ItemizedList></para> + <sect2 id="Sendpatch"> +- <title>Send a patch</title> +- <para> +-Good patches are nearly always applied in short order. Patches uploaded to <ulink url="http://sourceforge.net/tracker/?group_id=33106&atid=407808">SourceForge</ulink> trigger automatic notification to the &freetds; mailing list. +- </para> +- </sect2> ++ <title>Send a patch</title> ++ ++<para>Good patches are nearly always applied in short order. Patches uploaded to <ulink url="http://sourceforge.net/tracker/?group_id=33106&atid=407808">SourceForge</ulink> trigger automatic notification to the &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 <ulink url="mailto:jklowden@freetds.org">&freetds; FAQ Master</ulink>, or post a message to the list. +- </para> +- <para> +-The User Guide is maintained in <acronym>SGML</> DocBook format; the file in your distibution is <filename>doc/userguide.sgml</>. It is a flat ASCII file that you can edit with any text editor. You don't have to know <acronym>SGML</> to correct or add to the User Guide, however. Just open it up, find the place you're interested in, and type away. Do a <command>diff -u <replaceable>old_version</> <replaceable>your_version</></command> and post your patch to the SourceForge site. Any errors or lackings in your markup will be graciously emended by yours truly. +- </para> +- </sect2> ++ <title>Correct this User Guide</title> ++ ++<para>Any corrections or suggestions, be they typographical, grammatical, structural, factual, or mineral are most welcome. Please send it to <ulink url="mailto:jklowden@freetds.org">&freetds; FAQ Master</ulink>, or post a message to the list.</para> ++ ++<para>The User Guide is maintained in <acronym>SGML</> DocBook format; the file in your distibution is <filename>doc/userguide.sgml</>. It is a flat ASCII file that you can edit with any text editor. You don't have to know <acronym>SGML</> to correct or add to the User Guide, however. Just open it up, find the place you're interested in, and type away. Do a <command>diff -u <replaceable>old_version</> <replaceable>your_version</></command> and post your patch to the SourceForge site. Any errors or lackings in your markup will be graciously emended by yours truly.</para> ++ </sect2> + <sect2 id="Documentapi"> +- <title>Document an <acronym>API</></title> +- <para> +-We have just begun an independent reference manual to &freetds;; the main <acronym>API</> documents are the work of the server vendors. We're using <ulink url="http://www.stack.nl/~dimitri/doxygen/">Doxygen</>, which extracts documentation directly from comments in the source code, and we're maybe 25% done. +- </para> +- <para> +-The <acronym>TDS</> protocol is partly documented, as are the <acronym>API</>s to <filename>libtds</filename> and <systemitem class="library">db-lib</>, but much remains. +- </para> +- </sect2> ++ <title>Document an <acronym>API</></title> ++ ++<para>We have just begun an independent reference manual to &freetds;; the main <acronym>API</> documents are the work of the server vendors. We're using <ulink url="http://www.stack.nl/~dimitri/doxygen/">Doxygen</>, which extracts documentation directly from comments in the source code, and we're maybe 25% done.</para> ++ ++<para>The <acronym>TDS</> protocol is partly documented, as are the <acronym>API</>s to <filename>libtds</filename> and <systemitem class="library">db-lib</>, 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 your friendly project maintainer, <ulink url="mailto:jklowden@freetds.org">James K. Lowden</ulink>. +- </para> +- </sect2> ++ <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 your friendly project maintainer, <ulink url="mailto:jklowden@freetds.org">James K. Lowden</ulink>.</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 <systemitem class="library">ct-lib</systemitem> interface to Microsoft <productname>SQL Server</productname>. This feature alone allows <productname>DBD::Sybase</> and <command>sqsh</>, among others, to connect to Microsoft's product. </para></listitem> +- <listitem><para>Provide a bcp-capable interface and command-line utility on unix-like operating systems for Microsoft <productname>SQL Server</productname>.</para></listitem> +- <listitem><para>Run on many more operating systems than either vendor's libraries do.</para></listitem> +- <listitem><para>Get fixed, instead of telling you to get stuffed.</para></listitem> +- <listitem><para>Amuse and inform. Also frustrate and infuriate, but we don't put that under <quote>Advocacy</>. </para></listitem> +-</ItemizedList> +- <para>If more people knew, fewer would be stuck. +- </para> ++ ++ <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, connecting and logging in to the server, getting Apache going, 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> +- </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 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 — and, obviously hampering the project — 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 & server pair composed entirely of free software. </para> ++ </sect2> ++ + </sect1> +- <sect1 id="APIreference"><title>API Reference Manual</title> +- <para> +-The <ulink url="../reference/index.html">reference manual</ulink> is installed as part of <productname>FreeTDS</>. It can be regenerated at any time using <productname>Doxygen</productname> with <command>cd <filename>doc</>; make doc</command>. +- </para> +- <para> +-The reference manual is a work in progress: only the db-lib library is completely documented, and quite minimally at that. Should you find it inadequate, you may be interested to learn it's not hard to add to, technically. <productname>Doxygen</productname> generates a manual from encoded comments in the source code. Its markup syntax is not hard to learn. You can read more about it at the <ulink url="http://www.stack.nl/~dimitri/doxygen/">Doxygen website</>. +- </para> +- <para> +-Basic API coverage information for the db-lib, ct-lib, and ODBC client libraries is maintained in <filename>doc/api_status.txt</>, included in the source distribution. For your convenience and enjoyment, we include that file in the following sections. In each table, we note for the function +- <footnote><para>Sybase and Microsoft sometimes use slightly different names for the same function. It is the intention of the <option>--enable-msdblib</> option to align +- <productname>FreeTDS</> with one or the other's convention.</para></footnote> +-the extent to which it is implemented. The <emphasis>Status</> field may be: +- +-<variablelist id="dblib.api.status"> +- <title>db-lib API function status domain</title> +- <varlistentry> +- <term>(blank)</term> +- <listitem> +- <para>Function is not implemented.</para> +- </listitem> +- </varlistentry> +- <varlistentry> +- <term>stub</term> +- <listitem> +- <para>Function is implemented as a stub. Some such functions return <literal>SUCCEED</> even though they have no effect, to satisfy upper layers. </para> +- </listitem> +- </varlistentry> +- <varlistentry> +- <term>Partial</term> +- <listitem> +- <para>Function is partly implemented. We haven't dealt with every possible option, for instance. </para> +- </listitem> +- </varlistentry> +- <varlistentry> +- <term>OK</term> +- <listitem> +- <para>Function is implemented. Completely, we claim. </para> +- </listitem> +- </varlistentry> +-</variablelist> +- </para> ++ ++ <sect1 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; interface to Microsoft <productname>SQL Server</productname>. This feature alone allows <productname>DBD::Sybase</> and <command>sqsh</>, among others, to connect to Microsoft's product.</para></listitem> ++ <listitem><para>Provide a bcp-capable interface and command-line utility on unix-like operating systems for Microsoft <productname>SQL Server</productname>.</para></listitem> ++ <listitem><para>Run on many more operating systems than either vendor's libraries do.</para></listitem> ++ <listitem><para>Get fixed, instead of telling you to get stuffed.</para></listitem> ++ <listitem><para>Amuse and inform. Also frustrate and infuriate, but we don't put that under <quote>Advocacy</>.</para></listitem> ++ </ItemizedList> ++ ++<para>If more people knew, fewer would be stuck.</para> + </sect1> ++ </chapter> ++<!-- ////////////////// CHAPTER /////////////////////// --> ++<chapter id="programming"> ++ <title>Programming</title> + +- <sect1 id="dblib.api.summary"> +- <title>db-lib API Implementation Summary</title> +- <para>Microsoft's version of db-lib is +- <ulink url="http://msdn.microsoft.com/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> +- &dblibapisgml; ++<para></para> ++ <sect1 id="TDSprotocolref"> ++ <title>TDS protocol reference</title> ++ ++<para>Can be found on <ulink url="http://www.freetds.org/tds.html">www.freetds.org</ulink></para> + </sect1> ++ <sect1 id="APIreference"><title>API Reference Manual</title> ++ ++<para>The <ulink url="../reference/index.html">reference manual</ulink> is installed as part of <productname>FreeTDS</>. It can be regenerated at any time using <productname>Doxygen</productname> with <command>cd <filename>doc</>; make doc</command>.</para> ++ ++<para>The reference manual is a work in progress: only the db-lib library is completely documented, and quite minimally at that. Should you find it inadequate, you may be interested to learn it's not hard to add to, technically. <productname>Doxygen</productname> generates a manual from encoded comments in the source code. Its markup syntax is not hard to learn. You can read more about it at the <ulink url="http://www.stack.nl/~dimitri/doxygen/">Doxygen website</>.</para> ++ ++<para>Basic API coverage information for the db-lib, ct-lib, and ODBC client libraries is maintained in <filename>doc/api_status.txt</>, included in the source distribution. For your convenience and enjoyment, we include that file in the following sections. In each table, we note for the function ++ <footnote><para>Sybase and Microsoft sometimes use slightly different names for the same function. It is the intention of the <option>--enable-msdblib</> option to align ++ <productname>FreeTDS</> with one or the other's convention.</para></footnote> ++ the extent to which it is implemented. The <emphasis>Status</> field may be: ++ ++ <variablelist id="dblib.api.status"> ++ <title>db-lib API function status domain</title> ++ <varlistentry> ++ <term>(blank)</term> ++ <listitem> ++ ++<para>Function is not implemented.</para> ++ </listitem> ++ </varlistentry> ++ <varlistentry> ++ <term>stub</term> ++ <listitem> ++ ++<para>Function is implemented as a stub. Some such functions return <literal>SUCCEED</> even though they have no effect, to satisfy upper layers.</para> ++ </listitem> ++ </varlistentry> ++ <varlistentry> ++ <term>Partial</term> ++ <listitem> ++ ++<para>Function is partly implemented. We haven't dealt with every possible option, for instance.</para> ++ </listitem> ++ </varlistentry> ++ <varlistentry> ++ <term>OK</term> ++ <listitem> + +- <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> +- &ctlibapisgml; ++<para>Function is implemented. Completely, we claim.</para> ++ </listitem> ++ </varlistentry> ++ </variablelist></para> + </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> ++ <sect1 id="dblib.api.summary"> ++ <title>db-lib API Implementation Summary</title> ++ ++<para>Microsoft's version of db-lib is ++ <ulink url="http://msdn.microsoft.com/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. + +- <para>The functions are linked to the reference page on Microsoft's website. <footnote><para>Links such as these are quite perishable. Should you find them broken, please check the <ulink url="http://www.freetds.org/userguide/odbc.api.summary.htm">FreeTDS User Guide</ulink> posted on our website. If it's out of date, please let us know, so we can correct it. Thanks. </para></footnote></para> +- &odbcapisgml; ++ <footnote><para>Links such as these are quite perishable. Should you find them broken, please check the <ulink url="http://www.freetds.org/userguide/dblib.api.summary.htm">FreeTDS User Guide</ulink> posted on our website. If it's out of date, please let us know, so we can correct it. Thanks.</para></footnote></para> ++ &dblibapisgml; + </sect1> + +- <sect1 id="samplecode"> +- <title>DB-Library for the Tenderfoot</title> +- <epigraph><attribution>Mark Twain</> +- <para>Few things are harder to put up with than the annoyance of a good example.</para> </epigraph> +- +- <abstract><para>Below is a complete sample working db-lib 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</> directory. A complete program, heavily commented for your perusal, is <filename>apps/bsqldb.c</>.</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</> to have updated the data, when in fact it did not. </para> +- <para>Every db-lib 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</> to extract the <symbol>C</> code from the User Guide <symbol>SGML</> source. </para></listitem> +- <listitem><para>Compile </para></listitem> +- <listitem><para>Link </para></listitem> +- </orderedlist> ++ <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> ++ &ctlibapisgml; ++ </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> ++ &odbcapisgml; ++ </sect1> ++ ++ <sect1 id="samplecode"> ++ <title>DB-Library for the Tenderfoot</title> ++ <epigraph><attribution>Mark Twain</> ++ ++<para>Few things are harder to put up with than the annoyance of a good example.</para> </epigraph> ++ ++ <abstract><para>Below is a complete sample working db-lib 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</> directory. A complete program, heavily commented for your perusal, is <filename>apps/bsqldb.c</>.</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</> to have updated the data, when in fact it did not.</para> + ++<para>Every db-lib 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</> to extract the <symbol>C</> code from the User Guide <symbol>SGML</> 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</> </para></listitem> ++ <listitem><para><filename>sybfront.h</></para></listitem> + <listitem><para><filename>sybdb.h </></para></listitem> +- <listitem><para><filename>libsybdb.a</> or <filename>libsybdb.so</> </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.sgml > 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</> and <filename>/usr/local/lib</> are respectively the locations of your header files and libraries. +- </para> +- +- <para>We now proceed to the code proper.</para> +- ++ <listitem><para><filename>libsybdb.a</> or <filename>libsybdb.so</></para></listitem> ++ </itemizedlist> ++ Your library's extension may vary according to your operating system.</para> ++ + +- <sect2 id="samplecode.include"><title>Header files</title> +- <abstract><para>We need two header files to use db-lib. 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>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.sgml > 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</> and <filename>/usr/local/lib</> are respectively the locations of your header files and libraries.</para> ++ + +- <para><example id="e.g.samplecode.dblib.include"> +- <title>Sample Code: <symbol>db-lib</> header files</title> +- <programlisting linenumbering="unnumbered"> ++<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 db-lib. 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: <symbol>db-lib</> header files</title> ++ <programlisting linenumbering="unnumbered"> + <![CDATA[ + #include <stdio.h> + #include <stdlib.h> +@@ -3536,36 +3426,36 @@ the extent to which it is implemented. The <emphasis>Status</> field may be: + #include <errno.h> + #include <unistd.h> + #include <libgen.h> +-]]> +- ++ ]]> ++ + #include <sybfront.h> <lineannotation>/* <filename>sybfront.h</> always comes first */</lineannotation> + #include <sybdb.h> <lineannotation>/* <filename>sybdb.h</> 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> ++</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> + +- <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: <symbol>db-lib</> 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[]) +-{ ++<para><example id="e.g.samplecode.dblib.prolog"> ++ <title>Sample Code: <symbol>db-lib</> 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"> +@@ -3574,1390 +3464,1703 @@ main(int argc, char *argv[]) + 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); +- } ++ 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 +- && options.username && options.password)) { +- fprintf(stderr, syntax); +- exit(1); ++ && options.username && options.password)) { ++ fprintf(stderr, syntax); ++ exit(1); + } +- </programlisting></example> +- <calloutlist><title>Prolog Notes</title> +- <callout arearefs="samplecode.init.loginrec"> +- <para><symbol>LOGINREC</> 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</> is a structure that describes the connection. It is returned by <function>dbopen()</>. </para></callout> +- <callout arearefs="samplecode.init.retcode"> +- <para><symbol>RETCODE</> is the most common return code type for <symbol>db-lib</> functions. </para></callout> +- </calloutlist> +- </para> +- </sect2> ++ </programlisting></example> ++ <calloutlist><title>Prolog Notes</title> ++ <callout arearefs="samplecode.init.loginrec"> ++ ++<para><symbol>LOGINREC</> is a structure that describes the client. It's passed to the server at connect time.</para></callout> ++ <callout arearefs="samplecode.init.dbprocess"> + +- <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: <symbol>db-lib</> Initialize</title> +- <programlisting linenumbering="unnumbered"> ++<para><symbol>DBPROCESS</> is a structure that describes the connection. It is returned by <function>dbopen()</>.</para></callout> ++ <callout arearefs="samplecode.init.retcode"> + +-<co id="samplecode.init.dbinit" label="initialize"> ++<para><symbol>RETCODE</> is the most common return code type for <symbol>db-lib</> 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: <symbol>db-lib</> 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); ++ fprintf(stderr, "%s:%d: dbinit() failed\n", ++ options.appname, __LINE__); ++ exit(1); + } + +-<co id="samplecode.init.handlers"> ++ <co id="samplecode.init.handlers"> + dberrhandle(err_handler); + dbmsghandle(msg_handler); +- +-<co id="samplecode.init.login"> ++ ++ <co id="samplecode.init.login"> + if ((login = dblogin()) == NULL) { +- fprintf(stderr, "%s:%d: unable to allocate login structure\n", +- options.appname, __LINE__); +- exit(1); ++ fprintf(stderr, "%s:%d: unable to allocate login structure\n", ++ options.appname, __LINE__); ++ exit(1); + } +- +-<co id="samplecode.init.login.populate"> ++ ++ <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</> make <function>dbinit()</> the first db-lib 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()</> 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</> in the documentation. </para></callout> +- </calloutlist> +- </para> ++ ++ </programlisting></example> ++ <calloutlist><title>Initialization Notes</title> ++ <callout arearefs="samplecode.init.dbinit"> ++ ++<para><emphasis>Always</> make <function>dbinit()</> the first db-lib 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()</> 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</> in the documentation.</para></callout> ++ </calloutlist></para> + </sect2> ++ ++ <sect2 id="samplecode.connect"><title>Connect to the server</title> ++ <abstract><para><function>dbopen()</> forms a connection with the server. We pass our <symbol>LOGINREC</> 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> ++ + +- <sect2 id="samplecode.connect"><title>Connect to the server</title> +- <abstract><para><function>dbopen()</> forms a connection with the server. We pass our <symbol>LOGINREC</> 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: <symbol>db-lib</> Connect to the server</title> +- <programlisting> ++<para><example id="e.g.samplecode.dblib.Connect"> ++ <title>Sample Code: <symbol>db-lib</> 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); ++ fprintf(stderr, "%s:%d: unable to connect to %s as %s\n", ++ options.appname, __LINE__, ++ options.servername, options.username); ++ exit(1); + } +- ++ + if (options.dbname && (erc = dbuse(dbproc, options.dbname)) == FAIL) { +- fprintf(stderr, "%s:%d: unable to use to database %s\n", +- options.appname, __LINE__, options.dbname); +- exit(1); ++ fprintf(stderr, "%s:%d: unable to use to database %s\n", ++ options.appname, __LINE__, options.dbname); ++ exit(1); + } +- +- +- </programlisting></example> +- </para> ++ ++ </programlisting></example></para> + </sect2> +- +- <sect2 id="samplecode.query"><title>Send a query</title> ++ ++ <sect2 id="samplecode.query"><title>Send a query</title> + <abstract><para><symbol>db-lib</> maintains a <firstterm>command buffer</> to hold the SQL to be sent to the server. Two functions — <function>dbcmd()</> and <function>dbfcmd()</> — 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: <symbol>db-lib</> Send a query</title> +- <programlisting> +- for (i=0; i < 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"> + ++<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: <symbol>db-lib</> Send a query</title> ++<programlisting> ++ for (i=0; i < 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"> +- ++ 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()</> 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()</> 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()</> succeeded doesn't mean you're in the clear. +- </para> ++ </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()</> 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()</> 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()</> 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. Broadly, that entails providing buffers to <symbol>db-lib</> to fill, and iterating over the results a row (and column) at a time. </para></abstract> +- ++ ++ <sect2 id="samplecode.results"><title>Fetch Results</title> ++ <abstract><para>A query may produce zero, one, or more results. Broadly, that entails providing buffers to <symbol>db-lib</> to fill, and iterating over the results a row (and column) at a time.</para></abstract> ++ + <bridgehead id="samplecode.results.kinds.of.results" renderas="sect3">Kinds of Results</> + +- <para><firstterm>Results</> is a special term: it means more than rows or no rows. To <emphasis>process the results</> 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>UPDATE</>, or <symbol>DELETE</> 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</></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</> </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)</> </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</> </entry> +- </row> +- </tbody> +- </tgroup> +- </table> </para> ++ ++<para><firstterm>Results</> is a special term: it means more than rows or no rows. To <emphasis>process the results</> 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>UPDATE</>, or <symbol>DELETE</> 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</></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</> </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)</> </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</> </entry> ++ </row> ++ </tbody> ++ </tgroup> ++ </table></para> + +- <para>As the above table shows, results can comprise ordinary rows and <firstterm>compute rows</> (resulting from a <symbol>COMPUTE</> clause). Stored procedures may of course contain multiple SQL statements, some of which may be <symbol>SELECT</> statements and might include <symbol>COMPUTE</> clauses. In addition, they generate a <firstterm>return status</> (with a <symbol>RETURN</> statement or else automatically) and perhaps <symbol>OUTPUT</> parameters. </para> ++ ++<para>As the above table shows, results can comprise ordinary rows and <firstterm>compute rows</> (resulting from a <symbol>COMPUTE</> clause). Stored procedures may of course contain multiple SQL statements, some of which may be <symbol>SELECT</> statements and might include <symbol>COMPUTE</> clauses. In addition, they generate a <firstterm>return status</> (with a <symbol>RETURN</> statement or else automatically) and perhaps <symbol>OUTPUT</> parameters.</para> + + <bridgehead id="samplecode.results.metadata.and.data" renderas="sect3">Data and Metadata</> + +- <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</>. The server always returns metadata before any data (even for a a <symbol>SELECT</> 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()</></entry> +- <entry colname="type">metadata</entry> +- <entry colname="ret"><symbol>SUCCEED</>, <symbol>FAIL</> or, <symbol>NO_MORE_RESULTS</>. </entry> +- <entry colname="etc"><symbol>SUCCEED</> 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>nextrow()</></entry> +- <entry colname="type">data</entry> +- <entry colname="ret"> <symbol>REG_ROW</>, +- <firstterm>compute_id</>, +- <symbol>NO_MORE_ROWS</>, +- <symbol>BUF_FULL</>, +- or <symbol>FAIL</>. +- </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</> ++<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</>. The server always returns metadata before any data (even for a a <symbol>SELECT</> statement that produced no rows).</para> ++ + +- <para>Each time <symbol>dbresults()</> returns <symbol>SUCCEED</>, there is something to retrieve. <symbol>db-lib</> 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</>, and those that return the data in <quote>native</> form. </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()</></entry> ++ <entry colname="type">metadata</entry> ++ <entry colname="ret"><symbol>SUCCEED</>, <symbol>FAIL</> or, <symbol>NO_MORE_RESULTS</>. </entry> ++ <entry colname="etc"><symbol>SUCCEED</> 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>nextrow()</></entry> ++ <entry colname="type">data</entry> ++ <entry colname="ret"> <symbol>REG_ROW</>, ++ <firstterm>compute_id</>, ++ <symbol>NO_MORE_ROWS</>, ++ <symbol>BUF_FULL</>, ++ or <symbol>FAIL</>. ++ </entry> ++ <entry colname="etc">Places fetched data into bound columns, if any. </entry> ++ </row> ++ </tbody> ++ </tgroup> ++ </table></para> + +- <para>To understand binding, it may be easiest to examine two primitive functions, <function>dbdata()</> and <function>dbconvert()</>. <function>dbdata()</> returns a pointer to the column's data. The data to which it points are in <quote>native</> form, 4 bytes for an <symbol>INT</>, 8 bytes for a <symbol>DATETIME</> and so on. <function>dbconvert()</> converts between datatypes; you can hand it an integer and get back a character array (or a <symbol>C double</>. You might think of <function>dbconvert()</> as <function>atoi(3)</> on steroids). <function>dbbind()</> 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> ++ <bridgehead id="samplecode.results.binding" renderas="sect3">Binding</> + +- <para>To <emphasis>bind a column</> is to provide a buffer to <symbol>db-lib</> to fill and indicate which datatype the buffer is meant to hold. <footnote><para>This is the sort of thing <symbol>C++</>'s type system does so much better</para></footnote> </para> ++ ++<para>Each time <symbol>dbresults()</> returns <symbol>SUCCEED</>, there is something to retrieve. <symbol>db-lib</> 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</>, and those that return the data in <quote>native</> form.</para> ++ ++ ++<para>To understand binding, it may be easiest to examine two primitive functions, <function>dbdata()</> and <function>dbconvert()</>. <function>dbdata()</> returns a pointer to the column's data. The data to which it points are in <quote>native</> form, 4 bytes for an <symbol>INT</>, 8 bytes for a <symbol>DATETIME</> and so on. <function>dbconvert()</> converts between datatypes; you can hand it an integer and get back a character array (or a <symbol>C double</>. You might think of <function>dbconvert()</> as <function>atoi(3)</> on steroids). <function>dbbind()</> 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>It may be well to pause here to observe the three ways a datatype is described in a <symbol>db-lib</> program. +- <variablelist id="list.datatypes"><title><function>db-lib</> 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</>, 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</> type on the server.</quote> These all begin with <symbol>SYB</>, e.g. <symbol>SYBINT4</>. </para> +- </listitem> +- </varlistentry> +- <varlistentry> +- <term>Program Variable Datatype</term> +- <listitem> +- <para>Defines a <symbol>C</> variable in a machine-independent way. Because a <symbol>C</> defines its <symbol>int</> type according the CPU architecture, it may have 2, 4, 8, or some other number of bytes. A <symbol>DBINT</> 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</> column. These all begin with <symbol>DB</>, e.g. <symbol>DBREAL</>. </para> +- </listitem> +- </varlistentry> +- <varlistentry> +- <term>Bind Type</term> +- <listitem> +- <para>Prescribes a conversion operation. Indicates to <function>dbbind()</> the <emphasis>Program Variable Datatype</> defined by the target buffer. Sybase and Microsoft call this the <quote>vartype</>. These all <emphasis>end</> with <symbol>BIND</>, e.g. <symbol>STRINGBIND</>. </para> +- </listitem> +- </varlistentry> +- </variablelist> +- </para> + ++<para>To <emphasis>bind a column</> is to provide a buffer to <symbol>db-lib</> to fill and indicate which datatype the buffer is meant to hold. <footnote><para>This is the sort of thing <symbol>C++</>'s type system does so much better</para></footnote></para> + +- <para>Typically it's more convenient to have <symbol>db-lib</> convert the data into the desired form. The function that does that is <function>dbind()</>. So: after fetching the metadata, and before fetching the data, we usually prepare the bound columns. </para> + ++<para>It may be well to pause here to observe the three ways a datatype is described in a <symbol>db-lib</> program. ++ <variablelist id="list.datatypes"><title><function>db-lib</> 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</>, 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</> type on the server.</quote> These all begin with <symbol>SYB</>, e.g. <symbol>SYBINT4</>.</para> ++ </listitem> ++ </varlistentry> ++ <varlistentry> ++ <term>Program Variable Datatype</term> ++ <listitem> ++ ++<para>Defines a <symbol>C</> variable in a machine-independent way. Because a <symbol>C</> defines its <symbol>int</> type according the CPU architecture, it may have 2, 4, 8, or some other number of bytes. A <symbol>DBINT</> 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</> column. These all begin with <symbol>DB</>, e.g. <symbol>DBREAL</>.</para> ++ </listitem> ++ </varlistentry> ++ <varlistentry> ++ <term>Bind Type</term> ++ <listitem> ++ ++<para>Prescribes a conversion operation. Indicates to <function>dbbind()</> the <emphasis>Program Variable Datatype</> defined by the target buffer. Sybase and Microsoft call this the <quote>vartype</>. These all <emphasis>end</> with <symbol>BIND</>, e.g. <symbol>STRINGBIND</>.</para> ++ </listitem> ++ </varlistentry> ++ </variablelist></para> ++ ++ ++<para>Typically it's more convenient to have <symbol>db-lib</> convert the data into the desired form. The function that does that is <function>dbind()</>. 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</> + +- <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</> parameters</entry> +- </row> +- </thead> +- <tbody> +- <row> <entry colname="type">Meta </entry> +- <entry colname="reg"><function>dbnumcols()</> </entry> +- <entry colname="comp"> <function>dbnumcompute()</>, +- <function>dbnumalts()</>, +- <function>dbaltop()</>, +- <function>dbbylist()</> </entry> +- <entry colname="ret"><function>dbhasretstatus()</> </entry> +- <entry colname="out"><function>dbnumrets()</> </entry> +- </row> +- <row> <entry colname="type">Binding </entry> +- <entry colname="reg"><function>dbbind()</>, <function>dbnullbind()</> </entry> +- <entry colname="comp"> <function>dbaltbind()</>, +- <function>dbanullbind()</> </entry> +- <entry colname="ret"><function>dbretstatus()</> </entry> +- <entry colname="out">none </entry> +- </row> +- <row> <entry colname="type">Native </entry> +- <entry colname="reg"><function>dbdatlen()</>, <function>dbdata()</> </entry> +- <entry colname="comp"> <function>dbadlen()</>, +- <function>dbalttype()</>, +- <function>dbaltutype()</>, +- <function>dbaltlen()</>, +- <function>dbadata()</> </entry> +- <entry colname="ret">none </entry> +- <entry colname="out"> <function>dbretdata()</>, +- <function>dbretlen()</>, +- <function>dbretname()</>, +- <function>dbrettype()</> </entry> +- </row> +- </tbody> +- </tgroup> +- </table> </para> ++ ++<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</> parameters</entry> ++ </row> ++ </thead> ++ <tbody> ++ <row> <entry colname="type">Meta </entry> ++ <entry colname="reg"><function>dbnumcols()</> </entry> ++ <entry colname="comp"> <function>dbnumcompute()</>, ++ <function>dbnumalts()</>, ++ <function>dbaltop()</>, ++ <function>dbbylist()</> </entry> ++ <entry colname="ret"><function>dbhasretstatus()</> </entry> ++ <entry colname="out"><function>dbnumrets()</> </entry> ++ </row> ++ <row> <entry colname="type">Binding </entry> ++ <entry colname="reg"><function>dbbind()</>, <function>dbnullbind()</> </entry> ++ <entry colname="comp"> <function>dbaltbind()</>, ++ <function>dbanullbind()</> </entry> ++ <entry colname="ret"><function>dbretstatus()</> </entry> ++ <entry colname="out">none </entry> ++ </row> ++ <row> <entry colname="type">Native </entry> ++ <entry colname="reg"><function>dbdatlen()</>, <function>dbdata()</> </entry> ++ <entry colname="comp"> <function>dbadlen()</>, ++ <function>dbalttype()</>, ++ <function>dbaltutype()</>, ++ <function>dbaltlen()</>, ++ <function>dbadata()</> </entry> ++ <entry colname="ret">none </entry> ++ <entry colname="out"> <function>dbretdata()</>, ++ <function>dbretlen()</>, ++ <function>dbretname()</>, ++ <function>dbrettype()</> </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>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()</> </entry> +- <entry colname="once">Query</entry> +- <entry colname="freq">Program</entry> +- </row> +- <row> <entry colname="step">Fetch metadata </entry> +- <entry colname="func"><function>dbresults()</> </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()</> </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()</> </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()</> </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()</> </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()</> </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><symbol>db-lib</> doesn't insist every column — or even any column — 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</>. Before the <symbol>DBPROCESS</> 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</>. </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: <symbol>db-lib</> 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 < ncols; pcol++) { +- int c = pcol - columns + 1; ++ ++<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()</> </entry> ++ <entry colname="once">Query</entry> ++ <entry colname="freq">Program</entry> ++ </row> ++ <row> <entry colname="step">Fetch metadata </entry> ++ <entry colname="func"><function>dbresults()</> </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()</> </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()</> </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()</> </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()</> </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()</> </entry> ++ <entry colname="once">Stored procedure </entry> ++ <entry colname="freq">Program </entry> ++ </row> ++ </tbody> ++ </tgroup> ++ </table></para> + +- pcol->name = dbcolname(dbproc, c); <co id="samplecode.results.c"> +- pcol->type = dbcoltype(dbproc, c); +- pcol->size = dbcollen(dbproc, c); ++ ++<para><important><title>Fetch All Rows!</title> ++ <sidebar><para><symbol>db-lib</> doesn't insist every column — or even any column — 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</>. Before the <symbol>DBPROCESS</> 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</>.</para></sidebar></important></para> + +- if (SYBCHAR != pcol->type) { <co id="samplecode.results.dbcollen"> +- pcol->size = dbwillconvert(pcol->type, SYBCHAR); +- } +- +- 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); +- } ++ ++<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: <symbol>db-lib</> 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 < 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 = dbwillconvert(pcol->type, SYBCHAR); ++ } ++ ++ 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 < 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 < 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)); +- } ++ 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 < 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 < 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()</> reports <symbol>SUCCESS</>, the row's metadata are available. </para></callout> +- <callout arearefs="samplecode.results.c"><para><symbol>db-lib</> columns start with 1. </para></callout> +- <callout arearefs="samplecode.results.dbcollen"><para><function>dbcollen()</> returns the sizeof the native data (e.g. 4 bytes for a T-SQL <symbol>INT</>). We'll use <function>dbbind()</> to convert everything to strings. If the column is <symbol>[VAR]CHAR</>, we want the column's defined size, otherwise we want its maximum size when represented as a string, which FreeTDS's <function>dbwillconvert()</> returns (for fixed-length datatypes). <footnote><para>For IMAGE data, we need to multiply by 2, because <function>dbbind()</> will convert each byte to a hexadecimal pair. The example program will report an error with IMAGE data. </para></footnote></para></callout> +- <callout arearefs="samplecode.results.dbbind"><para><symbol>NTBSTRINGBIND</> null-terminates the character array for us. <quote>NTB</> might perhaps stand for <quote>null terminating byte</>. </para></callout> +- <callout arearefs="samplecode.results.dbnullbind"><para>A zero-length string is not a NULL! <function>dbnullbind()</> 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()</> returns <symbol>REG_ROW</>, 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> ++ } ++ </programlisting></example> ++ <calloutlist id="co.fetching"><title>Data-fetching Notes</title> ++ <callout arearefs="samplecode.results.dbresults"><para>As soon as <function>dbresults()</> reports <symbol>SUCCESS</>, the row's metadata are available.</para></callout> ++ <callout arearefs="samplecode.results.c"><para><symbol>db-lib</> columns start with 1.</para></callout> ++ <callout arearefs="samplecode.results.dbcollen"><para><function>dbcollen()</> returns the sizeof the native data (e.g. 4 bytes for a T-SQL <symbol>INT</>). We'll use <function>dbbind()</> to convert everything to strings. If the column is <symbol>[VAR]CHAR</>, we want the column's defined size, otherwise we want its maximum size when represented as a string, which FreeTDS's <function>dbwillconvert()</> returns (for fixed-length datatypes). <footnote><para>For IMAGE data, we need to multiply by 2, because <function>dbbind()</> will convert each byte to a hexadecimal pair. The example program will report an error with IMAGE data.</para></footnote></para></callout> ++ <callout arearefs="samplecode.results.dbbind"><para><symbol>NTBSTRINGBIND</> null-terminates the character array for us. <quote>NTB</> might perhaps stand for <quote>null terminating byte</>.</para></callout> ++ <callout arearefs="samplecode.results.dbnullbind"><para>A zero-length string is not a NULL! <function>dbnullbind()</> 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()</> returns <symbol>REG_ROW</>, 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</> (because they are: they arrive as messages from the server); the latter are termed <firstterm>errors</>. Their handling is a little intimidating. It requires writing and installing a callback function (whose parameters are predefined by <symbol>db-lib</>), and thinking about how to handle different types of errors. </para></abstract> +- ++ ++ <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</> (because they are: they arrive as messages from the server); the latter are termed <firstterm>errors</>. Their handling is a little intimidating. It requires writing and installing a callback function (whose parameters are predefined by <symbol>db-lib</>), 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</> 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> ++ ++<para><emphasis>Messages</> 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</> arise either because the application has misused <symbol>db-lib</> in some way — say, passed a NULL <symbol>DBPROCESS</> pointer or tried to issue a query while results were pending — 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><emphasis>Errors</> arise either because the application has misused <symbol>db-lib</> in some way — say, passed a NULL <symbol>DBPROCESS</> pointer or tried to issue a query while results were pending — 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 <symbol>db-lib</> use your handler, pass its name to the appropriate <function>dberrhandle()</> or <function>dbmsghandle()</> function immediately after calling <function>dbinit()</>. </para> ++ ++<para>To have <symbol>db-lib</> use your handler, pass its name to the appropriate <function>dberrhandle()</> or <function>dbmsghandle()</> function immediately after calling <function>dbinit()</>.</para> + +- <para><example id="e.g.samplecode.dblib.errors"> +- <title>Sample Code: <symbol>db-lib</> 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"> ++ ++<para><example id="e.g.samplecode.dblib.errors"> ++ <title>Sample Code: <symbol>db-lib</> 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 == 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, "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); ++ 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"> ++ } ++ ++ 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); ++ 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); ++ 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</> compiler that the address of your function is of the type accepted by <function>dbmsghandle()</>. <footnote><para>Back in K&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</> documentation, and can be set by the <symbol>T-SQL RAISERROR</> statement. </para></callout> +- <callout arearefs="samplecode.errors.msghandler.return"><para>Message handlers <emphasis>always and only ever</> 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</> compiler that the address of your function is of the type accepted by <function>dberrhandle()</>. <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 <symbol>db-lib</> into calling the error handler, too! If you have both installed — and of course you do, right? — then you can skip those lacking an error number. </para></callout> +- <callout arearefs="samplecode.errors.errhandler.return"><para>While <symbol>INT_CANCEL</> 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 <symbol>db-lib</> 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</> an error and usually the best that can happen is that the function will return <symbol>FAIL</>. The exception is timeout conditions, when the handler can stave off failure by requesting retries. </para></note></para> ++ } ++ </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</> compiler that the address of your function is of the type accepted by <function>dbmsghandle()</>. <footnote><para>Back in K&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</> documentation, and can be set by the <symbol>T-SQL RAISERROR</> statement.</para></callout> ++ <callout arearefs="samplecode.errors.msghandler.return"><para>Message handlers <emphasis>always and only ever</> 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</> compiler that the address of your function is of the type accepted by <function>dberrhandle()</>. <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 <symbol>db-lib</> into calling the error handler, too! If you have both installed — and of course you do, right? — then you can skip those lacking an error number.</para></callout> ++ <callout arearefs="samplecode.errors.errhandler.return"><para>While <symbol>INT_CANCEL</> 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 <symbol>db-lib</> keeps retrying timeout errors. See the documentation for details.</para></callout> ++ </calloutlist></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 line in my program where the error occurred? How to do that?</quote> First of all, remember the calling function — that's your application — will learn of an error from the return code. If it needs more detail, though, there are two ways to pass it. ++ ++<para><note><para>No matter what the error handler says or does, it can't remedy the error. It's <emphasis>still</> an error and usually the best that can happen is that the function will return <symbol>FAIL</>. The exception is timeout conditions, when the handler can stave off failure by requesting retries.</para></note></para> + +- <orderedlist> +- <listitem><para>Set a global variable. </para></listitem> +- <listitem><para>Use <function>setuserdata()</> and +- <function>getuserdata()</>. </para></listitem> +- </orderedlist> ++ ++<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 line in my program where the error occurred? How to do that?</quote> First of all, remember the calling function — that's your application — 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()</> and ++ <function>getuserdata()</>.</para></listitem> ++ </orderedlist> ++ ++ <tip><para>If your application is written in <symbol>C++</>, you may be tempted to use <function>throw()</>. Don't! Your handler is a <symbol>C</> function and, more important, <emphasis>it's an extension of <symbol>db-lib</></emphasis>. You can put a <function>throw()</> in your handler and it will compile. But when it executes, it's going to rip through <symbol>db-lib</>'s stack. Your application will be unuseable at that point, if it doesn't cause a segment fault.</para></tip></para> + +- <tip><para>If your application is written in <symbol>C++</>, you may be tempted to use <function>throw()</>. Don't! Your handler is a <symbol>C</> function and, more important, <emphasis>it's an extension of <symbol>db-lib</></emphasis>. You can put a <function>throw()</> in your handler and it will compile. But when it executes, it's going to rip through <symbol>db-lib</>'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 <symbol>db-lib</> tour. The almost 300 lines of <symbol>C</> above constitute program with these features: ++ ++ <sect2 id="samplecode.wrapup"><title>Last Remarks</title> ++ ++<para>We've reached the end of our <symbol>db-lib</> tour. The almost 300 lines of <symbol>C</> above constitute program with these features: + <itemizedlist><title> Sample Code features</> +- <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> ++ <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</> +- <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> ++ <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> +-<ulink url="mailto:misa@dntis.ro">Mihai Ibanescu</ulink> (misa@dntis.ro)</member> +-<member><acronym>GNU</>ified the packet</> +- <member> +-<ulink url="mailto:greggj@savvis.com">Gregg Jensen</ulink> (greggj@savvis.com)</member> +-<member>Message handlers and extra datatype support and some sybperl stuff</> +- <member> +-<ulink url="mailto:jklowden@schemamania.org">James K. Lowden</ulink> (jklowden@schemamania.org)</member> +-<member>Wrote most of the documentation. Helped out here and there. </> +- <member> +-<ulink url="mailto:smurph@smcomp.com">Steve Murphree</ulink> (smurph@smcomp.com)</member> +-<member>Added more ODBC functionality. </> +- <member> +-<ulink url="mailto:psaar@fenar.ee">Arno Pedusaar</ulink> (psaar@fenar.ee)</member> +-<member>Donated his <acronym>TDS</>4.2 code to the cause</> +- <member> +-<ulink url="mailto:mark@champ.tstonramp.com">Mark Schaal</ulink> (mark@champ.tstonramp.com)</member> +-<member>Cleaned up message handling, more datatype support, bug fixes</> +- <member> +-<ulink url="mailto:cts@internetcds.com">Craig Spannring</ulink> (cts@internetcds.com)</member> +-<member>Wrote the <acronym>JDBC</> and DBI drivers</> +- <member> +-<ulink url="mailto:thompbil@exchange.uk.ml.com">Bill Thompson</ulink> (thompbil@exchange.uk.ml.com)</member> +-<member>Completer of the <systemitem class="library">db-lib</systemitem> bcp API and author of <application>freebcp</application>.</> +- <member> +-<ulink url="mailto:freddy77@gmail.com">Frediano Ziglio</ulink> (freddy77@gmail.com)</member> +-<member>Extended the ODBC library, and added many, many fixes and enhancements to libtds. </> ++<!-- ////////////////// 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> ++ <ulink url="mailto:misa@dntis.ro">Mihai Ibanescu</ulink> (misa@dntis.ro)</member> ++ <member><acronym>GNU</>ified the packet</> ++ <member> ++ <ulink url="mailto:greggj@savvis.com">Gregg Jensen</ulink> (greggj@savvis.com)</member> ++ <member>Message handlers and extra datatype support and some sybperl stuff</> ++ <member> ++ <ulink url="mailto:jklowden@schemamania.org">James K. Lowden</ulink> (jklowden@schemamania.org)</member> ++ <member>Wrote most of the documentation. Helped out here and there. </> ++ <member> ++ <ulink url="mailto:smurph@smcomp.com">Steve Murphree</ulink> (smurph@smcomp.com)</member> ++ <member>Added more ODBC functionality. </> ++ <member> ++ <ulink url="mailto:psaar@fenar.ee">Arno Pedusaar</ulink> (psaar@fenar.ee)</member> ++ <member>Donated his <acronym>TDS</>4.2 code to the cause</> ++ <member> ++ <ulink url="mailto:mark@champ.tstonramp.com">Mark Schaal</ulink> (mark@champ.tstonramp.com)</member> ++ <member>Cleaned up message handling, more datatype support, bug fixes</> ++ <member> ++ <ulink url="mailto:cts@internetcds.com">Craig Spannring</ulink> (cts@internetcds.com)</member> ++ <member>Wrote the <acronym>JDBC</> and DBI drivers</> ++ <member> ++ <ulink url="mailto:thompbil@exchange.uk.ml.com">Bill Thompson</ulink> (thompbil@exchange.uk.ml.com)</member> ++ <member>Completer of the &dblib; bcp API and author of <application>freebcp</application>.</> ++ <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. </> + </simplelist> +- <para> +- </para> +- </sect1> + +- <sect1 id="Contributors"> +- <title>Contributors</title> +- <para>This user guide owes at least 100 words each to the following people. +- </para> +- <simplelist> +- <member>Brian Bruns</> +- <member>James Cameron</> +- <member>Allen Grace</> +- <member>James K. Lowden</> +- <member>Bill Thompson</> +- <member>Frediano Ziglio</> +- </simplelist> +- <para> +- </para> ++<para></para> + </sect1> ++ ++ <sect1 id="Contributors"> ++ <title>Contributors</title> ++ ++<para>This user guide owes at least 100 words each to the following people.</para> ++ <simplelist> ++ <member>Brian Bruns</> ++ <member>James Cameron</> ++ <member>Allen Grace</> ++ <member>James K. Lowden</> ++ <member>Bill Thompson</> ++ <member>Frediano Ziglio</> ++ </simplelist> + ++<para></para> ++ </sect1> ++ + </chapter> ++ ++<!-- ////////////////// Appendix ////////////////// --> ++ ++<Appendix id="rutime.linker"> ++ <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="rutime.linker.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 — i.e. actual code implementing it — 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 ones </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 those that don't, 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 — a location — in the <firstterm>text</firstterm> of a module. (<quote>Text</quote> here refers to the machine code output by the compiler.) ++--> ++ </section> + +- <!-- ////////////////// Appendix ////////////////// --> ++ <section id="rutime.linker.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="rutime.linker.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 — containing functions, of course — 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="rutime.linker.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 — or the wrong versions of them — can lead to head-scratching and other amusing behavior. </para> ++ ++<para>In Windows® 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 the implementation of those same functions 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 & 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 frequently 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> + +- <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. ++ <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 first symbols 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 — functions provided by the C standard library — 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> +- </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. ++ </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> +- </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. ++ </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> + +- <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> ++Although these examples refer to static libraries, <command>nm</command> works just as well with dynamic libraries, too. ++</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> ++<para>There are other tools besides <command>nm</command>. Windows®, for instance, has <command>dumpbin</command>, and the GNU bintools include <command>objdump</command>. </para> ++ </section> + +- <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> ++ <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 funtion'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' ++…</computeroutput> ++</screen> + </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> ++ </section> + +- </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> ++ <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 — also known as the runtime linker — 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] ++…</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. All it does is report 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.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> ++ </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.</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</>: What everyone knows</title> +- <para> +-The world we are all familiar with, programmingwise, is <acronym>ASCII</>. Our email (mostly), our <quote>text</quote> files, our web pages (mostly), all use <acronym>ASCII</> to represent English (or English-like) text. Perhaps because <ulink url="http://czyborra.com/charsets/iso646.html"><acronym>ASCII</></ulink> <footnote><para>czyborra.com is offline at the time of this writing (December 2003). It contained good information, so it's still included here, in case it comes back to life. </para></footnote> was standardized back in 1972 by the ISO, it seems like the <quote>natural</quote> way to store information. But let's look under the hood a little bit, and examine our assumptions. +- </para> +- <para> +-Our so-called <quote>text</quote> files are nothing special, nothing but a little agreement we enter into with our operating system. The only reason we can <quote>read</quote> them with <command>cat</command> or <command>vi</command> is that the operating system and its tools are in on the agreement. A file is only a stream of bytes, after all, no more <quote>text</quote> than an executable. The only thing distinguishing a <quote>text</quote> file from any other, is our understanding to treat it like one. We agree that the number 65 will represent the letter <literal>A</literal>, 66, <literal>B</literal>, and so on, 127 values in all. See <command>man ascii</command> for further details. +- </para> +- <para> +-The important thing to understand is that the designation of 65 for <literal>A</literal> and so on is a choice. It's an <emphasis>encoding standard</emphasis>, made necessary by the old simple fact that computers store numbers, not letters. <acronym>ASCII</> is so ubiquitous these days that it's hard sometimes to remember there was a time when it was but one of a set of competing encoding standards. Others you probably have heard of include <acronym>EBCDIC</> and the Baudot systems, but they are by no means the only historical alternatives, nor the only modern ones. +- </para> ++<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</>: What everyone knows</title> ++ ++<para>The world we are all familiar with, programmingwise, is <acronym>ASCII</>. Our email (mostly), our <quote>text</quote> files, our web pages (mostly), all use <acronym>ASCII</> to represent English (or English-like) text. Perhaps because <ulink url="http://czyborra.com/charsets/iso646.html"><acronym>ASCII</></ulink> <footnote><para>czyborra.com is offline at the time of this writing (December 2003). It contained good information, so it's still included here, in case it comes back to life.</para></footnote> was standardized back in 1972 by the ISO, it seems like the <quote>natural</quote> way to store information. But let's look under the hood a little bit, and examine our assumptions.</para> ++ ++<para>Our so-called <quote>text</quote> files are nothing special, nothing but a little agreement we enter into with our operating system. The only reason we can <quote>read</quote> them with <command>cat</command> or <command>vi</command> is that the operating system and its tools are in on the agreement. A file is only a stream of bytes, after all, no more <quote>text</quote> than an executable. The only thing distinguishing a <quote>text</quote> file from any other, is our understanding to treat it like one. We agree that the number 65 will represent the letter <literal>A</literal>, 66, <literal>B</literal>, and so on, 127 values in all. See <command>man ascii</command> for further details.</para> ++ ++<para>The important thing to understand is that the designation of 65 for <literal>A</literal> and so on is a choice. It's an <emphasis>encoding standard</emphasis>, made necessary by the old simple fact that computers store numbers, not letters. <acronym>ASCII</> is so ubiquitous these days that it's hard sometimes to remember there was a time when it was but one of a set of competing encoding standards. Others you probably have heard of include <acronym>EBCDIC</> and the Baudot systems, but they are by no means the only historical alternatives, nor the only modern ones.</para> + <section id="ASCIICompact"><title>The <acronym>ASCII</> Compact</title> +- <para> +-UNIX® and unix-like systems bought into <acronym>ASCII</> big time. Program code, filenames, string constants (and variables), configuration files, everything but everything is encoded in <acronym>ASCII</>. Practically every utility, command, and library assumes the <quote>text</> data will be <acronym>ASCII</>. At the dawn of the 21<superscript>st</> century, there is widespread recognition that <acronym>ASCII</> will no longer suffice, but the art of upgrading all the computers and computer programmers is, well, an unfinished work. +- </para> +- </section> ++ ++<para>UNIX® and unix-like systems bought into <acronym>ASCII</> big time. Program code, filenames, string constants (and variables), configuration files, everything but everything is encoded in <acronym>ASCII</>. Practically every utility, command, and library assumes the <quote>text</> data will be <acronym>ASCII</>. At the dawn of the 21<superscript>st</> century, there is widespread recognition that <acronym>ASCII</> will no longer suffice, but the art of upgrading all the computers and computer programmers is, well, an unfinished work.</para> ++ </section> + </section> +- <section id="ISO8859"><title>ISO 8859: What everyone would like to forget</title> +- <para> +-<acronym>ASCII</> won, it would seem, but the race goes not to the swift. <acronym>ASCII</> has many limitations, the most egregious of which is, it's not much good for anything besides English. It encodes all the letters and punctuation (almost) of the English alphabet, but is useless for German, Russian, and Greek, to say nothing of Chinese. +- </para> +- <para> +-<acronym>ASCII</> assigns one byte to every character, but deals with only 7 of the 8 available bits, the range 0-127 (with the <quote>high bit</quote> always zero). Demand for computers that could display and print languages besides English — even English with em dashes and cent (¢) signs — arrived soon enough, with the Marketing Department way out in front of the propeller heads. The predictable result was an array of <quote>8-bit <acronym>ASCII</></quote> encoding standards for a wide variety of alphabets. Eventually, they were standardized (or at least enumerated and documented) by the ISO. These are what our friendly database vendors are referring to when they talk about <emphasis>character sets</emphasis>. More information on this subject can be found at <ulink url="http://www.webreference.com/dlab/books/html/39-1.html">webreference.com</ulink>. +- +- </para> +- <para> +-The upshot is, there is no uniform standard, no agreement on the meaning of a byte, particularly if that byte's value is greater than 127. Let's say your client machine sends <literal>HELLO</literal> and your database stores it as <literal>72 69 76 76 79</literal>. When another client retrieves that value, it will convert it into human-readable form by applying an encoding standard. If everything's tightly wrapped, it will use the very same encoding that your database used (and the same one you had in mind when you sent it), and that client will also see <literal>HELLO</literal>. If things are not so tightly wrapped but that client is fortunate enough to be using a similar standard to what you were using, say, ISO 8859-1, he'll still see <literal>HELLO</literal>. Most languages based on the Roman alphabet can be represented by ISO 8859-1, and are thus interchangeable. Beyond that, things get quickly messy. Greek clients, for one, are not so lucky: there are three ISO 8859 standards for Greek, all mutually incompatible. ++ <section id="ISO8859"><title>ISO 8859: What everyone would like to forget</title> + +-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> ++<para><acronym>ASCII</> won, it would seem, but the race goes not to the swift. <acronym>ASCII</> has many limitations, the most egregious of which is, it's not much good for anything besides English. It encodes all the letters and punctuation (almost) of the English alphabet, but is useless for German, Russian, and Greek, to say nothing of Chinese.</para> ++ ++<para><acronym>ASCII</> assigns one byte to every character, but deals with only 7 of the 8 available bits, the range 0-127 (with the <quote>high bit</quote> always zero). Demand for computers that could display and print languages besides English — even English with em dashes and cent (¢) signs — arrived soon enough, with the Marketing Department way out in front of the propeller heads. The predictable result was an array of <quote>8-bit <acronym>ASCII</></quote> encoding standards for a wide variety of alphabets. Eventually, they were standardized (or at least enumerated and documented) by the ISO. These are what our friendly database vendors are referring to when they talk about <emphasis>character sets</emphasis>. More information on this subject can be found at <ulink url="http://www.webreference.com/dlab/books/html/39-1.html">webreference.com</ulink>. </para> ++ ++<para>The upshot is, there is no uniform standard, no agreement on the meaning of a byte, particularly if that byte's value is greater than 127. Let's say your client machine sends <literal>HELLO</literal> and your database stores it as <literal>72 69 76 76 79</literal>. When another client retrieves that value, it will convert it into human-readable form by applying an encoding standard. If everything's tightly wrapped, it will use the very same encoding that your database used (and the same one you had in mind when you sent it), and that client will also see <literal>HELLO</literal>. If things are not so tightly wrapped but that client is fortunate enough to be using a similar standard to what you were using, say, ISO 8859-1, he'll still see <literal>HELLO</literal>. Most languages based on the Roman alphabet can be represented by ISO 8859-1, and are thus interchangeable. Beyond that, things get quickly messy. Greek clients, for one, are not so lucky: there are three ISO 8859 standards for Greek, all mutually incompatible. ++ ++ For more information, see <ulink url="http://czyborra.com/charsets/iso8859.html">ISO 8859 Alphabet Soup</ulink>. Roman Czyborra's site is very informative; take your time there if you don't want your head to spin.</para> ++ ++<para>Database servers need to know what encoding standard to employ, too. It's not obvious at first, but notions like <quote>uppercase</quote> and <quote>lowercase</quote>, trailing blanks, and collation rules all depend on what letter is meant by what number. (Collation even depends on what culture is interpreting the letters.)</para> + </section> +- <section id="Unicode"><title>Unicode: East meets West</title> +- <para> +-<acronym>ASCII</> and its 8-bit cousins are on the way out, and with them the assumption that a character can be represented by a single byte. The new kid on the block is <ulink url="http://www.unicode.org/">Unicode</ulink>, similar to but not precisely the same as ISO 10646. Unicode (despite its name) is a set of standards. The most widely implemented is the 16-bit form, called UCS-2. As you might guess, UCS-2 uses two bytes per character, allowing it to encode most characters of most languages. Because <quote>most</quote> is far from <emphasis>all</emphasis>, there are nascent 32-bit forms, too, but they are neither complete nor in common use. +- </para> +- <para> +-In the same sense that 7-bit <acronym>ASCII</> was extended to 8 bits, Unicode extends the most prevalent <quote>8-bit <acronym>ASCII</></quote>, <acronym>ISO 8859-1</>, to 16 and 32 bits. The first 256 values remain in Unicode as in <acronym>ISO 8859-1</>: 65 is still <literal>A</literal>, except instead of being 8 bits (0x40), it's 16 bits (0x0040). Unlike the 8-bit extensions, Unicode has a unique 1:1 map of numbers to characters, so no language context or <quote>character set</quote> name is needed to decode a Unicode string. +- </para> +- <para> +-UCS-2 is the system employed by Microsoft NT-based systems. Microsoft database servers store UCS-2 strings in <type>nchar</type> and <type>nvarchar</type> datatypes. Microsoft also designed version 7.0 (and up) of the <acronym>TDS</> protocol around UCS-2: all metadata (table names and such) are encoded according to UCS-2 on the wire. +- </para> ++ <section id="Unicode"><title>Unicode: East meets West</title> ++ ++<para><acronym>ASCII</> and its 8-bit cousins are on the way out, and with them the assumption that a character can be represented by a single byte. The new kid on the block is <ulink url="http://www.unicode.org/">Unicode</ulink>, similar to but not precisely the same as ISO 10646. Unicode (despite its name) is a set of standards. The most widely implemented is the 16-bit form, called UCS-2. As you might guess, UCS-2 uses two bytes per character, allowing it to encode most characters of most languages. Because <quote>most</quote> is far from <emphasis>all</emphasis>, there are nascent 32-bit forms, too, but they are neither complete nor in common use.</para> ++ ++<para>In the same sense that 7-bit <acronym>ASCII</> was extended to 8 bits, Unicode extends the most prevalent <quote>8-bit <acronym>ASCII</></quote>, <acronym>ISO 8859-1</>, to 16 and 32 bits. The first 256 values remain in Unicode as in <acronym>ISO 8859-1</>: 65 is still <literal>A</literal>, except instead of being 8 bits (0x40), it's 16 bits (0x0040). Unlike the 8-bit extensions, Unicode has a unique 1:1 map of numbers to characters, so no language context or <quote>character set</quote> name is needed to decode a Unicode string.</para> ++ ++<para>UCS-2 is the system employed by Microsoft NT-based systems. Microsoft database servers store UCS-2 strings in <type>nchar</type> and <type>nvarchar</type> datatypes. Microsoft also designed version 7.0 (and up) of the <acronym>TDS</> protocol around UCS-2: all metadata (table names and such) are encoded according to UCS-2 on the wire.</para> + </section> +- <section id="Unicodegoodbad"><title>Unicode's Pluses and Minuses</title> +- <para> +-You will read from time to time that Unicode is not perfect. Surprise, surprise: it's true. From a linguistic point of view, Unicode is incomplete; in particular, UCS-2 is demonstrably too small (!) to hold all the forms of Chinese ideographs used over the centuries. (It is, however, quite useful and widely employed in representing modern Chinese.) Of more common concern to programmers are Unicode's technical problems, or rather, Unix's technical shortcomings <foreignphrase>vis-a-vis</foreignphrase> any encoding more complex than <acronym>ISO 8859-x</>. +- </para> +- <para> +-The basic problem, from a programmer's perspective, is the ancient agreement Unix entered into 30 years ago, the <quote><acronym>ASCII</> Compact,</quote> alluded to earlier. Assumptions about <acronym>ASCII</> are littered throughout Unix-like systems, beginning with C's convention of representing strings as arrays of characters ending in a zero. Returning to our HELLO example earlier, C will store <literal>HELLO</literal> as <literal>72 69 76 76 79 0</literal>, in very nice <acronym>ASCII</>. Many many parts of the operating system and its associated tools and applications will recognize that as a 5-letter word because it's terminated by a null (zero). In UCS-2 Unicode, though, that same <literal>HELLO</literal> uses 2 bytes for every character and becomes <literal>72 0 69 0 76 0 76 0 79 0 0 0</literal>. Practically the whole OS will think that's a 1-letter word, <quote>H</quote>. Not a good thing. +- </para> +- <para> +-Even if every OS were magically rid of all <acronym>ASCII</> assumptions and C strings, there would still be the problem of Endianism. <ulink url="http://whatis.techtarget.com/definition/0,,sid9_gci211659,00.html">Technical</ulink> <ulink url="http://www.noveltheory.com/TechPapers/endian.asp">explanations</ulink> on the subject are not hard to find. The long and short of it is, given a 16-bit integer (2 bytes), different hardware architectures will store the value differently. Asked to store our friend <quote>A</quote>, (0x41), for instance, a Sparc processor will put the least significant byte at the higher address (00 41) whereas an Intel processor will put it in the lower address (41 00). Put aside the questions of left, right, and wrong; architectures are a fact of life. Endianism shows up wherever integers are stored and retrieved in heterogeneous environments. +- </para> +- <para> +-The Unicode folks knew about Endianism, of course, and had to address it. A Unicode bytestream is supposed to begin with a byte-order mark. Needless to say, perhaps, many don't. +- </para> ++ <section id="Unicodegoodbad"><title>Unicode's Pluses and Minuses</title> ++ ++<para>You will read from time to time that Unicode is not perfect. Surprise, surprise: it's true. From a linguistic point of view, Unicode is incomplete; in particular, UCS-2 is demonstrably too small (!) to hold all the forms of Chinese ideographs used over the centuries. (It is, however, quite useful and widely employed in representing modern Chinese.) Of more common concern to programmers are Unicode's technical problems, or rather, Unix's technical shortcomings <foreignphrase>vis-a-vis</foreignphrase> any encoding more complex than <acronym>ISO 8859-x</>.</para> ++ ++<para>The basic problem, from a programmer's perspective, is the ancient agreement Unix entered into 30 years ago, the <quote><acronym>ASCII</> Compact,</quote> alluded to earlier. Assumptions about <acronym>ASCII</> are littered throughout Unix-like systems, beginning with C's convention of representing strings as arrays of characters ending in a zero. Returning to our HELLO example earlier, C will store <literal>HELLO</literal> as <literal>72 69 76 76 79 0</literal>, in very nice <acronym>ASCII</>. Many many parts of the operating system and its associated tools and applications will recognize that as a 5-letter word because it's terminated by a null (zero). In UCS-2 Unicode, though, that same <literal>HELLO</literal> uses 2 bytes for every character and becomes <literal>72 0 69 0 76 0 76 0 79 0 0 0</literal>. Practically the whole OS will think that's a 1-letter word, <quote>H</quote>. Not a good thing.</para> ++ ++<para>Even if every OS were magically rid of all <acronym>ASCII</> assumptions and C strings, there would still be the problem of Endianism. <ulink url="http://whatis.techtarget.com/definition/0,,sid9_gci211659,00.html">Technical</ulink> <ulink url="http://www.noveltheory.com/TechPapers/endian.asp">explanations</ulink> on the subject are not hard to find. The long and short of it is, given a 16-bit integer (2 bytes), different hardware architectures will store the value differently. Asked to store our friend <quote>A</quote>, (0x41), for instance, a Sparc processor will put the least significant byte at the higher address (00 41) whereas an Intel processor will put it in the lower address (41 00). Put aside the questions of left, right, and wrong; architectures are a fact of life. Endianism shows up wherever integers are stored and retrieved in heterogeneous environments.</para> ++ ++<para>The Unicode folks knew about Endianism, of course, and had to address it. A Unicode bytestream is supposed to begin with a byte-order mark. Needless to say, perhaps, many don't.</para> + </section> +- <section id="UnicodeUtf"><title>Unicode Transformation Format: UTF-8</title> +- <para> +-The presence of nulls embedded in character data and of byte order issues make straight Unicode i.e., UCS-2 or UCS-4 hard to work with in a heterogeneous environment. Too many opportunities arise for the data to be truncated or misinterpreted, and too many systems would fail even to transmit such data. In short, when 16-bit data are thrust into a multi-architecture 8-bit world, it frequently bodes ill for the data. +- </para> +- <para> +-To answer that problem, to make Unicode transmissible and unambiguous to most machines, several <quote>transformation formats</quote> were adopted. Their goals were generally similar: to create a generally recognized format that would unambiguously and safely convey Unicode information between machines and across the Internet. To do that, they sought to remove nulls and endianism from the data stream. The most popular one — practically the only one used — is known as UTF-8. +- </para> +- <para> +-UTF-8 found wide acceptance for many reasons. UTF-8 represents any Unicode character as a combination of 1-4 bytes. The number of bytes required depends on the integer value of the Unicode character, and only one byte is used to represent the old <acronym>ASCII</> range (0-127). UTF-8 does not use zero to represent any part of any character (except for the <acronym>ASCII</> NUL). In consequence, UTF-8 is efficient with respect to space, has no endianism issues, and embeds no nulls. UTF-8 strings can be treated as plain old <acronym>ASCII</> strings. These properties make UTF-8 data relatively easy for systems accustomed to processing <acronym>ASCII</> data. +- </para> +- <para> +-Here's a small example showing the difference between UCS-2 and UTF-8. ++ <section id="UnicodeUtf"><title>Unicode Transformation Format: UTF-8</title> ++ ++<para>The presence of nulls embedded in character data and of byte order issues make straight Unicode i.e., UCS-2 or UCS-4 hard to work with in a heterogeneous environment. Too many opportunities arise for the data to be truncated or misinterpreted, and too many systems would fail even to transmit such data. In short, when 16-bit data are thrust into a multi-architecture 8-bit world, it frequently bodes ill for the data.</para> ++ ++<para>To answer that problem, to make Unicode transmissible and unambiguous to most machines, several <quote>transformation formats</quote> were adopted. Their goals were generally similar: to create a generally recognized format that would unambiguously and safely convey Unicode information between machines and across the Internet. To do that, they sought to remove nulls and endianism from the data stream. The most popular one — practically the only one used — is known as UTF-8.</para> ++ ++<para>UTF-8 found wide acceptance for many reasons. UTF-8 represents any Unicode character as a combination of 1-4 bytes. The number of bytes required depends on the integer value of the Unicode character, and only one byte is used to represent the old <acronym>ASCII</> range (0-127). UTF-8 does not use zero to represent any part of any character (except for the <acronym>ASCII</> NUL). In consequence, UTF-8 is efficient with respect to space, has no endianism issues, and embeds no nulls. UTF-8 strings can be treated as plain old <acronym>ASCII</> strings. These properties make UTF-8 data relatively easy for systems accustomed to processing <acronym>ASCII</> data.</para> ++ ++<para>Here's a small example showing the difference between UCS-2 and UTF-8. + <example id="e.g.HELLO"> +-<title><quote>HELLO</quote> in UCS-2 and UTF-8</title> ++ <title><quote>HELLO</quote> in UCS-2 and UTF-8</title> + <screen> +-$ <userinput>echo HELLO | iconv -f ascii -t UCS-2 | hexdump -C</userinput> +-00000000 00 48 00 45 00 4c 00 4c 00 4f 00 0a |.H.E.L.L.O..| +-0000000c +-$ <userinput>echo HELLO | iconv -f ascii -t utf-8 | hexdump -C</userinput> +-00000000 48 45 4c 4c 4f 0a |HELLO.| +-00000006 +-$ <userinput>echo HELLO | hexdump -C</userinput> +-00000000 48 45 4c 4c 4f 0a |HELLO.| +-00000006 +-</screen> +- </example> +-It is the similarity of the last two outputs that makes UTF-8 so attractive. It behaves like <acronym>ASCII</> when <acronym>ASCII</>'s all that's needed. But it lacks <acronym>ASCII</>'s limitations. </para> +- <para> +-While UTF-8 solves many technical problems, it doesn't magically transform every <acronym>ASCII</>-assuming system into a Unicode system. For example, to display Unicode data correctly — even Unicode data in UTF-8 format — the system still needs a suitable font. And it must distinguish the buffer size (and byte count) from the character count. +- </para> ++ $ <userinput>echo HELLO | iconv -f ascii -t UCS-2 | hexdump -C</userinput> ++ 00000000 00 48 00 45 00 4c 00 4c 00 4f 00 0a |.H.E.L.L.O..| ++ 0000000c ++ $ <userinput>echo HELLO | iconv -f ascii -t utf-8 | hexdump -C</userinput> ++ 00000000 48 45 4c 4c 4f 0a |HELLO.| ++ 00000006 ++ $ <userinput>echo HELLO | hexdump -C</userinput> ++ 00000000 48 45 4c 4c 4f 0a |HELLO.| ++ 00000006</screen> ++ </example> ++ It is the similarity of the last two outputs that makes UTF-8 so attractive. It behaves like <acronym>ASCII</> when <acronym>ASCII</>'s all that's needed. But it lacks <acronym>ASCII</>'s limitations.</para> ++ ++<para>While UTF-8 solves many technical problems, it doesn't magically transform every <acronym>ASCII</>-assuming system into a Unicode system. For example, to display Unicode data correctly — even Unicode data in UTF-8 format — the system still needs a suitable font. And it must distinguish the buffer size (and byte count) from the character count.</para> + </section> +- <section id="UnicodeFreeTDS"><title>Unicode and FreeTDS</title> +- <para> +-Microsoft servers using TDS 7.0 and above (anything since SQL Server 6.5) transmit their data in UCS-2 format (16-bit integers). Because most applications linked to &freetds; are not prepared to deal with UCS-2 data, &freetds; can convert the data to something more acceptable, including <acronym>ASCII</>. 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. +- </para> +- <para> +-Sybase servers, by the way, adhere to a <quote>server makes right</quote> policy: they transmit their data in whatever character set the client requested at login time. The list of available character sets is fairly short, but includes UTF-8. While <productname>FreeTDS</> <emphasis>could</> convert Sybase data streams as easily as it does Microsoft data streams, to our knowledge no one is doing so. The Sybase server can perform the conversion itself, making <productname>FreeTDS</>'s capability in this regard largely redundant and irrelevant. +- </para> +- <section id="moreinfo"><title>For further information</title> +-<simplelist type=vert columns=1> +- <member><ulink url="http://www.cl.cam.ac.uk/~mgk25/unicode.html">UTF-8 and Unicode FAQ for Unix/Linux</ulink>, by Markus Kuhn. As the man says, very comprehensive. </member> +- <member><ulink url="http://www.wps.com/projects/codes/">ASCII: American Standard Code for Information Infiltration</ulink>, by Tom Jennings. Everything you ever wanted know about ASCII, but didn't know whom to ask. </member> +- <member><ulink url="http://tronweb.super-nova.co.jp/characcodehist.html">A Brief History of Character Codes</ulink>, by Steven J. Searle. Includes useful references. </member> +- <member><ulink url="http://www.unicode.org/">Unicode Home Page</ulink>. </member> +- <!--member><ulink url=""></ulink>. </member --> +-</simplelist> +- +- ++ <section id="UnicodeFreeTDS"><title>Unicode and FreeTDS</title> ++ ++<para>Microsoft servers using TDS 7.0 and above (anything since SQL Server 6.5) transmit their data in UCS-2 format (16-bit integers). Because most applications linked to &freetds; are not prepared to deal with UCS-2 data, &freetds; can convert the data to something more acceptable, including <acronym>ASCII</>. 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.</para> ++ ++<para>Sybase servers, by the way, adhere to a <quote>server makes right</quote> policy: they transmit their data in whatever character set the client requested at login time. The list of available character sets is fairly short, but includes UTF-8. While <productname>FreeTDS</> <emphasis>could</> convert Sybase data streams as easily as it does Microsoft data streams, to our knowledge no one is doing so. The Sybase server can perform the conversion itself, making <productname>FreeTDS</>'s capability in this regard largely redundant and irrelevant.</para> ++ <section id="moreinfo"><title>For further information</title> ++ <simplelist type=vert columns=1> ++ <member><ulink url="http://www.cl.cam.ac.uk/~mgk25/unicode.html">UTF-8 and Unicode FAQ for Unix/Linux</ulink>, by Markus Kuhn. As the man says, very comprehensive. </member> ++ <member><ulink url="http://www.wps.com/projects/codes/">ASCII: American Standard Code for Information Infiltration</ulink>, by Tom Jennings. Everything you ever wanted know about ASCII, but didn't know whom to ask. </member> ++ <member><ulink url="http://tronweb.super-nova.co.jp/characcodehist.html">A Brief History of Character Codes</ulink>, by Steven J. Searle. Includes useful references. </member> ++ <member><ulink url="http://www.unicode.org/">Unicode Home Page</ulink>. </member> ++<!--member><ulink url=""></ulink>. </member --> ++ </simplelist> ++ + </section> + </section> + </Appendix> + <appendix id="gfdl"> +-<title>GNU Free Documentation License</title> ++ <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"> + +- <!-- 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>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>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>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>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> ++<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> ++ + +-</appendix> ++<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