FreeTDS User Guide: A Guide to Installing, Configuring, and Running FreeTDS
Prev | Chapter 3. Install FreeTDS | Next

# Confirm the installation

## tsql

The tsql utility is provided as part of FreeTDS expressly for troubleshooting. tsql is superficially similar to an isql, but uses `libtds` directly, bypassing the client libraries (e.g., db-lib).

tsql can either use or bypass the configuration files. By trying both options, you can usually determine if it's your dataserver that's not responding, or your configuration files that are messed up.

### Using `freetds.conf`:

tsql {-S`server`} {-U`username`} [-P`password`] [-C]

Example 3-2. Failing to connect with tsql

    $ tsql -S emforester -U sa   #only connect?
    Password:
    src/tds/login.c: tds_connect: 192.168.1.12:4100: Connection refused
    Msg 20009, Level 9, State 0, Server OpenClient, Line 0
    Server is unavailable or does not exist.
    There was a problem connecting to the server

Example 3-3. Connect with tsql using a servername in `freetds.conf`

    $ tsql -S sandbox -U sa
    Password:
    1>

### Bypassing `freetds.conf`:

tsql {-H `hostname`} {-p `port`} {-U `username`} [-P`password`] [-C]

Keep in mind that the TDS protocol version normally comes from `freetds.conf`. When using tsql this way, the library uses the compiled-in default (set by the `configure` script). If that's not what you want, override it using the `TDSVER` environment variable.

Example 3-4. Connect with tsql using a hostname and port number

    $ TDSVER=7.0 tsql -H hillary -p 4100 -U sa
    Password:
    1>

Another handy diagnostic feature of tsql is that it can show you the compile-time settings of the installed version of FreeTDS:

Example 3-5. Show compile-time settings with tsql

    $ tsql -C
    Password:
    locale is "C"
    locale charset is "646"
    Compile-time settings (established with the "configure" script):
                               Version: freetds v0.62.dev.20030804
        MS db-lib source compatibility: no
           Sybase binary compatibility: unknown
                         Thread safety: no
                         iconv library: no
                           TDS version: 7.0
                                 iODBC: no
                              unixodbc: no

For details on tsql, see the its man page.

## Unit Tests

The source code directory of each FreeTDS library includes a `unittests` directory.

    $ ls -d -1 src/*/unittests
    src/ctlib/unittests
    src/dblib/unittests
    src/odbc/unittests
    src/tds/unittests

The unit tests rely on the `PWD` file in root of the FreeTDS source tree. `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 `README`.

To invoke the tests, edit the `PWD` file and issue the command make check. In order to execute all tests successfully, you must indicate a working, available dataserver in `PWD`. Some tests require permission to create stored procedures on server.

To complete successfully, the ODBC tests require some additional setup. In your `PWD` file, add a `SRV` entry specifying the DSN entry for your `odbc.ini`. The ODBC tests all build their own `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.

| The `PWD` provided by FreeTDS includes usernames and passwords that probably don't exist on your server.

Prev | Home | Next
Port override syntax | Up | Preparing ODBC