The code in this directory is

Copyright (c) 1994-1996 Andreas Koenig <a.koenig@mind.de>

and may be used, copied and redistributed under the same terms as perl 
(see the files README, Copying and Artistic in the perl distribution).

Prerequisites
-------------

libmsql.a library written by David Hughes <bambi@Bond.edu.au> that
implements an API between arbitrary client programs and the mSQL
database engine. You get that library and the database engine from

    ftp://Bond.edu.au/pub/Minerva/msql/msql-*.tar.gz

To use the adaptor you definitely have to install the database and the
library first. From Version 1.04 of MsqlPerl you need perl5.002 or
better installed.

What you achieve with MsqlPerl
------------------------------

MsqlPerl is an interface between the perl programming language and the
mSQL programming API that comes with the mSQL relational database
management system. All functions provided by the mSQL programming API
are supported.

From perl you activate the interface by the statement

    use Msql;

After that you can Connect to multiple msql database servers and send
multiple queries to any of them via an object oriented simple
interface. Two types of objects are available: database handles and
statement handles. Perl returns a database handle to the Connect
method like so:

    $dbh = Msql->Connect($hostname,$databasename);

Once you have connected to a database, you get a statement handle
with:

    $sth = $dbh->Query("select foo from bar");

You can open as many queries as you like simultaneously by selecting a
different scalar to hold the object:

    $another_sth = $dbh->Query("select bar from foo");

The statement handle allows you to step through the virtual table
returned from the database with the FetchRow method:

    @row = $sth->FetchRow;

You can access all metadata that mSQL supplies for a given table. To
find out the number of rows or the number of fields returned by a
query you simply say:

    $numrows = $sth->numrows;
    $numfields = $sth->numfields;

To find out the size in bytes for the field with the offset 0 (the
first field of a query), you say:

    $length = $sth->length->[0];

As for other metadata available, consult the manpage that comes with
MsqlPerl and study the examples in the file t/msql.t, which is the
extensive testscript to test your installation.

Installing The Adaptor
----------------------

Unpack in any directory anywhere on you filesystem and run

    perl Makefile.PL
    make
    make test

The latter will give you some instructions, if msqld is not running or
if a database "test" is not available. Rest assured, that no existing
data in this database will be overwritten.

If the tests finish with `ok', give it a try to

    make install

If anything fails, check the documentation of the ExtUtils::MakeMaker
module. Especially if you're facing problems with dynamic loading, set
the environment variable PERL_DL_DEBUG to some value greater 0 to get
some more information from the DynaLoader.

Documentation
-------------

Documentation is available in pod format within the file Msql.pm. You
can turn this file into a manpage or a html page with the pod2*
programs that come with the perl distribution. Try 'man Msql', and if
this doesn't work on your system, try 'perldoc Msql'.

The tutorial that may be helpful for you is in the file t/msql.t. This
file is the test program for this package and illustrates all basic
operations that are available.

Mailing list
------------

Announcements of new versions will be made on comp.lang.perl.announce
and on the mailing list devoted to the maintenance of the package:
subscribe to the list by sending mail to

    msqlperl-request@franz.ww.tu-berlin.de

with the word "subscribe" in the body of the message. It's a low-volume
mailing list.

You send messages to the list directly when you mail to
msqlperl@franz.ww.tu-berlin.de.


...have fun,
andreas koenig <a.koenig@mind.de>