rdelaage/postgresql
1
0
Fork 0
mirror of https://git.postgresql.org/git/postgresql.git synced 2024-10-01 20:21:20 +02:00
Code Issues Packages Projects Releases Wiki Activity
9583aea9d0
postgresql/doc/src/sgml/odbc.sgml
Peter Eisentraut 74bbe8097d Replace some oldish, non-SQL'ish elements with more standard forms. (cast 
syntax, type names, function names, etc.)
2001-01-20 20:59:29 +00:00

767 lines
22 KiB
Plaintext
Raw Blame History

<!--
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/odbc.sgml,v 1.21 2001/01/20 20:59:28 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>
<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
transportable between servers from different manufacturers..
</para>
<sect1 id="odbc-background">
<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 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
app).
</para>
</sect1>
<sect1 id="odbc-install">
<title>Installation</title>
<para>
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 <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.
</para>
<para>
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.
</para>
<para>
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.
</para>
<para>
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.
</para>
<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>
<sect1 id="odbc-config">
<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>prefix</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>
[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 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>
</sect2>
</sect1>
<sect1 id="odbc-applixware">
<title>ApplixWare</title>
<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>Postgres</productname> 7.0
using the <productname>psqlODBC</productname>
driver contained in the <productname>Postgres</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>Postgres</productname>
<acronym>ODBC</acronym> software drivers.
</para>
<procedure>
<title>Enabling ApplixWare Database Access</title>
<para>
These instructions are for the <literal>4.4.2</literal> 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.
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 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 "<literal>Starting elfodbc server</literal>"
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>
<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 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
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 "<literal>Cannot launch gateway on server</literal>",
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 "<literal>sqldemo</literal>", 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 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
username 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:
-->
Reference in New Issue View Git Blame Copy Permalink