head	1.31;
access;
symbols
	REL7_2_8:1.29
	REL7_2_7:1.29
	REL7_2_6:1.29
	REL7_2_5:1.29
	REL7_2_4:1.29
	REL7_2_3:1.29
	REL7_3_STABLE:1.30.0.2
	REL7_2_STABLE:1.29.0.2
	REL7_2:1.29
	REL7_2_RC2:1.29
	REL7_2_RC1:1.29
	REL7_2_BETA5:1.29
	REL7_2_BETA4:1.28
	REL7_2_BETA3:1.27
	REL7_2_BETA2:1.26
	REL7_2_BETA1:1.25
	REL7_1_2:1.21
	REL7_1_STABLE:1.21.0.2
	REL7_1_BETA:1.18
	REL7_1_BETA3:1.20
	REL7_1_BETA2:1.20
	REL7_1:1.21
	REL7_0_PATCHES:1.15.0.2
	REL7_0:1.15
	REL6_5_PATCHES:1.11.0.2
	REL6_5:1.11
	REL6_4:1.9.0.2
	release-6-3:1.1;
locks; strict;
comment	@# @;


1.31
date	2002.10.21.23.10.09;	author momjian;	state dead;
branches;
next	1.30;

1.30
date	2002.03.22.19.20.16;	author petere;	state Exp;
branches
	1.30.2.1;
next	1.29;

1.29
date	2002.01.07.02.29.12;	author petere;	state Exp;
branches;
next	1.28;

1.28
date	2001.11.21.05.53.41;	author thomas;	state Exp;
branches;
next	1.27;

1.27
date	2001.11.12.19.19.39;	author petere;	state Exp;
branches;
next	1.26;

1.26
date	2001.10.31.20.39.30;	author petere;	state Exp;
branches;
next	1.25;

1.25
date	2001.10.09.22.32.32;	author petere;	state Exp;
branches;
next	1.24;

1.24
date	2001.09.13.15.55.23;	author petere;	state Exp;
branches;
next	1.23;

1.23
date	2001.09.10.21.58.47;	author petere;	state Exp;
branches;
next	1.22;

1.22
date	2001.05.12.22.51.35;	author petere;	state Exp;
branches;
next	1.21;

1.21
date	2001.01.20.20.59.28;	author petere;	state Exp;
branches;
next	1.20;

1.20
date	2000.12.22.21.51.58;	author petere;	state Exp;
branches;
next	1.19;

1.19
date	2000.12.22.18.57.49;	author petere;	state Exp;
branches;
next	1.18;

1.18
date	2000.09.29.20.21.34;	author petere;	state Exp;
branches;
next	1.17;

1.17
date	2000.09.18.20.11.37;	author petere;	state Exp;
branches;
next	1.16;

1.16
date	2000.08.29.20.02.07;	author momjian;	state Exp;
branches;
next	1.15;

1.15
date	2000.05.02.20.01.52;	author thomas;	state Exp;
branches;
next	1.14;

1.14
date	2000.03.31.03.27.41;	author thomas;	state Exp;
branches;
next	1.13;

1.13
date	2000.03.29.03.57.11;	author thomas;	state Exp;
branches;
next	1.12;

1.12
date	2000.03.27.17.14.35;	author thomas;	state Exp;
branches;
next	1.11;

1.11
date	99.06.03.04.21.49;	author thomas;	state Exp;
branches;
next	1.10;

1.10
date	98.12.29.02.24.18;	author thomas;	state Exp;
branches;
next	1.9;

1.9
date	98.10.30.19.37.06;	author thomas;	state Exp;
branches;
next	1.8;

1.8
date	98.10.25.00.31.20;	author thomas;	state Exp;
branches;
next	1.7;

1.7
date	98.10.21.05.33.22;	author thomas;	state Exp;
branches;
next	1.6;

1.6
date	98.10.10.17.12.15;	author thomas;	state Exp;
branches;
next	1.5;

1.5
date	98.09.30.05.41.47;	author thomas;	state Exp;
branches;
next	1.4;

1.4
date	98.09.16.14.44.00;	author thomas;	state Exp;
branches;
next	1.3;

1.3
date	98.09.01.15.48.00;	author thomas;	state Exp;
branches;
next	1.2;

1.2
date	98.07.29.06.50.00;	author thomas;	state Exp;
branches;
next	1.1;

1.1
date	98.03.01.08.15.59;	author thomas;	state Exp;
branches;
next	;

1.30.2.1
date	2002.11.04.21.24.29;	author tgl;	state dead;
branches;
next	;


desc
@@


1.31
log
@Move odbc.sgml to gborg ODBC project.
@
text
@<!--
$Header: /cvsroot/pgsql-server/doc/src/sgml/odbc.sgml,v 1.30 2002/03/22 19:20:16 petere Exp $
-->

 <chapter id="odbc">
  <docinfo>
   <authorgroup>
    <author>
     <firstname>Tim</firstname>
     <surname>Goeke</surname>
    </author>
    <author>
     <firstname>Thomas</firstname>
     <surname>Lockhart</surname>
    </author>
   </authorgroup>
   <date>1998-10-21</date>
  </docinfo>

  <title>ODBC Interface</title>

  <indexterm zone="odbc">
   <primary>ODBC</primary>
  </indexterm>

 <sect1 id="odbc-intro">
  <title>Introduction</title>

  <note>
   <para>
    Background information originally by Tim Goeke
    (<email>tgoeke@@xpressway.com</email>)
   </para>
  </note>

  <para>
   <acronym>ODBC</acronym> (Open Database Connectivity) is an abstract 
   <acronym>API</acronym> 
   that allows you to write applications that can interoperate
   with various <acronym>RDBMS</acronym> servers.
   <acronym>ODBC</acronym> provides a product-neutral interface 
   between frontend applications and database servers,
   allowing a user or developer to write applications that are 
   portable between servers from different manufacturers..
  </para>

   <para>
    The <acronym>ODBC</acronym> <acronym>API</acronym> matches up 
    on the backend to an <acronym>ODBC</acronym>-compatible data source.
    This could be anything from a text file to an Oracle or 
    <productname>PostgreSQL</productname> <acronym>RDBMS</acronym>.
   </para>

   <para>
    The backend access comes from <acronym>ODBC</acronym> drivers, 
    or vendor-specific drivers that
    allow data access.   <productname>psqlODBC</productname>, which is included in the <productname>PostgreSQL</> distribution, is such a driver,
    along with others that are
    available, such as the <productname>OpenLink</productname> <acronym>ODBC</acronym> drivers.
   </para>

   <para>
    Once you write an <acronym>ODBC</acronym> application, 
    you <emphasis>should</emphasis> be able to connect to <emphasis>any</emphasis>
    back-end database, regardless of the vendor, as long as the database schema
    is the same.
   </para>

   <para>
    For example. you could have <productname>MS SQL Server</productname>
    and <productname>PostgreSQL</productname> servers that have
    exactly the same data.  Using <acronym>ODBC</acronym>, 
    your Windows application would make exactly the
    same calls and the back-end data source would look the same (to the Windows
    application).
   </para>
  </sect1>

  <sect1 id="odbc-install">
   <title>Installation</title>

   <para>
    In order to make use of an <acronym>ODBC</> driver there must
    exist a <firstterm>driver manager</> on the system where the
    <acronym>ODBC</> driver is to be used.  There are two free
    <acronym>ODBC</> driver managers for Unix-like operating systems
    known to us: <indexterm><primary>iODBC</primary></indexterm>
    <ulink url="http://www.iodbc.org"><productname>iODBC</></ulink>
    and <indexterm><primary>unixODBC</primary></indexterm> <ulink
    url="http://www.unixodbc.org"><productname>unixODBC</></ulink>.
    Instructions for installing these driver managers are to be found
    in the respective distribution.  Software that provides database
    access through <acronym>ODBC</acronym> should provide its own
    driver manager (which may well be one of these two).  Having said
    that, any driver manager that you can find for your platform
    should support the <productname>PostgreSQL</> <acronym>ODBC</>
    driver, or any other <acronym>ODBC</> driver for that matter.
   </para>

   <note>
    <para>
     The <productname>unixODBC</> distribution ships with a
     <productname>PostgreSQL</> <acronym>ODBC</> driver of its own,
     which is similar to the one contained in the
     <productname>PostgreSQL</> distribution.  It is up to you which
     one you want to use.  We plan to coordinate the development of
     both drivers better in the future.
    </para>
   </note>

   <para>
    To install the <acronym>ODBC</> you simply need to supply the
    <option>--enable-odbc</> option to the <filename>configure</>
    script when you are building the entire <productname>PostgreSQL</>
    distribution. The library will then automatically be built and
    installed with the rest of the programs. If you forget that option
    or want to build the ODBC driver later you can change into the
    directory <filename>src/interfaces/odbc</> and do <literal>make</>
    and <literal>make install</> there.
   </para>

   <para>
    It is also possible to build the driver to be specifically tuned
    for use with <productname>iODBC</> or <productname>unixODBC</>.
    This means in particular that the driver will use the driver
    manager's routines to process the configuration files, which is
    probably desirable since it creates a more consistent
    <acronym>ODBC</> environment on your system.  If you want to do
    that, then supply the <filename>configure</> options
    <option>--with-iodbc</> or <option>--with-unixodbc</> (but not
    both).
   </para>

   <para>
    If you build a <quote>stand-alone</quote> driver (not tied to
    <productname>iODBC</> or <productname>unixODBC</>), then you can
    specify where the driver should look for the configuration file
    <filename>odbcinst.ini</>.  By default it will be the directory
    <filename>/usr/local/pgsql/etc/</>, or equivalent, depending on
    what <option>--prefix</> and/or <option>--sysconfdir</> options
    you supplied to <filename>configure</>.  To select a specific
    location outside the <productname>PostgreSQL</> installation
    layout, use the <option>--with-odbcinst</> option.  To be most
    useful, it should be arranged that the driver and the driver
    manager read the same configuration file.
   </para>

   <para>
    <indexterm><primary>odbc.sql</></>
    Additionally, you should install the ODBC catalog extensions.  That will
    provide a number of functions mandated by the ODBC standard that are not
    supplied by <productname>PostgreSQL</> by default. The file
    <filename>/usr/local/pgsql/share/odbc.sql</> (in the default installation layout)
    contains the appropriate definitions, which you can install as follows:
<programlisting>
psql -d template1 -f <replaceable>LOCATION</>/odbc.sql
</programlisting>
    where specifying <literal>template1</literal> as the target
    database will ensure that all subsequent new databases will have
    these same definitions.  If for any reason you want to remove
    these functions again, run the file
    <filename>odbc-drop.sql</filename> through
    <command>psql</command>.
   </para>
  </sect1>

  <sect1 id="odbc-config">
   <title>Configuration Files</title>

   <indexterm zone="odbc-config"><primary>.odbc.ini</></>

   <para>
    <filename>~/.odbc.ini</filename> contains user-specified access information 
    for the <productname>psqlODBC</productname> driver. 
    The file uses conventions typical for <productname>Windows</productname> 
    Registry files.
   </para>

   <para>
    The <filename>.odbc.ini</filename> file has three required sections. 
    The first is <literal>[ODBC Data Sources]</literal>
    which is a list of arbitrary names and descriptions for each database 
    you wish to access. The second required section is the 
    Data Source Specification and there will be one of these sections
    for each database. 
    Each section must be labeled with the name given in 
    <literal>[ODBC Data Sources]</literal> and must contain the following entries: 

<programlisting>
Driver = <replaceable>prefix</replaceable>/lib/libpsqlodbc.so
Database = <replaceable>DatabaseName</replaceable>
Servername = localhost
Port = 5432
</programlisting>

    <tip>
     <para>
      Remember that the <productname>PostgreSQL</productname> database name is
      usually a single word, without path names of any sort. 
      The <productname>PostgreSQL</productname> server manages the actual access
      to the database, and you need only specify the name from the client.
     </para>
    </tip>

    Other entries may be inserted to control the format of the display. 
    The third required section is <literal>[ODBC]</literal> 
    which must contain the <literal>InstallDir</literal> keyword 
    and which may contain other options.
   </para>

   <para>
    Here is an example <filename>.odbc.ini</filename> file, 
    showing access information for three databases:

<programlisting>
[ODBC Data Sources]
DataEntry = Read/Write Database
QueryOnly = Read-only Database
Test = Debugging Database
Default = Postgres Stripped

[DataEntry]
ReadOnly = 0
Servername = localhost
Database = Sales

[QueryOnly]
ReadOnly = 1
Servername = localhost
Database = Sales

[Test]
Debug = 1
CommLog = 1
ReadOnly = 0
Servername = localhost
Username = tgl
Password = "no$way"
Port = 5432
Database = test

[Default]
Servername = localhost
Database = tgl
Driver = /opt/postgres/current/lib/libpsqlodbc.so

[ODBC]
InstallDir = /opt/applix/axdata/axshlib
</programlisting>
   </para>
  </sect1>

  <sect1 id="odbc-windows">
   <title><productname>Windows</productname> Applications</title>

   <para>
    In the real world, differences in drivers and the level of 
    <acronym>ODBC</acronym> support
    lessens the potential of <acronym>ODBC</acronym>:

    <itemizedlist spacing="compact" mark="bullet">
     <listitem>
      <para>
       Access, Delphi, and Visual Basic all support <acronym>ODBC</acronym> directly.
      </para>
     </listitem>
     <listitem>
      <para>
       Under C++, such as Visual C++, 
       you can use the C++ <acronym>ODBC</acronym> <acronym>API</acronym>.
      </para>
     </listitem>

     <listitem>
      <para>
       In Visual C++, you can use the <classname>CRecordSet</classname> class, which wraps the 
       <acronym>ODBC</acronym> <acronym>API</acronym>
       set within an <application>MFC</application> 4.2 class.  This is the easiest route if you are doing
       Windows C++ development under Windows NT.
      </para>
     </listitem>
    </itemizedlist>
   </para>

   <sect2>
    <title>Writing Applications</title>

    <para>
     <quote>
      If I write an application for <productname>PostgreSQL</productname> 
      can I write it using <acronym>ODBC</acronym> calls
      to the <productname>PostgreSQL</productname> server, 
      or is that only when another database program 
      like MS SQL Server or Access needs to access the data?
     </quote>
    </para>
    <para>
     The <acronym>ODBC</acronym> <acronym>API</acronym>
     is the way to go.
     For <productname>Visual C++</productname> coding you can find out more at
     Microsoft's web site or in your <productname>Visual C++</productname>
     documentation.
    </para>

    <para>
     Visual Basic and the other <acronym>RAD</acronym> tools have <classname>Recordset</classname> objects 
     that use <acronym>ODBC</acronym>
     directly to access data.  Using the data-aware controls, you can quickly
     link to the <acronym>ODBC</acronym> back-end database 
     (<emphasis>very</emphasis> quickly).
    </para>

    <para>
     Playing around with <productname>MS Access</> will help you sort this out.  Try using
     <menuchoice><guimenu>File</><guimenuitem>Get External Data</></menuchoice>.
    </para>

    <tip>
     <para>
      You'll have to set up a <acronym>DSN</acronym> first.
     </para>
    </tip>

   </sect2>
  </sect1>

  <sect1 id="odbc-applixware">
   <title><application>ApplixWare</application></title>

   <indexterm zone="odbc-applixware">
    <primary>Applixware</primary>
   </indexterm>

   <para>
    <productname>Applixware</productname> has an 
    <acronym>ODBC</acronym> database interface
    supported on at least some platforms. 
    <productname>Applixware</productname> 4.4.2 has been
    demonstrated under Linux with <productname>PostgreSQL</productname> 7.0 
    using the <productname>psqlODBC</productname>
    driver contained in the <productname>PostgreSQL</productname> distribution.
   </para>

   <sect2>
    <title>Configuration</title>

    <para>
     <productname>Applixware</productname> must be configured correctly
     in order for it to
     be able to access the <productname>PostgreSQL</productname>
     <acronym>ODBC</acronym> software drivers.
    </para>

    <procedure>
     <title>Enabling <application>Applixware</application> Database Access</title>

     <para>
      These instructions are for the 4.4.2 release of
      <productname>Applixware</productname> on <productname>Linux</productname>.
      Refer to the <citetitle>Linux Sys Admin</citetitle> on-line book
      for more detailed information.
     </para>

     <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 <application>Applixware</application> distribution,
       but <filename>axnet.cnf</filename> needs to be modified to point to the 
       correct location.
      </para>

      <para>
       As root, edit the file
       <filename><replaceable>applixroot</replaceable>/applix/axdata/axnet.cnf</filename>.
      </para>

      <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>
	</para>
       </step>
       <step performance="required">
	<para>
	 Change line to read

<programlisting>
libFor elfodbc <replaceable>applixroot</replaceable>/applix/axdata/axshlib/lib
</programlisting>

	 which will tell <literal>elfodbc</literal> to look in this directory
	 for the <acronym>ODBC</acronym> support library.
	 Typically <productname>Applix</productname> is installed in
	 <filename>/opt</filename> so the full path would be
	 <filename>/opt/applix/axdata/axshlib/lib</filename>,
	 but if you have installed <productname>Applix</productname>
	 somewhere else then change the path accordingly.
	</para>
       </step>
      </substeps>
     </step>

     <step performance="required">
      <para>
       Create <filename>.odbc.ini</filename> as 
       described in <xref linkend="odbc-config">.  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>.
      </para>
     </step>
    </procedure>

    <procedure>
     <title>Testing <application>Applixware</application> ODBC Connections</title>

     <step performance="required">
      <para>
       Bring up <application>Applix Data</application>
      </para>
     </step>

     <step performance="required">
      <para>
       Select the <productname>PostgreSQL</productname> database of interest.
      </para>

      <substeps>

       <step performance="required">
	<para>
	 Select <menuchoice><guimenu>Query</guimenu><guimenuitem>Choose Server</guimenuitem></menuchoice>.  
	</para>
       </step>
       <step performance="required">
	<para>
	 Select <guimenuitem>ODBC</guimenuitem>, and click <guibutton>Browse</guibutton>.
	 The database you configured in <filename>.odbc.ini</filename>
	 should be shown.  Make sure that the <guilabel>Host:</guilabel> field
	 is empty (if it is not, <literal>axnet</> will try to contact <literal>axnet</> on another machine
	 to look for the database).
	</para>
       </step>
       <step performance="required">
	<para>
	 Select the database in the box that was launched by <guibutton>Browse</guibutton>,
	 then click <guibutton>OK</guibutton>.
	</para>
       </step>
       <step performance="required">
	<para>
	 Enter user name and password in the login identification dialog,
	 and click <guibutton>OK</guibutton>.
	</para>
       </step>
      </substeps>

      <para>
       You should see <guilabel>Starting elfodbc server</guilabel>
       in the lower left corner of the
       data window.  If you get an error dialog box, see the debugging section
       below.
      </para>
     </step>
     <step performance="required">
      <para>
       The <quote>Ready</quote> message will appear in the lower left corner of the data
       window.  This indicates that you can now enter queries.
      </para>
     </step>
     <step performance="required">
      <para>
       Select a table from
       <menuchoice><guimenu>Query</><guimenuitem>Choose
       tables</></menuchoice>, and then select
       <menuchoice><guimenu>Query</><guimenuitem>Query</></menuchoice>
       to access the database.  The first 50 or so rows from the table
       should appear.
      </para>
     </step>
    </procedure>
   </sect2>

   <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>
	<computeroutput>Cannot launch gateway on server</computeroutput>
       </term>
       <listitem>
	<para>
	 <literal>elfodbc</literal> can't find <filename>libodbc.so</filename>.  
	 Check your <filename>axnet.cnf</filename>.
	</para>
       </listitem>
      </varlistentry>

      <varlistentry>
       <term><computeroutput>
	Error from ODBC Gateway:
	IM003::[iODBC][Driver Manager]Specified driver could not be loaded</computeroutput>
       </term>
       <listitem>
	<para>
	 <filename>libodbc.so</filename> cannot find the driver listed in
	 <filename>.odbc.ini</filename>. Verify the settings.
	</para>
       </listitem>
      </varlistentry>

      <varlistentry>
       <term>
	<computeroutput>Server: Broken Pipe</computeroutput>
       </term>

       <listitem>
	<para>
	 The driver process has terminated due to some other
	 problem.  You might not have an up-to-date version
	 of the <productname>PostgreSQL</productname>
	 <acronym>ODBC</acronym> package.
	</para>
       </listitem>
      </varlistentry>

      <varlistentry>
       <term>
	<computeroutput>setuid to 256: failed to launch gateway</computeroutput>
       </term>

       <listitem>
	<para>
	 The September release of <application>Applixware</application> 4.4.1 (the first release with official
	 <acronym>ODBC</acronym> support under Linux) shows problems when user names
	 exceed eight (8) characters in length.
	 Problem description contributed by Steve Campbell
	 (<email>scampbell@@lear.com</email>).
	</para>
       </listitem>
      </varlistentry>

     </variablelist>
    </para>

    <para>
     <note>
      <title>Author</title>

      <para>
       Contributed by Steve Campbell (<email>scampbell@@lear.com</email>),
       1998-10-20
      </para>
     </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
     multiuser 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.
    </para>
   </sect2>

   <sect2>
    <title>Debugging <application>Applixware</application> ODBC Connections</title>

    <para>
     One good tool for debugging connection problems uses the Unix system
     utility <application>strace</application>.
    </para>
    <procedure>
     <title>Debugging with <command>strace</command></title>

     <step performance="required">
      <para>
       Start <application>Applixware</application>.
      </para>
     </step>
     <step performance="required">
      <para>
       Start an <application>strace</application> on
       the <literal>axnet</literal> process.  For example, if

<screen>
<prompt>$</prompt> <userinput>ps -aucx | grep ax</userinput>
</screen>

       shows

<screen>
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
</screen>
      </para>

      <para>
       Then run

<screen>
<prompt>$</prompt> <userinput>strace -f -s 1024 -p 10432</userinput>
</screen>
      </para>
     </step>

     <step performance="required">
      <para>
       Check the <command>strace</command> output.
      </para>
      <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 <command>strace</command> is the way to find out.
       </para>
      </note>
     </step>
    </procedure>

    <para>
     For example, after getting
     a <errorname>Cannot launch gateway on server</errorname>, 
     I ran <command>strace</command> on <literal>axnet</literal> and got

<screen>
[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)
</screen>  
     So what is happening is that <literal>applix elfodbc</literal> is searching for <filename>libodbc.so</filename>, but it
     cannot find it.  That is why <filename>axnet.cnf</filename> needed to be changed.
    </para>
   </sect2>

   <sect2>
    <title>Running the <application>Applixware</application> Demo</title>

    <comment>I think the condition this refers to is gone. -- petere 2002-01-07</comment>

    <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>PostgreSQL</productname> does not currently allow this option.
    </para>

    <para>
     To get around this problem, you can do the following:
    </para>

    <procedure>
     <title>Modifying the <application>Applixware</application> Demo</title>

     <step performance="required">
      <para>
       Copy <filename>/opt/applix/axdata/eng/Demos/sqldemo.am</filename>
       to a local directory.
      </para>
     </step>

     <step performance="required">
      <para>
       Edit this local copy of <filename>sqldemo.am</filename>:
      </para>

      <substeps>

       <step performance="required">
	<para>
	 Search for <literal>null_clause = "NULL"</literal>.
	</para>
       </step>

       <step performance="required">
	<para>
	 Change this to <literal>null_clause = ""</literal>.
	</para>
       </step>

      </substeps>
     </step>
     <step performance="required">
      <para>
       Start <application>Applix Macro Editor</application>.
      </para>
     </step>

     <step performance="required">
      <para>
       Open the <filename>sqldemo.am</filename> file from the <application>Macro Editor</application>.
      </para>
     </step>

     <step performance="required">
      <para>
       Select <menuchoice><guimenu>File</><guimenuitem>Compile and Save</></menuchoice>.
      </para>
     </step>

     <step performance="required">
      <para>
       Exit <application>Macro Editor</application>.
      </para>
     </step>

     <step performance="required">
      <para>
       Start <application>Applix Data</application>.
      </para>
     </step>

     <step performance="required">
      <para>
       Select <menuchoice><guimenu>*</><guimenuitem>Run Macro</guimenuitem></menuchoice>.
      </para>
     </step>

     <step performance="required">
      <para>
       Enter the value <literal>sqldemo</literal>, then click <guibutton>OK</guibutton>.
      </para>

      <para>
       You should see the progress in the status line of the data window
       (in the lower left corner).
      </para>
     </step>

     <step performance="required">
      <para>
       You should now be able to access the demo tables.
      </para>
     </step>
    </procedure>
   </sect2>

   <sect2>
    <title>Useful Macros</title>

    <para>
     You can add information about your
     database login and password to the standard <application>Applix</application> start-up
     macro file. This is an example 
     <filename>~/axhome/macros/login.am</filename> file:

<programlisting>
macro login
set_set_system_var@@("sql_username@@","tgl")
set_system_var@@("sql_passwd@@","no$way")
endmacro
</programlisting>

     <caution>
      <para>
       You should be careful about the file protections on any file containing
       user name and password information.
      </para>
     </caution>
    </para>
   </sect2>

  </sect1>
 </chapter>

<!-- Keep this comment at the end of the file
Local variables:
mode:sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"./reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:("/usr/lib/sgml/catalog")
sgml-local-ecat-files:nil
End:
-->
@


1.30
log
@Spell checking and markup additions
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/odbc.sgml,v 1.29 2002/01/07 02:29:12 petere Exp $
@


1.30.2.1
log
@Back-patch recent file removals into REL7_3_STABLE branch.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/Attic/odbc.sgml,v 1.30 2002/03/22 19:20:16 petere Exp $
@


1.29
log
@Editorial review
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/odbc.sgml,v 1.28 2001/11/21 05:53:41 thomas Exp $
d331 1
a331 1
    <primary>ApplixWare</primary>
d335 1
a335 1
    <productname>ApplixWare</productname> has an 
d338 1
a338 1
    <productname>ApplixWare</productname> 4.4.2 has been
d348 1
a348 1
     <productname>ApplixWare</productname> must be configured correctly
d355 1
a355 1
     <title>Enabling <application>ApplixWare</application> Database Access</title>
d359 1
a359 1
      <productname>ApplixWare</productname> on <productname>Linux</productname>.
d370 1
a370 1
       This library is included with the <application>ApplixWare</application> distribution,
d428 1
a428 1
     <title>Testing <application>ApplixWare</application> ODBC Connections</title>
d553 1
a553 1
	 The September release of <application>ApplixWare</application> 4.4.1 (the first release with official
d586 1
a586 1
    <title>Debugging <application>ApplixWare</application> ODBC Connections</title>
d597 1
a597 1
       Start <application>ApplixWare</application>.
d634 1
a634 1
	Many of the error messages from <productname>ApplixWare</productname>
d659 1
a659 1
    <title>Running the <application>ApplixWare</application> Demo</title>
d665 1
a665 1
     <citetitle>ApplixWare Data Tutorial</citetitle>, you need to create
d677 1
a677 1
     <title>Modifying the <application>ApplixWare</application> Demo</title>
@


1.28
log
@Deprecate 'current' for date/time input.
Fix up references to "PostgreSQL" rather than "Postgres". Was roughly
 evenly split between the two before. ref/ files not yet done.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/odbc.sgml,v 1.27 2001/11/12 19:19:39 petere Exp $
d26 3
d44 1
a44 1
   transportable between servers from different manufacturers..
a46 3
  <sect1 id="odbc-background">
   <title>Background</title>

d55 1
a55 1
    The backend access come from <acronym>ODBC</acronym> drivers, 
d57 1
a57 1
    allow data access.   <productname>psqlODBC</productname> is such a driver,
d65 1
a65 1
    back end database, regardless of the vendor, as long as the database schema
d74 2
a75 2
    same calls and the back end data source would look the same (to the Windows
    app).
d176 1
a176 1
    Registry files, but despite this restriction can be made to work.
d189 1
a189 1
    <programlisting>
d191 4
a194 4
Database=<replaceable>DatabaseName</replaceable>
Servername=localhost
Port=5432
    </programlisting>
d215 1
a215 1
    <programlisting>
d249 1
a249 1
    </programlisting>
d301 2
a302 1
     Microsoft's web site or in your <productname>VC++</productname> docs.
d309 1
a309 1
     link to the <acronym>ODBC</acronym> back end database 
d314 1
a314 1
     Playing around with MS Access will help you sort this out.  Try using
d358 1
a358 1
      These instructions are for the <literal>4.4.2</literal> release of
d415 1
a415 1
       described above.  You may also want to add the flag
d480 1
a480 1
       The <literal>Ready</literal> message will appear in the lower left corner of the data
d553 1
a553 1
	 The September release of <application>ApplixWare</application> v4.4.1 (the first release with official
d578 1
a578 1
     multiple user system it really should be run with root security 
d637 1
a637 1
	is sent, so <application>strace</application> is the way to find out.
d645 1
a645 1
     a <literal>Cannot launch gateway on server</literal>, 
d649 3
a651 6
[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)
d661 2
d671 1
d721 1
a721 1
       Select <command>File->Compile and Save</command>.
d739 1
a739 1
       Select <command>*->Run Macro</command>
d745 1
a745 1
       Enter the value <literal>sqldemo</literal>, then click <command>OK</command>.
d761 1
d771 1
a771 1
     <programlisting>
d776 1
a776 1
     </programlisting>
@


1.27
log
@Add some more index entries.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/odbc.sgml,v 1.26 2001/10/31 20:39:30 petere Exp $
d51 1
a51 1
    <productname>Postgres</productname> <acronym>RDBMS</acronym>.
d71 1
a71 1
    and <productname>Postgres</productname> servers that have
d198 1
a198 1
      Remember that the <productname>Postgres</productname> database name is
d200 1
a200 1
      The <productname>Postgres</productname> server manages the actual access
d290 1
a290 1
      If I write an application for <productname>Postgres</productname> 
d292 1
a292 1
      to the <productname>Postgres</productname> server, 
d338 1
a338 1
    demonstrated under Linux with <productname>Postgres</productname> 7.0 
d340 1
a340 1
    driver contained in the <productname>Postgres</productname> distribution.
d349 1
a349 1
     be able to access the <productname>Postgres</productname>
d437 1
a437 1
       Select the <productname>Postgres</productname> database of interest.
d669 1
a669 1
     and <productname>Postgres</productname> does not currently allow this option.
@


1.26
log
@A little reformatting for better print appearance.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/odbc.sgml,v 1.25 2001/10/09 22:32:32 petere Exp $
d149 1
d170 2
d314 1
a314 1
     <literal>File->Get External Data</literal>.
@


1.25
log
@Allow optional () after current_user, session_user, user, current_time,
current_timestamp, current_date for ODBC compatibility.

Add more functions to odbc.sql catalog extension, use new CREATE OR
REPLACE FUNCTION.

Document iODBC/unixODBC build options.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/odbc.sgml,v 1.24 2001/09/13 15:55:23 petere Exp $
d383 1
a383 1
	 <programlisting>
d385 1
a385 1
	 </programlisting>
d392 1
a392 1
	 <programlisting>
d394 1
a394 1
	 </programlisting>
d413 1
a413 1
       <programlisting>
d415 1
a415 1
       </programlisting>
d441 1
a441 1
	 Select <command>Query->Choose Server</command>.  
d446 1
a446 1
	 Select <acronym>ODBC</acronym>, and click <command>Browse</command>.
d448 1
a448 1
	 should be shown.  Make sure that the <option>Host: field</option>
d455 2
a456 2
	 Select the database in the box that was launched by <command>Browse</command>,
	 then click <command>OK</command>.
d462 1
a462 1
	 and click <command>OK</command>.
d468 1
a468 1
       You should see <literal>Starting elfodbc server</literal>
d482 6
a487 3
       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.
d536 1
a536 1
	 of the <productname>Postgres</productname>
d601 3
a603 3
       <programlisting>
% ps -aucx | grep ax 
       </programlisting>
d607 1
a607 1
       <programlisting>
d610 1
a610 1
       </programlisting>
d616 3
a618 3
       <programlisting>
% strace -f -s 1024 -p 10432
       </programlisting>
d644 1
a644 1
<programlisting>
d651 1
a651 1
</programlisting>  
@


1.24
log
@Replace ASCII-quotes with proper markup.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/odbc.sgml,v 1.23 2001/09/10 21:58:47 petere Exp $
d83 15
a97 13
    The first thing to note about the <productname>psqlODBC</> driver
    (or any <acronym>ODBC</> driver) is that there must exist a
    <firstterm>driver manager</> on the system where the
    <acronym>ODBC</> driver is to be used. There exists a free
    <acronym>ODBC</> driver for Unix called
    <indexterm><primary>iODBC</primary></indexterm>
    <productname>iODBC</> which can be obtained via <ulink
    url="http://www.iodbc.org">http://www.iodbc.org</ulink>.
    Instructions for installing <productname>iODBC</> are contained in
    the <productname>iODBC</> distribution. Having said that, any
    driver manager that you can find for your platform should support
    the <productname>psqlODBC</> driver, or any other <acronym>ODBC</>
    driver for that matter.
d100 11
d112 8
a119 7
    To install <productname>psqlODBC</> you simply need to supply the
    <option>--enable-odbc</> option to the <filename>configure</> script when you are
    building the entire <productname>PostgreSQL</> distribution. The library
    and header files will then automatically be built and installed with the
    rest of the programs. If you forget that option or want to build the ODBC
    driver later you can change into the directory <filename>src/interfaces/odbc</>
    and do <literal>make</> and <literal>make install</> there.
d123 23
a145 7
    The installation-wide configuration file <filename>odbcinst.ini</> will be
    installed into the directory <filename>/usr/local/pgsql/etc/</>, or equivalent,
    depending on what <option>--prefix</> and/or <option>--sysconfdir</> options
    you supplied to <filename>configure</>. Since this file can also be shared
    between different <acronym>ODBC</> drivers you can also install it in a shared
    location. To do that, override the location of this file with the
    <option>--with-odbcinst</> option.
d158 5
a162 2
    database will ensure that all subsequent new databases will
    have these same definitions.
a163 11

   <sect2>
    <title>Supported Platforms</title>
    <para>
     <productname>psqlODBC</productname> has been built and tested
     on <systemitem class="osname">Linux</>. There have been reports of success
     with <systemitem class="osname">FreeBSD</> and with <systemitem class="osname">Solaris</>. There are no known restrictions
     on the basic code for other platforms which already support
     <productname>Postgres</productname>.
    </para>
   </sect2>
@


1.23
log
@Markup and spell-check run over Programmer's Guide (rather incomplete still).
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/odbc.sgml,v 1.22 2001/05/12 22:51:35 petere Exp $
d454 1
a454 1
       The 'Ready' message will appear in the lower left corner of the data
d666 1
a666 1
	 Search for 'null_clause = "NULL"
d672 1
a672 1
	 Change this to null_clause = ""
d716 1
a716 1
       Enter the value "<literal>sqldemo</literal>", then click <command>OK</command>.
@


1.22
log
@Add index.  Only some parts of the manual set have index entries so far...
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/odbc.sgml,v 1.21 2001/01/20 20:59:28 petere Exp $
d56 1
a56 1
    or vendor specifc drivers that
d59 1
a59 1
    available, such as the OpenLink <acronym>ODBC</acronym> drivers.
d136 2
a137 2
     on <productname>Linux</productname>. There have been reports of success
     with FreeBSD and with Solaris. There are no known restrictions
d251 1
a251 1
       In Visual C++, you can use the CRecordSet class, which wraps the 
d253 1
a253 1
       set within an MFC 4.2 class.  This is the easiest route if you are doing
d280 1
a280 1
     Visual Basic and the other RAD tools have Recordset objects 
d294 1
a294 1
      You'll have to set up a DSN first.
d302 1
a302 1
   <title>ApplixWare</title>
d329 1
a329 1
     <title>Enabling ApplixWare Database Access</title>
d344 1
a344 1
       This library is included with the ApplixWare distribution,
d374 1
a374 1
	 which will tell elfodbc to look in this directory
d402 1
a402 1
     <title>Testing ApplixWare ODBC Connections</title>
d427 1
a427 1
	 is empty (if it is not, axnet will try to contact axnet on another machine
d439 1
a439 1
	 Enter username and password in the login identification dialog,
d446 1
a446 1
       You should see "<literal>Starting elfodbc server</literal>"
d479 1
a479 1
	Cannot launch gateway on server
d490 1
a490 1
       <term>
d492 1
a492 1
	IM003::[iODBC][Driver Manager]Specified driver could not be loaded
d504 1
a504 1
	Server: Broken Pipe
d519 1
a519 1
	setuid to 256: failed to launch gateway
d524 2
a525 2
	 The September release of ApplixWare v4.4.1 (the first release with official
	 <acronym>ODBC</acronym> support under Linux) shows problems when usernames
d527 1
a527 1
	 Problem description ontributed by Steve Campbell
d557 1
a557 1
    <title>Debugging ApplixWare ODBC Connections</title>
d564 1
a564 1
     <title>Debugging with strace</title>
d568 1
a568 1
       Start applixware.
d574 1
a574 1
       the axnet process.  For example, if
d599 1
a599 1
       Check the strace output.
d616 2
a617 2
     a "<literal>Cannot launch gateway on server</literal>", 
     I ran strace on axnet and got
d619 1
a619 1
     <programlisting>
d626 3
a628 3
     </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.
d633 1
a633 1
    <title>Running the ApplixWare Demo</title>
d648 1
a648 1
     <title>Modifying the ApplixWare Demo</title>
d686 1
a686 1
       Open the sqldemo.am file from the <application>Macro Editor</application>.
d737 1
a737 1
     database login and password to the standard Applix start-up
d751 1
a751 1
       username and password information.
@


1.21
log
@Replace some oldish, non-SQL'ish elements with more standard forms. (cast
syntax, type names, function names, etc.)
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/odbc.sgml,v 1.20 2000/12/22 21:51:58 petere Exp $
d22 4
d87 3
a89 2
    <acronym>ODBC</> driver for Unix called <productname>iODBC</>
    which can be obtained via <ulink
d303 4
@


1.20
log
@Make use of <email> tag for marking up email addresses.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/odbc.sgml,v 1.19 2000/12/22 18:57:49 petere Exp $
a292 8
    <!--
   <Para>
   <Tip>
   <Para>
    The <productname>Postgres</productname> datetime type will break MS Access.
   </Para>
   </Tip>
    -->
@


1.19
log
@Replace incorrect uses of 'which' with 'that'.  (so-called "wicked which")
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/odbc.sgml,v 1.18 2000/09/29 20:21:34 petere Exp $
d24 2
a25 2
    Background information originally by
    <ulink url="mailto:tgoeke@@xpressway.com">Tim Goeke</ulink>
d526 2
a527 2
	 Problem description ontributed by 
	 <ulink url="mailto:scampbell@@lear.com">Steve Campbell</ulink>.
d540 2
a541 3
       Contributed by 
       <ulink url="mailto:scampbell@@lear.com">Steve Campbell</ulink> on
       1998-10-20.
@


1.18
log
@Add `id' attributes to all `chapter' and `sect1' tags, to generate useful
names for the HTML files (e.g., not x4856.htm).
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/odbc.sgml,v 1.17 2000/09/18 20:11:37 petere Exp $
d32 1
a32 1
   which allows you to write applications which can interoperate
d36 1
a36 1
   allowing a user or developer to write applications which are 
d67 1
a67 1
    and <productname>Postgres</productname> servers which have
@


1.17
log
@Move contrib/odbc/odbc.sql together with odbc driver, remove old files;
revise ODBC "installation instructions"; update some other outdated
documentation; update contrib documentation
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/odbc.sgml,v 1.16 2000/08/29 20:02:07 momjian Exp $
d40 1
a40 1
  <sect1>
d75 1
a75 1
  <sect1>
d139 1
a139 1
  <sect1>
d223 1
a223 1
  <sect1>
d304 1
a304 2

  <sect1>
@


1.16
log
@Startup is actually start-up.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/odbc.sgml,v 1.15 2000/05/02 20:01:52 thomas Exp $
a72 12

<!--
   <para>
    <ulink url="http://www.insightdist.com/">Insight Distributors</ulink> 
    provides active and ongoing
    support for the core <productname>psqlODBC</productname> distribution. 
    They provide a
    <ulink url="http://www.insightdist.com/psqlodbc/"><acronym>FAQ</acronym></ulink>,
    ongoing development on the code base, and actively participate on the 
    <ulink url="mailto:interfaces@@postgresql.org">interfaces mailing list</ulink>.
   </para>
-->
d76 1
a76 1
   <title><productname>Windows</productname> Applications</title>
d79 13
a91 3
    In the real world, differences in drivers and the level of 
    <acronym>ODBC</acronym> support
    lessens the potential of <acronym>ODBC</acronym>:
d93 9
a101 12
    <itemizedlist spacing="compact" mark="bullet">
     <listitem>
      <para>
       Access, Delphi, and Visual Basic all support <acronym>ODBC</acronym> directly.
      </para>
     </listitem>
     <listitem>
      <para>
       Under C++, such as Visual C++, 
       you can use the C++ <acronym>ODBC</acronym> <acronym>API</acronym>.
      </para>
     </listitem>
d103 8
a110 9
     <listitem>
      <para>
       In Visual C++, you can use the CRecordSet class, which wraps the 
       <acronym>ODBC</acronym> <acronym>API</acronym>
       set within an MFC 4.2 class.  This is the easiest route if you are doing
       Windows C++ development under Windows NT.
      </para>
     </listitem>
    </itemizedlist>
a112 52
   <sect2>
    <title>Writing Applications</title>

    <para>
     <quote>
      If I write an application for <productname>Postgres</productname> 
      can I write it using <acronym>ODBC</acronym> calls
      to the <productname>Postgres</productname> server, 
      or is that only when another database program 
      like MS SQL Server or Access needs to access the data?
     </quote>
    </para>
    <para>
     The <acronym>ODBC</acronym> <acronym>API</acronym>
     is the way to go.
     For <productname>Visual C++</productname> coding you can find out more at
     Microsoft's web site or in your <productname>VC++</productname> docs.
    </para>

    <para>
     Visual Basic and the other RAD tools have Recordset objects 
     that use <acronym>ODBC</acronym>
     directly to access data.  Using the data-aware controls, you can quickly
     link to the <acronym>ODBC</acronym> back end database 
     (<emphasis>very</emphasis> quickly).
    </para>

    <para>
     Playing around with MS Access will help you sort this out.  Try using
     <literal>File->Get External Data</literal>.
    </para>

    <tip>
     <para>
      You'll have to set up a DSN first.
     </para>
    </tip>

    <!--
   <Para>
   <Tip>
   <Para>
    The <productname>Postgres</productname> datetime type will break MS Access.
   </Para>
   </Tip>
    -->
   </sect2>
  </sect1>

  <sect1>
   <title>Unix Installation</title>

d114 11
a124 7
    <productname>ApplixWare</productname> has an 
    <acronym>ODBC</acronym> database interface
    supported on at least some platforms. 
    <productname>ApplixWare</productname> v4.4.2 has been
    demonstrated under Linux with <productname>Postgres</productname> v7.0 
    using the <productname>psqlODBC</productname>
    driver contained in the <productname>Postgres</productname> distribution.
d128 1
a128 2
    <title>Building the Driver</title>

d130 5
a134 44
     The first thing
     to note about the <productname>psqlODBC</productname> driver
     (or any <acronym>ODBC</acronym> driver) is that there must
     exist a driver manager on the system where
     the <acronym>ODBC</acronym> driver is to be
     used. There exists a freeware <acronym>ODBC</acronym> driver for Unix
     called <productname>iodbc</productname> which
     can be obtained from various locations on the Net, including at
     <ulink url="http://www.as220.org/FreeODBC/iodbc-2.12.shar.Z">AS200</ulink>. 
     Instructions for installing <productname>iodbc</productname>
     are beyond the scope of this
     document, but there is a <filename>README</filename>
     that can be found inside the <productname>iodbc</productname> compressed
     .shar file that should explain how to get it up and running.
    </para>

    <para>
     Having said that, any driver manager that you can find for your platform
     should support the <productname>psqlODBC</productname> driver
     or any <acronym>ODBC</acronym> driver.
    </para>

    <para>
     The Unix configuration files for <productname>psqlODBC</productname>
     have recently been extensively
     reworked to allow for easy building on supported platforms as
     well as to allow for support of other Unix platforms in the future.
     The new configuration and build files for the driver should make it
     a simple process to build the driver on the supported platforms. Currently
     these include Linux and FreeBSD but we are hoping other users will
     contribute the necessary information to quickly expand the number of
     platforms for which the driver can be built.
    </para>

    <para>
     There are actually two separate methods to build the driver depending on
     how you received it and these differences come down to only where and how to
     run <application>configure</application> and <application>make</application>. 
     The driver can be built in a standalone, client-only installation, or can be 
     built as a part of the main <productname>Postgres</productname> distribution.
     The standalone installation is convenient if you have <acronym>ODBC</acronym>
     client applications on multiple, heterogeneous platforms. The integrated
     installation is convenient when the target client is the same as the
     server, or when the client and server have similar runtime configurations.
a135 333

    <para>
     Specifically if you have received the <productname>psqlODBC</productname>
     driver as part of the <productname>Postgres</productname> distribution
     (from now on referred to as an "integrated" build) then you will
     configure and make the <acronym>ODBC</acronym> driver
     from the top level source directory
     of the <productname>Postgres</productname> distribution
     along with the rest of its libraries.
     If you received the driver as a standalone package than you will run
     configure and make from the directory in which you unpacked the
     driver source.
    </para>

    <procedure>
     <title>Integrated Installation</title>

     <para>
      This installation procedure is appropriate for an integrated installation.
     </para>

     <step performance="required">
      <para>
       Specify the <option>--with-odbc</option>
       command-line argument for <application>src/configure</application>:

       <programlisting>
% ./configure --with-odbc
% make
       </programlisting>
      </para>
     </step>

     <step performance="required">
      <para>
       Rebuild the <productname>Postgres</productname> distribution:

       <programlisting>
% make install
       </programlisting>
      </para>
     </step>

     <step performance="optional">
      <para>
       Install the ODBC catalog extensions available in
       <filename>PGROOT/contrib/odbc/odbc.sql</filename>:

       <programlisting>
% psql -e template1 &lt; $PGROOT/contrib/odbc/odbc.sql
       </programlisting>

       where specifying <literal>template1</literal> as the target
       database will ensure that all subsequent new databases will
       have these same definitions.
      </para>
     </step>
    </procedure>

    <para>
     Once configured, the <acronym>ODBC</acronym> driver will be built and installed
     into the areas defined for the other components of the
     <productname>Postgres</productname> system. The installation-wide
     <acronym>ODBC</acronym> configuration file will be placed into
     the top directory of the Postgres target tree (<envar>POSTGRESDIR</envar>).
     This can be overridden from the <application>make</application> command-line
     as
     <programlisting>
% make ODBCINST=<replaceable>filename</replaceable> install
     </programlisting>
    </para>

    <procedure>
     <title>Pre-v6.4 Integrated Installation</title>

     <para>
      If you have a <productname>Postgres</productname> installation older than
      v6.4, you have the original source tree available, 
      and you want to use the newest version of the <acronym>ODBC</acronym>
      driver, then you may want to try this form of installation.
     </para>

     <step performance="required">
      <para>
       Copy the output tar file to your target system and unpack it into a 
       clean directory.
      </para>
     </step>
     <step performance="required">
      <para>
       From the directory containing the
       sources, type:

       <programlisting>
% ./configure
% make
% make POSTGRESDIR=<replaceable class="parameter">PostgresTopDir</replaceable> install
       </programlisting>
      </para>
     </step>

     <step performance="optional">
      <para>
       If you would like to install components into different trees, 
       then you can specify various destinations explicitly:

       <programlisting>
% make BINDIR=bindir  LIBDIR=libdir  HEADERDIR=headerdir ODBCINST=instfile install
       </programlisting>
      </para>
     </step>
    </procedure>

    <procedure>
     <title>Standalone Installation</title>

     <para>
      A standalone installation is not integrated with or built on the normal
      <productname>Postgres</productname> distribution. It should be best suited
      for building the <acronym>ODBC</acronym> driver for multiple, heterogeneous
      clients who do not have a locally-installed <productname>Postgres</productname>
      source tree.
     </para>

     <para>
      The default location for libraries and headers 
      for the standalone installation is <filename>/usr/local/lib</filename>
      and <filename>/usr/local/include/iodbc</filename>, respectively.
      There is another system wide configuration file that gets installed
      as <filename>/share/odbcinst.ini</filename> (if <filename>/share</filename>
      exists) or as <filename>/etc/odbcinst.ini</filename>
      (if <filename>/share</filename> does not exist).
     </para>

     <note>
      <para>
       Installation of files into <filename>/share</filename>
       or <filename>/etc</filename> requires system root privileges.
       Most installation steps for <productname>Postgres</productname> do not
       have this requirement, and you can choose another destination which
       is writable by your non-root <productname>Postgres</productname> superuser
       account instead.
      </para>
     </note>

     <step performance="required">
      <para>
       The standalone installation distribution can be built from the
       <productname>Postgres</productname> distribution or may be obtained from 
       <ulink url="http://www.insightdist.com/psqlodbc">Insight Distributors</ulink>,
       the current maintainers of the non-Unix sources.
      </para>

      <para>
       Copy the zip
       or gzipped tarfile to an empty directory. If using the zip package
       unzip it with the command 
       <programlisting>
% unzip -a <replaceable>packagename</replaceable>
       </programlisting>

       The <option>-a</option> option
       is necessary to get rid of <acronym>DOS</acronym> 
       CR/LF pairs in the source files.
      </para>

      <para>
       If you have the gzipped tar package than simply run

       <programlisting>
% tar -xzf <replaceable>packagename</replaceable>
       </programlisting>
      </para>

      <substeps>

       <step performance="optional">
	<para>
	 To create a tar file for a complete standalone installation
	 from the main <productname>Postgres</productname> source tree:
	</para>
       </step>
      </substeps>
     </step>
     <step performance="required">
      <para>
       Configure the main <productname>Postgres</productname> distribution.
      </para>
     </step>
     <step performance="required">
      <para>
       Create the tar file:

       <programlisting>
% cd interfaces/odbc
% make standalone
       </programlisting>
      </para>
     </step>

     <step performance="required">
      <para>
       Copy the output tar file to your target system. Be sure to transfer as
       a binary file if using <application>ftp</application>.
      </para>
     </step>

     <step performance="required">
      <para>
       Unpack the tar file into a clean
       directory.
      </para>
     </step>

     <step performance="required">
      <para>
       Configure the standalone installation:

       <programlisting>
% ./configure
       </programlisting>
      </para>

      <para>
       The configuration can be done with options:

       <programlisting>
% ./configure --prefix=<replaceable>rootdir</replaceable> --with-odbc=<replaceable>inidir</replaceable>
       </programlisting>

       where <option>--prefix</option> installs the libraries and headers in
       the directories <filename><replaceable>rootdir</replaceable>/lib</filename> and
       <filename><replaceable>rootdir</replaceable>/include/iodbc</filename>, and
       <option>--with-odbc</option> installs <filename>odbcinst.ini</filename> in the
       specified directory.
      </para>

      <para>
       Note that both of these options can also be used from the integrated build
       but be aware that <emphasis>when used in the integrated build</emphasis>
       <option>--prefix</option> will also apply to the rest of
       your <productname>Postgres</productname> installation.
       <option>--with-odbc</option> applies only to the configuration file
       <filename>odbcinst.ini</filename>.
      </para>
     </step>

     <step performance="required">
      <para>
       Compile and link the source code:

       <programlisting>
% make ODBCINST=<replaceable>instdir</replaceable>
       </programlisting>
      </para>

      <para>
       You can also override the default location for installation on the
       'make' command line. This only applies to the installation of the
       library and header files. Since the driver needs to know the location
       of the odbcinst.ini file attempting to override the enviroment variable
       that specifies its installation directory will probably cause you
       headaches. It is safest simply to allow the driver to install the
       odbcinst.ini file in the default directory or the directory you specified
       on the './configure' command line with --with-odbc.
      </para>
     </step>

     <!--
     This doesn't currently work - thomas 1998-10-19
    <tip>
    <para>
    <envar>ODBCINST</envar> can be specified during configuration or during
     the compilation. It is not necessary to do so in both steps.
    </tip>
     -->

     <step performance="required">
      <para>
       Install the source code:

       <programlisting>
% make POSTGRESDIR=<replaceable>targettree</replaceable> install
       </programlisting>
      </para>

      <para>
       To override the library and header installation directories separately
       you need to pass the correct installation variables on the
       <literal>make install</literal> command line. These variables are
       <envar>LIBDIR</envar>, <envar>HEADERDIR</envar>
       and <envar>ODBCINST</envar>.
       Overriding <envar>POSTGRESDIR</envar> on the make command line will cause
       <envar>LIBDIR</envar> and <envar>HEADERDIR</envar>
       to be rooted at the new directory you specify. 
       <envar>ODBCINST</envar> is independent of <envar>POSTGRESDIR</envar>.
      </para>

      <para>
       Here is how you would specify the various destinations explicitly:

       <programlisting>
% make BINDIR=<replaceable>bindir</replaceable> LIBDIR=<replaceable>libdir</replaceable> HEADERDIR=<replaceable>headerdir</replaceable> install
       </programlisting>
      </para>

      <para>
       For example, typing

       <programlisting>
% make POSTGRESDIR=/opt/psqlodbc install
       </programlisting>

       (after you've used
       <application>./configure</application> and <application>make</application>)
       will cause the libraries and headers to be installed in the directories
       <filename>/opt/psqlodbc/lib</filename>
       and <filename>/opt/psqlodbc/include/iodbc</filename> respectively.
      </para>

      <para>
       The command

       <programlisting>
% make POSTGRESDIR=/opt/psqlodbc HEADERDIR=/usr/local install
       </programlisting>

       should cause the libraries to be installed in /opt/psqlodbc/lib and
       the headers in /usr/local/include/iodbc. If this doesn't work as
       expected please contact one of the maintainers.
      </para>
     </step>
    </procedure>
d160 1
a160 1
Driver = <replaceable>POSTGRESDIR</replaceable>/lib/libpsqlodbc.so
d224 82
d308 10
a756 2
   <sect2>
    <title>Supported Platforms</title>
a757 8
    <para>
     <productname>psqlODBC</productname> has been built and tested
     on <productname>Linux</productname>. There have been reports of success
     with FreeBSD and with Solaris. There are no known restrictions
     on the basic code for other platforms which already support
     <productname>Postgres</productname>.
    </para>
   </sect2>
@


1.15
log
@Fixups in content and markup for 7.0 release.
@
text
@d2 1
a2 1
$Header: /usr/local/cvsroot/pgsql/doc/src/sgml/odbc.sgml,v 1.14 2000/03/31 03:27:41 thomas Exp $
d1073 1
a1073 1
     database login and password to the standard Applix startup
@


1.14
log
@Minor markup changes. Refer to (".../catalog") in the emacs hints.
@
text
@d2 1
a2 1
$Header$
d128 2
a129 1
      like MS SQL Server or Access needs to access the data?</quote>
d175 2
a176 2
    <productname>ApplixWare</productname> v4.4.1 has been
    demonstrated under Linux with <productname>Postgres</productname> v6.4 
d257 2
a258 2
	% ./configure --with-odbc
	% make
d262 1
d268 1
a268 1
	% make install
d272 15
d298 1
a298 1
      % make ODBCINST=<replaceable>filename</replaceable> install
d324 3
a326 3
	% ./configure
	% make
	% make POSTGRESDIR=<replaceable class="parameter">PostgresTopDir</replaceable> install
d337 1
a337 1
	% make BINDIR=bindir  LIBDIR=libdir  HEADERDIR=headerdir ODBCINST=instfile install
d388 1
a388 1
	% unzip -a <replaceable>packagename</replaceable>
d400 1
a400 1
	tar -xzf <replaceable>packagename</replaceable>
d424 2
a425 2
	% cd interfaces/odbc
	% make standalone
d449 1
a449 1
	% ./configure
d457 1
a457 2
	% ./configure --prefix=<replaceable>rootdir</replaceable>
	--with-odbc=<replaceable>inidir</replaceable>
d482 1
a482 1
	% make ODBCINST=<replaceable>instdir</replaceable>
d512 1
a512 1
	% make POSTGRESDIR=<replaceable>targettree</replaceable> install
d532 1
a532 3
	% make BINDIR=<replaceable>bindir</replaceable>
	LIBDIR<replaceable>>libdi</replaceable>>
	HEADERDIR=<replaceable>headerdir</replaceable> install
d540 1
a540 1
	% make POSTGRESDIR=/opt/psqlodbc install
d554 1
a554 1
	% make POSTGRESDIR=/opt/psqlodbc HEADERDIR=/usr/local install
d587 4
a590 4
     Driver = <replaceable>POSTGRESDIR</replaceable>/lib/libpsqlodbc.so
     Database=<replaceable>DatabaseName</replaceable>
     Servername=localhost
     Port=5432
d649 1
d697 1
a697 1
	  #libFor elfodbc /ax/<replaceable>...</replaceable>
d706 1
a706 1
	  libFor elfodbc <replaceable>applixroot</replaceable>/applix/axdata/axshlib/lib
d727 1
a727 1
	TextAsLongVarchar=0
d781 1
a781 1
       You should see <quote>Starting elfodbc server</quote>
d913 1
a913 1
	ps -aucx | grep ax 
d919 2
a920 2
	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
d928 1
a928 1
	strace -f -s 1024 -p 10432 
d952 1
a952 1
     a <quote>Cannot launch gateway on server</quote>, 
d956 6
a961 6
      [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)
d1052 1
a1052 1
       Enter the value <quote>sqldemo</quote>, then click <command>OK</command>.
d1078 4
a1081 4
      macro login
      set_set_system_var@@("sql_username@@","tgl")
      set_system_var@@("sql_passwd@@","no$way")
      endmacro
@


1.13
log
@Change rules for interpreting date/time input to disallow 1 and 3 character
 years. Rejects dates like '0.085', which were accepted previously.
Minor mods of ODBC markup.
@
text
@d1 4
d1103 1
a1103 1
sgml-local-catalogs:("/usr/lib/sgml/CATALOG")
@


1.12
log
@Start updating for the v7.0 release.
Use "generic functions" for math and other routines.
Use SQL92 "type 'literal'" syntax rather than Postgres "'literal'::type".
@
text
@d695 2
a696 2
	 but if you have installed applix somewhere else then
	 change the path accordingly.
@


1.11
log
@Markup changes for v6.5 release.
Clean out duplicate stuff in odbc.sgml resulting from a faulty patch.
@
text
@d1 68
a68 148
<Chapter Id="odbc">
<DocInfo>
<AuthorGroup>
<Author>
<FirstName>Tim</FirstName>
<Surname>Goeke</Surname>
</Author>
<Author>
<FirstName>Thomas</FirstName>
<Surname>Lockhart</Surname>
</Author>
</AuthorGroup>
<Date>1998-10-21</Date>
</DocInfo>

<Title>ODBC Interface</Title>

<Note>
<Para>
Background information originally by
 <ULink url="mailto:tgoeke@@xpressway.com">Tim Goeke</ULink>
</Para>
</Note>

<Para>
<acronym>ODBC</acronym> (Open Database Connectivity) is an abstract 
<acronym>API</acronym> 
which allows you to write applications which can interoperate
with various <acronym>RDBMS</acronym> servers.
<acronym>ODBC</acronym> provides a product-neutral interface 
between frontend applications and database servers,
allowing a user or developer to write applications which are 
transportable between servers from different manufacturers..
</Para>

<Sect1>
<Title>Background</Title>

<Para>
The <acronym>ODBC</acronym> <acronym>API</acronym> matches up 
on the backend to an <acronym>ODBC</acronym>-compatible data source.
This could be anything from a text file to an Oracle or 
<productname>Postgres</productname> <acronym>RDBMS</acronym>.
</Para>

<Para>
The backend access come from <acronym>ODBC</acronym> drivers, 
or vendor specifc drivers that
allow data access.   <productname>psqlODBC</productname> is such a driver,
 along with others that are
available, such as the OpenLink <acronym>ODBC</acronym> drivers.
</Para>

<Para>
Once you write an <acronym>ODBC</acronym> application, 
you <emphasis>should</emphasis> be able to connect to <emphasis>any</emphasis>
back end database, regardless of the vendor, as long as the database schema
is the same.
</Para>

<Para>
For example. you could have <productname>MS SQL Server</productname>
 and <productname>Postgres</productname> servers which have
exactly the same data.  Using <acronym>ODBC</acronym>, 
your Windows application would make exactly the
same calls and the back end data source would look the same (to the Windows
app).
</Para>

<para>
<ulink url="http://www.insightdist.com/">Insight Distributors</ulink> 
provides active and ongoing
support for the core <productname>psqlODBC</productname> distribution. 
They provide a
<ulink url="http://www.insightdist.com/psqlodbc/"><acronym>FAQ</acronym></ulink>,
 ongoing development on the code base, and actively participate on the 
<ulink url="mailto:interfaces@@postgresql.org">interfaces mailing list</ulink>.
</Para>
</sect1>

<sect1>
<title><productname>Windows</productname> Applications</title>

<Para>
In the real world, differences in drivers and the level of 
<acronym>ODBC</acronym> support
lessens the potential of <acronym>ODBC</acronym>:

<ItemizedList Mark="bullet" Spacing="compact">
<ListItem>
<Para>
Access, Delphi, and Visual Basic all support <acronym>ODBC</acronym> directly.
</Para>
</listitem>
<ListItem>
<Para>
Under C++, such as Visual C++, 
you can use the C++ <acronym>ODBC</acronym> <acronym>API</acronym>.
</Para>
</listitem>

<ListItem>
<Para>
In Visual C++, you can use the CRecordSet class, which wraps the 
<acronym>ODBC</acronym> <acronym>API</acronym>
set within an MFC 4.2 class.  This is the easiest route if you are doing
Windows C++ development under Windows NT.
</Para>
</listitem>
</ItemizedList>
</Para>

<sect2>
<title>Writing Applications</title>

<Para>
<quote>
If I write an application for <productname>Postgres</productname> 
can I write it using <acronym>ODBC</acronym> calls
to the <productname>Postgres</productname> server, 
or is that only when another database program 
like MS SQL Server or Access needs to access the data?</quote>
</para>
<Para>
The <acronym>ODBC</acronym> <acronym>API</acronym>
is the way to go.
For <productname>Visual C++</productname> coding you can find out more at
Microsoft's web site or in your <productname>VC++</productname> docs.
</Para>

<Para>
Visual Basic and the other RAD tools have Recordset objects 
that use <acronym>ODBC</acronym>
directly to access data.  Using the data-aware controls, you can quickly
link to the <acronym>ODBC</acronym> back end database 
(<Emphasis>very</Emphasis> quickly).
</Para>

<Para>
Playing around with MS Access will help you sort this out.  Try using
<literal>File->Get External Data</literal>.
</Para>

<Tip>
<Para>
You'll have to set up a DSN first.
</Para>
</Tip>
d71 9
a79 6
<Para>
<Tip>
<Para>
The <productname>Postgres</productname> datetime type will break MS Access.
</Para>
</Tip>
d81 1
a81 2
</sect2>
</sect1>
d83 2
a84 2
<sect1>
<title>Unix Installation</title>
d86 507
a592 310
<para>
<productname>ApplixWare</productname> has an 
<acronym>ODBC</acronym> database interface
supported on at least some platforms. 
<productname>ApplixWare</productname> v4.4.1 has been
demonstrated under Linux with <productname>Postgres</productname> v6.4 
using the <productname>psqlODBC</productname>
driver contained in the <productname>Postgres</productname> distribution.
</Para>

<sect2>
<title>Building the Driver</title>

<para>
The first thing
to note about the <productname>psqlODBC</productname> driver
 (or any <acronym>ODBC</acronym> driver) is that there must
exist a driver manager on the system where
 the <acronym>ODBC</acronym> driver is to be
used. There exists a freeware <acronym>ODBC</acronym> driver for Unix
 called <productname>iodbc</productname> which
can be obtained from various locations on the Net, including at
<ulink url="http://www.as220.org/FreeODBC/iodbc-2.12.shar.Z">AS200</ulink>. 
Instructions for installing <productname>iodbc</productname>
 are beyond the scope of this
document, but there is a <filename>README</filename>
 that can be found inside the <productname>iodbc</productname> compressed
.shar file that should explain how to get it up and running.
</Para>

<para>
Having said that, any driver manager that you can find for your platform
should support the <productname>psqlODBC</productname> driver
 or any <acronym>ODBC</acronym> driver.
</Para>

<para>
The Unix configuration files for <productname>psqlODBC</productname>
 have recently been extensively
reworked to allow for easy building on supported platforms as
well as to allow for support of other Unix platforms in the future.
The new configuration and build files for the driver should make it
a simple process to build the driver on the supported platforms. Currently
these include Linux and FreeBSD but we are hoping other users will
contribute the necessary information to quickly expand the number of
platforms for which the driver can be built.
</Para>

<para>
There are actually two separate methods to build the driver depending on
how you received it and these differences come down to only where and how to
run <application>configure</application> and <application>make</application>. 
The driver can be built in a standalone, client-only installation, or can be 
built as a part of the main <productname>Postgres</productname> distribution.
The standalone installation is convenient if you have <acronym>ODBC</acronym>
client applications on multiple, heterogeneous platforms. The integrated
installation is convenient when the target client is the same as the
server, or when the client and server have similar runtime configurations.
</Para>

<para>
Specifically if you have received the <productname>psqlODBC</productname>
 driver as part of the <productname>Postgres</productname> distribution
 (from now on referred to as an "integrated" build) then you will
configure and make the <acronym>ODBC</acronym> driver
 from the top level source directory
of the <productname>Postgres</productname> distribution
 along with the rest of its libraries.
If you received the driver as a standalone package than you will run
configure and make from the directory in which you unpacked the
driver source.
</Para>

<procedure>
<title>Integrated Installation</title>

<para>
This installation procedure is appropriate for an integrated installation.
</Para>

<step performance="required">
<para>
Specify the <option>--with-odbc</option>
command-line argument for <application>src/configure</application>:

<programlisting>
% ./configure --with-odbc
% make
</programlisting>
</Para>
</step>
<step performance="required">
<para>
Rebuild the <productname>Postgres</productname> distribution:

<programlisting>
% make install
</programlisting>
</Para>
</step>
</procedure>

<para>
Once configured, the <acronym>ODBC</acronym> driver will be built and installed
into the areas defined for the other components of the
<productname>Postgres</productname> system. The installation-wide
<acronym>ODBC</acronym> configuration file will be placed into
the top directory of the Postgres target tree (<envar>POSTGRESDIR</envar>).
This can be overridden from the <application>make</application> command-line
as
<programlisting>
% make ODBCINST=<replaceable>filename</replaceable> install
</programlisting>
</Para>

<procedure>
<title>Pre-v6.4 Integrated Installation</title>

<para>
If you have a <productname>Postgres</productname> installation older than
v6.4, you have the original source tree available, 
and you want to use the newest version of the <acronym>ODBC</acronym>
driver, then you may want to try this form of installation.
</Para>

<step performance="required">
<para>
Copy the output tar file to your target system and unpack it into a 
clean directory.
</Para>
</step>
<step performance="required">
<para>
From the directory containing the
sources, type:

<programlisting>
% ./configure
% make
% make POSTGRESDIR=<replaceable class="parameter">PostgresTopDir</replaceable> install
</programlisting>
</Para>
</step>

<step performance="optional">
<para>
If you would like to install components into different trees, 
then you can specify various destinations explicitly:

<programlisting>
% make BINDIR=bindir  LIBDIR=libdir  HEADERDIR=headerdir ODBCINST=instfile install
</programlisting>
</Para>
</step>
</procedure>

<procedure>
<title>Standalone Installation</title>

<para>
A standalone installation is not integrated with or built on the normal
<productname>Postgres</productname> distribution. It should be best suited
for building the <acronym>ODBC</acronym> driver for multiple, heterogeneous
clients who do not have a locally-installed <productname>Postgres</productname>
source tree.
</Para>

<para>
The default location for libraries and headers 
for the standalone installation is <filename>/usr/local/lib</filename>
 and <filename>/usr/local/include/iodbc</filename>, respectively.
There is another system wide configuration file that gets installed
as <filename>/share/odbcinst.ini</filename> (if <filename>/share</filename>
 exists) or as <filename>/etc/odbcinst.ini</filename>
 (if <filename>/share</filename> does not exist).
</Para>

<note>
<para>
Installation of files into <filename>/share</filename>
 or <filename>/etc</filename> requires system root privileges.
Most installation steps for <productname>Postgres</productname> do not
have this requirement, and you can choose another destination which
is writable by your non-root <productname>Postgres</productname> superuser
account instead.
</Para>
</note>

<step performance="required">
<para>
The standalone installation distribution can be built from the
<productname>Postgres</productname> distribution or may be obtained from 
<ulink url="http://www.insightdist.com/psqlodbc">Insight Distributors</ulink>,
the current maintainers of the non-Unix sources.
</Para>

<para>
Copy the zip
or gzipped tarfile to an empty directory. If using the zip package
unzip it with the command 
<programlisting>
% unzip -a <replaceable>packagename</replaceable>
</programlisting>

The <option>-a</option> option
is necessary to get rid of <acronym>DOS</acronym> 
CR/LF pairs in the source files.
</Para>

<para>
If you have the gzipped tar package than simply run

<programlisting>
tar -xzf <replaceable>packagename</replaceable>
</programlisting>
</Para>

<substeps>

<step performance="optional">
<para>
To create a tar file for a complete standalone installation
from the main <productname>Postgres</productname> source tree:
</Para>
</step>
</substeps>
</step>
<step performance="required">
<para>
Configure the main <productname>Postgres</productname> distribution.
</Para>
</step>
<step performance="required">
<para>
Create the tar file:

<programlisting>
% cd interfaces/odbc
% make standalone
</programlisting>
</Para>
</step>

<step performance="required">
<para>
Copy the output tar file to your target system. Be sure to transfer as
a binary file if using <application>ftp</application>.
</Para>
</step>

<step performance="required">
<para>
Unpack the tar file into a clean
directory.
</Para>
</step>

<step performance="required">
<para>
Configure the standalone installation:

<programlisting>
% ./configure
</programlisting>
</Para>

<para>
The configuration can be done with options:

<programlisting>
% ./configure --prefix=<replaceable>rootdir</replaceable> --with-odbc=<replaceable>inidir</replaceable>
</programlisting>

where <option>--prefix</option> installs the libraries and headers in
the directories <filename><replaceable>rootdir</replaceable>/lib</filename> and
<filename><replaceable>rootdir</replaceable>/include/iodbc</filename>, and
<option>--with-odbc</option> installs <filename>odbcinst.ini</filename> in the
specified directory.
</Para>

<para>
Note that both of these options can also be used from the integrated build
but be aware that <emphasis>when used in the integrated build</emphasis>
<option>--prefix</option> will also apply to the rest of
your <productname>Postgres</productname> installation.
<option>--with-odbc</option> applies only to the configuration file
 <filename>odbcinst.ini</filename>.
</Para>
</step>

<step performance="required">
<para>
Compile and link the source code:

<programlisting>
% make ODBCINST=<replaceable>instdir</replaceable>
</programlisting>
</Para>

<para>
You can also override the default location for installation on the
'make' command line. This only applies to the installation of the
library and header files. Since the driver needs to know the location
of the odbcinst.ini file attempting to override the enviroment variable
that specifies its installation directory will probably cause you
headaches. It is safest simply to allow the driver to install the
odbcinst.ini file in the default directory or the directory you specified
on the './configure' command line with --with-odbc.
</Para>
</step>
d594 1
a594 115
<!--
This doesn't currently work - thomas 1998-10-19
<tip>
<para>
<envar>ODBCINST</envar> can be specified during configuration or during
the compilation. It is not necessary to do so in both steps.
</tip>
-->

<step performance="required">
<para>
Install the source code:

<programlisting>
% make POSTGRESDIR=<replaceable>targettree</replaceable> install
</programlisting>
</Para>

<para>
To override the library and header installation directories separately
you need to pass the correct installation variables on the
<literal>make install</literal> command line. These variables are
<envar>LIBDIR</envar>, <envar>HEADERDIR</envar>
 and <envar>ODBCINST</envar>.
Overriding <envar>POSTGRESDIR</envar> on the make command line will cause
 <envar>LIBDIR</envar> and <envar>HEADERDIR</envar>
 to be rooted at the new directory you specify. 
<envar>ODBCINST</envar> is independent of <envar>POSTGRESDIR</envar>.
</Para>

<para>
Here is how you would specify the various destinations explicitly:

<programlisting>
% make BINDIR=<replaceable>bindir</replaceable> LIBDIR=<replaceable>libdir</replaceable> HEADERDIR=<replaceable>headerdir</replaceable> install
</programlisting>
</Para>

<para>
For example, typing

<programlisting>
% make POSTGRESDIR=/opt/psqlodbc install
</programlisting>

(after you've used
 <application>./configure</application> and <application>make</application>)
will cause the libraries and headers to be installed in the directories
<filename>/opt/psqlodbc/lib</filename>
 and <filename>/opt/psqlodbc/include/iodbc</filename> respectively.
</Para>

<para>
The command

<programlisting>
% make POSTGRESDIR=/opt/psqlodbc HEADERDIR=/usr/local install
</programlisting>

should cause the libraries to be installed in /opt/psqlodbc/lib and
the headers in /usr/local/include/iodbc. If this doesn't work as
expected please contact one of the maintainers.
</Para>
</step>
</procedure>
</sect2>
</sect1>

<sect1>
<title>Configuration Files</title>

<para>
<filename>~/.odbc.ini</filename> contains user-specified access information 
for the <productname>psqlODBC</productname> driver. 
The file uses conventions typical for <productname>Windows</productname> 
Registry files, but despite this restriction can be made to work.
</Para>

<para>
The <filename>.odbc.ini</filename> file has three required sections. 
The first is <literal>[ODBC Data Sources]</literal>
which is a list of arbitrary names and descriptions for each database 
you wish to access. The second required section is the 
Data Source Specification and there will be one of these sections
for each database. 
Each section must be labeled with the name given in 
<literal>[ODBC Data Sources]</literal> and must contain the following entries: 

<programlisting>
Driver = <replaceable>POSTGRESDIR</replaceable>/lib/libpsqlodbc.so
Database=<replaceable>DatabaseName</replaceable>
Servername=localhost
Port=5432
</programlisting>

<tip>
<para>
Remember that the <productname>Postgres</productname> database name is
usually a single word, without path names of any sort. 
The <productname>Postgres</productname> server manages the actual access
to the database, and you need only specify the name from the client.
</Para>
</tip>

Other entries may be inserted to control the format of the display. 
The third required section is <literal>[ODBC]</literal> 
which must contain the <literal>InstallDir</literal> keyword 
and which may contain other options.
</Para>

<para>
Here is an example <filename>.odbc.ini</filename> file, 
showing access information for three databases:

<programlisting>
d628 194
a821 191
</programlisting>
</Para>
</sect1>
<sect1>
<title>ApplixWare</title>

<sect2>
<title>Configuration</title>

<para>
<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.
</Para>

<procedure>
<title>Enabling ApplixWare Database Access</title>

<para>
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.
</Para>

<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>

<para>
As root, edit the file
<filename><replaceable>applixroot</replaceable>/applix/axdata/axnet.cnf</filename>.
</Para>

<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>
</Para>
</step>
<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.
</Para>
</step>
</substeps>
</step>

<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>.
</Para>
</step>
</procedure>

<procedure>
<title>Testing ApplixWare ODBC Connections</title>

<step performance="required">
<para>
    Bring up <application>Applix Data</application>
</Para>
</step>

<step performance="required">
<para>
Select the <productname>Postgres</productname> database of interest.
</Para>

<substeps>

<step performance="required">
<para>
Select <command>Query->Choose Server</command>.  
</Para>
</step>
<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).
</Para>
</step>
<step performance="required">
<para>
Select the database in the box that was launched by <command>Browse</command>,
 then click <command>OK</command>.
</Para>
</step>
<step performance="required">
<para>
Enter username and password in the login identification dialog,
 and click <command>OK</command>.
</Para>
</step>
</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.
</Para>
</step>
<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.
</Para>
</step>
<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.
</Para>
</step>
</procedure>
</sect2>

<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
</term>
<listitem>
<para>
<literal>elfodbc</literal> can't find <filename>libodbc.so</filename>.  
Check your <filename>axnet.cnf</filename>.
</Para>
</listitem>
</varlistentry>

<varlistentry>
<term>
Error from ODBC Gateway:
IM003::[iODBC][Driver Manager]Specified driver could not be loaded
</term>
<listitem>
<para>
<filename>libodbc.so</filename> cannot find the driver listed in
<filename>.odbc.ini</filename>. Verify the settings.
</Para>
</listitem>
</varlistentry>

<varlistentry>
<term>
Server: Broken Pipe
</term>
d823 2
a824 2
<listitem>
<para>
d828 258
a1085 258
<acronym>ODBC</acronym> package.
</Para>
</listitem>
</varlistentry>

<varlistentry>
<term>
setuid to 256: failed to launch gateway
</term>

<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>.
</Para>
</listitem>
</varlistentry>

</variablelist>
</para>

<para>
<note>
<title>Author</title>

<para>
Contributed by 
<ulink url="mailto:scampbell@@lear.com">Steve Campbell</ulink> on
1998-10-20.
</para>
</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.
</para>
</sect2>

<sect2>
<title>Debugging ApplixWare ODBC Connections</title>

<para>
One good tool for debugging connection problems uses the Unix system
utility <application>strace</application>.
</para>
<procedure>
<title>Debugging with strace</title>

<step performance="required">
<para>
Start applixware.
</para>
</step>
<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>

<para>
Then run

<programlisting>
   strace -f -s 1024 -p 10432 
</programlisting>
</para>
</step>

<step performance="required">
<para>
Check the strace output.
</para>
<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.
</para>
</note>
</step>
</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.
</para>
</sect2>

<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>
<para>
To get around this problem, you can do the following:
</para>

<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.
</para>
</step>

<step performance="required">
<para>
Edit this local copy of <filename>sqldemo.am</filename>:
</para>

<substeps>

<step performance="required">
<para>
Search for 'null_clause = "NULL"
</para>
</step>

<step performance="required">
<para>
Change this to null_clause = ""
</para>
</step>

</substeps>
</step>
<step performance="required">
<para>
Start <application>Applix Macro Editor</application>.
</para>
</step>

<step performance="required">
<para>
Open the sqldemo.am file from the <application>Macro Editor</application>.
</para>
</step>

<step performance="required">
<para>
Select <command>File->Compile and Save</command>.
</para>
</step>

<step performance="required">
<para>
Exit <application>Macro Editor</application>.
</para>
</step>

<step performance="required">
<para>
Start <application>Applix Data</application>.
</para>
</step>

<step performance="required">
<para>
Select <command>*->Run Macro</command>
</para>
</step>

<step performance="required">
<para>
Enter the value <quote>sqldemo</quote>, then click <command>OK</command>.
</para>

<para>
You should see the progress in the status line of the data window
 (in the lower left corner).
</para>
</step>

<step performance="required">
<para>
You should now be able to access the demo tables.
</para>
</step>
</procedure>
</sect2>
<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:

<programlisting>
macro login
    set_set_system_var@@("sql_username@@","tgl")
    set_system_var@@("sql_passwd@@","no$way")
endmacro
</programlisting>

<caution>
<para>
You should be careful about the file protections on any file containing
username and password information.
</para>
</caution>
</para>
</sect2>
<sect2>
<title>Supported Platforms</title>

<para>
<productname>psqlODBC</productname> has been built and tested
on <productname>Linux</productname>. There have been reports of success
with FreeBSD and with Solaris. There are no known restrictions
on the basic code for other platforms which already support
<productname>Postgres</productname>.
</para>
</sect2>
</sect1>
</Chapter>
d1089 1
a1089 1
mode: sgml
d1099 1
a1099 1
sgml-local-catalogs:"/usr/lib/sgml/CATALOG"
@


1.10
log
@Clean up to ensure tag completion as required by the newest versions
 of Norm's Modular Style Sheets and jade/docbook.
From Vince Vielhaber <vev@@michvhf.com>.
@
text
@a1049 388
=======
<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.
</para>
<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.
</para>
<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>
<para>
As root, edit the file
<filename><replaceable>applixroot</replaceable>/applix/axdata/axnet.cnf</filename>.
</para>
<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>
</para>
</step>

<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.
</para>
</step>

</substeps>
</step>

<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>.
</para>
</step>

</procedure>

<procedure>
<title>Testing ApplixWare ODBC Connections</title>

<step performance="required">
<para>
    Bring up <application>Applix Data</application>
</para>
</step>

<step performance="required">
<para>
Select the <productname>Postgres</productname> database of interest.
</para>

<substeps>

<step performance="required">
<para>
Select <command>Query->Choose Server</command>.  
</para>
</step>

<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).
</para>
</step>

<step performance="required">
<para>
Select the database in the box that was launched by <command>Browse</command>,
 then click <command>OK</command>.
</para>
</step>

<step performance="required">
<para>
Enter username and password in the login identification dialog,
 and click <command>OK</command>.
</para>
</step>

</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.
</para>
</step>
<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.
</para>
</step>

<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.
</para>
</step>

</procedure>
</sect2>

<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
</term>
<listitem>
<para>
<literal>elfodbc</literal> can't find <filename>libodbc.so</filename>.  
Check your <filename>axnet.cnf</filename>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
Error from ODBC Gateway:
IM003::[iODBC][Driver Manager]Specified driver could not be loaded
</term>

<listitem>
<para>
<filename>libodbc.so</filename> cannot find the driver listed in
<filename>.odbc.ini</filename>. Verify the settings.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
Server: Broken Pipe
</term>

<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.
</para>
</listitem>
</varlistentry>

</variablelist>
</para>
</sect2>

<sect2>
<title>Debugging ApplixWare ODBC Connections</title>

<para>
One good tool for debugging connection problems uses the Unix system
utility <application>strace</application>.
</para>
<procedure>
<title>Debugging with strace</title>

<step performance="required">
<para>
Start applixware.
</para>
</step>
<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>

<para>
Then run

<programlisting>
   strace -f -s 1024 -p 10432 
</programlisting>
</para>
</step>
<step performance="required">
<para>
Check the strace output.
</para>

<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.
</para>
</note>
</step>
</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.
</para>
</sect2>
<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>

<para>
To get around this problem, you can do the following:
</para>

<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.
</para>
</step>

<step performance="required">
<para>
Edit this local copy of <filename>sqldemo.am</filename>:
</para>

<substeps>

<step performance="required">
<para>
Search for 'null_clause = "NULL"
</para>
</step>

<step performance="required">
<para>
Change this to null_clause = ""
</para>
</step>
</substeps>
</step>
<step performance="required">
<para>
Start <application>Applix Macro Editor</application>.
</para>
</step>
<step performance="required">
<para>
Open the sqldemo.am file from the <application>Macro Editor</application>.
</para>
</step>

<step performance="required">
<para>
Select <command>File->Compile and Save</command>.
</para>
</step>

<step performance="required">
<para>
Exit <application>Macro Editor</application>.
</para>
</step>

<step performance="required">
<para>
Start <application>Applix Data</application>.
</para>
</step>

<step performance="required">
<para>
Select <command>*->Run Macro</command>
</para>
</step>

<step performance="required">
<para>
Enter the value <quote>sqldemo</quote>, then click <command>OK</command>.
</para>

<para>
You should see the progress in the status line of the data window
 (in the lower left corner).
</para>
</step>

<step performance="required">
<para>
You should now be able to access the demo tables.
</para>
</step>

</procedure>
</sect2>

<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:

@


1.9
log
@Minor editing and markup changes as a result of preparing the Postscript
 documentation for v6.4.
Bigger updates to the installation instructions (install and config).
@
text
@a17 1
<Para>
d34 1
d44 1
d52 1
d59 1
d68 1
d78 2
d93 2
a94 1

d99 2
d108 2
d111 1
d123 1
a123 1

d129 1
d137 1
d142 1
d158 2
d172 1
d192 1
d198 1
d210 1
d222 1
d235 1
d242 1
d253 2
a254 1

d262 2
a263 1

d277 1
d287 1
d293 2
a294 1

d305 2
d316 2
a317 1

d329 1
d339 1
d349 1
d358 1
d371 1
d379 1
d387 2
a388 1

d390 1
a390 1

d394 2
a395 1

d404 2
d411 2
d418 2
d428 1
d442 1
d451 2
d461 1
d472 2
d491 1
d503 1
d511 1
d525 1
d537 2
a538 1

d540 2
d551 1
d576 1
d583 1
d624 2
a625 1

a628 2
<para>

d637 1
d647 1
d658 1
d663 1
d675 2
a676 1

d689 2
a690 1

d692 1
d705 2
a706 1

d715 2
d721 1
d728 2
a729 1

d737 2
a738 1

d743 2
a744 1

d749 2
a750 1

d758 2
a759 1

d764 2
a765 1

d771 2
a772 1

d774 1
d788 1
a788 1

d793 3
d801 1
a801 1

d806 3
d813 1
d821 3
d828 1
d837 3
d842 1
d852 1
d862 2
d871 1
a871 1

d878 2
a879 1

d895 1
d903 2
d909 1
a909 1

d918 1
d920 1
a920 1

d938 2
d951 1
a951 1

d954 1
d963 2
d969 1
d976 2
d982 2
d986 1
a986 1

d990 2
d996 2
d1002 2
d1008 2
d1014 2
d1020 2
d1026 1
d1031 2
d1037 2
a1038 1

d1040 1
a1040 1

d1055 1
a1055 1

d1065 1
a1065 1

d1075 1
a1075 1

d1079 1
a1079 1

d1090 2
d1105 2
d1109 1
d1122 2
d1133 2
d1139 1
d1146 2
d1156 2
d1163 2
d1170 2
d1180 2
a1181 1

d1186 2
d1194 2
d1198 1
d1212 1
a1212 1

d1217 3
a1219 1

d1224 1
d1230 3
d1237 1
d1245 3
d1250 2
d1259 1
a1259 1

d1266 2
a1267 1

d1283 1
d1291 2
a1292 1

d1296 1
d1306 1
d1308 1
a1308 1

d1326 2
a1327 1

d1338 1
d1342 1
d1351 2
d1357 1
d1364 2
d1370 2
a1371 1

d1373 1
a1373 1

d1377 2
a1378 1

d1382 2
d1388 2
d1394 2
d1400 2
d1406 2
d1412 1
d1417 2
d1423 2
d1427 1
d1449 1
d1451 2
a1452 1

d1462 3
a1464 1

d1477 1
a1477 1
sgml-default-dtd-file:"../reference.ced"
d1479 1
a1479 1
sgml-local-catalogs:"/usr/lib/sgml/catalog"
@


1.8
log
@Add debugging info from Cary O'Brien.
Include comments from Robert Burrows.
@
text
@d580 1
a580 2
Note that
these instructions are for the 4.4.1 release of
@


1.7
log
@Incorporate information from Cary and Robert.
More how-to stuff on ApplixWare.
@
text
@d735 351
@


1.6
log
@Clean up markup.
Add new bibliographic references from Paul Aoki.
Include libpq++ docs from the old man page in the Programmer's Guide.
Update Unix installation info for ODBC.
@
text
@d13 1
a13 1
<Date>1998-08-25</Date>
d29 2
a30 1
which allows you to write standard "ODBC" applications.
d33 2
a34 1
allowing a user or developer to write applications which are portable among servers.
d62 1
a62 1
your Windows app would make exactly the
d83 3
a85 2
<SimpleList>
<Member>
d88 2
a89 1
<Member>
d93 2
a94 1
<Member>
d99 4
a102 1
</SimpleList>
d105 2
a106 1
If I write an app for <productname>Postgres</productname> 
d110 1
a110 1
like MS SQL Server or Access needs to access the data?
d113 1
a113 1
Again, the <acronym>ODBC</acronym> <acronym>API</acronym> set 
d115 2
a116 2
For <productname>Visual C++</productname> you can find out more at
Microsoft's web site or in your docs.
d145 1
a145 1
<title>Unix Applications</title>
d160 35
d202 13
a214 1
<sect3>
d218 15
a232 2
For an integrated installation, specify the <option>--with-odbc</option>
command-line argument for src/configure:
d235 1
a235 1
./configure --with-odbc
d238 3
d249 1
a249 1
% make ODBCINST=<replaceable>filename</replaceable>
d252 37
a288 1
<sect3>
d299 20
d320 2
a321 2
<productname>Postgres</productname> distribution or may be obtained
from <ulink url="http://insightdist.com/psqlodbc">Insight Distributors</ulink>,
d325 34
a358 3
To create a tar file for a complete standalone installation, first
configure the main <productname>Postgres</productname> distribution.
Then, create the tar file:
d365 18
d384 1
a384 2
Copy the output tar file to your target system, unpack it into a clean
directory, and then:
d387 68
a454 2
% ./configure --with-odbcinst=<replaceable>instfile</replaceable>
% make POSTGRESDIR=<replaceable>targettree</replaceable> ODBCINST=<replaceable>instfile</replaceable>
a456 1
<note>
d458 11
a468 2
The <envar>ODBCINST</envar> can be specified on either or both command lines.
</note>
d471 1
a471 2
If you would like to install components into different trees, then you
can specify various destinations explicitly:
d474 1
a474 1
% make BINDIR=<replaceable>bindir</replaceable> LIBDIR=<replaceable>libdir</replaceable> HEADERDIR=<replaceable>headerdir</replaceable> ODBCINST=<replaceable>instfile</replaceable>
d477 7
a483 1
<sect2>
d493 30
d562 8
d571 320
a890 1
For Applix, here is an example ~/axhome/macros/login.am file:
d893 2
a894 2
        set_set_system_var@@("sql_username@@","tgl")
        set_system_var@@("sql_passwd@@","no$way")
d898 7
a904 1
<sect1>
d908 5
a912 3
<productname>psqlODBC</productname> has been built and tested 
on <productname>Linux</productname>. There have been reports of success 
with FreeBSD and with Solaris.
@


1.5
log
@Clean up pages. Add information for operator precedence.
Split introduction sections into separate files to allow the legal notice
 and notation sections appear in all documents without having the history
 show up everplace too.
Add full list of reserved and non-reserved key words in syntax.sgml.
Add a separate chapter to the admin guide on security.
@
text
@d44 4
a47 2
The backend access come from <acronym>ODBC</acronym> drivers, or vendor specifc drivers that
allow data access.   <productname>psqlODBC</productname> is such a driver, along with others that are
d51 2
a52 1
Once you write an <acronym>ODBC</acronym> application, you SHOULD be able to connect to ANY
d59 3
a61 2
exactly the same data.  Using <acronym>ODBC</acronym>, your Windows app would make exactly the
same calls and the back end data source would look the same (to the windows
d65 6
a70 4
<ulink url="http://www.insightdist.com/">Insight Distributors</ulink> provides active and ongoing
support for the core <productname>psqlODBC</productname> distribution. They provide a
<ulink url="http://www.insightdist.com/psqlodbc/"><acronym>FAQ</acronym></ulink>, ongoing development
on the code base, and actively participate on the 
d77 2
a78 1
In the real world, differences in drivers and the level of <acronym>ODBC</acronym> support
d86 2
a87 1
Under C++, such as Visual C++, you can use the C++ <acronym>ODBC</acronym> <acronym>API</acronym>.
d99 2
a100 1
to the <productname>Postgres</productname> server, or is that only when another database program 
d104 4
a107 3
Again, the <acronym>ODBC</acronym> <acronym>API</acronym> set is the way to go.
You can find out more at
Microsoft's web site or in your Visual C++ docs (if that's what you are using.)
d110 2
a111 1
Visual Basic and the other RAD tools have Recordset objects that use <acronym>ODBC</acronym>
d113 2
a114 1
link to the <acronym>ODBC</acronym> back end database (<Emphasis>very</Emphasis> quickly).
d118 1
a118 1
File->Get External Data
a119 1
<Para>
d139 4
a142 2
<productname>ApplixWare</productname> has an <acronym>ODBC</acronym> database interface
supported on at least some platforms. <productname>ApplixWare</productname> v4.4.1 has been
d148 81
d232 4
a235 5
The <filename>~/.odbc.ini</filename> contains user-specified access information 
for the <productname>psqlODBC</productname>
driver. The file uses conventions typical for <productname>Windows</productname> 
Registry files, but despite this
restriction can be made to work.
@


1.4
log
@Add Unix-specific installation and configuration info for psqlodbc.
@
text
@d16 1
a16 1
<Title><acronym>ODBC</acronym> Interface</Title>
@


1.3
log
@Initial information for Linux/Unix installation.
@
text
@d125 1
a125 1
<title><productname>Unix</productname> Applications</title>
@


1.2
log
@Add id field to chapter and book tags to allow output file names
 to be meaningful.
@
text
@d8 4
d13 1
a13 1
<Date>Transcribed 1998-02-12</Date>
d16 1
a16 1
<Title>ODBC Interface</Title>
d21 2
a22 1
Contributed by <ULink url="mailto:tgoeke@@xpressway.com">Tim Goeke</ULink>
d27 6
a32 2
ODBC is an abstract API which allows you to write standard "ODBC" code,
using the ODBC API.
d38 4
a41 2
The ODBC API matches up on the backend to an ODBC compatible data source.
This could be anything from a text file to an Oracle RDBMS.
d44 3
a46 3
The backend access come from ODBC drivers, or vendor specifc drivers that
allow data access.   PostODBC is such a driver, along with others that are
available, such as the OpenLink ODBC drivers.
d49 1
a49 1
Once you write an ODBC application, you SHOULD be able to connect to ANY
d54 3
a56 2
For example. you could have MS SQL Server and PostgreSQL servers which have
exactly the same data.  Using ODBC, your Windows app would make exactly the
d60 10
d71 2
a72 2
In the real world, differences in drivers and the level of ODBC support
lessens the potential of ODBC:
d76 1
a76 1
Access, Delphi, and Visual Basic all support ODBC directly.
d79 1
a79 1
Under C++, such as Visual C++, you can use the C++ ODBC API.
d82 3
a84 2
In Visual C++, you can use the CRecordSet class, which wraps the ODBC API
set within and MFC 4.2 class.  This is the easiest route if you are doing
d89 3
a91 2
If I write an app for PostgreSQL can I write it using ODBC calls
to the PostgreSQL server, or is that only when another database program 
d95 3
a97 3
Again, the ODBC API set is the way to go.   You can find out more at
Microsoft's web site or in your Visual C++ docs (if that's what you are
using.)
d100 1
a100 1
Visual Basic and the other RAD tools have Recordset objects that use ODBC
d102 1
a102 1
link to the ODBC back end database (<Emphasis>very</Emphasis> quickly).
d115 1
d119 1
a119 1
The PostgreSQL datetime type will break MS Access.
d122 78
d202 17
@


1.1
log
@SGML source for new documentation.
@
text
@d1 1
a1 1
<Chapter>
@
