next up previous external
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 and 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 implemented through a separate database interface module (DBI) for each database system. Specific details, and exceptions are documented in the notes for the individual WDB DBI's.

At the time of writing this document four database systems are supported : Sybase, Informix, Oracle and mSQL. Notes for these interfaces are included in the Appendix.

Installing Perl

NEW DBI/DBD Support
Past versions of WDB supported the now-elderly version 4 of Perl. Database extensions built with Perl 4 result in a stand-alone version of Perl dedicated to a single database. If you wanted to use WDB with more than one database, you were required to build more than one version of enhanced Perl, and keep multiple copies of WDB cluttering up your system. No more.

WDB now uses Perl 5 and the DBI/DBD method of accessing databases from Perl 5. More information about DBI and the individual DBD database modules can be found at:

http://www.hermetica.com/technologia/perl/DBI/index.html.
Note:the use of Perl 5 and DBI/DBD means WDB no longer supports the standalone versions of Perl: sybperl, oraperl, isqlperl, or MsqlPerl. The performance, features, and convenience of the new method far outweighs the inconvenience of changing software.

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 DBD::Sybase for Sybase, DBD::Oracle for Oracle, DBD::Informix for Informix, and DBD::mSQL for Mini SQL. These are all extremely useful 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, but the DBI/DBD development community is trying to make the DBD modules as similar as possible.

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 nearest version of the Perl source, make sure you get the right version. If you want to use mod_perl, you will need Perl 5.004 or better. It's generally best to get the latest release of Perl anyway. There is also the possibility that the DBD module you use will require a particular version of Perl. 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 normally included a few examples. Try to run these. (This might save you some headaches 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 normally 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/

NEW mod_perl Support
This new version of WDB runs just fine under CGI, but if you need better performance and hate the overhead of using Perl as a CGI language, WDB has been converted to use the Apache module mod_perl. More information about the Apache Web server and mod_perl is available from:

http://www.apache.org/
http://www.osf.org/~dougm/apache/

Put simply, mod_perl allows you to compile a Perl interpreter into the Apache Web server process, so your Perl programs bypass CGI and are interpreted directly by the Web server. Once interpreted, your Perl programs stay in memory to process future requests. This can greatly increase performance and reduce the load on your Web server machine, plus your Perl programs can access the Apache API to do more than any CGI program can do.

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).

NEW This directory contains cgi-lib.pl. This is a copy of Steven E. Brenner's Perl Routines to Manipulate CGI input. The version included with WDB has been modified to work with mod_perl, and WDB requires this version whether you use mod_perl or not. You can rename it to something else, install it in the Perl library, and edit both wdb and mkfdf to use the new name, or you can use Perl's use lib command to specify where this modified version of cgi-lib.pl is located. Or, if you have no other programs that use cgi-lib.pl, just install this version in the Perl library and all of your future Perl programs can use it and be mod_perl compatible.

html/
Move these files to a directory in your WWW tree. (For example /wdb/ in the document root directory.) The HTML files in this directory are the online documentation for WDB (which you are reading now to get this information :).

man/
Manual pages. You can install them with your other man pages if you want.

NEW mark_lines/
This directory contains a program for adding line numbers to the WDB program. If you make changes to the WDB executable, run the mark_lines program in this directory to renumber the marked lines in WDB. This is essential to get correct debugging information and line numbers in Perl error messages.

NEW sample_fdf/
This directory contains a collection of sample FDFs to show you how to use some of the advanced capabilities of WDB. Eventually, a complete database and tutorials based on these examples will be included with the WDB distribution.

Note:You will need to create two more directories. One is needed 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. Once you create the fdf directory, set the $FORMDIR variable in the wdb.conf file equal to that path.

The other directory for you to create is needed for the WDB Web page counters, if you decide to use them. Each Web page with a counter needs a file to hold the count of visitors. The path to this file is specified in the VISITOR_COUNT_FILE form variable. You can scatter your counter files all over the hard drive if you want to, but it's a good idea to keep them in one place for neatness' sake.

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 two lines of the wdb script:

    #!/usr/local/bin/perl 

If you are running WDB under CGI, change the first line to point to your Perl interpreter that you installed earlier. If you are running under mod_perl, delete the first line altogether.

Next, locate the $CONFIG_DIR variable and set it to the directory where you installed the file wdb.conf, detailed in the following section. 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 configuration parameters at the top of the wdb.conf file in the conf/ directory. All of these variables must exist because of changes made to run under mod_perl, so do not remove the ones you don't use. Otherwise you will get errors about undeclared variables.

$WDB
The path used by the Web server to locate where you've put the WDB program. Usually, $ENV{'SCRIPT_NAME'} can be used with no problems, but if you have a strange server, you may need to add your path manually. It's a good idea to do it just in case.

$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 it should be readable by the user-id of the HTTP server. (This applies to all files used by WDB!)

$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.

NEWIf you prefer to set a different Home Page for an FDF, you can now override $MAIN_MENU in the FDF. See the Form Definition File Syntax page for more details.

$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)

NEW $HELP_BUTTON

Path to the image to use as the help button.

NEW $HOME_BUTTON

Path to the image to use as the home button.

NEW $QUERY_BUTTON

Path to the image to use as the query button.

$QUERY_HELP
This should be the URL for the html/wdb_query_help.html file. (Normally = $WDB_HTML/wdb_query_help.html ).

$USER
The database user to use for queries. Some databases require this, others do not. If yours does not, leave it blank.

$PSWD
The password for the database user. Some databases require this, others do not. If yours does not, leave it blank. (Make sure your Web server does not allow program files to be read by anybody who shouldn't! If a hacker gets the username and password, he/she might wreck your database!)

$SERVER
The database server machine 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.

$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 'msql_dbi.pl' is supplied with WDB, which is the interface to the DBD::mSQL Mini SQL commands. See the appendix on the database interface to your database system, to see what DBI file to use.

$MAXROWCOUNT
Maximum allowed value for $ROWCOUNT. (The user can't exceed this)

$ROWCOUNT
Maximum number of rows returned by a query. (The user has the option to change this )

$DATEFORMAT
This is an optional configuration parameter to set the date format. The format used is the same as for the Sybase SQL command 'set date format', please refer to your 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 = "")

NEW @IP_IGNORE

A list of IP addresses for the NEW Web page counter to ignore. This allows you to ignore the WDB administrator or anyone else that you don't want counted so the counter gives a more accurate count of Web page visitors. For example :
    @IP_IGNORE     = qw(123.123.123.123 321.321.321.321);

%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.

NEW $SECURE_WDB
The path to a password protected directory and copy or symlink to WDB. If a user has access to WDB through this path, they can perform update and delete actions. If you don't care about security, just set this to the standard path to WDB and update and delete will work fine for everyone. Just don't be upset when a Web hacker whacks your database.

$debug
Set this variable to enable extra debug output in the HTML output. If you don't want this (probably not!) simply set $debug equal to 0. 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.

Be advised the debug output can be quite messy and you may prefer to add the lines $debug = 1 and $debug = 0 around the specific section of code you are debugging instead of wading through all of the debug output.

$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 prints 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 .... :-)

NEW This can now be turned off in the FDF if some WDB users don't want it on their pages for some reason. See the Form Definition File Syntax page for more details.


next up previous external
Next: Writing Form Definition Files Up: WDB Installation and Users Previous: Introduction

Copyright © 1996 Bo Frese Rasmussen and Jeff Rowe