MyODBC compilation and installation under Unix
==============================================

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:
	* iODBC 2.50 or later, (http://www.openlinksw.com/iodbc/), installed
	* unixODBC Alpha 3 or later (http://genix.net/unixODBC/), 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. 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.

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


3. Building the ODBC driver

   $ make
   Shold do it.

   $ make install
   Will install libmyodbc.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 myodbc.lo options.lo prepare.lo results.lo transact.lo utility.lo misc.lo  -L/usr/local/mysql/lib/mysql -lc  -Wl,-soname -Wl,libmyodbc-2.50.27.so -o .libs/libmyodbc-2.50.27.so

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

gcc -shared  catalog.lo connect.lo dll.lo execute.lo info.lo myodbc.lo options.lo prepare.lo results.lo transact.lo utility.lo misc.lo  -L/usr/local/mysql/lib/mysql -lmysqlclient -lc  -Wl,-soname -Wl,libmyodbc-2.50.27.so -o .libs/libmyodbc-2.50.27.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!)


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

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

   [foo]
   DSN		= foo
   # the path where you installed myodbc.so
   Driver	= /usr/local/lib/libmyodbc.so
   Database	= test
   Server	= foo.domain.com
   Port		= 3306
 
   Then, connecting using SQLConnect("foo",user,password) or SQLDriverConnect
   ("DSN=foo;...") should work.

   Examples of other options you can use are:

   # to use a unix socket (remove the Server line)
   Socket	 = /tmp/mysql.sock
   
   # Mysqlclient options  (You can find a full description of these in the
   # README-MSDOS file
   Options	 = 0

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


5. Testing with libiodbc-2.50.3:

   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-2.50.27) ldd /usr/local/lib/libmyodbc.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/libmyodbc.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)

  

Have fun.

On behalf of the TcX Gang:

Michael Widenius.
myodbc@lists.mysql.com
