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. It 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="-DUSE_PLSQL_SSI" \
	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
	
    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>"
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.
    There are currently two ways to configure mod_plsql
    1. Put database alias user name & password dirrectly into .htaccess or
    httpd.conf
		    OR
    2. Put it into separate configuration file and use ScriptAlias -like
    dirrective to tell that any location matching sertain pattern should
    be used for connecting to database using data in that file.
       This second way is slightly more flexible, and in future may become
    more secure.
    First way to do configuration is as follows.
        There are three configuration  dirrectives:
	    a. DBAl -- database alias to be used when connecting to Oracle
	    b. DBUser --...:)
	    c. DBPwd -- ...:)
	You can place them in access.conf in <Location> section for example.
        Also you must do something like this to enable /plsql/Pack.Proc?... 
	behaviour :
	    <Location /my/plsql>
	        DBUser me
	        DBPwd passwd
	        SetHandler plsql
	    </Location>
	OR
	    <Location ~ "/~(.)*/plsql/(.)*">
		SetHandler plsql
	    </Localtion>
	    to make plsql procedures available to any user.
	    then user must set his database access information in .htaccess

    Second way of doing this is:
        use special directive in httpd.conf.
	format is:
		DBAlias <URI-match> [config-file]
	DBAlias		-- name of directive, it 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.
	config file format is very simple: it just contains those same directives
	from method #1. One per line, extra spaces can cause trouble, empty line in the end.
	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
	      
	!!!ALERT!!! See TODO#12 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:
    
?!?! 0. Rewrite whole thing in  C++.

1. 
2. Some authentication mechanisms and something like owa_auth...
3. 
4. 
5. Make it dynamicaly linkable.
6. Add more OWA-like procedures. Especially to owa_util package
7. Add support for complex types as input to dirrectly called procedures.
8.
10. Support for bind variables in mod_includes.
11.
12. 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.
13. Make db.conf parser little bit more forgiving.
14. Fix security bug: check for procedure existace before executing it.
    Otherwice somone too smart can make it execute unwanted code.
15. Bring mod_include up to date. Or at least check if i still works.

Done:
4. Fix support for POST method of passing parameters.
8. Fix overloaded procedures handling.
11. Supprot multiple parameters with same name (pass as PL/SQL tables)
3. Move actual configuration data to separate file.
1. Persistent/cached database connections.
2. Partially done: Some authentication mechanisms and something like owa_auth...
9. URI->file name translation handler. (For something like ScriptAliasing)
Author:
    Ilya A. Volynets, Total Knowledge Software.

Copyright:
/*********************************************************************\
 * Copyright (c) 2000-2001 Total Knowledge Software		     *
\*********************************************************************/

/* ====================================================================
 * 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.