JezK
Edit File: ConfirmInstall.html
<?xml version="1.0" encoding="UTF-8" standalone="no"?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Confirm the installation</title><link rel="stylesheet" type="text/css" href="userguide.css" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="home" href="index.html" title="FreeTDS User Guide" /><link rel="up" href="install.html" title="Chapter 3. Install FreeTDS" /><link rel="prev" href="PortOverride.html" title="Port/instance override syntax" /><link rel="next" href="prepodbc.html" title="Chapter 4. Preparing ODBC" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Confirm the installation</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="PortOverride.html">Prev</a> </td><th width="60%" align="center">Chapter 3. Install <span class="productname">FreeTDS</span></th><td width="20%" align="right"> <a accesskey="n" href="prepodbc.html">Next</a></td></tr></table><hr /></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ConfirmInstall"></a>Confirm the installation</h2></div></div></div><p>We want to make sure that when your application requests a connection to your server, it actually works. In detail, we want to know: </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><span class="productname">FreeTDS</span> can find and read <code class="filename">freetds.conf</code></p></li><li class="listitem"><p><em class="replaceable"><code>servername</code></em> exists in <code class="filename">freetds.conf</code></p></li><li class="listitem"><p>a <em class="replaceable"><code>host</code></em> property exists for <em class="replaceable"><code>servername</code></em></p></li><li class="listitem"><p><em class="replaceable"><code>host</code></em> can be resolved to a network address</p></li><li class="listitem"><p>the server is listening to the <em class="replaceable"><code>port</code></em> or named <em class="replaceable"><code>instance</code></em></p></li><li class="listitem"><p>the user can log in to the server</p></li></ul></div><p> Each of the above can be confirmed independently with tsql. Once you're sure you can connect and log in, you can run the unit tests to see if the software works as promised.</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="tsql"></a><span class="application">tsql</span></h3></div></div></div><p>The <em class="firstterm">tsql</em> utility is provided as part of <span class="productname">FreeTDS</span> expressly for troubleshooting. <span class="command"><strong>tsql</strong></span> is superficially similar to an <span class="command"><strong>isql</strong></span>, but uses <code class="filename">libtds</code> directly, bypassing the client libraries (e.g., <code class="systemitem">DB-Library</code>). It can also report where it looks for <code class="filename">freetds.conf</code> and other compile-time settings (with <span class="command"><strong>tsql -C</strong></span>).</p><div class="example"><a id="e.g.tsqlShowsettings"></a><p class="title"><strong>Example 3.2. Show compile-time settings with <span class="command">tsql</span></strong></p><div class="example-contents"><pre class="screen"> <code class="prompt">$ </code><strong class="userinput"><code>tsql -C </code></strong> <code class="prompt">Password: </code> <code class="computeroutput">Compile-time settings (established with the "configure" script) Version: freetds v1.3 freetds.conf directory: /usr/local/etc MS db-lib source compatibility: no Sybase binary compatibility: no Thread safety: yes iconv library: yes TDS version: auto iODBC: no unixodbc: no SSPI "trusted" logins: no Keberos: no OpenSSL: yes GnuTLS: no MARS: yes </code></pre></div></div><br class="example-break" /><p>For details on the use of <span class="command"><strong>tsql</strong></span>, consult its man page.</p><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="tsql.freetds.conf"></a><em class="replaceable"><code>servername</code></em> Lookup</h4></div></div></div><p>If all goes well, the first time you fire up <span class="command"><strong>tsql</strong></span> it connects and you can issue your first query. More often, though, the result is less joyous. Listed below for your troubleshooting pleasure are a variety of <em class="replaceable"><code>servername</code></em> lookup failures and their corresponding messages.</p><p>When <em class="replaceable"><code>servername</code></em> cannot be converted to an address, up to two messages may result. Successful conversion (by any means) never produces an error message. </p><div class="example"><a id="e.g.notfound"></a><p class="title"><strong>Example 3.3. Failure to find <em class="replaceable"><code>servername</code></em> in <code class="filename">freetds.conf</code></strong></p><div class="example-contents"><pre class="screen"> <code class="prompt">$ </code><strong class="userinput"><code>tsql -S <em class="replaceable"><code>nobox</code></em> -U <em class="replaceable"><code>sa</code></em> </code></strong> <code class="prompt">Password: </code> <code class="computeroutput">locale is "C" locale charset is "646" Password: Error 20012 (severity 2): Server name not found in configuration files. Error 20013 (severity 2): Unknown host machine name. There was a problem connecting to the server </code> <code class="prompt">$ </code><strong class="userinput"><code>host nobox</code></strong> <code class="computeroutput">Host not found.</code></pre></div></div><p><br class="example-break" /> In the above case message 20012 indicates <code class="literal">nobox</code> was not found in <code class="filename">freetds.conf</code>. The library then treated <code class="literal">nobox</code> as a network hostname but found it also not to be valid per DNS, leading to message 20013.</p><p>If <em class="replaceable"><code>servername</code></em> is found in the configuration files, but refers to an invalid hostname, only message 20013 is returned. </p><div class="example"><a id="e.g.badname"></a><p class="title"><strong>Example 3.4. Failure to resolve hostname for <em class="replaceable"><code>servername</code></em></strong></p><div class="example-contents"><pre class="screen"> <code class="prompt">$ </code><strong class="userinput"><code>tsql -S <em class="replaceable"><code>nonesuch</code></em> -U <em class="replaceable"><code>sa</code></em> </code></strong> <code class="prompt">Password: </code> <code class="computeroutput">locale is "C" locale charset is "646" Error 20013 (severity 2): Unknown host machine name. There was a problem connecting to the server</code></pre></div></div><p><br class="example-break" /> Unfortunately, the <span class="quote">“<span class="quote">host machine name</span>”</span> (the right side of the <code class="literal">host</code> line in <code class="filename">freetds.conf</code>) isn't mentioned in the error message. Fortunately, this kind of setup problem is rarely encountered by users.</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="tsql.connect"></a>Connecting to the Server</h4></div></div></div><p>If name lookup succeeds, <span class="productname">FreeTDS</span> next attempts to connect to the server. <span class="emphasis"><em>To connect</em></span> means to form at TCP connection by calling <code class="function">connect(2)</code>. A valid connection must exist before any information can be exchanged with the server. Specifically, we need a connection before we can log in.</p><p>A few things can go wrong at this point. The address returned by DNS may not be that of the machine hosting the server, or indeed of <span class="emphasis"><em>any</em></span> machine! The machine may be down. The server may not be running. The server may be running but not listening to the port <span class="productname">FreeTDS</span> is attempting to connect to. In rare cases, both ends are correctly configured, but a firewall stands in the way.</p><p>If no server accepts the connection, no connection can be established. It's difficult to know why, and the message is consequently vague. </p><div class="example"><a id="e.g.noconnect"></a><p class="title"><strong>Example 3.5. Failing to connect with tsql</strong></p><div class="example-contents"><pre class="screen"> <code class="prompt">$ </code><strong class="userinput"><code>tsql -S <em class="replaceable"><code>emforester</code></em> -U <em class="replaceable"><code>sa</code></em> #only connect?</code></strong> <code class="prompt">Password: </code> <code class="computeroutput">Msg 20009, Level 9, State -1, Server OpenClient, Line -1 Unable to connect: Adaptive Server is unavailable or does not exist There was a problem connecting to the server</code></pre></div></div><p><br class="example-break" /> If you get message 20009, remember you haven't connected to the machine. It's a configuration or network issue, <span class="emphasis"><em>not a protocol failure</em></span>. Verify the server is up, has the name and IP address <span class="productname">FreeTDS</span> is using, and is listening to the configured port.</p><p>Named instances provide another way for connections to fail. You can verify the instance name and the port the server is using with <span class="command"><strong>tsql -L</strong></span>. </p><div class="example"><a id="e.g.instance.name"></a><p class="title"><strong>Example 3.6. Getting instance information with tsql</strong></p><div class="example-contents"><pre class="screen"> <code class="prompt">$ </code><strong class="userinput"><code>tsql -LH <em class="replaceable"><code>servername</code></em> </code></strong> <code class="computeroutput">locale is "C" locale charset is "646" ServerName TITAN InstanceName MSSQLSERVER IsClustered No Version 8.00.194 tcp 1433 np \\TITAN\pipe\sql\query</code></pre></div></div><p><br class="example-break" /> <em class="replaceable"><code>servername</code></em> could be configured to use instance <code class="literal">MSSQLSERVER</code> or port <code class="literal">1433</code>.</p><p>After a valid connection is formed, <span class="productname">FreeTDS</span> sends a login packet. The TDS protocol provides no way to interrogate the server for its TDS version. If you specify the wrong one, you'll get an error. </p><div class="example"><a id="e.g.bad.tdsver"></a><p class="title"><strong>Example 3.7. Using the wrong protocol for the server</strong></p><div class="example-contents"><pre class="screen"> <code class="prompt">$ </code><strong class="userinput"><code>tsql -S <em class="replaceable"><code>servername</code></em> </code></strong> <code class="prompt">Password: </code> <code class="computeroutput">Msg 20017, Level 9, State -1, Server OpenClient, Line -1 Unexpected EOF from the server Msg 20002, Level 9, State -1, Server OpenClient, Line -1 Adaptive Server connection failed There was a problem connecting to the server</code></pre></div></div><p><br class="example-break" /> <span class="quote">“<span class="quote">Unexpected EOF from the server</span>”</span> seems to be a fairly common message when the wrong TDS version is used. Note that there's no complaint about the login.</p><p>If the right TDS version is used, the server will accept the login packet and examine its contents to authenticate the user. If there's a problem, the server will say so. This is the first time we're receiving a message from the server. <a href="#ftn.idm1802" class="footnote" id="idm1802"><sup class="footnote">[8]</sup></a> </p><div class="example"><a id="e.g.bad.login"></a><p class="title"><strong>Example 3.8. Login failure</strong></p><div class="example-contents"><pre class="screen"> <code class="prompt">$ </code><strong class="userinput"><code>tsql -S <em class="replaceable"><code>servername</code></em> -U notme </code></strong> <code class="prompt">Password: </code> <code class="computeroutput">Msg 18456, Level 14, State 1, Server [<em class="replaceable"><code>servername</code></em>], Line 0 Login failed for user 'notme'. Msg 20002, Level 9, State -1, Server OpenClient, Line -1 Adaptive Server connection failed There was a problem connecting to the server</code></pre></div></div><p><br class="example-break" /></p><h4><a id="idm1815"></a>Bypassing <code class="filename">freetds.conf</code>:</h4><div class="cmdsynopsis"><p><code class="command">tsql</code> {-H <em class="replaceable"><code>hostname</code></em>} {-p <em class="replaceable"><code>port</code></em>} {-U <em class="replaceable"><code>username</code></em>} [-P<em class="replaceable"><code>password</code></em>] [-C]</p></div><p> Keep in mind that the TDS protocol version normally comes from <code class="filename">freetds.conf</code>. When using <span class="command"><strong>tsql</strong></span> this way, the library uses the compiled-in default (set by the <code class="filename">configure</code> script). If that's not what you want, override it using the <code class="envar">TDSVER</code> environment variable.</p><div class="example"><a id="e.g.tsqlhostname"></a><p class="title"><strong>Example 3.9. Connect with <span class="command">tsql</span> using a hostname and port number</strong></p><div class="example-contents"><pre class="screen"> <code class="prompt">$ </code><strong class="userinput"><code>TDSVER=auto tsql -H <em class="replaceable"><code>hillary</code></em> -p <em class="replaceable"><code>4100</code></em> -U <em class="replaceable"><code>sa</code></em></code></strong> <code class="prompt">Password: </code> <code class="computeroutput">1></code></pre></div></div><br class="example-break" /><p>For details on <span class="command"><strong>tsql</strong></span>, see the its man page.</p></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Tests"></a><span class="application">Unit Tests</span></h3></div></div></div><p>The source code directory of each <span class="productname">FreeTDS</span> library includes a <code class="filename">unittests</code> directory. Although the directories are named <code class="filename">unittests</code> they are not unit tests, most of them require a configured database to work. </p><pre class="screen"> <code class="prompt">$ </code><strong class="userinput"><code>ls -d -1 src/*/unittests</code></strong> <code class="computeroutput">src/ctlib/unittests src/dblib/unittests src/odbc/unittests src/replacements/unittests src/tds/unittests src/utils/unittests</code></pre><p> The tests rely on the <code class="filename">PWD</code> file in root of the <span class="productname">FreeTDS</span> source tree. <code class="filename">PWD</code> 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 <code class="filename">README.md</code>.</p><p>To invoke the tests, edit the <code class="filename">PWD</code> file (you can copy from <code class="filename">PWD.in</code> which is a template) and issue the command <span class="command"><strong>make check</strong></span>. In order to execute all tests successfully, you must indicate a working, available servername in <code class="filename">PWD</code>. Some tests require permission to create stored procedures on server. In addition, some may require that a database named <code class="literal">freetds_test</code> exists on the server, and the user whose credentials are used during the testing process has sufficient permissions to create and manipulate tables in this database.</p><p>To complete successfully, the ODBC tests require some additional setup. In your <code class="filename">PWD</code> file, add a <code class="literal">SRV</code> entry specifying the DSN entry for your <code class="filename">odbc.ini</code>. The ODBC tests all build their own <code class="filename">odbc.ini</code> and try to redirect the Driver Manager to it, however this functionality is very DM dependent and may well fail unless you have either <code class="systemitem">iODBC</code> or <code class="systemitem">unixODBC</code>.</p><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Tip"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../images/tip.gif" /></td><th align="left">Tip</th></tr><tr><td align="left" valign="top"><p> The <code class="filename">PWD</code> provided by <span class="productname">FreeTDS</span> includes usernames and passwords that probably don't exist on your server. </p></td></tr></table></div></div><div class="footnotes"><br /><hr style="width:100; text-align:left;margin-left: 0" /><div id="ftn.idm1802" class="footnote"><p><a href="#idm1802" class="para"><sup class="para">[8] </sup></a>If you'd like to help the project and want to so something fairly easy but still useful, modify tsql to distinguish clearly between errors returned by the library, and those returned by the server. Errors should be marked <span class="quote">“<span class="quote">error</span>”</span> and don't return <span class="emphasis"><em>state</em></span> or a line number, but can contain an error code (and message) from the operating system.</p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="PortOverride.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="install.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="prepodbc.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Port/instance override syntax </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 4. Preparing ODBC</td></tr></table></div></body></html>