.\" cf. groff_mdoc
.Dd April 26, 2012
.Os FreeTDS 1.4.22
.Dt OSQL FreeTDS "FreeTDS Reference Manual"
.\"
.Sh NAME
.Nm osql
.Nd utility to test FreeTDS connections and queries
.\"
.Sh SYNOPSIS
.Pp
.Nm
.Fl S Ar dsn 
.Fl U Ar username
.Fl P Ar password
.Op Fl I Pa ini_directory
.\"
.Sh DESCRIPTION
.Pp
.Nm
is a diagnostic tool provided as part of FreeTDS. It is a
Bourne shell script that checks and reports on your configuration
files. If everything checks out OK, it invokes isql.
.Pp
.Nm
works only with the isql that comes with unixODBC.
.\"
.Sh OPTIONS
.Bl -tag -width indent
.It Fl S Ar dsn
the Data Source Name to which to connect, as known to 
.Pa odbc.ini Ns .
.It Fl U Ar username
database
login name.
.It Fl P Ar password
database password.
.It Fl I Ar ini_dir
override
.Pa odbc.ini
file location.
.El
.\"
.Sh EXAMPLE
If you have an
.Pa odbc.ini
with a section like this:
.Bd -literal -offset indent
.Bq myDSN
servername = myserver
TDS_Version = 5.0
.Ed
.Pp
You would invoke 
.Nm
as:
.Pp
.Li osql -S myDSN 
.Op .\|.\|.\&
.\"
.Sh FILES
.Pa odbc.ini
.Pa freetds.conf
.\"
.Sh NOTES
If you can connect with
.Ql osql -S servername -U user -P passwd Ns ,
your FreeTDS ODBC installation is working.
.Pp
.Nm
guesses where unixODBC might look for its
.Pa odbc.ini
by examining the binary. This is not always an effective approach. If
it doesn't work, you'll receive a report of candidate strings. Kindly
pass along the output to help improve the guessing.  
.Pp
If
.Nm
cannot intuit your
.Pa odbc.ini
directory, you can force the issue with
the 
.Fl I
option. However, you're then instructing 
.Nm
what to test, not where unixODBC will eventually look. Your override
is therefore only as good as you are. Look carefully at the error
output before overriding.  
.Pp
If you have suggestions for ways to make
.Nm
more useful as a diagnostic tool, please post them to the FreeTDS
mailing list.
.\"
.Sh HISTORY
.Nm
first appeared in FreeTDS 0.65.
.\"
.Sh AUTHORS
The 
.Nm
utility was written by 
.An James K. Lowden Ns .