<!-- -*- sgml -*- -->
<!doctype linuxdoc system>

<article>

<title>Libodbc++ Installation 

<author>Manush Dodunekov
<htmlurl url="mailto:manush@litecom.net" name="<manush@litecom.net>">
<date>Version 0.2.0, 1999-06-03

<abstract>
This tries to explain the installation procedure for libodbc++
</abstract>

<toc>

<sect>Software requirements
<p>
<sect1>C++ compiler
<p>
To compile libodbc++, you'll need a c++ compiler that supports
exceptions, templates and namespaces and
has a reasonable standard c++ library. On free unices,
your best choice is <bf>egcs</bf> 1.1.2 or later, which can be 
obtained from <url url="http://egcs.cygnus.com/" name="the egcs homepage">.

On windows, testing has only been done with MSC 5.0.

<sect1>ODBC Driver Manager
<p>
The ODBC Driver Manager is the software layer between 
applications and ODBC drivers. You must have one installed
in order to use this library.
The usual free choice on UNIX is
<url url="http://www.openlinksw.com/iodbc/" name="iODBC">. Make sure you
have version 2.50.2 or later.

You can also try <url url="http://genix.net/unixODBC/" name="unixODBC">.

<sect1>Drivers
<p>To actually use libodbc++, you will need
one or more ODBC drivers. Examples of free database engines
with ODBC drivers are:
<itemize>
<item><url url="http://www.mysql.com/" name="MySQL">
<item><url url="http://www.postgresql.org/" name="PostgreSQL">
</itemize>

<bf>MyODBC</bf> (the <bf>MySQL ODBC</bf> driver 
version 2.50.23 or later is known to work fine with both
<bf>iODBC</bf> and <bf>libodbc++</bf>).

If you need to access a commercial RDBMS from a UNIX, 
<url url="http://www.openlinksw.com/" name="Openlink Software"> has
a universal driver that covers most of them (commercial).



<sect>Installation

<sect1>UNIX
<p>The following information applies for installing libodbc++ on unices.

<sect2>Configuration
<p>
First, you need to configure libodbc++ for your system. 
Go into the source directory and do

<tscreen><verb>
&dollar; ./configure
</verb></tscreen>

or, if <bf/iODBC/ isn't installed in it's default location <file>/usr/local</file>, do

<tscreen><verb>
&dollar; ./configure --with-iodbc=DIR
</verb></tscreen>

This will make <file>./configure</file> look for <bf/iODBC/ in 
<file>DIR/include/</file> and <file>DIR/lib/</file>.

If you aren't using <bf/iODBC/, try

<tscreen><verb>
&dollar; ./configure --with-odbc=DIR
</verb></tscreen>

Works the same as above, except it looks for standard <bf/ODBC/ headers and libraries
instead of the <bf/iODBC/ ones. This should be used with for example
<bf>unixODBC</bf> and <bf>Intersolv</bf>.

If you wish to install libodbc++ in a location other than /usr/local, add
<tt>--prefix=PREFIX</tt> to the <file>./configure</file> arguments.

If the c++ compiler you wish to use to compile this package isn't the system
default one, you will need to set the environment variable <tt/CXX/ to
the name of it's executable. For example, if you have an old <tt/gcc/ or
<tt/egcs/ as a system default compiler, but installed a newer 
<tt/egcs/ in <file>/usr/local/egcs</file>, do like this:

<tscreen><verb>
&dollar; CXX=/usr/local/egcs/bin/c++ ./configure --with-iodbc
</verb></tscreen>

If you wish to enable support for multithreaded programs, add
<tt/--enable-threads/ to the <file>./configure</file> arguments. 
This requires pthreads, will probably not work on anything else
than linux and solaris, and is still experimental.

You can control the ODBC version libodbc++ uses by specifying:
<tt/--with-odbc-version=ODBCVER/, where <tt/ODBCVER/ should be a 
four-digit hexadecimal value. For example <tt/0x0250/ means
ODBC 2.50.

<sect2>Compilation
<p>
Just type

<tscreen><verb>
&dollar; make
</verb></tscreen>

If it all goes well, you can try a couple of the test programs in 
<file>tests/</file>. You'll need to configure some datasources before
running most of the tests. For simply reality-checking your current ODBC
setup, you can try running <file>tests/dmtest</file>, which lists
all available datasources and drivers.

<sect2>Installing libodbc++
<p>
If you have write privileges in <tt>PREFIX</tt>, just do

<tscreen><verb>
&dollar; make install
</verb></tscreen>

Otherwise, you'll have to use

<tscreen><verb>
&dollar; su root -c 'make install'
</verb></tscreen>

If you are using linux, now is a good time to run

<tscreen><verb>
&dollar; su root -c '/sbin/ldconfig'
</verb></tscreen>

to update your dynamic linker's cache.

<sect1>Win32
<p>A makefile for win32 is provided in the win32 directory of
the source distribution. Use
<tscreen><verb>
nmake /f makefile.w32 CFG=<config>
</verb></tscreen>
where <tt>&lt;config&gt;</tt> is one of:
<itemize>
<item><tt>debug-lib</tt> - Static library with debugging information
<item><tt>debug-dll</tt> - Shared library with debugging information
<item><tt>prod-lib</tt> - Production static library
<item><tt>prod-dll</tt> - Production shared library
</itemize>

This will build odbc++.lib (and possibly .DLL) in the corresponding
subdirectory.

Note that when compiling an application against <file>odbc++.dll</file>
(ie using the <file>odbc++.lib</file> import library from a <file>*-dll</file>
subdirectory) you have to define the macro <tt/ODBCXX_DLL/ before including
any library header files.

A makefile for compiling the tests can be found in the 
<file>win32/tests</file> subdirectory. Build the <file>debug-lib</file>
version of the library, and use
<tscreen><verb>
nmake /f makefile.w32
</verb></tscreen>

to build them.
</article>
