DISCLAIMER:

 THIS SOFTWARE IS PROVIDED BY THE TOTAL KNOWLEDGE SOFTWARE ``AS IS''
 AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
 TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
 PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE TOTAL 
 KNOWLEDGE SOFTWARE OR ITS CONTRIBUTORS OR SUBSIDIARIES BE LIABLE
 FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, 
 OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT 
 OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
 OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
 WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF 
 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.


    This is a README file for mod_plsql -- Apache module, that allows 
you to access Oracle databases in a way Oracle Application Server 
does with it's PL/SQL cartridge.
    Also there is a modified version of SSI module, that allows inclusion
of PL/SQL code dirrectly into SSI documents.
	<!-- plsql block="BEGIN htp.print('I am BLOCK!!!');END;" --><BR>
executes PL/SQL block and outputs everything printed using HTP.PRINT 
to a web page in place of directive.

OR
	<!-- plsql proc="pkA.A" --><BR>
runs procedure A from package pkA in the same manner.

			To install module:

0. To use this stuff you need oracle client and OCI libraies installed on the
   macine running web server.
1. Copy mod_plsql.c and mod_plsql.h to <apache_source_root>/src/modules/extra 
   and (optionally) mod_include.c to <apache_source_root>/src/modules/standard
2. Patch your apache distribution with apache.diff.
    # cd apache-1.3.12/
    # patch -p1<../mod_plsql/apache.diff
   This patch was made against apache 1.3.12, but will probably
   work against any 1.3.x version. It adds a function nessasary
   for owa_sec.set_protection_realm.
3. Run
    # CFLAGS="-DDEBUG_PLSQL=0" \
	OPTIM="-O2" \
	LDFLAGS="-L$ORACLE_HOME/lib/ -L$ORACLE_HOME/rdbms/lib" \
	LIBS="$ORACLE_HOME/rdbms/lib/ssdbaed.o $ORACLE_HOME/rdbms/lib/kpudfo.o $ORACLE_HOME/lib/nautab.o $ORACLE_HOME/lib/naeet.o $ORACLE_HOME/lib/naect.o $ORACLE_HOME/lib/naedhs.o -lnetv2 -lnttcp -lnetwork -lncr -lclient -lvsn -lcommon -lgeneric -lmm -lnlsrtl3 -lcore4 -lnlsrtl3 -lcore4 -lnlsrtl3 -lnetv2 -lnttcp -lnetwork -lncr -lclient -lvsn -lcommon -lgeneric -lepc -lnlsrtl3 -lcore4 -lnlsrtl3 -lcore4 -lnlsrtl3 -lclient -lvsn -lcommon -lgeneric -lnlsrtl3 -lcore4 -lnlsrtl3 -lcore4 -lnlsrtl3 -lnsl -lm -ldl -lm -ldl -lnetv2 -lnttcp -lnetwork -lncr -lnetv2 -lnttcp -lnetwork -lncr -lnetv2 -lnttcp -lnetwork -lncr -lnetv2 -lnttcp -lnetwork -lncr -lnetv2 -lnttcp -lnetwork -lncr -lsql -lsql" \
	configure --prefix=/usr --activate-module=src/modules/extra/mod_plsql.c
	
	DEBUG_PLSQL = [0-9]
	
    Note:
	List of Oracle Client libraries might be different for your Oracle
	version. Hack something like $ORACLE_HOME/rdbms/demo/demo_rdbms.mk or 
	whatever make file was provided to you. What I did, was find the target
	for building regular applications for oracle, make similar one, but
	instead of actually buildng anything just echo all related variables.
	Then just "$ make .... <your_target_name>"
    Example:
	add to demo_rdbms.mk
	showvars:
		@echo LIBS=$(OCISHAREDLIBS) $(LIBS)
		@echo INCLUDES=$(INCLUDE)
		@echo LDFLAGS=$(LDFLAGS)
	and hen run
	  # make -f $ORACLE_HOME/rdbms/demo/demo_rdbms.mk showvars
	this will give you all needed settings
4. Run
    # make;make install
5. Run ioa.sql as system. It will create all nesasary packages and public
   synonyms for them. You can also hack *.sql scripts, if you want to grant
   access to these packages on per-user basis.
6. Configure apache.
    Put ScriptAlias-like dirrective to tell Apache  that any location
	matching sertain pattern should be used for connecting to database
	using data in mod_plsql condifuration file (by default named db.conf).
	DBAlias <URI-match> [config-file]
	DBAlias		-- name of directive. This has NOTHING to do with
			   SQL*Net database aliases.
	URI-match	-- pattern that matches URLs this dirrective applies to.
	config-file	-- file that contains database connection info.
			   Default is "db.conf"
			   If it starts with "/", it is considered to be an
			   absolute path, otherwise it is considered to be
			   relative to physical path, matching the URI in
			   question. If URI contains ~, username expansion is done.

	db.conf format is very simple:
		diective=value
	No extra spaces for now, must have empty line in the end
    These are configuration  dirrectives:
	    a. DBAl -- database (SQL*Net) alias to be used when connecting to Oracle
	    b. DBUser --...:)
	    c. DBPwd -- ...:)
		d. DBLogFile -- name of the log file, where owa_log.log_error writes.
		   can be either relative to location of db.conf, or absloute path.

	Example:
	    1. To make it work with user's dirs:
		  DBAlias ^/~(.*)/plsql
	    2. Then user can create $HOME/public_html/plsql/db.conf file
	      and start using database.
	      db.conf:
	      DBUser=xxx
	      DBPwd=yyy
	      DBAl=zzz
	!!!ALERT!!! See TODO#1 below.


TODO:
    This thing is in its early days, so there are too many things on this
    list, but some that come to mind right away:

-- Fix security bug: anyone with ablility to run CGI scripts
   can see database configuration data, since web server should have read
   access to configuration files, and CGIs, (to the extent of my knowledge)
   run under identity of webserver's user.
-- Some authentication mechanisms and something like owa_auth (Done, to degree I need it)...
-- Make it possible to create a dso module.
-- Add more OWA-like procedures. Especially to owa_util package
-- Add support for complex types as input to dirrectly called procedures.
-- Support for bind variables in mod_includes.
-- Make db.conf parser little bit more forgiving.
-- Fix security bug: check for procedure/package existace before
   executing it. Otherwice somone too smart can make it execute
   unwanted code (almost done).
-- Bring mod_includes up to date. Or at least check if it still works.

Done:
-- Fix support for POST method of passing parameters.
-- Fix overloaded procedures handling.
-- Supprot multiple parameters with same name (pass as PL/SQL tables)
-- Move actual configuration data to separate file.
-- Persistent/cached database connections.
-- Partially done: Some authentication mechanisms and something like owa_auth...
-- URI->file name translation handler. (For something like ScriptAliasing)

Author:
    Ilya A. Volynets, Total Knowledge Software.

Copyright:
/*********************************************************************\
 * Copyright (c) 2000-2001 Total Knowledge Software		     *
\*********************************************************************/
This code is based on mod_example.c from Apache group and thus 
following note also has to be present:

/* ====================================================================
 * Copyright (c) 1995-1999 The Apache Group.  All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer. 
 *
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in
 *    the documentation and/or other materials provided with the
 *    distribution.
 *
 * 3. All advertising materials mentioning features or use of this
 *    software must display the following acknowledgment:
 *    "This product includes software developed by the Apache Group
 *    for use in the Apache HTTP server project (http://www.apache.org/)."
 *
 * 4. The names "Apache Server" and "Apache Group" must not be used to
 *    endorse or promote products derived from this software without
 *    prior written permission. For written permission, please contact
 *    apache@apache.org.
 *
 * 5. Products derived from this software may not be called "Apache"
 *    nor may "Apache" appear in their names without prior written
 *    permission of the Apache Group.
 *
 * 6. Redistributions of any form whatsoever must retain the following
 *    acknowledgment:
 *    "This product includes software developed by the Apache Group
 *    for use in the Apache HTTP server project (http://www.apache.org/)."
 *
 * THIS SOFTWARE IS PROVIDED BY THE APACHE GROUP ``AS IS'' AND ANY
 * EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE APACHE GROUP OR
 * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
 * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 * OF THE POSSIBILITY OF SUCH DAMAGE.
 * ====================================================================
 *
 * This software consists of voluntary contributions made by many
 * individuals on behalf of the Apache Group and was originally based
 * on public domain software written at the National Center for
 * Supercomputing Applications, University of Illinois, Urbana-Champaign.
 * For more information on the Apache Group and the Apache HTTP server
 * project, please see <http://www.apache.org/>.
 *
 */


All mentioned trademarks are property of their respective owners.
