Add debugging info from Cary O'Brien.

Include comments from Robert Burrows.

diff --git a/doc/src/sgml/odbc.sgml b/doc/src/sgml/odbc.sgml
index d23779254fd8296bd9197d47a82a897e55869710..069b9ab41ad5ac81428fce68fd38ab2f49c3b7c4 100644 (file)
--- a/doc/src/sgml/odbc.sgml
+++ b/doc/src/sgml/odbc.sgml
@@ -732,6 +732,357 @@ Server: Broken Pipe
     of the Postgres
 ODBC package.
 
+
+
+setuid to 256: failed to launch gateway
+
+
+
+The September release of ApplixWare v4.4.1 (the first release with official
+ODBC support under Linux) shows problems when usernames
+exceed eight (8) characters in length.
+Problem description ontributed by 
+Steve Campbell.
+
+
+
+
+
+Author
+
+
+Contributed by 
+Steve Campbell on
+1998-10-20.
+
+
+The axnet program's security system
+ seems a little suspect. axnet 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.
+
+
+Debugging ApplixWare ODBC Connections
+
+
+One good tool for debugging connection problems uses the Unix system
+utility strace.
+
+
+Debugging with strace
+
+
+
+Start applixware.
+
+
+
+Start an strace on
+the axnet process.  For example, if
+
+
+ps -aucx | grep ax 
+
+
+shows
+
+
+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
+
+
+
+Then run
+
+
+   strace -f -s 1024 -p 10432 
+
+
+
+
+Check the strace output.
+
+
+Note from Cary
+
+
+Many of the error messages from ApplixWare
+go to stderr, 
+but I'm not sure where stderr
+is sent, so strace is the way to find out.
+
+
+
+
+
+  For example, after getting
+a Cannot launch gateway on server, 
+I ran strace on axnet and got
+
+
+[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)
+  
+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.
+
+
+Running the ApplixWare Demo
+
+
+In order to go through the 
+ApplixWare Data Tutorial, 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 Postgres does not currently allow this option.
+
+
+To get around this problem, you can do the following:
+
+
+Modifying the ApplixWare Demo
+
+
+
+Copy /opt/applix/axdata/eng/Demos/sqldemo.am
+ to a local directory.
+
+
+
+Edit this local copy of sqldemo.am:
+
+
+
+
+
+Search for 'null_clause = "NULL"
+
+
+
+Change this to null_clause = ""
+
+
+
+
+
+Start Applix Macro Editor.
+
+
+
+Open the sqldemo.am file from the Macro Editor.
+
+
+
+Select File->Compile and Save.
+
+
+
+Exit Macro Editor.
+
+
+
+Start Applix Data.
+
+
+
+Select *->Run Macro
+
+
+
+Enter the value sqldemo, then click OK.
+
+
+You should see the progress in the status line of the data window
+ (in the lower left corner).
+
+
+
+You should now be able to access the demo tables.
+
+
+
+
+Useful Macros
+
+
+You can add information about your
+database login and password to the standard Applix startup
+macro file. This is an example 
+~/axhome/macros/login.am file:
+
+=======
+ApplixWare must be configured correctly
+ in order for it to
+be able to access the Postgres
+ ODBC software drivers.
+
+
+Enabling ApplixWare Database Access
+
+
+Note that
+these instructions are for the 4.4.1 release of
+ ApplixWare on Linux.
+Refer to the Linux Sys Admin on-line book
+ for more detailed information.
+
+
+
+You must modify axnet.cnf so that
+ elfodbc can
+find libodbc.so
+ (the ODBC driver manager) shared library.
+This library is included with the ApplixWare distribution,
+but axnet.cnf needs to be modified to point to the 
+correct location.
+
+
+As root, edit the file
+applixroot/applix/axdata/axnet.cnf.
+
+
+
+
+
+At the bottom of axnet.cnf,
+find the line that starts with
+
+
+#libFor elfodbc /ax/...
+
+
+
+
+Change line to read
+
+
+libFor elfodbc applixroot/applix/axdata/axshlib/lib
+
+
+which will tell elfodbc to look in this directory
+for the ODBC support library.
+If you have installed applix somewhere else,
+change the path accordingly.
+
+
+
+
+
+Create .odbc.ini as 
+described above.  You may also want to add the flag
+
+
+TextAsLongVarchar=0
+
+
+to the database-specific portion of .odbc.ini
+so that text fields will not be shown as **BLOB**.
+
+
+
+
+Testing ApplixWare ODBC Connections
+
+
+
+    Bring up Applix Data
+
+
+
+Select the Postgres database of interest.
+
+
+
+
+
+Select Query->Choose Server.  
+
+
+
+ Select ODBC, and click Browse.
+The database you configured in .odbc.ini
+    should be shown.  Make sure that the Host: field
+ is empty (if it is not, axnet will try to contact axnet on another machine
+ to look for the database).
+
+
+
+Select the database in the box that was launched by Browse,
+ then click OK.
+
+
+
+Enter username and password in the login identification dialog,
+ and click OK.
+
+
+
+
+    You should see Starting elfodbc server
+ in the lower left corner of the
+    data window.  If you get an error dialog box, see the debugging section
+    below.
+
+
+
+    The 'Ready' message will appear in the lower left corner of the data
+    window.  This indicates that you can now enter queries.
+
+
+
+    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.
+
+
+
+
+Common Problems
+
+
+The following messages can appear while trying to make an
+ODBC connection through 
+Applix Data:
+
+
+
+
+Cannot launch gateway on server
+
+
+
+elfodbc can't find libodbc.so.  
+Check your axnet.cnf.
+
+
+
+Error from ODBC Gateway:
+IM003::[iODBC][Driver Manager]Specified driver could not be loaded
+
+
+
+libodbc.so cannot find the driver listed in
+.odbc.ini. Verify the settings.
+
+
+
+Server: Broken Pipe
+
+
+
+    The driver process has terminated due to some other
+    problem.  You might not have an up-to-date version
+    of the Postgres
+ODBC package.
+