BASIC INSTALLATION
==================

To install the package you usually just type

    perl Makefile.PL
    make               # optional
    make test          # optional
    make install

See WIN32 INSTALLATION below for additional steps under Win32.
See KNOWN PROBLEMS below for troubleshooting.

During the first step you will be asked some questions. First of all,
you have to decide, which database engines you want to be supported:
MySQL or mSQL (any or both of mSQL1 and mSQL2).

If you install the mSQL driver, but not for both of mSQL1 or mSQL2,
the perl modules will be named DBD::mSQL and Msql. If you install
both of mSQL1 and mSQL2, the drivers will be named DBD::mSQL and
Msql (mSQL2) or DBD::mSQL1 and Msql1, respectively.

Once this is done, for any DBMS you'll be asked in which directory the
respective API libraries and headerfiles are installed. You can avoid
this question by setting the MSQL_HOME and MYSQL_HOME environment
variables. If, for example, the file $MSQL_HOME/include/msql.h exists,
you will not be prompted for the installation directory.

If "make test" fails with a message like

	Cannot connect: Can't connect to local mSQL server
        Either your server is not up and running or you have no
        permissions for acessing the DSN DBI:mSQL:test.
        This test requires a running server and write permissions.
        Please make sure your server is running and you have
        permissions, then retry.

this can have a number of possible reasons:

  - your database engine is not up and running
  - you don't have a database "test"; either create one or try setting
    the environment variable DBI_DSN to the correct value:

	DBI_DSN="DBI:mSQL:mydb"; export DBI_DSN		# Bourne-Shell
	setenv DBI_DSN="DBI:mSQL:mydb"			# C-Shell

  - your engine is not running on the local host; fix this by by adding
    the host name and port to DBI_DSN, for example

	DBI_DSN="DBI:mSQL:test:hostname=localhost:port=3333"


WIN32 INSTALLATION
==================

I have never attempted to install DBD::mSQL under Win32, so this is only
for MySQL. If anyone succeeds, please let me know what you did.

First of all, unless you choose a binary distribution of the Msql-Mysql-
modules as offered on www.tcx.se, you definitely *need* a C compiler.
And it *must* be the same compiler that was being used for compiling
Perl itself. If you don't have a C compiler, the file README.win32 from
the Perl source distribution tells you where to obtain freely distributable
C compilers like egcs or gcc. The Perl sources are available on any CPAN
mirror in the src directory, for example

    ftp://ftp.funet.fi/pub/languages/perl/CPAN/src/latest.tar.gz

I recommend using the win32clients package for installing DBD::mysql
under Win32, available for download on www.tcx.se. The following steps
have been required for me:

  - Extract sources into C:\. This will create a directory C:\mysql with
    subdirectories include and lib.

    IMPORTANT: Make sure this subdirectory is not shared by other TCX
    files! In particular do *not* store the MySQL server in the same
    directory. If the server is already installed in C:\mysql, choose
    a location like C:\tmp, extract the win32clients there. Note that
    you can remove this directory entirely once you have installed the
    Msql-Mysql-modules.
  - Extract the Msql-Mysql-modules sources into another directory, for
    example C:\src\siteperl
  - Open a DOS shell and change directory to C:\src\siteperl
  - The next step is only required if you repeat building the modules: Make
    sure that you have a clean build tree by running

	nmake realclean

    If you don't have VC++, replace nmake with your flavour of make.
    If error messages are reported in this step, you may safely ignore
    them.
  - Run

	perl Makefile.PL

    which will prompt you for some settings. The really important ones are:

	Which DBMS do you want to use?

    enter a 1 here (MySQL only), and
 
	Where is your mysql installed? Please tell me the directory that
	contains the subdir include.

    where you have to enter the win32clients directory, for example
    C:\mysql or C:\tmp\mysql.
  - Continued in the usual way:

	nmake
	nmake install

See the first section of KNOWN PROBLEMS below.

If you want to create a PPM package for the ActiveState Perl version, then
modify the above steps as follows: Run

	perl Makefile.PL NAME=DBD-mysql BINARY_LOCATION=DBD-mysql.tar.gz
	nmake ppd
	nmake

Once that is done, use tar and gzip (for example those from the CygWin32
distribution) to create an archive:

	mkdir x86
	tar cf x86/DBD-mysql.tar blib
	gzip x86/DBD-mysql.tar

Put the files x86/DBD-mysql.tar.gz and DBD-mysql.ppd onto some WWW server
and install them by typing

	install http://your.server.name/your/directory/DBD-mysql.ppd

in the PPM program.


KNOWN PROBLEMS
==============

1.) If linking fails under Win32 because of a missing symbol
pthread_cond_init, apply the following patch to dbd/dbdimp.c:

	*** dbd/dbdimp.c.orig	Wed Sep 23 14:39:33 1998
	--- dbd/dbdimp.c	Fri Oct 02 10:37:16 1998
	***************
	*** 1708,1712 ****
	--- 1709,1720 ----
	      }
	      return TRUE;
	  }
	+ 
	+ #if !defined(_UNIX_)  &&  defined(WIN32)
	+ int pthread_cond_init()
	+ {
	+   return 0;
	+ }
	+ #endif
	  
	  #endif

(I could make this part of the source distribution, but I think this is an
ugly hack and hopefully Monty will fix the missing symbol in the next
release of MyODBC.)

2.) If the MySQL binaries are compiled with gcc or egcs (as the precompiled
binaries are), but your Perl is using another compiler, it is likely that
you receive an error message like the following when running "make test":

    t/00base............install_driver(mysql) failed: Can't load
    '../blib/arch/auto/DBD/mysql/mysql.so' for module DBD::mysql:
    ../blib/arch/auto/DBD/mysql/mysql.so: undefined symbol: _umoddi3
    at /usr/local/perl-5.005/lib/5.005/i586-linux-thread/DynaLoader.pm
    line 168.

This means, that your linker doesn't include libgcc.a. You have the
following options:

a) Either recompile Perl or Mysql, it doesn't matter which. The important
   thing is that you use the same compiler for both. This is definitely
   the recommended solution in the long term.

b) A simple workaround is to include libgcc.a manually. Do a "make clean"
   and "make" and in the output wait for a line like

        LD_RUN_PATH="/usr/lib/mysql:/lib" egcs -o
        ../blib/arch/auto/DBD/mysql/mysql.so  -shared -L/usr/local/lib
        dbdimp.o mysql.o -L/usr/lib/mysql -L/usr/lib/mysql -lmysqlclient
        -lm

    Repeat the same line in the shell by adding

        -L/usr/lib/gcc-lib/i386-redhat-linux/gcc-2.7.2.3 -lgcc

    where the directory is the location of libgcc.a. The best choice
    for locating this file is executing

	gcc --print-libgcc-file

    or

	gcc -v


3.) By default mSQL is installed to allow local access only. This can break
the test scripts akmisc.t, msql1.t and msql2.t. You might notice a message
like

  t/akmisc............Can't connect to MSQL server on localhost at
  t/akmisc.t line 131
  Cannot connect: Can't connect to MSQL server on localhost
  It looks as if your server (on localhost) is not up and running.
  This test requires a running server.
  Please make sure your server is running and retry.
  dubious
  Test returned status 10 (wstat 2560, 0xa00)

If this is the case, try to change the value of "Remote_Access" in
your msql.conf file to "True". If the value was set intentionally,
you might restore the old value after the tests ran ok.


4.) Recent versions of mSQL have a bug that appears in the test script
t/40bindparam.t:

> Date: Tue, 14 Jul 1998 00:59:07 +0200 (CEST)
> From: Barry Lagerweij <barry@euromedia.nl>
> To: weder@arch.ethz.ch
> Cc: msql-jdbc@list.imaginary.com, support@hughes.com.au
> Subject: [MSQL-JDBC]: mSQL 2.0.4.1 ORDER BY bug
> 
> Hello Andreas,
> 
> I read your message concerning the mSQL ORDER BY bug, since I suffered
> from the same problems.
> 
> I dived into the source, and came up with a solution: in avl_tree.c, the
> copy/compare functions do not take the first (aka NULL) byte into account.
> mSQL 2.0.4.1 supports NULL values, but these are not handled correctly in
> the index functions. The following patch corrects this :
> 
> ----------------cut here----------------
> 
> *** avl_tree.c.orig     Mon Jul 13 14:22:31 1998
> --- avl_tree.c  Mon Jul 13 15:37:59 1998
> ***************
> *** 218,223 ****
> --- 218,224 ----
>                 *dst;
>         avltree *tree;
>   {
> +       *dst++ = *src++;
>         switch(tree->sblk->keyType)
>         {
>                 case AVL_INT:
> ***************
> *** 529,534 ****
> --- 530,538 ----
>                 *v2;
>         avltree *tree;
>   {
> +       int     i;
> +
> +       if ((i = (*v1++ - *v2++)) != 0) return(i);
>         switch(tree->sblk->keyType)
>         {
>                 case AVL_INT:
> 
> -------------cut here------------------




Please let us know, if you have further questions that should be dealt
with in this document.


Enjoy,
Andreas & Jochen


