***************************************
	  *       MySQL ODBC 3.51 Driver        *
  	  *               INSTALL               *
          * (C) Copyright MySQL AB 1995-2002	*
	  ***************************************

=========
CONTENTS
=========
1. SOFTWARE REQUIREMENTS
2. MYODBC 3.51 CONFIGURATION OPTIONS
3. CONFIGURATION
4. BUILDING THE DRIVER
5. BUILDING THE DRIVER ON WINDOWS
6. CONFIGURING DATA SOURCE
7. TESTING THE DRIVER
8. TESTING WITH iodbc
9. TESTING WITH unixODBC

=========================
1. SOFTWARE REQUIREMENTS
=========================

* MySQL client libraries and include files from 3.23.14 and above
  This is required because MyODBC uses new calls that only exists
  starting from the above library.
  
* The MySQL library must be configured with '--with-thread-safe-client'

* libmysqlclient installed as a shared library.

* One of unix ODBC driver managers:
  * iODBC 3.00 or later, (http://www.iodbc.org), installed
  * unixODBC Alpha 3 or later (http://www.unixodbc.org), installed
  
* If you using a character set that isn't compiled into the MySQL
    client library (the defaults are:
    latin1 big5 czech euc_kr gb2312 gbk sjis tis620 ujis
     ) then you need to install the mysql character definitions from the
     charsets directory into SHAREDIR (default 
    /usr/local/mysql/share/mysql/charsets);  These should already be into
    place if you have installed the MySQL server on the same machine.

====================================
2. MYODBC 3.51 CONFIGURATION OPTIONS
====================================

Usage: configure [options] [host]
Options: [defaults in brackets after descriptions]

Configuration:
  --cache-file=FILE       cache test results in FILE
  --help                  print this message
  --no-create             do not create output files
  --quiet, --silent       do not print `checking...' messages
  --version               print the version of autoconf that created configure

Directory and file names:
  --prefix=PREFIX         install architecture-independent files in PREFIX
                          [/usr/local]
  --exec-prefix=EPREFIX   install architecture-dependent files in EPREFIX
                          [same as prefix]
  --bindir=DIR            user executables in DIR [EPREFIX/bin]
  --sbindir=DIR           system admin executables in DIR [EPREFIX/sbin]
  --libexecdir=DIR        program executables in DIR [EPREFIX/libexec]
  --datadir=DIR           read-only architecture-independent data in DIR
                          [PREFIX/share]
  --sysconfdir=DIR        read-only single-machine data in DIR [PREFIX/etc]
  --sharedstatedir=DIR    modifiable architecture-independent data in DIR
                          [PREFIX/com]
  --localstatedir=DIR     modifiable single-machine data in DIR [PREFIX/var]
  --libdir=DIR            object code libraries in DIR [EPREFIX/lib]
  --includedir=DIR        C header files in DIR [PREFIX/include]
  --oldincludedir=DIR     C header files for non-gcc in DIR [/usr/include]
  --infodir=DIR           info documentation in DIR [PREFIX/info]
  --mandir=DIR            man documentation in DIR [PREFIX/man]
  --srcdir=DIR            find the sources in DIR [configure dir or ..]
  --program-prefix=PREFIX prepend PREFIX to installed program names
  --program-suffix=SUFFIX append SUFFIX to installed program names
  --program-transform-name=PROGRAM
                          run sed PROGRAM on installed program names
Host type:
  --build=BUILD           configure for building on BUILD [BUILD=HOST]
  --host=HOST             configure for HOST [guessed]
  --target=TARGET         configure for TARGET [TARGET=HOST]

Features and packages:
  --disable-FEATURE       do not include FEATURE (same as --enable-FEATURE=no)
  --enable-FEATURE[=ARG]  include FEATURE [ARG=yes]
  --with-PACKAGE[=ARG]    use PACKAGE [ARG=yes]
  --without-PACKAGE       do not use PACKAGE (same as --with-PACKAGE=no)
  --x-includes=DIR        X include files are in DIR
  --x-libraries=DIR       X library files are in DIR

--enable and --with options recognized:
  --enable-shared[=PKGS]  build shared libraries [default=yes]
  --enable-static[=PKGS]  build static libraries [default=no]
  --enable-fast-install[=PKGS]  optimize for fast installation [default=yes]
  --with-gnu-ld           assume the C compiler uses GNU ld [default=no]
  --disable-libtool-lock  avoid locking (might break parallel builds)
  --with-mysql-libs=DIR   Look for mysql client libraries in DIR
  --with-mysql-includes=DIR   Look for mysql include files in DIR
  --with-unixODBC[=DIR]   Use unixODBC located in DIR
  --with-unixODBC-includes=DIR Find unixODBC headers in DIR
  --with-unixODBC-libs=DIR Find unixODBC libraries in DIR
  --with-iodbc[=DIR]      Use iODBC located in DIR
  --with-iodbc-includes=DIR Find iODBC headers in DIR
  --with-iodbc-libs=DIR   Find iODBC libraries in DIR
  --with-odbc-ini=PATH    Location of system odbc.ini [IODBCDIR/etc/odbc.ini]
  --with-ldflags=option   Extra arguments for linking. Normally -lmysqlclient

================
3. CONFIGURATION
================

   The only required options are
       --with-mysql-dirs=DIR
       --with-mysql-includes=DIR
   where DIR is the directory where the mysql libraries and include files are.
 
   If you are using iODBC:

      If your iODBC is not installed in it's default location - /usr/local,
      you might have to use

	  --with-iodbc=DIR

      or if the iODBC headers aren't residing in DIR/include, you can also use

          --with-iodbc-includes=INCDIR

      Same goes for libraries - if they aren't in DIR/lib, use

          --with-iodbc-libs=LIBDIR


   If you are using unixODBC:

      To make configure look for unixODBC instead of iODBC, use

          --with-unixODBC=DIR

      Where DIR is where unixODBC is installed.
  
      And (as usual), if the unixODBC headers and libraries aren't located
      in DIR/include and DIR/lib, use
 
          --with-unixODBC-libs=LIBDIR
	  --with-unixODBC-includes=INCDIR


   You might want to specify a prefix other than /usr/local for installation,
   I for example keep my ODBC drivers in /usr/local/odbc/lib, so I add

       --prefix=/usr/local/odbc

   Configuration example:
   
   $ ./configure --prefix=/usr/local 
                 --with-iodbc=/usr/local 
                 --with-mysql-dirs=/usr/local/mysql/lib/mysql 
                 --with-mysql-includes=/usr/local/mysql/include/mysql


Note that you can normally ignore the following warning:
----------------------------------------------------------------
Warning: using iODBC but libiodbcinst library not found.
Enabling workaround, which will search for mysql datasource
configuration as follows:

1. $ODBCINI, and if not found - $HOME/.odbc.ini (User data sources)
2. /usr/local/etc/odbc.ini (System data sources)

If you want to change (2), re-run configure using the
   --with-odbc-ini=/some/other/path/odbc.ini
option.

----------------------------------------------------------------

=======================
4. BUILDING THE DRIVER
=======================

once the driver is configured, then just execute the
following commands:

   $ make
   Shold do it.

   $ make install
   Will install libmyodbc3.so


If you happen to only have a static version of the libmysqlclient
library, but this is compiled with position independent code (normally -fpic)
then you can still make a shared libmyodbc.so file by adding -lmysqlclient
to the command that makes the shared library. For example:  Assume makes ends
with:

gcc -shared  catalog.lo connect.lo dll.lo execute.lo info.lo myodbc3.lo 
             options.lo error.lo prepare.lo results.lo transact.lo 
             utility.lo misc.lo  -L/usr/local/mysql/lib/mysql -lc  -Wl 
             -soname -Wl,libmyodbc-3.51.01.so -o .libs/libmyodbc-3.51.01.so

You can now get a working libmyodbc3.so file by doing:

gcc -shared  catalog.lo connect.lo dll.lo execute.lo info.lo myodbc3.lo 
             options.lo error.lo prepare.lo results.lo transact.lo 
             utility.lo misc.lo  -L/usr/local/mysql/lib/mysql -lmysqlclient
             -lc  -Wl -soname -Wl,libmyodbc-3.51.01.so 
             -o .libs/libmyodbc-3.51.01.so

and then continue with make install

(If someone can fix configure to automaticly do the above, please mail
myodbc@lists.mysql.com about this!)

=================================
5. BUILDING THE DRIVER ON WINDOWS
=================================

On Windows, one should be able to build the driver using the Makefiles
distributed with the souce. WIN_Makefile is used to build the release
version and WIN_Makefile_debug for building the Debug version of the
driver DLLs.

Download and extract the sources to a folder myodbc3, and follow the
commands to build and install the release version

 Command> cd myodbc3
 Command> nmake -f Win_Makefile, builds the release version of the driver.
 Command> nmake -f Win_Makefile install, installs the driver files to 
system folders.

NOTE: Make sure to specify the correct MySQL client libraries and header
files path in the Makefiles. It assumes the default path as C:\mysql\include
and C:\mysql\lib\opt for release DLLs and C:\mysql\lib\debug for debug
versions.

=================================
6. CONFIGURATING DATA SOURCE NAME
=================================

Configuring one or more myodbc datasources (iodbc specific)

   With ODBC, there are two kinds of datasources: 'system' and 'user'.
   User datasources are configured in either the file $ODBCINI points to
   or $HOME/.odbc.ini.
   System datasources are configured in a global file, usually 
   /usr/local/etc/odbc.ini. If you want odbc.ini file in any directory,
   then add this complete path to ODBCINI environment variable as
   
   export ODBCINI=/home/mysql/myodbc3/odbc.ini

   In the file you chose to use, for a mysql server on machine 
   'www.mysql.com' listening on port 3306, add the following to set up
   a datasource for database 'test':

   [test]
   DSN	     = test
   # the path where you installed myodbc3.so
   DRIVER    = /usr/local/lib/libmyodbc3.so
   SERVER    = www.mysql.com
   DATABASE  = test
   USER      = root
   PASSWORD  =
   PORT	     = 3306
   SOCKET    = /tmp/mysql.sock
   OPTION    = 3
   STMT      =
    
   Then, connecting using SQLConnect("test",user,password) or SQLDriverConnect
   ("DSN=test;...") should work.

   Examples of other options you can use are:

   # to use a unix socket (remove the Server line)
   Socket	 = /tmp/mysql.sock
   
   # provide a default user and password
   User		 = joe
   Password	 = secret

   Enable tracing (Only if libmysqlclient is configured with --with-debug)

   Trace    = On
   TraceFile= stderr

   Please note that this configuration procedure is only temporary. In the near
   future, as iodbc evolves, hand editing of ini files will be obsolete.

=====================
7. TESTING THE DRIVER
=====================

Test the driver libraries and or DLLs, by running the basic samples
that are distributed in the sub-directory 'samples' along with the
driver sources.

On UNIX platforms, after building the driver, go to the 'samples'
sub-directory and start building them using 'make'

  Command> make or 
  Command> make -f Makefile

On Windows, goto the samples directory and execute the following
command to build all the samples:

  Command> cd myodbc3/samples
  Command> nmake -f Win-Makefile

And start executing each samples, by specifying the DSN name as the
command line arguments. All samples accepts the following command
line arguments:

  Command> sample_executable [DSN] [UID] [PWD]

=====================
8. TESTING WITH iodbc
=====================

Go to the samples directory for libiodbc run 'odbctest'.If you enter '?' in 
the prompt you should see the databases you have configured in .odbc.ini.

Here is a sample run that checks if your odbc setup works.

(This assumes you have a DSN named 'test' in your .odbc.ini file):

(/my/local/src/libiodbc-2.50.3/samples) odbctest
OpenLink ODBC Demonstration program
This program shows an interactive SQL processor

Enter ODBC connect string (? shows list): ?

DSN                            | Description
---------------------------------------------------------------
test                           |

Enter ODBC connect string (? shows list): DSN=test

SQL>select version();
version()
------------------
3.23.14-alpha
 1 row(s) fetched.

SQL>quit

Have a nice day.


If you can't get the above to work (you get the SQLSTATE=IM008 error),
verify that your loader can find the libmysqlclient.so library:

(/my/local/src/myodbc-3.51.01) ldd /usr/local/lib/libmyodbc3.so
        libmysqlclient.so.7 => not found
        libc.so.6 => /lib/libc.so.6 (0x40018000)
        /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x80000000)

The above means that libmysqlclient.so can't be found.

You can fix this in some of the following ways:

- Add the path the the libmysqlclient library to /etc/ld.so.conf and run
  ldconfig
- copy or link libmysqlclient.a to some library that is searched by ldconfig
  and run ldconfig.
- Add the path to the LD_LIBRARY_PATH variable.

In the following example, I used the last method:
(/my/local/src/libiodbc-2.50.3/samples) export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/mysql/lib/mysql
(/my/local/src/libiodbc-2.50.3/samples) ldd /usr/local/lib/libmyodbc3.so
        libmysqlclient.so.7 => /usr/local/mysql/lib/mysql/libmysqlclient.so.7 (0x40014000)
        libc.so.6 => /lib/libc.so.6 (0x4002c000)
        libnsl.so.1 => /lib/libnsl.so.1 (0x400d3000)
        libm.so.6 => /lib/libm.so.6 (0x400d9000)
        libz.so.1 => /usr/lib/libz.so.1 (0x400f2000)
        libcrypt.so.1 => /lib/libcrypt.so.1 (0x40100000)
        /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x80000000)

========================
9. TESTING WITH unixODBC
========================

Locate the command line utility 'isql' distributed with unixodbc
and then try "isql -v test" where test is the DSN for MyODBC 3.51
  

For more information, read the FAQs on MyODBC from 
http://www.mysql.com/products/myodbc/faq_toc.html


Have fun.

On behalf of the MySQL AB team:

Michael Widenius.
myodbc@lists.mysql.com