Next: Writing Form Definition Files Up: WDB Installation and Users Previous: Introduction
Installation
To install WDB is quite easy - but you need a few other products like an HTTP server, a database system, and an interface between Perl an your database system. (Installing these are actually the hard part).
To make things a little bit more complicated, WDB supports several different database systems and the exact installation procedures varies slightly depending on which database system you are going to use. The following are therefore generic instructions, that are common for all database systems. Support of the different databases are implemetet through a sperate database interface module (DBI) for each database system. Specific details, and exceptions are documentet in the notes for the individual WDB DBI's.
At the time of writing this document three database systems are supportet : Sybase, Informix, Oracle and mSQL. Notes for these interfaces are included in the Appendix.
Installing Perl
WDB is written in Perl, but we need to add some commands to your Perl interpreter to enable it to talk to your database. Fortunately packages with these commands are already available on the Internet. There are sybperl for Sybase, oraperl for Oracle, isqlperl for Informix, etc.. These are all extremely usefull packages written by different people, with different needs, and different ideas. Unfortunately this means that they all use different commands to do the same things.....
To allow WDB to talk to all of them, it uses a separate database interface module for each database system, which is simply an encapsulation of the real database commands. All you have to do is to install Perl - with the commands for your database - and tell WDB which interface to use. If you do have a set of perl commands to access your database, but no WDB interface to them, you can write your own. See the appendix on porting to different databases for more details on this.
Before rushing out and grabbing the neareast version of the Perl source, make sure you get the right version. See the WDB DBI for your database system for details.
When you have downloaded and installed this : Make sure it works ! With the database interface to perl there are normaly included a few examples. Try to run these. (This might save you some headache later ...)
In the following when Perl or the Perl executable is mentioned it is always the version of the Perl executable which includes the database extensions that is meant.
Installing an HTTP Server
To be able to interface to the World Wide Web you need a server that understands Hyper Text Transfer Protocol (HTTP). There are several of these server programs around. I use NCSA's HTTP server and have been happy with it, but any server should do, as long as it supports CGI scripts.
CGI is the Common Gateway Interface standard for how HTTP servers communicate with programs on the server. As these programs are started on request from the clients by simply referencing them in a URL like any other HTTP request, the server has to have some way of knowing when to send a file back to the client, and when to execute it and send the result back instead. This is normaly done by configuring the server to treat all files in a specified directory as CGI programs. There are a few other methods, but in the following I will assume that you have configured your HTTP server to use the /cgi-bin directory for this.
Online hypertext documentation including installation instructions, feature list, demonstration, etc. for the NCSA http server is available from :
http://hoohoo.ncsa.uiuc.edu/
Installing WDB ...
Download the WDB distribution, and un-tar it. This will give you a set of sub-directories that needs to be installed by moving them to the appropriate places.
- cgi-bin/
-
In this directory you will find the wdb script itself and a
script called comments, which you can use to allow your
users to send comments back to you from the WDB forms (and any
other HTML page). Move these files to your HTTP servers cgi-bin
directory.
- bin/
-
This directory contains several versions of the mkfdf script,
one for each database system. See the notes on the WDB DBI for your
database system on which script to use. Rename this script to
mkfdf.
You need to modify the first line of the script to point to your
perl executable. Then move the mkfdf script to a
directory in your PATH - or modify your PATH to point to this
directory.
- conf/
-
This directory contains configuration files for WDB - only the
user-id of the HTTP server process needs read access to these.
( - and your database password will be in one of these
files, so make sure you protect them adequately ! ) I suggest
to move them to
~http/wdb/(if http is the user running the HTTP server). - html/
-
Move these files to a directory in your WWW tree. (For example
/wdb/ in the document root directory.)
- man/
-
Manual pages. You can install them with your other man pages if
you want.
- perl-lib
-
This directory contains cgi-lib.pl. This is a copy of
Steven E. Brenner's Perl Routines to Manipulate CGI input, if
you haven't got it already please install it in you perl
library.
You will also need to create a directory to keep the FDF files. This directory does not have to be in the WWW tree, but it should be readable by the HTTP process.
Because the wdb script is started by the HTTP server, and we have little control over how it is started, and with what environment, you have to edit the first two lines of the wdb script :
#!/usr/server/arc/bin/sybperl
$CONFIG_DIR = '/usr/local/etc/httpd/wdb';
Change the first line to point to your Perl interpreter that you installed earlier. The second line tells WDB where to find your local configuration files. Change this to the directory where you installed these. Also, make sure that wdb is executable
chmod +x wdb
Now update the configuration file.
Configuring WDB
To configure WDB to your local environment and preferences you have to edit the wdb.conf file in the conf directory (or wherever you copied it to).
The WDB configuration file contains the following configuration parameters :
- $formdir
-
This is the directory where the form definition files are located.
This directory doesn't need to be in the WWW document tree, but is
should be readable by the user-id of the HTTP server. (this applies to
all files !)
- $user
-
The database user to use for queries.
- $pswd
-
The password for the database user. (Make sure that the wdb.conf
file are not readable by anybody who shouldn't ! )
- $server
-
The database server name. Depending on what database system you are
using, you might not need this and/or the $user and $pswd
parameters. In that case simply set them to the empty string ( "" ),
but keep them defined.
- $MAIN_MENU
-
This should be set to a URL pointing to the main menu ("homepage")
for your WDB pages with links to all the query forms that you
create. This will be used for the 'Home' button in the WDB
screens. If you don't like this, simply remove the definition of
$MAIN_MENU.
- $WDB_HTML
-
Base URL to the directory where you installed the files in html/
- $IMAGEDIR
-
Base URL to the directory where the GIF buttons (html/*_btn.gif) are
installed. (Normally = $WDB_HTML)
- $QUERY_HELP
-
This should be the URL for the
html/wdb_query_help.html file.
(Normally = $WDB_HTML/wdb_query_help.html ).
- $rowcount
-
Maximum number of rows returned by a query. (The user has the option
to change this )
- $MAXROWCOUNT
-
Maximum allowed value for $rowcount. (The user can't exceed this)
- $DATEFORMAT
-
This is an optional configuration parameter to set the
dateformat. The format used is the same as for the Sybase SQL
command 'set dateformat', please refer to you Sybase manual for
details. (ex.: $DATEFORMAT = "dmy"; for European
date format Day/Month/Year). For other database systems than
Sybase this parameter might be ignored or defined differently. See
the appendix on the database interface to your database system.
- $NULL_VALUE
-
The value to display for NULL fields (Normally = "")
- %SPEC_NULL
-
This is an associative array of field types and special values that are
to be interpreted as NULL. For example :
%SPEC_NULL = ( 'int', -2147483647, 'smallint', -32768, );This tells WDB to interpret the value of -2147483647 (the smallest possible value) in an int field as NULL. If you don't need this, simply remove the definition of %SPEC_NULL from the configuration file. - $DBI_FILE
-
This is the name of the DBI (DataBase Interface) file. This file
defines the interface between WDB and the database commands in your
Perl interpreter. For example a file called 'syb_dbi.pl' is
supplied with WDB, which is the interface to the sybperl
Sybase commands. See the appendix on the database interface to your
database system, to see what DBI file to use.
- $debug
-
Set this variable to enable extra debug output in the $debugfile
and at the end of the HTML output. If you don't want this (probably
not!) simply remove the definition of $debug. However, enabling
debug, can be useful if you are in doubt what SQL select statement
is being used by WDB, or if you start adding advanced Perl commands to
the FDF files, or perhaps even start enhancing the WDB script itself.
- $debugfile
-
File to write debug output to when debug is enabled.
- $helptext
-
This is a standard text that is displayed when an error occurs.
You might want to change the contact person etc.
- sub html_tail
-
This is a small Perl subroutine that print the HTML 'tail' at the
end of each HTML page generated by WDB. Please change the default
email address of the person to send comments to, and please keep the
link to the WDB homepage ( - or add it to one of your other pages,
so I get some credit .... :-)
The comments script is included in the WDB distribution in the cgi-bin/ directory. If you want to use this feature please install your own local copy of the script.
Next: Writing Form Definition Files Up: WDB Installation and Users Previous: Introduction Copyright © 1996 Bo Frese Rasmussen
Last update: Sun Mar 10 22:57:31 1996
| ||||
| ||||