Firstly, please read the README file! It's important that you know how these files are distributed, and where you can find out more information. Overview ======== Chapter 11 of "Theory and Practice of Relational Databases", (TandP) contains a case study that attempts to bring together the database theory covered throughout the book, into a worked example of an implementation. It's not intended to be a fully featured example of all the best programming practices, but aims to help enforce the important concepts, and help the student move forward in their understanding of how databases fit in to a working system. Assumptions =========== You're assumed to be comfortable with Unix if you're following this by yourself. If you're not, you may have difficulties getting things to work (but it's definately not impossible! You might learn a lot this way!). Don't be afraid to ask local staff and support groups for help if there are things you don't understand, or don't have permission to do in your environment. If you're studying this as part of a database course, the local staff may have set things up for you to get going without any of the grief. If this is the case, PLEASE consult your local documentation and staff in preference to this document. We've tried hard to make these instructions useful, and point out common problems and pitfalls. However, we couldn't make these instructions a cook-book step by step guide for all because, unfortunately, every site and machine is different, and what works in one case will not work in others. Therefore, we've given as much information as we can, and hope that you can get things going with the guidelines included. Contents ======== INSTALL - This file README - The first file to read! COPYRIGHT - The GNU General Public License. Read it to understand the license under which these files are distributed. sql/ - This directory contains the SQL needed to create the database. htdocs/ - Static HTML that can be used to test the webserver is working. cgi-bin/ - The examples from the book. Each sub-directory contains a README file which outlines which file is what. Consult that for more information on a particular file. Installation ============ IMPORTANT!!!! These files will probably NOT WORK without some minor modification, as your database setup is very likely to be different. Inspect each file first, paying particularly close attention to the DBI->connect call(s), and where appropriate changing the DBD module, database name, host name, passwords etc. - Consult local staff/documentation if you have difficulties. Apache ------ You need a working Apache installation where YOU can place files and execute CGI scripts (ie. perl). Often this is through a public_html directory, but do make sure that you can run arbitrary scripts, as this is often disabled by system administrators to reduce the risk of abuse by users. A common problem is execute permissions are not set on the directory, and your browser displays the script code rather than execute it! Also, make sure you know where the log files are going, as many error messages may be sent to the error log rather than the web browser or your screen. Perl ---- Perl needs to be installed. The example scripts expect to find it as /usr/bin/perl (the usual place on Linux), but it can often be found as /usr/local/bin/perl. Change the scripts as appropriate. DBI/DBD modules - Check they're installed by inspecting the output from running "perldoc perllocal", or ask your Systems administrator nicely if you're not sure. DBD modules are the Database specific component (DBI provides an abstraction layer to make code more portable). The examples included here assume you're using MySQL, but you may be using Oracle, Sybase or some other. Make sure you've changed the connect call appropriately! Do make sure the scripts are executable at the Unix level as well. Run "chmod +x *.pl" to set the execute bit for all users (not just you - apache needs to be able to run it too!). MySQL/DBMS ---------- If you have installed or got access to MySQL, or have been given access to a different DBMS, you'll need to create the SQL tables for the examples. These are in sql/create-tables.sql - and should run without problems on most DBMS's (check the command termination command is correct - a semi-colon (;) works fine in many. The script "test.pl" will test your DB connection, and "test-apache.pl", will check it as a CGI script under apache. Check that your database user id/password is entered correctly in the scripts. And make sure that you don't use an important password! Version: $Id: INSTALL,v 1.1 2001/06/30 15:45:23 rleyton Exp $