The code in this package is Copyright (c) 1994-1996 Andreas König 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 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 with the statement use Msql; After that you can connect to multiple msql database servers and send multiple queries to any of them via an simple object oriented 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; or %hash = $sth->fetchhash; 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]; The list of the names for each column is returned by @list => $sth->name; 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, but is heavily commented, so you may use it as a tutorial. Installing The Adaptor ---------------------- Unpack in any directory anywhere on your 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. During installation this should be turned into a manpage. 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. pmsql ----- This package comes with a small standalone program, pmsql. It is a lightweight shell for your interactive communication needs with your mSQL server(s). Try 'man pmsql' or 'perldoc pmsql' after installation to get at the documention embedded in the program. pmsql is similar to both the msql monitor and the relshow program. The main advantage over those is that if you have Term::ReadKey and Term::ReadLine::Perl installed on your system, you have access to a readline clone, entirely written in perl with command line editor, a basic completion and history, and you get the output of any select query piped into your favorite pager program. 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 könig