Add debugging info from Cary O'Brien.

Include comments from Robert Burrows.

doc/src/sgml/odbc.sgml

@@ -732,6 +732,357 @@ Server: Broken Pipe
 	 of the <productname>Postgres</productname>
 <acronym>ODBC</acronym> package.
 
+<varlistentry>
+<term>
+setuid to 256: failed to launch gateway
+
+<listitem>
+<para>
+The September release of ApplixWare v4.4.1 (the first release with official
+<acronym>ODBC</acronym> support under Linux) shows problems when usernames
+exceed eight (8) characters in length.
+Problem description ontributed by 
+<ulink url="mailto:scampbell@lear.com">Steve Campbell</ulink>.
+
+</variablelist>
+
+<para>
+<note>
+<title>Author</title>
+
+<para>
+Contributed by 
+<ulink url="mailto:scampbell@lear.com">Steve Campbell</ulink> on
+1998-10-20.
+</note>
+
+The <application>axnet</application> program's security system
+ seems a little suspect. <application>axnet</application> does things
+ on behalf of the user and on a true
+ multiple user system it really should be run with root security 
+(so it can read/write in each user's directory).  
+I would hesitate to recommend this, however, since we have no idea what 
+security holes this creates.
+
+<sect2>
+<title>Debugging ApplixWare ODBC Connections</title>
+
+<para>
+One good tool for debugging connection problems uses the Unix system
+utility <application>strace</application>.
+
+<procedure>
+<title>Debugging with strace</title>
+
+<step performance="required">
+<para>
+Start applixware.
+
+<step performance="required">
+<para>
+Start an <application>strace</application> on
+the axnet process.  For example, if
+
+<programlisting>
+ps -aucx | grep ax 
+</programlisting>
+
+shows
+
+<programlisting>
+cary   10432  0.0  2.6  1740   392  ?  S  Oct  9  0:00 axnet
+cary   27883  0.9 31.0 12692  4596  ?  S   10:24  0:04 axmain
+</programlisting>
+
+<para>
+Then run
+
+<programlisting>
+   strace -f -s 1024 -p 10432 
+</programlisting>
+
+<step performance="required">
+<para>
+Check the strace output.
+
+<note>
+<title>Note from Cary</title>
+
+<para>
+Many of the error messages from <productname>ApplixWare</productname>
+go to <filename>stderr</filename>, 
+but I'm not sure where <filename>stderr</filename>
+is sent, so <application>strace</application> is the way to find out.
+</note>
+
+</procedure>
+
+<para>
+  For example, after getting
+a <quote>Cannot launch gateway on server</quote>, 
+I ran strace on axnet and got
+
+<programlisting>
+[pid 27947] open("/usr/lib/libodbc.so", O_RDONLY) = -1 ENOENT
+    (No such file or directory)
+[pid 27947] open("/lib/libodbc.so", O_RDONLY) = -1 ENOENT
+    (No such file or directory)
+[pid 27947] write(2, "/usr2/applix/axdata/elfodbc:
+    can't load library 'libodbc.so'\n", 61) = -1 EIO (I/O error)
+</programlisting>  
+So what is happening is that applix elfodbc is searching for libodbc.so, but it
+can't find it.  That is why axnet.cnf needed to be changed.
+
+<sect2>
+<title>Running the ApplixWare Demo</title>
+
+<para>
+In order to go through the 
+<citetitle>ApplixWare Data Tutorial</citetitle>, you need to create
+the sample tables that the Tutorial refers to.  The ELF Macro used to
+create the tables tries to use a NULL condition 
+on many of the database columns,
+and <productname>Postgres</productname> does not currently allow this option.
+
+<para>
+To get around this problem, you can do the following:
+
+<procedure>
+<title>Modifying the ApplixWare Demo</title>
+
+<step performance="required">
+<para>
+Copy <filename>/opt/applix/axdata/eng/Demos/sqldemo.am</filename>
+ to a local directory.
+
+<step performance="required">
+<para>
+Edit this local copy of <filename>sqldemo.am</filename>:
+
+<substeps>
+
+<step performance="required">
+<para>
+Search for 'null_clause = "NULL"
+
+<step performance="required">
+<para>
+Change this to null_clause = ""
+
+</substeps>
+
+<step performance="required">
+<para>
+Start <application>Applix Macro Editor</application>.
+
+<step performance="required">
+<para>
+Open the sqldemo.am file from the <application>Macro Editor</application>.
+
+<step performance="required">
+<para>
+Select <command>File->Compile and Save</command>.
+
+<step performance="required">
+<para>
+Exit <application>Macro Editor</application>.
+
+<step performance="required">
+<para>
+Start <application>Applix Data</application>.
+
+<step performance="required">
+<para>
+Select <command>*->Run Macro</command>
+
+<step performance="required">
+<para>
+Enter the value <quote>sqldemo</quote>, then click <command>OK</command>.
+
+<para>
+You should see the progress in the status line of the data window
+ (in the lower left corner).
+
+<step performance="required">
+<para>
+You should now be able to access the demo tables.
+
+</procedure>
+
+<sect2>
+<title>Useful Macros</title>
+
+<para>
+You can add information about your
+database login and password to the standard Applix startup
+macro file. This is an example 
+<filename>~/axhome/macros/login.am</filename> file:
+
+=======
+<productname>ApplixWare</productname> must be configured correctly
+ in order for it to
+be able to access the <productname>Postgres</productname>
+ <acronym>ODBC</acronym> software drivers.
+
+<procedure>
+<title>Enabling ApplixWare Database Access</title>
+
+<para>
+Note that
+these instructions are for the 4.4.1 release of
+ <productname>ApplixWare</productname> on <productname>Linux</productname>.
+Refer to the <citetitle>Linux Sys Admin</citetitle> on-line book
+ for more detailed information.
+
+<step performance="required">
+<para>
+You must modify <filename>axnet.cnf</filename> so that
+ <filename>elfodbc</filename> can
+find <filename>libodbc.so</filename>
+ (the <acronym>ODBC</acronym> driver manager) shared library.
+This library is included with the ApplixWare distribution,
+but <filename>axnet.cnf</filename> needs to be modified to point to the 
+correct location.
+
+<para>
+As root, edit the file
+<filename><replaceable>applixroot</replaceable>/applix/axdata/axnet.cnf</filename>.
+
+<substeps>
+
+<step performance="required">
+<para>
+At the bottom of <filename>axnet.cnf</filename>,
+find the line that starts with
+
+<programlisting>
+#libFor elfodbc /ax/<replaceable>...</replaceable>
+</programlisting>
+
+<step performance="required">
+<para>
+Change line to read
+
+<programlisting>
+libFor elfodbc <replaceable>applixroot</replaceable>/applix/axdata/axshlib/lib
+</programlisting>
+
+which will tell elfodbc to look in this directory
+for the <acronym>ODBC</acronym> support library.
+If you have installed applix somewhere else,
+change the path accordingly.
+
+</substeps>
+
+<step performance="required">
+<para>
+Create <filename>.odbc.ini</filename> as 
+described above.  You may also want to add the flag
+
+<programlisting>
+TextAsLongVarchar=0
+</programlisting>
+
+to the database-specific portion of <filename>.odbc.ini</filename>
+so that text fields will not be shown as <literal>**BLOB**</literal>.
+
+</procedure>
+
+<procedure>
+<title>Testing ApplixWare ODBC Connections</title>
+
+<step performance="required">
+<para>
+    Bring up <application>Applix Data</application>
+
+<step performance="required">
+<para>
+Select the <productname>Postgres</productname> database of interest.
+
+<substeps>
+
+<step performance="required">
+<para>
+Select <command>Query->Choose Server</command>.  
+
+<step performance="required">
+<para>
+ Select <acronym>ODBC</acronym>, and click <command>Browse</command>.
+The database you configured in <filename>.odbc.ini</filename>
+    should be shown.  Make sure that the <option>Host: field</option>
+ is empty (if it is not, axnet will try to contact axnet on another machine
+ to look for the database).
+
+<step performance="required">
+<para>
+Select the database in the box that was launched by <command>Browse</command>,
+ then click <command>OK</command>.
+
+<step performance="required">
+<para>
+Enter username and password in the login identification dialog,
+ and click <command>OK</command>.
+
+</substeps>
+
+<para>
+    You should see <quote>Starting elfodbc server</quote>
+ in the lower left corner of the
+    data window.  If you get an error dialog box, see the debugging section
+    below.
+
+<step performance="required">
+<para>
+    The 'Ready' message will appear in the lower left corner of the data
+    window.  This indicates that you can now enter queries.
+
+<step performance="required">
+<para>
+    Select a table from Query->Choose tables, and then select Query->Query
+    to access the database.  The first 50 or so rows from the table should
+    appear.
+
+</procedure>
+
+<sect2>
+<title>Common Problems</title>
+
+<para>
+The following messages can appear while trying to make an
+<acronym>ODBC</acronym> connection through 
+<productname>Applix Data</productname>:
+
+<variablelist>
+<varlistentry>
+<term>
+Cannot launch gateway on server
+
+<listitem>
+<para>
+<literal>elfodbc</literal> can't find <filename>libodbc.so</filename>.  
+Check your <filename>axnet.cnf</filename>.
+
+<varlistentry>
+<term>
+Error from ODBC Gateway:
+IM003::[iODBC][Driver Manager]Specified driver could not be loaded
+
+<listitem>
+<para>
+<filename>libodbc.so</filename> cannot find the driver listed in
+<filename>.odbc.ini</filename>. Verify the settings.
+
+<varlistentry>
+<term>
+Server: Broken Pipe
+
+<listitem>
+<para>
+	 The driver process has terminated due to some other
+	 problem.  You might not have an up-to-date version
+	 of the <productname>Postgres</productname>
+<acronym>ODBC</acronym> package.
+
 </variablelist>
 
 <sect2>