MOWI Version 2 Installation Instructions

Written by Andrew McAllister and Jon Ballenger

Copyright August 3, 1996


MOWI Version 2 is distributed as source code so that it can be used with a variety of systems. It should successfully compile and run on most (if not all) unix systems supported by Oracle. There is currently no version for Windows NT. But the port shouldn't be too hard, as long as the NT web server supports the cgi spec 1.1.

Installation of MOWI Version 2 is realatively simple. BUT, you should already be familiar with cgi scripting, httpd configuration, and compilation of C programs on your machine. Because this document cannot possibly cover all of the different web servers (httpd) it is assumed that you have already configured your web server to use cgi scripts. This document assumes you are using NCSA's http daemon, although there should be few changes for other free web servers.

To make MOWI version 2 run on your server, you will need...

The following instructions should serve to guide you through the installation process. It is important to follow the steps below in order. Some steps will be general in nature because of differences between various systems, others steps will be very precise and should be followed as closely as possible. It is assumed that you already have Oracle installed with the procedure option, that it is configured, and running and that you can run SQL*Plus from a prompt.

  1. Login to your machine with an account that uses Oracle. Make sure that you can run SQL*Plus, and that your path, etc include ORACLE_HOME. Exit SQL*Plus
  2. Create a directory for the MOWI source code etc. Unpack mowi2.tar by running the following system command: tar -xvf mowi2.tar
    (MOWI may be stored in a compressed state, (mowi2.tgz or mowi2.tar.Z) if so, then uncompress it first with one of the following commands: gunzip mowi2.tgz or uncompress mowi2.tar.Z)
  3. The tar file should produce several .c, .h, and .sql files and a documentation directory containing this document and others. Be sure to check the README file for the latest information on MOWI v2
  4. Run SQL*DBA or Server Manager or your tool of choice and login to Oracle as sys (or internal). Create a new user id specifically for running MOWI. Make sure that the user has tablespace quotas and has the following priviledges:
    Obviously your user should have drop privs as well.
    I created a user called "web" for my installation. It is also possible, but not recommended, to install MOWI in the scott/tiger account if you haven't already deleted it.
  5. Exit your DBA tool and login on your new "web" account using SQL*Plus. Make sure you start SQL*Plus from the MOWI source code directory
  6. Run the following commands in SQL*Plus (in this order):
    The ht.sql script loads all of the wrapper procedures and functions used in producing HTML output for web browsers.
    The mowi.sql script creates a table called sqlcommands and installs a web sql utility application that you can use to execute sql commands from the web.
    The htu.sql script loads some dynamic sql utilities that might be usefull for advanced web designers. THIS SCRIPT IS NOT YET COMPLETE
    The utils.sql script loads a web based sql prompt and utilites.THIS SCRIPT IS NOT YET COMPLETE
    The dictionary.sql script installs some data dictionary viewing pages (this script is optional).
    The sample.sql script installs a sample Pizza ordering application (this script is optional).
    While you load ht.sql, you should not see any error messages. If you do, make sure that your web user has the create and drop priviledges mentioned above and that you have the PL/SQL option installed in your database. During the mowi.sql load, you may see a couple error messages saying that a table or sequence does not exist. This is normal the first time you load mowi.sql; these are drop commands for the sqlcommands table and the sqlcommands_seq sequence.
  7. Verify that the ht.sql script ran correctly by typing in the following lines while still in SQL*Plus:
    You should see Hello World appear.
    Exit SQL*Plus
  8. Now it's time to customize the mowi cgi script for your machine. Open the mowi script with your favorite text editor. Set the following parameters according to your Oracle environment. If you do not know what these are, talk to your database administrator.
    Save your changes and then do the same steps for the "testme" script. Leave the DEBUG setting on POST in the testme script. Save your scripts and exit your text editor
  9. Make sure that your scripts are executable (ls -l scriptnamehere). If not, then change their mode (chmod 755 scriptnamehere)
  10. Decide whether you want to run MOWI in standalone or daemon mode. For now we'll asume you want to run in standalone mode. There are also instructions for daemon mode.
  11. Copy the oracle.mk file from $ORACLE_HOME/rdbms/lib to your mowi source directory (cp $ORACLE_HOME/rdbms/lib/oracle.mk .) The oracle.mk file is specific to each Oracle platform so I don't include it with MOWI. It is used to link your Oracle programs when Oracle is installed on your machine. If you don't have a copy of oracle.mk, then look really hard for it. It is important. You will need it to continue.
  12. Combine the oracle.mk file and the mowi.mk file by copying the entire contents of mowi.mk to the end of the oracle.mk file; save the file as "Makefile". You can use your text editor or the following unix command:
    cat oracle.mk mowi.mk > Makefile
    The new Makefile should contain lots and lots of stuff with the mowi specific parts at the end.
  13. Now it's time to configure the mowi source code... Open mowicfg.h in your text editor
  14. Edit the defines according to your installation. The mowicfg.h file is used to switch mowi from standalone to daemon modes and it turns debugging on and off. Also, if you run an older version of Oracle (like 7.1.5) you'll need to uncomment the OLD_ORACLE_OCI line. If you have a stupid version of unix without the strncase and strcase functions in the standard libraries, be sure to uncomment the lines for them as well.
  15. Save the mowicfg.h file and get ready to compile...
  16. At a unix prompt type:
    make mowistub
    DO NOT TYPE make all by itself! You could end up re-making all of Oracle for all I know. (I've tried this on my machine with no problems, but don't try this on yours)
    This should produce a bunch of lines with all kinds of linking info etc
    Obviously this is where most everything could go wrong. Keep the following points in mind.
  17. Once mowistub (notice the spelling and case) is compiled you can run the testme script. Run it like: ./testme
    You should get three lines of output. The first will say Content-type: text/html
    The next line wil be blank
    The final line should say "Hello"
  18. OK, almost finished. Assuming the testme script worked you'll need to move the mowi script and the mowistub program into your web server's cgi directory. For NCSA's httpd server the default directory is /usr/local/etc/httpd/cgi-bin
    Of course, the location of this directory will be dependent on what web server you use as well as how and where it is setup.
    I actually have three cgi directories set up with my web server. One is "cgi-bin" and it has very little in it. Another is "webacle" where I keep public access scripts etc. The third is "oracle". This last directory is protected by my web server from people outside my domain because this is the main entrance to my database from the web.
  19. The final step is to make sure that the scripts run from the web.
    The easiest way to test this is to type the following url in your browser (everything up until the "/mowi..." portion of the url will be machine dependent so make sure you substitute your machine and cgi directory for the one in the url)
    http://yourwww.address.here/cgi-bin/mowi/htp.p?cbuf=Hello+World
    Possible errors here are 404 not found or permissions errors.
  20. If you are getting a 403 Forbidden error then it is likely that the web server doesn't have permissions to execute the mowi script or the mowistub. This happens when the web server is set up to run as a "nobody" user and the mowi script doesn't have the world read and execute flags set. Rather than setting those flags, I suggest that you find out which userid the web server runs under and change the owner of the mowi script and mowistub to that user. If you set the world read and execute flags, then anyone on your system can see the userid and password of your web account. By setting the owner to the same as the web server and making sure that he permissions flags on the mowi and mowistub files are r-xr-x--- then you should be OK. Consult with your system administrator for more details on local security issues.
  21. Once you are up and running, take a look at the sample application included with MOWI.
    The easiest way to test this is to type the following url in your browser (everything up until the "/mowi..." portion of the url will be machine dependent so make sure you substitute your machine and cgi directory for the one in the url)
    http://yourwww.address.here/cgi-bin/mowi/sample.intro

Configuring MOWI in Daemon Mode

  1. First thing is to run through the first 7 steps of the stand alone configuration instructions.
  2. Now it's time to customize the mowi cgi script in daemon mode for your machine. Open the mowi script with your favorite text editor. Set the following parameters according to your Oracle environment. If you do not know what these are, talk to your database administrator.
    Save your changes and then do the same steps for the "testme" script. Leave the DEBUG setting on POST in the testme script.
    Here's the extra step for daemon mode: change all the references to "mowistub" in the mowi and testme scripts to read "mowiStub". Notice the case of the letter "S". Make sure you use "mowiStub". Save your scripts and exit your text editor
  3. Same as in standalone mode...Make sure that your scripts are executable (ls -l scriptnamehere). If not, then change their mode (chmod 755 scriptnamehere)
  4. Same as in standalone mode...Copy the oracle.mk file from $ORACLE_HOME/rdbms/lib to your mowi source directory (cp $ORACLE_HOME/rdbms/lib/oracle.mk .) The oracle.mk file is specific to each Oracle platform so I don't include it with MOWI. It is used to link your Oracle programs when Oracle is installed on your machine. If you don't have a copy of oracle.mk, then look really hard for it. It is important. You will need it to continue.
  5. Same as in standalone mode...Combine the oracle.mk file and the mowi.mk file by copying the entire contents of mowi.mk to the end of the oracle.mk file; save the file as "Makefile". You can use your text editor or the following unix command:
    cat oracle.mk mowi.mk > Makefile
    The new Makefile should contain lots and lots of stuff with the mowi specific parts at the end.
  6. Now it's time to configure the mowi source code... Open mowicfg.h in your text editor
  7. Edit the mowicfg.h file for daemon mode. Uncomment the MOWIDAEMON define statement (make sure that the "#" sign is the first character on the line. Then go down a few screens to the daemon mode options section... Also, if you run an older version of Oracle (like 7.1.5) you'll need to uncomment the OLD_ORACLE_OCI line. If you have a stupid version of unix without the strncase and strcase functions in the standard libraries, be sure to uncomment the lines for them as well.
  8. Save the mowicfg.h file and get ready to compile...
  9. At a unix prompt type:
    make mowidaemon
    DO NOT TYPE make all by itself! You could end up re-making all of Oracle for all I know. (I've tried this on my machine with no problems, but don't try this on yours)
    This should produce a bunch of lines with all kinds of linking info etc
    Obviously this is where most everything could go wrong. Keep the following points in mind.
  10. Edit the mowid.cfg file set the number of daemon process you want and the default userid and password (I suggest the web account you created above) I also suggest using a minimum of 2 deamons for reasonable efficiency. The log options should be obvious. The minimum log level is 0 the max is 9. the higher the number the bigger and faster the logfile will grow. If you are going to run at level 9 I suggest setting the file to a partition with lots of space
  11. Once mowiStub (notice the spelling and case) and mowid are compiled you must start the daemon before running the test me script.
    start the daemon by typing: mowid startup
    Then run the testme script. Run it like: ./testme
    You should get three lines of output. The first will say Content-type: text/html
    The next line will be blank
    The final line should say "Hello"
  12. OK, almost finished. Assuming the testme script worked you'll need to move the mowi script and the mowiStub (notice the case of the "S") program into your web server's cgi directory. For NCSA's httpd server the default directory is /usr/local/etc/httpd/cgi-bin
    Of course, the location of this directory will be dependent on what web server you use as well has how and where it is setup.
  13. The final step is to make sure that the scripts run from the web.
    The easiest way to test this is to type the following url in your browser (everything up until the "/mowi..." portion of the url will be machine dependent so make sure you substitute your machine and cgi directory for the one in the url)
    http://yourwww.address.here/cgi-bin/mowi/htp.p?cbuf=Hello+World
    Possible errors here are 404 not found or permissions errors.
  14. If you are getting a 403 Forbidden error then it is likely that the web server doesn't have permissions to execute the mowi script or the mowistub. This happens when the web server is set up to run as a "nobody" user and the mowi script doesn't have the world read and execute flags set. Rather than setting those flags, I suggest that you find out which userid the web server runs under and change the owner of the mowi script and mowistub to that user. If you set the world read and execute flags, then anyone on your system can see the userid and password of your web account. By setting the owner to the same as the web server and making sure that he permissions flags on the mowi and mowistub files are r-xr-x--- then you should be OK. Consult with your system administrator for more details on local security issues.
  15. If you get an error like
    mowiStub: I/O problem with control file: /tmp/mowid.ctl
    Then the mowiStub program can't find the mowid control file and therefore doesn't know how to communicate with mowid. Possible reasons for this error are:
  16. Once you are up and running, take a look at the sample application included with MOWI.
    The easiest way to test this is to type the following url in your browser (everything up until the "/mowi..." portion of the url will be machine dependent so make sure you substitute your machine and cgi directory for the one in the url)
    http://yourwww.address.here/cgi-bin/mowi/sample.intro

MOWI hase been tested on the following machines: