FreeTDS User Guide

A Guide to Installing, Configuring, and Running FreeTDS

Brian Bruns

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
How to build: Configure and make
For Experts
For Everyone Else
OS-specific Issues
VMS®
OS X®
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
Configurations that Work
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
TDS 7.0 for Nonwestern Languages
Domain Logins
Implementation details
Appending Dump Files
TDS Connection Pooling
stunnel HOWTO
6. 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
7. Troubleshooting
Known Issues
Text Fields
Endianism
Datetime and Money
dbopen Conflicts with dbm
Microsoft's "Integrated Security"
Is the server there?
Start with ping
Test with telnet
Test with tsql
Logging
Environment Variables that Control Logging
"Page contains no data"
Slow connection or data retrieval
8. Getting Help
Isolate the cause
The Mailing List
The Archive
Ask the list
What to include when asking for help
Waddya got?
What Happened?
Help the Help
9. Helping
Pick a weak spot and fix it.
Send a patch
Correct this User Guide
Document an API
Add to the FAQ
Advocacy
10. Programming
TDS protocol reference
API Reference Manual
db-lib API Implementation Summary
ct-lib API Implementation Summary
ODBC API Implementation Summary
Examples [future reference]
11. 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. Deprecated freetds.conf settings
3-4. Combinations of FreeTDS Clients and Servers (April 2001)
4-1. Connection attributes
5-1. pool.conf settings
10-1. db-lib API Implementation Summary
10-2. ct-lib API Implementation Summary
10-3. ODBC API Implementation Summary
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
6-1. The SQSH Makefile
6-2. Building DBD::Sybase
6-3. Connect to a server with DBD::Sybase
6-4. Building DBD::ODBC
6-5. Connect to a server with DBD::ODBC
6-6. PHP and db-lib for "Sybase"
7-1. Finding the server's host
7-2. Finding the server
7-3. Connecting to the server, bypassing freetds.conf
7-4. Connecting to the server using freetds.conf
A-1. An interfaces file example
B-1. "HELLO" in UCS-2 and UTF-8