FreeTDS™ User Guide
   Next

FreeTDS
 User Guide

A Guide to Installing, Configuring, and Running FreeTDS

Brian Bruns

James K. Lowden

Frediano Ziglio

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

Copyright © 2015, 2016, 2017, 2018, 2019, 2020, 2021, 2022, 2023 Frediano Ziglio

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
Alternatives
2. Build FreeTDS™
The GNU World
What to build: Packages, Tarballs, and the git™ repository
How to build: Configure and make
For Experts
(FreeTDS™ for Dummies?)
OS-specific Issues
Win32 and Win64
VMS®
OS X®
AIX®
GNU/Linux distributions that use RPMs
3. Install FreeTDS™
The local environment
Choosing a TDS protocol version
Choosing protocol version since FreeTDS™ 1.1
Choosing protocol version before FreeTDS™ 1.1
Regarding obsolete versions
servername Lookup
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
Environment variables
What they're for
Setting environment variables
Checking your work
Port/instance 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
Localization and TDS 7.0
Microsoft Server Note
Domain Logins
Implementation details
Kerberos Support
Threading in unixODBC
Appending Dump Files
TDS Connection Pooling
6. Use FreeTDS™
FreeTDS™ Utilities
7. How to get what works with it working
SQSH
Perl
DBD::ODBC
DBD::Sybase
Sybperl
Building and using the Perl modules
PHP
DB-Library
CT-Library
ODBC
Python
pymssql
Sybase module
Qt
ODBC on Unix
ODBC and 64-bit
sizeof(SQLWCHAR)
Default charset
8. Troubleshooting
Known Issues
Porting Issues
Text Fields
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
Reconfirm the installation
Isolate the cause
Try a different client
Check permissions
The Mailing List
The Archive
Ask the list
What to include when asking for help
Waddya got?
Attach a logfile
Show your work
10. Helping
Pick a weak spot and fix it.
Send a patch
Correct this User Guide
Document an API
Be the Webmaster
Light another's taper
Ambitious ideas
libtds2
libstddb
Server code
Advocacy
11. Programming
TDS protocol reference
API Reference Manual
DB-Library 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. On Linkers
What is a C function?
What is a C library?
Static libraries
Dynamic libraries
Checking if a Library Provides a Function
How Dost Thy Linker Link?
Static Linker
Dynamic Linker
Keep in Mind
B. The interfaces File
Where it came from
Where it goes
What it does
What it looks like
C. 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
D. 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. What Version of the TDS Protocol Should I use with Microsoft SQL Server?
3.3. freetds.conf settings
3.4. 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-Library API Implementation Summary
11.2. CT-Library 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
B.1. Services Line

List of Examples

3.1. A freetds.conf file example
3.2. Show compile-time settings with tsql
3.3. Failure to find servername in freetds.conf
3.4. Failure to resolve hostname for servername
3.5. Failing to connect with tsql
3.6. Getting instance information with tsql
3.7. Using the wrong protocol for the server
3.8. Login failure
3.9. Connect with tsql using a hostname and port number
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.
4.8. Use osql to test the ODBC setup.
5.1. Configuring for GREEK freetds.conf setting
5.2. Configuring for UTF-8 freetds.conf setting
5.3. Logging in with a domain login
5.4. Sample odbcinst.ini for threading model
5.5. Sample odbc.ini for threading model
5.6. Turning on Dump File Append mode in freetds.conf
5.7. pool.conf
7.1. The SQSH Makefile
7.2. Building DBD::ODBC
7.3. Connect to a server with DBD::ODBC
7.4. Building DBD::Sybase
7.5. Connect to a server with DBD::Sybase
7.6. PHP and DB-Library 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-Library header files
11.3. Sample Code: DB-Library prolog
11.4. Sample Code: DB-Library Initialize
11.5. Sample Code: DB-Library Connect to the server
11.6. Sample Code: DB-Library Send a query
11.7. Sample Code: DB-Library Fetch Results
11.8. Sample Code: DB-Library Error and Message handlers
A.1. Missing library name
A.2. Library not found
B.1. An interfaces file example
C.1. “HELLO” in UCS-2 and UTF-8
   Next
   About this User Guide