886 lines
33 KiB
HTML
886 lines
33 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
|
|
<HTML>
|
|
<HEAD>
|
|
<META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.9">
|
|
<TITLE>A mSQL and perl Web Server Mini HOWTO: Installation Procedure</TITLE>
|
|
<LINK HREF="WWW-mSQL-HOWTO-4.html" REL=next>
|
|
<LINK HREF="WWW-mSQL-HOWTO-2.html" REL=previous>
|
|
<LINK HREF="WWW-mSQL-HOWTO.html#toc3" REL=contents>
|
|
</HEAD>
|
|
<BODY>
|
|
<A HREF="WWW-mSQL-HOWTO-4.html">Next</A>
|
|
<A HREF="WWW-mSQL-HOWTO-2.html">Previous</A>
|
|
<A HREF="WWW-mSQL-HOWTO.html#toc3">Contents</A>
|
|
<HR>
|
|
<H2><A NAME="s3">3. Installation Procedure</A></H2>
|
|
|
|
<P>
|
|
<P>
|
|
<H2><A NAME="ss3.1">3.1 Hardware Requirements</A>
|
|
</H2>
|
|
|
|
<P>No general statement can be made about the hardware requirements of
|
|
a database server. Too much depends on the expected number of users,
|
|
the kind of application, the network load etc. In a small environment
|
|
with only a few users and little network traffic a i486-equivalent
|
|
machine with 16 MB of RAM can be completely sufficient. Linux, the
|
|
operating system, is very efficient in terms of resources, and can
|
|
supply enough horse-power for running a broad variety of applications
|
|
at the same time. Of course, faster processors and more RAM mean more
|
|
speed, but much more important than the processor is the amount of
|
|
RAM. The more RAM the system has the less it is forced to swap
|
|
memory intensive processes to disk in case a bottleneck occurs.
|
|
<P>Given anything like 32 MB RAM and a PCI bus, searches and sorting
|
|
operations can be done without much resorting to swap files etc.,
|
|
resulting in lightening fast speed.
|
|
<P>The model installation described in this article was made on a IBM 686
|
|
(133Mhz) with 32 MB RAM and a 1.2 GB IDE hard disk. Assuming that the
|
|
installation process starts from scratch, here is a list of the
|
|
necessary steps.
|
|
<P>
|
|
<H2><A NAME="ss3.2">3.2 Software Requirements</A>
|
|
</H2>
|
|
|
|
<P>
|
|
<P>The software described in this article is available from the Internet
|
|
or from CD-ROM. The following products were used:
|
|
<UL>
|
|
<LI> Red Hat Linux PowerTools: 6 CD's Complete Easy-to-Use
|
|
Red Hat 4.2, Summer '97; alternatively from
|
|
<CODE>http://www.redhat.com</CODE>;
|
|
</LI>
|
|
<LI> msql SQL database server: it is now available in
|
|
two versions. The versions have differences in
|
|
the number of transactions they can handle, the
|
|
administration interface, etc. The elder version,
|
|
1.0.16, is available from Sunsite mirrors. The
|
|
ELF executable can be found at
|
|
<CODE>sunsite:apps/database/sql/msql-1.0.16</CODE>
|
|
or on CD-ROM (here: disc 4 of InfoMagic Linux Developer's
|
|
Resource, 6-CD set, December 1996) or alternatively
|
|
from the following URL:
|
|
<CODE>http://www.infomagic.com</CODE>.
|
|
|
|
The newer version, 2.0.1, can be directly obtained
|
|
from Hughes' homepage in Australia
|
|
(<CODE>http://www.hughes.com.au</CODE>) or from numerous
|
|
mirror sites around the world;
|
|
</LI>
|
|
<LI> perl from CPAN: The Comprehensive Perl Archive Network.
|
|
Walnut Creek CDROM, ISBN 1-57176-077-6, May 1997;
|
|
</LI>
|
|
<LI> Michael Schilli's CGI example program from computer
|
|
journal iX 8/1997, pages 150--152, available via ftp from
|
|
<CODE>ftp.uni-paderborn.de:/doc/magazin/iX</CODE>;</LI>
|
|
</UL>
|
|
<P>
|
|
<H2><A NAME="ss3.3">3.3 Installing the Operating System</A>
|
|
</H2>
|
|
|
|
<P>Linux is installed in form of the Red Hat Linux Distribution 4.2. In order
|
|
to install successfully, the machine must either have a DOS-accessible
|
|
CD-ROM drive, a bootable CD-ROM drive, or else a boot disk must be made
|
|
following the instructions on the Linux CD.
|
|
<P>During installation the user has the choice to select and configure
|
|
numerous software packages. It is convenient to select the following
|
|
items now:
|
|
<P>
|
|
<UL>
|
|
<LI> TCP/IP network support,</LI>
|
|
<LI> the http server Apache, and</LI>
|
|
<LI> the scripting language perl, and</LI>
|
|
<LI> the X Window System, as well as</LI>
|
|
<LI> the browsers Arena (graphical) and Lynx (text-based).</LI>
|
|
</UL>
|
|
<P>All these packages are provided with the Linux distribution.
|
|
If you do not install these packages now you still have the chance to
|
|
do this later with the assistance of glint, the graphical and intuitive
|
|
software package installation manager. Be sure to be root when installing
|
|
these packages.
|
|
<P>It is beyond the scope of this article to describe the network installation
|
|
and initialization procedure. Please consult the online (manpages, HTML,
|
|
texinfo) and printed (Linux Bible, etc. etc.) documentation.
|
|
<P>The installation procedure of Red Hat is very mature and requires only
|
|
little user attention besides the usual choices (like providing host names,
|
|
etc.). Once the installation ends successfully, the system is basically
|
|
ready to go.
|
|
<P>Installing the X Window System is not mandatory for a pure server but
|
|
it makes local access and testing much easier. The X installation procedure
|
|
is done by any of several programs; XF86Setup offers the most extensive
|
|
self-testing facilities and needs the least handling of hairy details
|
|
(like video clock programming, etc.). The only requirement is that the
|
|
software can detect the video adapter. A cheap accelerated graphics
|
|
adapter (like Trio S64 based cards prior to S64UV+) usually works
|
|
``out of the box''.
|
|
<P>At this point we assume that our system is up and running and that
|
|
Apache, Perl and the X Window System have been successfully installed.
|
|
We further assume that all standard structures like the file and
|
|
directory structure are kept as they are defined in the installation.
|
|
Last but not least we leave the host name as it is, and do at this moment
|
|
accept the name <CODE>localhost</CODE>. We'll use this name for testing
|
|
the installation; once the whole system works the true name can be added.
|
|
Please note that the network setup also requires editing the
|
|
files <CODE>/etc/hosts</CODE>, among others. Ideally this should be done with
|
|
the administration tools provided to user root.
|
|
<P>
|
|
<P>
|
|
<H2><A NAME="ss3.4">3.4 The http Server</A>
|
|
</H2>
|
|
|
|
<P>
|
|
<P>The http server supplied with Linux is known as Apache to humans and
|
|
as httpd to the system. The manpage (man httpd) explains how to install
|
|
and start the http daemon (hence http<EM>d</EM>) but, as mentioned, if
|
|
the installation went without problems then the server should be running.
|
|
You can verify the directory tree: there must be a directory
|
|
<CODE>/home/httpd/</CODE> with three subdirectories: <CODE>../cgi-bin/</CODE>,
|
|
<CODE>../html/</CODE> and <CODE>../icons/</CODE>. In <CODE>../html/</CODE> there must
|
|
be a file <CODE>index.html</CODE>. Later we will manipulate or replace this
|
|
file by our own <CODE>index.html</CODE>. All configuration information is
|
|
stored in<CODE>/etc/httpd/conf/</CODE>. The system is well preconfigured
|
|
and does not need further setup provided the installation went without
|
|
error.
|
|
<P>
|
|
<H2><A NAME="ss3.5">3.5 The Browsers</A>
|
|
</H2>
|
|
|
|
<P>
|
|
<P>There are essentially three types of browsers available for Linux:
|
|
pure text-based systems like Lynx, experimental and simple ones like
|
|
Arena (free!) and commercial ones like Netscape (shareware!) with
|
|
Java support. While Lynx and Arena come with Linux, Netscape must
|
|
be procured from other sources. Netscape is available as a precombiled
|
|
binary for Linux on ix86 architectures and will run ``out of the box''
|
|
as soon as the archive is unpacked.
|
|
<P>
|
|
<H3>Configuring Lynx</H3>
|
|
|
|
<P>
|
|
<P>Once Lynx is started it will look for a `default URL' which is usually
|
|
not very meaningful if the system does not have permanent Internet access.
|
|
In order to change the default URL (and lots of other configuration details)
|
|
the system administrator should edit <CODE>/usr/lib/lynx.cfg</CODE>. The file
|
|
is big, around 57000 bytes and contains occasionally contradicting
|
|
information. It states its own home as <CODE>/usr/local/lib/</CODE>. Not
|
|
far from top is a line beginning with <CODE>STARTFILE</CODE>. We replace this
|
|
line by the following entry: <CODE>STARTFILE:http://localhost</CODE> and
|
|
make sure that no spacing etc. is inserted:
|
|
<HR>
|
|
<PRE>
|
|
# STARTFILE:http://www.nyu.edu/pages/wsn/subir/lynx.html
|
|
STARTFILE:http://localhost
|
|
</PRE>
|
|
<HR>
|
|
|
|
After saving the file, Lynx should now reveal our <CODE>index.html</CODE>
|
|
document if started without arguments.
|
|
<P>
|
|
<H3>Configuring Arena</H3>
|
|
|
|
<P>
|
|
<P>Arena first looks for its own default URL when started without arguments.
|
|
This URL is hard-wired into the executable but can be overrun by the
|
|
environment variable <CODE>WWW_HOME</CODE>. The system administrator can place
|
|
a line saying <CODE>WWW_HOME="http://localhost"</CODE> in <CODE>/etc/profile</CODE>.
|
|
The variable must then be exported, either by a separate statement
|
|
(<CODE>export WWW_HOME</CODE>) or by appending <CODE>WWW_HOME</CODE> to the
|
|
existing export statement:
|
|
<HR>
|
|
<PRE>
|
|
WWW_HOME="http://localhost"
|
|
export WWW_HOME
|
|
</PRE>
|
|
<HR>
|
|
|
|
After relaunching a login shell, the new default URL is now
|
|
system-wide known to Arena.
|
|
<P>
|
|
<P>
|
|
<H3>Installing and Configuring Netscape</H3>
|
|
|
|
<P>
|
|
<P>Netscape is a commercial product and thus not included with the
|
|
Linux distributions. It is either downloadable from the
|
|
Internet or available from software collections on CDROM. Netscape
|
|
comes in form of precompiled binaries for every important hardware
|
|
platform. For installation purposes, it is useful to create a directory
|
|
<CODE>/usr/local/Netscape/</CODE> where the archive is unpacked. The files
|
|
can be kept in place (except for the Java library: follow the instructions
|
|
in the <CODE>README</CODE> file that comes with the Netscape binary), and
|
|
it is sufficient to create a soft link in <CODE>/usr/local/bin/</CODE> by
|
|
issuing the command
|
|
<PRE>
|
|
# ln -s /usr/local/Netscape/netscape .
|
|
</PRE>
|
|
|
|
from within <CODE>/usr/local/bin/</CODE>.
|
|
<P>Netscape is now ready for use and can be configured via the ``Options''
|
|
menu. In ``General Preferences'' there is a card ``Appearance'' with
|
|
the entry ``Home Page Location''. Enter <CODE>http://localhost</CODE> here
|
|
and do not forget to save the options (via ``Options'' --- ``Save Options'')
|
|
before exiting Netscape. At the next startup, Netscape will now show
|
|
the Apache `homepage'.
|
|
<P>
|
|
<H2><A NAME="ss3.6">3.6 Cooperation of Apache and Browsers</A>
|
|
</H2>
|
|
|
|
<P>
|
|
<P>You can now conduct the first real test of both the
|
|
browser and the http server: simply start any of the available browsers
|
|
and the <CODE>Apache: Red Hat Linux Web Server</CODE> page will pop up.
|
|
This page shows the file locations and other basics of http server
|
|
installation. If this page is not displayed please check whether the
|
|
files mentioned above are in place and whether the browser configuration
|
|
is correct. Close edited configuration files before you start the browser
|
|
again. If all files are in place and the browsers seem to be configured
|
|
correctly then examine the network setup of your machine. Either the
|
|
host name is different from what was entered in the configuration, or
|
|
the network setup as such is not correct. It is utterly important
|
|
that <CODE>/etc/hosts</CODE> contains at least a line like
|
|
<HR>
|
|
<PRE>
|
|
127.0.0.1 localhost localhost.localdomain
|
|
</PRE>
|
|
<HR>
|
|
|
|
which implies that you can connect locally to your machine. One can
|
|
verify this by issuing any network-sensitive command requiring a host name
|
|
as argument, like <CODE>telnet localhost</CODE> (provided <CODE>telnet</CODE>
|
|
is installed). If that does not work then the network setup must be
|
|
verified before continuing with the main task.
|
|
<P>
|
|
<P>
|
|
<H2><A NAME="ss3.7">3.7 The Database Engine and its Installation</A>
|
|
</H2>
|
|
|
|
<P>
|
|
<P>Installing the database requires only little more preparation than the
|
|
previous installation steps. There are a few SQL database engines available
|
|
with different runtime and administrative requirements, and possibly
|
|
one of the most straightforward systems is msql, or ``Mini-SQL'' by David
|
|
Hughes. msql is shareware. Depending on the version used, commercial sites
|
|
are charged USD 250.00 and more, private users are charged USD
|
|
65.00 and more, and only educational institutions and registered
|
|
non-profit organizations can use this software free of charge.
|
|
Please note that the exact figures are provided in the licence notes
|
|
of the database documentation. The figures given here serve as a rough
|
|
indicator only.
|
|
<P>A few words are in place here why the author chose msql. First of
|
|
all, there is personal experience. While searching for a database
|
|
engine the author found msql to be about the easiest to install
|
|
and maintain, and it provides enough coverage of the SQL language
|
|
to meet general needs. Only when writing these lines, the author
|
|
discovered the following words of praise in Alligator Descartes'
|
|
DBI FAQ (perl database interface FAQ):
|
|
<P>
|
|
<BLOCKQUOTE>
|
|
From the current author's point of view, if the dataset is
|
|
relatively small, being tables of less than 1 million
|
|
rows, and less than 1000 tables in a given database, then
|
|
mSQL is a perfectly acceptable solution to your problem.
|
|
This database is extremely cheap, is wonderfully robust
|
|
and has excellent support. [...]
|
|
</BLOCKQUOTE>
|
|
<P>Msql is available in two versions now, msql-1.0.16 and msql-2.0.1,
|
|
which differ in performance (not noticeable in small scale projects)
|
|
and accompanying software (the newer version comes with more tools,
|
|
its own scripting language, etc.). We will describe both versions
|
|
of msql since their installion differs in a few points.
|
|
<P>
|
|
<H3>Installing msql-1.0.16</H3>
|
|
|
|
<P>
|
|
<P>msql is available as source and as compiled executable with ELF support.
|
|
Using the ELF binaries makes installation easy since the archive file
|
|
<CODE>msql-1.0.16.ELF.tgz</CODE> contains a complete absolute directory tree
|
|
so that all directories are generated properly when unpacked from <CODE>/</CODE>.
|
|
<P>If you decide to compile msql-1.0.16 yourself and are going to use
|
|
the MsqlPerl package rather than the DBI interface (see a detailed
|
|
discussion on the difference between these two further down) then be
|
|
prepared that MsqlPerl might complain during the test suites that some
|
|
instruction inside msql failed. In this case a patch may be necessary
|
|
which is described in the MsqlPerl documentation (file
|
|
<CODE>patch.lost.tables</CODE>). Notably, this demands including three lines
|
|
in <CODE>msqldb.c</CODE> after line 1400 which says <CODE> entry->def = NULL;</CODE>:
|
|
<PRE>
|
|
*(entry->DB) = 0;
|
|
*(entry->table) = 0;
|
|
entry->age = 0;
|
|
</PRE>
|
|
|
|
The code fragment should now look like
|
|
<HR>
|
|
<PRE>
|
|
freeTableDef(entry->def);
|
|
safeFree(entry->rowBuf);
|
|
safeFree(entry->keyBuf);
|
|
entry->def = NULL;
|
|
*(entry->DB) = 0;
|
|
*(entry->table) = 0;
|
|
entry->age = 0;
|
|
</PRE>
|
|
<HR>
|
|
<P>Compiling msql involves several steps. After unpacking the source
|
|
archive, it is necessary to build a target directory. This is done
|
|
by saying
|
|
<PRE>
|
|
# make target
|
|
</PRE>
|
|
|
|
If successful, the system will then answer with
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
Build of target directory for Linux-2.0.30-i486 complete
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
|
|
You must now change into this newly created directory and run a
|
|
<PRE>
|
|
# ./setup
|
|
</PRE>
|
|
|
|
command first. The <CODE>./</CODE> sequence is necessary to make sure
|
|
that really the command <CODE>setup</CODE> in this directory and not another
|
|
command which happens to have the same name is executed. You will
|
|
then be asked questions on the location of the source directory and
|
|
whether a root installation is desired. These questions answered,
|
|
the system should then run a number of tests checking for available
|
|
software (compilers, utilities etc.) and finally say
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
Ready to build mSQL.
|
|
|
|
You may wish to check "common/site.h" although the defaults should be
|
|
fine. When you're ready, type "make all" to build the software
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
|
|
We say
|
|
<PRE>
|
|
# make all
|
|
</PRE>
|
|
|
|
If everything went as intended, we'll read:
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
make[2]: Leaving directory `/usr/local/Minerva/src/msql'
|
|
<-- [msql] done
|
|
|
|
Make of mSQL complete.
|
|
You should now mSQL using make install
|
|
|
|
NOTE : mSQL cannot be used free of charge at commercial sites.
|
|
Please read the doc/License file to see what you have to do.
|
|
|
|
make[1]: Leaving directory `/usr/local/Minerva/src'
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
<P>All binaries must then be made visible to the search paths by creating
|
|
soft links in <CODE>/usr/local/bin/</CODE>. Change to that directory and
|
|
issue the command
|
|
<PRE>
|
|
# ln -s /usr/local/Minerva/bin/* .
|
|
</PRE>
|
|
|
|
after which the links will be properly set.
|
|
<P>
|
|
<H3>Testing msql-1</H3>
|
|
|
|
<P>
|
|
<P>After the installation it is now possible to test whether the database
|
|
works. Before anything else is done, the server daemon must be started.
|
|
The system administrator holding root privileges issues the command
|
|
<PRE>
|
|
# msqld &
|
|
</PRE>
|
|
|
|
(do not forget to add the <CODE>&</CODE>, otherwise msql won't run in
|
|
the background.) after which the following screen message appears:
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
mSQL Server 1.0.16 starting ...
|
|
|
|
Warning : Couldn't open ACL file: No such file or directory
|
|
Without an ACL file global access is Read/Write
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
<P>This message tells us that everything so far worked since we did
|
|
not set up any access restrictions. For the moment it is sufficient
|
|
to start the msql daemon from within a shell but later we may want
|
|
to have the system startup automatically execute this command for us.
|
|
The command must then be mentioned in a suitable <CODE>rc.d</CODE> script.
|
|
Only now the administrator can issue the first genuine database command:
|
|
<PRE>
|
|
# msqladmin create inventur
|
|
</PRE>
|
|
|
|
msql replies by saying <CODE>Database "inventur" created.</CODE>. As a further
|
|
proof, we find that the directory <CODE>/usr/local/Minerva/msqldb/</CODE>
|
|
contains now the empty subdirectory <CODE>../inventur/</CODE>. We could
|
|
manipulate the newly created database with the administration tools;
|
|
these procedures are all covered in detail in the msql documentation.
|
|
<P>
|
|
<H3>Installing msql-2.0.1</H3>
|
|
|
|
<P>
|
|
<P>There is now a newer, more powerful version of Hughes' mSQL server available
|
|
the installation of which is different in a few points. Installing msql-2
|
|
from scratch involves the following steps. Copy the archive to your
|
|
extraction point, e. g. <CODE>/usr/local/msql-2/</CODE>, then untar the archive:
|
|
<PRE>
|
|
# tar xfvz msql-2.0.1.tar.gz
|
|
</PRE>
|
|
<P>Change to the root direction of the install tree and issue a
|
|
<PRE>
|
|
# make target
|
|
</PRE>
|
|
<P>Change to <CODE>targets</CODE> and look for your machine type. There should
|
|
be a new subdirectory <CODE>Linux-</CODE><I>(your version)-(your cpu)/</I>.
|
|
Change to that directory and start the setup facility located here:
|
|
<PRE>
|
|
# ./setup
|
|
</PRE>
|
|
<P>There is also a file <CODE>site.mm</CODE> which can be edited. Maybe you
|
|
have got used to the directory name <CODE>/usr/local/Minerva/</CODE> and
|
|
want to preserve it? In this case change the <CODE>INST_DIR=...</CODE>
|
|
line to your desired target directory. Otherwise, leave everything as
|
|
it is.
|
|
<P>Now you can start building the database:
|
|
<PRE>
|
|
# make
|
|
# make install
|
|
</PRE>
|
|
<P>
|
|
<P>If everything went successfully, we'll see a message like:
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
[...]
|
|
|
|
Installation of mSQL-2 complete.
|
|
|
|
*********
|
|
** This is the commercial, production release of mSQL-2.0
|
|
** Please see the README file in the top directory of the
|
|
** distribution for license information.
|
|
*********
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
<P>After all is installed properly we have to take care of the
|
|
administration details. Here, the real differences from msql-1
|
|
begin. First, a user <CODE>msql</CODE> is created which is responsible for
|
|
database administration.
|
|
<P>
|
|
<PRE>
|
|
# adduser msql
|
|
</PRE>
|
|
<P>
|
|
<P>Then we have to change all ownerships in the mSQL directory to
|
|
<CODE>msql</CODE>
|
|
by saying:
|
|
<PRE>
|
|
# cd /usr/local/Minerva
|
|
# chown -R msql:msql *
|
|
</PRE>
|
|
<P>
|
|
<P>Then we create soft links for all database binaries in
|
|
<CODE>/usr/local/bin/</CODE>
|
|
by saying:
|
|
<PRE>
|
|
# ln -s /usr/local/Minerva/bin/* .
|
|
</PRE>
|
|
<P>
|
|
<P>
|
|
<H3>Testing msql-2</H3>
|
|
|
|
<P>We can now start the database server by issuing the command
|
|
<CODE>msql2d &</CODE> and should get a response similar to this one:
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
Mini SQL Version 2.0.1
|
|
Copyright (c) 1993-4 David J. Hughes
|
|
Copyright (c) 1995-7 Hughes Technologies Pty. Ltd.
|
|
All rights reserved.
|
|
|
|
Loading configuration from '/usr/local/Minerva/msql.conf'.
|
|
Server process reconfigured to accept 214 connections.
|
|
Server running as user 'msql'.
|
|
Server mode is Read/Write.
|
|
|
|
Warning : No ACL file. Using global read/write access.
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
<P>That looks perfect. The database is compiled and in place, and we
|
|
can now continue with the perl modules since these rely partially
|
|
on the presence of a working database server for testing.
|
|
<P>Accidentally, this is also a good moment to print the complete
|
|
manual that comes with msql-2.0.1:
|
|
<PRE>
|
|
# gzip -d manual.ps.gz
|
|
# lpr manual.ps
|
|
</PRE>
|
|
<P>We can proceed to building the interfaces now, but it is a good idea
|
|
to keep the newly created SQL server up and running since that makes
|
|
testing the interface libraries somewhat simpler.
|
|
<P>
|
|
<P>
|
|
<H2><A NAME="ss3.8">3.8 Choice of Interfaces: DBI/mSQL, MsqlPerl, and Lite</A>
|
|
</H2>
|
|
|
|
<P>A frequently quoted saying in the Camel Book (the authorative perl
|
|
documentation) states that there is more than one way to achieve a
|
|
result when using perl. This, alas, holds true for our model
|
|
application, too. Basically there are three ways to access an msql
|
|
database via CGI. First of all the question is whether or not perl
|
|
shall be used. If we use perl (on which this article focuses) then
|
|
we still have the choice between two completely different interface
|
|
models. Besides using perl, we can also employ msql's own scripting
|
|
language, called Lite, which is reasonably simple and a close
|
|
clone of C.
|
|
<P>
|
|
<H3>DBI and DBD-mSQL</H3>
|
|
|
|
<P>By the time of this writing, using perl's generic database interface
|
|
called DBI is the method of choice. DBI has a few advantages: It
|
|
provides unified access control to a number of commercial databases
|
|
with a single command set. The actual database in use on a given system
|
|
is then contacted through a driver which effectively hides the
|
|
pecularities of that database from the programmer. Being such, using
|
|
DBI provides for a smooth transition between different databases by
|
|
different makers. In one single script it is even possible to contact
|
|
several different databases. Please refer to the DBI-FAQ for details.
|
|
There is, however, one drawback: The DBI interface is still under
|
|
development and shows rapidly galloping version numbers (sometimes
|
|
with updates taking place within less than a month). Similarly, the
|
|
individual database drivers are also frequently updated and may
|
|
rely on specific versions of the database interface. Users making
|
|
first-time installations should stick to the version numbers given
|
|
in this article since other versions may cause compilation and
|
|
testing problems the trouble shooting of which is nothing for the
|
|
faint-hearted.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<H3>MsqlPerl</H3>
|
|
|
|
<P>MsqlPerl is a library for directly accessing msql from perl scripts.
|
|
It bypasses the DBI interface and is fairly compact. Though it works
|
|
fine with both versions of msql, its usage is not promoted anymore
|
|
in favour of the generalized DBI interface. Nonetheless, in a given
|
|
installation it may prove to be the interface of choice since it is
|
|
small and easy to install. Notably, it has less version dependencies
|
|
than revealed by the interaction of DBI and particular database
|
|
drivers.
|
|
<P>
|
|
<H3>msql's own scripting language: Lite</H3>
|
|
|
|
<P>Last but not least msql-2 comes with its own scripting language:
|
|
Lite. The language is a close relative of C stripped of its oddities
|
|
with additional shell-like features (in a way, something like a very
|
|
specialized version of perl). Lite is a simple language and is well
|
|
documented in the msql-2 manual. The msql-2 package also comes with
|
|
a sample application sporting Lite.
|
|
<P>We will not describe Lite here because it is well documented but
|
|
fairly specific to msql-2, and because it is assumed that the readers
|
|
of this article have a basic interest in and a basic understanding
|
|
of perl. Nonetheless it is highly recommended to have a closer look
|
|
at Lite: it may well be the case that Lite offers the solution of
|
|
choice in an exclusive msql-2 environment (implying no other
|
|
databases are involved) due to its simplicity and straightforward
|
|
concept.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<H2><A NAME="ss3.9">3.9 Going the generic way: DBI and DBD-msql</A>
|
|
</H2>
|
|
|
|
<P>We assume that perl was installed during the system setup or via the
|
|
package manager mentioned above. No further details will be given here.
|
|
Nonetheless we first test whether our version of perl is up to date:
|
|
<P>
|
|
<PRE>
|
|
# perl -v
|
|
</PRE>
|
|
<P>perl should respond with the following message:
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
|
|
This is perl, version 5.003 with EMBED
|
|
Locally applied patches:
|
|
SUIDBUF - Buffer overflow fixes for suidperl security
|
|
|
|
built under linux at Apr 22 1997 10:04:46
|
|
+ two suidperl security patches
|
|
|
|
Copyright 1987-1996, Larry Wall
|
|
[...]
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
|
|
So far, everything is fine. The next step includes installing the
|
|
perl libraries for databases in general (DBI), the msql driver
|
|
(DBD-mSQL) and CGI. The CGI driver is necessary in any case.
|
|
The following archives are necessary:
|
|
<OL>
|
|
<LI> DBI-0.81.tar.gz</LI>
|
|
<LI> DBD-mSQL-0.65.tar.gz</LI>
|
|
<LI> CGI.pm-2.31.tar.gz (or higher)</LI>
|
|
</OL>
|
|
<P>A caveat is necessary here for beginners: the test installation
|
|
described here works fine using software with <EM>exactly</EM> these
|
|
version numbers, and combinations of other versions failed in one or
|
|
the other way. Debugging flawed version combinations is nothing for
|
|
those who are not very familiar with the intimate details of the
|
|
calling conventions etc. of the interfaces. Sometimes only a method
|
|
is renamed while performing the same task, but sometimes the internal
|
|
structure changes significantly. So, again, stick with these version
|
|
numbers if you want to be on the safe side even if you discover that
|
|
version numbers have increased in the meantime. Frequent updates of
|
|
these interfaces are the rule rather than the exception, so you should
|
|
really anticipate problems when installing other versions than those
|
|
indicated here.
|
|
<P>It is very important that the database driver for mSQL (DBD-mSQL)
|
|
is installed <EM>after</EM> the generic interface DBI.
|
|
<P>We start by creating the directory <CODE>/usr/local/PerlModules/</CODE> as
|
|
it is very important to keep the original perl directory tree untouched.
|
|
We could also choose a different directory name since the name is completely
|
|
uncritical, and unfortunately that is not really mentioned in the README
|
|
files of the verious perl modules. Having copied the above-mentioned
|
|
archives to <CODE>/usr/local/PerlModules/</CODE> we unpack them saying
|
|
<PRE>
|
|
# tar xzvf [archive-file]
|
|
</PRE>
|
|
<P>for every single of the three archives. Do not forget to supply the
|
|
real archive name to <CODE>tar</CODE>. The installation process
|
|
for the three modules is essentially stardardized; only the screen
|
|
messages showing important steps of individual packages are
|
|
reproduced here.
|
|
<P>
|
|
<H3>Installing perl's Database Interface DBI</H3>
|
|
|
|
<P>
|
|
<P>The database interface must always be installed before installing
|
|
the specific database driver. Unpacking the DBI archive creates
|
|
the directory <CODE>/usr/local/PerlModules/DBI-0.81/</CODE>. Change to
|
|
that directory. There are a <CODE>README</CODE> file (you should read
|
|
it) and a perl-specific makefile. Now issue the command
|
|
<PRE>
|
|
# perl Makefile.PL
|
|
</PRE>
|
|
<P>The system should answer with a lengthy message of which the most
|
|
important part is shown here::
|
|
<P>
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
[...]
|
|
MakeMaker (v5.34)
|
|
Checking if your kit is complete...
|
|
Looks good
|
|
NAME => q[DBI]
|
|
PREREQ_PM => { }
|
|
VERSION_FROM => q[DBI.pm]
|
|
clean => { FILES=>q[$(DISTVNAME)/] }
|
|
dist => { DIST_DEFAULT=>q[clean distcheck disttest [...]
|
|
Using PERL=/usr/bin/perl
|
|
|
|
WARNING! By default new modules are installed into your 'site_lib'
|
|
directories. Since site_lib directories come after the normal library
|
|
directories you MUST delete old DBI files and directories from your
|
|
'privlib' and 'archlib' directories and their auto subdirectories.
|
|
|
|
Writing Makefile for DBI
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
|
|
This looks good, as the program says, and we can proceed with the
|
|
next step:
|
|
<PRE>
|
|
# make
|
|
</PRE>
|
|
|
|
If no error message occurs (the detailed protocol dumped on screen
|
|
is <EM>not</EM> an error message) we test the newly installed library
|
|
with the command
|
|
<PRE>
|
|
# make test
|
|
</PRE>
|
|
|
|
Watch the output for the following lines (you can always scroll back
|
|
with <CODE>[Shift]-[PgUp]</CODE>):
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
[...]
|
|
t/basics............ok
|
|
t/dbidrv............ok
|
|
t/examp.............ok
|
|
All tests successful.
|
|
[...]
|
|
DBI test application $Revision: 1.20 $
|
|
Switch: DBI-0.81 Switch by Tim Bunce, 0.81
|
|
Available Drivers: ExampleP, NullP, Sponge
|
|
ExampleP: testing 2 sets of 5 connections:
|
|
Connecting... 1 2 3 4 5
|
|
Disconnecting...
|
|
Connecting... 1 2 3 4 5
|
|
Disconnecting...
|
|
Made 10 connections in 0 secs ( 0.00 usr 0.00 sys = 0.00 cpu)
|
|
|
|
test.pl done
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
|
|
The final step is to install all files in their proper directories. The
|
|
following command will take care of it:
|
|
<PRE>
|
|
# make install
|
|
</PRE>
|
|
|
|
No more duties are left. If for some reason the installation failed and
|
|
you want to redo it do not forget to issue
|
|
<PRE>
|
|
# make realclean
|
|
</PRE>
|
|
|
|
first. This will remove stale leftovers of the previous installation.
|
|
You can also remove the files which were installed by copying the
|
|
screen contents (shown abbreviated)
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
Installing /usr/lib/perl5/site_perl/i386-linux/./auto/DBI/DBIXS.h
|
|
Installing /usr/lib/perl5/site_perl/i386-linux/./auto/DBI/DBI.so
|
|
Installing /usr/lib/perl5/site_perl/i386-linux/./auto/DBI/DBI.bs
|
|
[...]
|
|
Writing /usr/lib/perl5/site_perl/i386-linux/auto/DBI/.packlist
|
|
Appending installation info to /usr/lib/perl5/i386-linux/5.003/perllocal.pod
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
|
|
into a file, replacing every <CODE>Installing</CODE> with <CODE>rm</CODE>. Provided
|
|
you named the file <CODE>uninstall</CODE> you can then say
|
|
<PRE>
|
|
# . uninstall
|
|
</PRE>
|
|
|
|
which will remove the recently installed files.
|
|
<P>
|
|
<H3>perl's msql Driver DBD-mSQL</H3>
|
|
|
|
<P>
|
|
<P>The msql driver can only be installed <EM>after</EM> a successful installation
|
|
of perl's generic database interface.
|
|
<P>The basic steps are the same as above; so first go through
|
|
<PRE>
|
|
# perl Makefile.PL
|
|
</PRE>
|
|
<P>Here, the system should answer with an urgent warning to read the
|
|
accompanying documentation. It will then detect where msql resides,
|
|
and asks which version you use:
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
|
|
$MSQL_HOME not defined. Searching for mSQL...
|
|
Using mSQL in /usr/local/Hughes
|
|
|
|
-> Which version of mSQL are you using [1/2]?
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
|
|
State your correct version number. Quite a few lines of text will
|
|
follow. Watch for the following ones:
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
Splendid! Your mSQL daemon is running. We can auto-detect your configuration!
|
|
|
|
I've auto-detected your configuration to be running on port: 1114
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
<P>You can now test the driver by saying
|
|
<PRE>
|
|
# make test
|
|
</PRE>
|
|
|
|
Again, a lengthy output follows. If it ends with
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
Testing: $cursor->func( '_ListSelectedFields' ). This will fail.
|
|
ok: not a SELECT in msqlListSelectedFields!
|
|
Re-testing: $dbh->do( 'DROP TABLE testaa' )
|
|
ok
|
|
*** Testing of DBD::mSQL complete! You appear to be normal! ***
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
|
|
you are on the safe side of life and can install your driver by
|
|
saying
|
|
<PRE>
|
|
# make install
|
|
</PRE>
|
|
|
|
You are now ready to go and can skip the next paragraph.
|
|
<P>
|
|
<P>
|
|
<H2><A NAME="ss3.10">3.10 The MsqlPerl Interface</A>
|
|
</H2>
|
|
|
|
<P>If you decide to use the exclusive MsqlPerl interface then no generic
|
|
database driver is needed, only <CODE>MsqlPerl-1.15.tar.gz</CODE>, since,
|
|
as mentioned earlier, MsqlPerl provides a direct interface between
|
|
perl and the database server without using the DBI interface.
|
|
Installing and testing is straightforward.
|
|
<P>After saying <CODE>perl Makefile.PL</CODE> the make utility can be started.
|
|
First you have to answer the question where mSQL resides. If it
|
|
resides in <CODE>/usr/local/Minerva/</CODE> the default answer can be confirmed.
|
|
<P>Then do a <CODE>make test</CODE>. Before doing so you must ensure that you
|
|
have a database named <CODE>test</CODE> and that you have read and write
|
|
permissions for it. This can be done by
|
|
<PRE>
|
|
# msqladmin create test
|
|
</PRE>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<H2><A NAME="ss3.11">3.11 perl's CGI library</A>
|
|
</H2>
|
|
|
|
<P>
|
|
<P>Installing perl's CGI part is the simpliest of the three steps.
|
|
Execute the following commands in the given order and everything
|
|
is done:
|
|
<P>
|
|
<PRE>
|
|
# perl Makefile.PL
|
|
# make
|
|
# make install
|
|
</PRE>
|
|
<P>
|
|
<P>Unlike the previous drivers this interface does not have a test
|
|
option (<CODE># make test</CODE>) whereas the other modules <EM>should</EM>
|
|
be tested in any case.
|
|
<P>A subdirectory with CGI example scripts is also created. You can
|
|
copy the contents of this directory into <CODE>/home/http/cgi-bin/</CODE>
|
|
and use the browser to experiment with the scripts.
|
|
<P>
|
|
<P>
|
|
<H2><A NAME="ss3.12">3.12 Installation Checklist</A>
|
|
</H2>
|
|
|
|
<P>We went through the following steps, in this order:
|
|
<OL>
|
|
<LI> Install Linux with networking support</LI>
|
|
<LI> Install a http server, e. g. Apache</LI>
|
|
<LI> Install a browser, e. g. Arena, lynx or Netscape</LI>
|
|
<LI> Install an SQL server, e. g. msql</LI>
|
|
<LI> Install a suitable perl SQL interface</LI>
|
|
<LI> Install the CGI files</LI>
|
|
</OL>
|
|
<P>Finally, you can do some clean-up. All source trees for msql and
|
|
the perl modules can be safely deleted (however, you should not
|
|
delete your archive files!) since the binaries and documentation
|
|
are now based in different directories.
|
|
<P>
|
|
<HR>
|
|
<A HREF="WWW-mSQL-HOWTO-4.html">Next</A>
|
|
<A HREF="WWW-mSQL-HOWTO-2.html">Previous</A>
|
|
<A HREF="WWW-mSQL-HOWTO.html#toc3">Contents</A>
|
|
</BODY>
|
|
</HTML>
|