The Msql Perl Adaptor
---------------------

Adaptor-Version: alpha 1
Based on mSQL version: 0.2 with patch 1 applied
Based on Perl version: 5beta1.

mSQL is a libmsql.a library written by David Hughes
<bambi@Bond.edu.au> (Thanks, David!!!). You get that stuff at

	Host	: Bond.edu.au
	IP Addr	: 131.244.1.1
	Path	: /pub/Bond_Uni/Minerva/msql

To use the adaptor you definitely have to install this library first.

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

After unpacking THIS package in the perl distribution directory change
to the ext/Msql/ directory and edit the first lines of the Makefile.SH
to your needs. In case you installed msql with its own defaults, you
won't have to change anything. Then run

    sh Makefile.SH
    make

Then,

    make test

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 test finishes with `ok', give it a try to

    make install

If anything fails, set up the environment variable PERL_DL_DEBUG to
some value greater 0 to get some more information from the DynaLoader.


DBperl 
------

DBperl is not yet ready for being a model, but I tried to implement
most of the ideas presented by Tim Bunce in recent postings. Upgrading
to become DBperl compliant should be feasible, I hope. That's why it's
definitely to be considered alpha -- the interface will probably
change. Maybe it will be possible to write DBperl as a layer between
DBperl and an unaltered MsqlPerl, I dunno.


The Manual
----------

The manual provided by David Hughes describes in great detail how
everything should work. But, hey, we are in perl, not in C. So
consider the following:

Internally you are dealing with the two classes Msql and
Msql::Statement. You will never see the latter, because you reach it
through a statement handle returned by a Query or a ListFields
statement. The only class you name explicitly is Msql. It offers you
the Connect command:

$dbh = Connect Msql;
$dbh = Connect Msql HOST;
$dbh = Connect Msql HOST, DATABASE;

[Perl allows you to choose which notation you prefer. Equivalent are
the following arrow notations: 
$dbh = Msql->Connect; 
$dbh = Msql->Connect(HOST); 
$dbh = Msql->Connect(HOST, DATABASE);]

This connects you with the desired host/database. With no argument or
with "localhost" as the first argument connects to the UNIX socket
/dev/msql, which is a performance gain. A database name as the second
argument selects the chosen database within the connection. The return
value is a database handle. You will need this handle to gain further
access to the database. Issue multiple `Connect' statements -- no
problem.

SelectDB $dbh DATABASE;

If you haven't chosen a database with the `Connect' command, or if you
want to change the connection to a different database using a database
handle you have got from a previous `Connect', then use SelectDB.

$sth = ListFields  $dbh TABLE;
$sth = Query       $dbh SQL_STATEMENT;

These 2 work rather similar as descibed in David's manual. They return
a statement handle which lets you further explore what the server has
to tell you.

@arr = ListDBs     $dbh;
@arr = ListTables  $dbh;

An array is returned that contains the requested names without any
further information. The second wont

Insert      $dbh TABLE, VALUE [, VALUE]... ;

This is a handy method defined in Msql.pm. It does for you a full SQL
insert statement. You have to supply the correct number of columns
though. Insert calls ListFields for you to fill in the SQL insert
statement correctly. Might be a performance loss against your own
supplied insert statement.

@arr = FetchRow   $sth;

returns an array of the values of the next row fetched from the
server.

DataSeek          $sth  row;

lets you specify a certain offset of the data associated with the
statement handle. The next FetchRow will then return the appropriate
row (first row being 0).


Metadata
--------

Now lets reconsider the above methods with regard to metadata.

$dbh = Connect Msql HOST, DATABASE;

$dbh is a hash reference for a hash that contains three entries: SOCK,
HOST, and DATABASE. The names are pretty selfexplanatory, aren't they?
DATABASE is empty, if you have connected without or with only one
argument (but it gets filled by any SelectDB).

$sth = ListFields  $dbh TABLE;
$sth = Query       $dbh SQL_STATEMENT;

Those two fill the hash table referenced by the $sth with all metadata
that are provided by the API:
NUMROWS       SCALAR
NUMFIELDS     SCALAR
TABLE         ARRAY of the names of the tables of each column
NAME          ARRAY of the names of the columns
TYPE          ARRAY of the type of each column, defined in msql.h
                    and accessible via &Msql::CHAR_TYPE,
                    &Msql::INT_TYPE, &Msql::REAL_TYPE, 
IS_NOT_NULL   ARRAY of boolean
IS_PRI_KEY    ARRAY of boolean
RESULT        internal SCALAR (adress in the API)
HOST          SCALAR copied from $dbh
SOCK          SCALAR copied from $dbh
DATABASE      SCALAR copied from $dbh

All these data are currently writable, what they shouldn't be. This is
on the Todo list for the next release.


The -w switch
-------------

Also with Msql the -w switch is your friend! If you call your perl
program with the -w switch you get the warnings that normally are
stored in $Msql::db_errstr on STDERR. This is a handy method to get
the error messages from the msql server without coding it into your
program. If you want to know in greater detail what's going on, set
the environment variables that are described in David's
manual. David's debugging aid is excellent, there's nothing to be
added.



That's it! Have fun!
--andreas koenig <k@franz.ww.TU-Berlin.DE>

