FreeTDS User Guide

A Guide to Installing, Configuring, and Running FreeTDS

Brian Bruns

James K. Lowden

Copyright © 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 Brian Bruns and James K. Lowden

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 GNU Free Documentation License.

Table of Contents
About this User Guide
1. What is FreeTDS?
Background: The TDS Protocol and related APIs
History of TDS Versions
History of FreeTDS
Current Projects, Language Bindings, and Alternatives
Current Projects
Status
Languages besides C and Java
Alternatives
2. Build FreeTDS
The GNU World
What to build: Packages, Tarballs, and the CVS repository
How to build: Configure and make
For Experts
For Everyone Else
OS-specific Issues
VMS®
OS X®
AIX®
GNU/Linux distributions that use RPMs
3. Install FreeTDS
The local environment
Choosing a TDS protocol version
The freetds.conf file
What it does
Where it goes
What it looks like
The locales.conf file
What it does
Where it goes
What it looks like
Setting the environment variables
What they're for
Setting environment variables
Checking your work
Port override syntax
Confirm the installation
tsql
Unit Tests
4. Preparing ODBC
Background and Terminology
Connection attributes
DSN-less configuration
ODBC-only configuration
ODBC-combined configuration
Troubleshooting ODBC connections
With iODBC
With unixODBC
5. Advanced Configurations
Big Endian Clients with Buggy SQL Servers
Localization and TDS 7.0
Domain Logins
Implementation details
Appending Dump Files
TDS Connection Pooling
stunnel HOWTO
6. Use FreeTDS
FreeTDS Utilities
7. How to get what works with it working
SQSH
Perl
DBD::Sybase
DBD::ODBC
Sybperl
Building and using the Perl modules
PHP
db-lib
ct-lib
ODBC
SybSQL
Python
8. Troubleshooting
Known Issues
Text Fields
Endianism
Datetime and Money
Microsoft's "Integrated Security"
Is the server there?
Start with ping
Test with telnet
Test with tsql
Logging
Environment Variables that Control Logging
freetds.conf variables that Control Logging
Logging in ODBC land
"Page contains no data"
Slow connection or data retrieval
9. Getting Help
Isolate the cause
Try a different client
The Mailing List
The Archive
Ask the list
What to include when asking for help
Waddya got?
Attach a logfile
Help the Help
10. Helping
Pick a weak spot and fix it.
Send a patch
Correct this User Guide
Document an API
Be the Webmaster
Advocacy
11. Programming
TDS protocol reference
API Reference Manual
db-lib API Implementation Summary
ct-lib API Implementation Summary
ODBC API Implementation Summary
DB-Library for the Tenderfoot
Header files
Prolog
Initialize
Connect to the server
Send a query
Fetch Results
Messages and Errors
Last Remarks
12. Acknowledgments
Codesmyths
Contributors
A. The interfaces File
Where it came from
Where it goes
What it does
What it looks like
B. About Unicode, UCS-2, and UTF-8
ASCII: What everyone knows
The ASCII Compact
ISO 8859: What everyone would like to forget
Unicode: East meets West
Unicode's Pluses and Minuses
Unicode Transformation Format: UTF-8
Unicode and FreeTDS
For further information
C. GNU Free Documentation License
PREAMBLE
APPLICABILITY AND DEFINITIONS
VERBATIM COPYING
COPYING IN QUANTITY
MODIFICATIONS
COMBINING DOCUMENTS
COLLECTIONS OF DOCUMENTS
AGGREGATION WITH INDEPENDENT WORKS
TRANSLATION
TERMINATION
FUTURE REVISIONS OF THIS LICENSE
How to use this License for your documents
List of Tables
3-1. Versions of the TDS Protocol, by Product
3-2. freetds.conf settings
3-3. Valid bitmask values for debug flags entry in freetds.conf
4-1. Connection attributes used only in connection strings
4-2. Connection attributes that may appear in odbc.ini
5-1. pool.conf settings
11-1. db-lib API Implementation Summary
11-2. ct-lib API Implementation Summary
11-3. ODBC API Implementation Summary
11-4. Kinds of Results
11-5. Result-fetching functions
11-6. Data-fetching functions
11-7. Putting it all together
A-1. Services Line
List of Examples
3-1. A freetds.conf file example
3-2. Failing to connect with tsql
3-3. Connect with tsql using a servername in freetds.conf
3-4. Connect with tsql using a hostname and port number
3-5. Show compile-time settings with tsql
4-1. Sample files for a DSN-less configuration
4-2. Connecting with a DSN-less configuration
4-3. Connecting with a DSN-less configuration that does not use freetds.conf
4-4. Sample ODBC-only odbc.ini file
4-5. Sample ODBC-combined odbc.ini file
4-6. Sample ODBC-combined freetds.conf file
4-7. Compile odbctest without a driver manager.
5-1. Emulate Little Endian freetds.conf setting
5-2. Configuring for GREEK freetds.conf setting
5-3. Configuring for UTF-8 freetds.conf setting
5-4. Logging in with a domain login
5-5. Turning on Dump File Append mode in freetds.conf
5-6. pool.conf
5-7. Unencrypted entry in freetds.conf
5-8. Encrypted entry in freetds.conf
7-1. The SQSH Makefile
7-2. Building DBD::Sybase
7-3. Connect to a server with DBD::Sybase
7-4. Building DBD::ODBC
7-5. Connect to a server with DBD::ODBC
7-6. PHP and db-lib for "Sybase"
8-1. Finding the server's host
8-2. Finding the server
8-3. Connecting to the server, bypassing freetds.conf
8-4. Connecting to the server using freetds.conf
11-1. Building the Sample Code
11-2. Sample Code: db-lib header files
11-3. Sample Code: db-lib prolog
11-4. Sample Code: db-lib Initialize
11-5. Sample Code: db-lib Connect to the server
11-6. Sample Code: db-lib Send a query
11-7. Sample Code: db-lib Fetch Results
11-8. Sample Code: db-lib Error and Message handlers
A-1. An interfaces file example
B-1. "HELLO" in UCS-2 and UTF-8
  Next
  About this User Guide