Apache PL/SQL Gateway Module

mod_owa is an open-source implementation of the PL/SQL gateway available in Oracle's OAS/OWS product. The gateway is able to call PL/SQL procedures in a manner similar to the way Java servlets are supported, with the Oracle database acting as the "virtual machine". Arguments are marshalled through SQL*Net to your procedures, and responses returned the same way. HTTP header elements are made available via a CGI-like mechanism.

The original version of mod_owa was written by Alvydas Gelzinis (alvydas@kada.lt) and Oksana Kulikova (oksana@kada.lt). My version is a rewrite, adding functionality omitted by the original version, fixing several bugs, and adding some performance improvements. The motivation for this was to provide access to OWA-based content through the Apache web server at a time when Oracle lacked an Apache strategy. Edward Jiang (Edward.Jiang@oracle.com) contributed the file caching and range transfer support.

Oracle has now released a Java version of the PL/SQL gateway, as part of ORDS: http://www.oracle.com/technetwork/developer-tools/rest-data-services/overview/index.html

This servlet is professional-quality, well-tested, and officially supported. Although it's not open source, it's freely downloadable and should work in your choice of Java application server. It is 100% compliant with the gateway spec (including the NLS/multi-byte support and document upload/download) and supports additional functionality needed by Apex. I encourage anyone considering the mod_owa gateway to look at this alternative.

These are my notes from installing and configuring ORDS, in case they are of help to you: ords_setup.htm.

Oracle has its own Apache PL/SQL gateway module, modplsql, but this module is being desupported. Though functionally similar, modplsql and mod_owa share no source code. modplsql and the scripts for the database (PL/SQL) side of the gateway are bundled with the Oracle database, including the XE version, and with the Oracle application server. The modplsql code, absent the Apache linkage, is also now built directly into the database listener, allowing you to run PL/SQL applications directly against the database without Apache.

Please note that mod_owa doesn't support numerous features that have been added to modplsql, and therefore doesn't support some Oracle PL/SQL applications, likely including Apex. A particular area of incompatibility is file uploading and downloading, as documented in later sections. Some users have, for various reasons, been required to avoid using the Oracle HTTP listener (Oracle's Apache) and the Oracle application server. Note that even in such cases, it should be possible to use mod_proxy to direct PL/SQL traffic from your Apache site into the built-in (EPG) listener. This article may be of help in configuring the EPG, either for direct use instead of Apache, or as a back-end to a proxying Apache: http://www.oracle-base.com/articles/10g/dbms_epg_10gR2.php

It is assumed that you've already obtained and installed the OWA PL/SQL procedures supplied by Oracle with OAS, iAS, Portal, and several other products. That code has not been approved for open-source license so I can't make it available here. You can, of course, implement your own OWA work-alike. An incomplete sample of one is included in the test scripts, in file modowa.sql.

The module requires an Oracle client installation to run. Specificially, it requires a so-called ORACLE_HOME area to be installed, complete with the Required Support Files (RSF) including the OCI client library.

Versions of the module exist for Apache 2.4, 2.2, and 2.0. The older 1.3 version is deprecated. This documentation is oriented towards the 2.x versions, though 1.3 is discussed for the sake of those with older releases. The code was designed for Oracle 8.1.x, and is currently built with the Oracle 11g client libraries. It contains calls that won't be satisfied by the oldest 8.0 versions of the client libraries.

A few new features have been added that have not been well-tested and that may not be generally useful. Use them with caution. In particular, the new OwaAlternate modes supporting request timing and logging are very specialized to the user who requested the feature, and may require you to change owalog.c if you want to use it. The support for WebDB file upload and download and Apex-compatible PL/SQL calling modes is also experimental.

If you have problems or questions, you can e-mail me at Doug.McMahon@oracle.com .

Note: this version of mod_owa breaks backward compatibility with some older versions. It has two changes that are not compatible (by default) with older versions. In both cases, use of directives can make mod_owa behave in a compatible manner.

1. Admin functions restricted by default
   In older releases, mod_owa had the administrative/control functions enabled by default, requiring the use of the OwaAdmin directive to explicitly disable or restrict them. This is now reversed; the functions are disabled by default, requiring the use of OwaAdmin to explicitly enable/restrict them. I expect little problem from this; few people are likely to be using this feature, and those that are most likely are already setting OwaAdmin.
2. Query string arguments for POST requests
   The original Gelzinis/Kulikova code folded both GET and POST requests down to a single code path for procedure argument processing. The argument string for GET was taken from the URL's query string, while for POST it was taken from the request body. I continued this in the initial rewrite, and it's been that way ever since. Unfortunately, it's wrong; POST requests can also have URL query string arguments. I've now fixed this by including any URL query string arguments with the request body arguments - they're processed first, just ahead of the request body (in case argument order matters to your code). I decided I did not want mod_owa to have the incorrect behavior by default, so I've made this the default. It can be disabled, and the old incorrect behavior restored, by using the new NOMERGE argument to the OwaAlternate directive:
   

   OwaAlternate  OWA  NOMERGE

mod_owa is packed in two separate bundles, windows_all.zip for the Windows platform, and unix_all.tgz for Linux and other Unix platforms. Both bundles have files in a similar directory structure, described below. Note that any ASCII-based file (e.g. source files and scripts) will be in the carriage-control format native to the platform (i.e. with newline separators for Unixes and carriage-return + line-feed for Windows).

Note: the name of the module has been changed from ApacheModuleOwa.dll to mod_owa.dll. You can rename the file if you like; otherwise, be sure your configuration file's LoadModule command matches the new name.

I am no longer able to supply binaries for HP/UX, AIX, or Solaris, because I no longer have access to machines and environments where I can do the builds. Users that need support for these should rebuild the code from source using the makefiles supplied in the unix_all.tgz as a starting point.

Special note: posix threads, httpd, and libclntsh.so

After upgrading to 8.1.6 and to RedHat 6.1, I discovered that mod_owa.so would no longer load into httpd. The httpd simply fails to start, without issuing any useful error message. I believe this problem is due to the fact that Oracle's libclntsh.so now depends on the posix threads library, libpthread.so, which must be linked with the main executable, httpd, with the flag "-lpthread". If this is not done, then when httpd attempts to load mod_owa.so, and hence libclntsh.so, the loader will error out because it can't do a dynamic load (via the dlopen() system call) of libpthread.so. Replacing the shipped Apache with a rebuilt listener solved the problem; I edited the Makefile produced by Apache's "configure" script to make sure LDFLAGS1 is set to "-lpthread". A quick way to check this is to use the "ldd" command to see what bindings your httpd is built with - make sure libpthread.so is one of them!

Note: this may no longer be a problem on modern Apache builds, which link to libpthread out of the box.

If you suspect you have this problem, I've included a very simple module, mod_test.so, which does little more than initialize the OCI (and, by omitting the "-DWITH_OCI" compile flag and the "-lclntsh" link flag, not even that much). If you can't get mod_test.so to load, try building it without the OCI dependency, and see if it loads. If it does, you have this problem. If it still doesn't load, then you have some other incompatibility between the build environment you're using to build mod_test.so and the build environment that produced your httpd. Either way, the only answer I have is to rebuild Apache from source to see if that clears the problem.

Oracle ran into this problem with the first version of iAS, and we are now going to ship the httpd that comes with iAS built with -lpthread on all platforms.

HP/UX may also need to have libcl linked into httpd (e.g. "-lcl").

Older versions of Oracle on Linux (e.g. 8.0.x) did not seem to have a dependency on libpthread. mod_owa was originally developed on 8.0.x, and so I didn't encounter this problem, or even understand it, until after the upgrade to 8i.

An OSX binary can be produced by following the procedure for Unix; in place of modowa.mk, use the make file osx.mk found in the makefiles sub-directory. The OSX build was contributed by John T. Chung of Nyquest Consulting. Please read his more detailed guide to building the module for OSX, found in osx_notes.txt in the doc sub-directory.

If you need to rebuild mod_owa for any reason, you should be aware of the following compilation flags:

The source files are:

A few very simple test procedures are supplied with mod_owa, in the form of some HTML test forms and SQL scripts to create database test objects:

Please note that the scripts contain references to SQL object types, LOBs, and NCHARs, which you might have to remove to get them to run against an older database server.

I no longer provide 32-bit builds of mod_owa for Linux or Windows. Users who need a 32-bit build should do so from source files. On a transitional basis, the new windows_all.zip contains 32-bit builds for Apache 2.4, in folder apache24_32, and for Apache 2.2, in folder apache22_32.

mod_owa wasn't designed to handle very large file-like LOB transfers. Transfers up to 10s of megabytes in size aren't a problem, but sizes into gigabytes are well beyond what was envisioned when the PL/SQL gateway was developed.

The OCI client interface on which mod_owa relied for years still use 32-bit signed integers and therefore imposes a 2 gigabyte upper limit on a LOB. As of Oracle 10g, a newer interface became available that uses 64-bit sizes; mod_owa now uses this newer version by default. As this breaks compatibility with 9g and earlier, users who need the older interfaces must rebuild the module with the OLD_LOBS flag set. (32-bit binaries for Windows will continue to use the old interfaces.)

There is no point in enabling the larger LOB limits on 32-bit builds of mod_owa because the module would be unable to process them in any case.

File uploads suffer from another drawback. mod_owa wasn't designed to support Apex-style calls and file uploads, and so that functionality had to be retrofitted to mod_owa's architecture. Since mod_owa performs its argument gathering phase prior to pinning an OCI connection for the request, this means that any files in the body have to be buffered in memory before they can be streamed to LOBs via OCI. Until this is fixed, assume any uploads are going to need an amount of memory equivalent to the total request size, which is very problematic if gigabyte-sized objects are transmitted.

As a practical matter it's unclear what PL/SQL and LOB application would realistically need to support such objects. Oracle LOBs are transactional, which is both their advantage and a potential weakness. For very large objects (say, a 5 gigabyte movie) the need to keep an OCI connection pinned during the entire upload process, plus the need to tie up an Apache worker process or thread, seems not to scale very well. Another problem: if a network glitch or other system error occurs during the transfer, the entire operation gets rolled back. For these types of applications it seems as if a torrent-like (fault-tolerant, multi-stream) approach would work better. Ideally an application could transfer blocks of the large object in arbitrary order, with multiple server-side workers cooperating to stream blocks into a slowly reassembled copy, and with re-transmits for lost blocks, errors, etc. Oracle LOBs can't work that way - only one logical database transaction can have a LOB open for writting.

Code path for these older versions of the Oracle client libraries has been removed from the module.

The Unix system clock measures time in seconds since January 1, 1970. This clock will run past the maximum value of a 32-bit signed integer and will wrap around, appearing to be a large negative integer, on or about January 19, 2038. mod_owa is potentially vulnerable to this problem, although because it uses 32-bit unsigned integers, mod_owa's internal timestamp values may still work until approximately 2116. mod_owa uses Unix-like timestamps internally even on Windows. Any problem would most likely affect the file-system caching feature, because of the way timestamps are reported from that layer. Other areas of the code that consult the system clock (such as logging, header generation, and timeouts) have been switched to 64-bit timestamps.

I suggest starting by reading the information in this document carefully. There's a good chance your problem is covered somewhere already, and even the contents of this section assume you already know concepts discussed later in this document. That said, here are some common errors with mod_owa installations:

OWA_CUSTOM.AUTHORIZE

Oracle ships the OWA_CUSTOM (and, in older OWAs, the OWA_INIT) package with a default implementation of AUTHORIZE that always returns false. If you've set OwaAuth in httpd.conf, mod_owa will call this routine and it will effectively disable any calls to your procedures. The symptom is usually an HTTP 404 error (URL not found). Remove the OwaAuth directive or change AUTHORIZE to return true if you don't want security. Otherwise, be sure to replace AUTHORIZE with a correct security check.

Flexible arguments

The old OAS apparently had a feature whereby it would call a procedure with the "flexible argument mode" despite the lack of the required "!" prefix on the URL. It had some sort of heuristic where it was able to figure out that this should be done, probably after a call built with the signature set by the OWA specification silently failed. mod_owa doesn't have this feature, and it can't be added because there is no foolproof way to figure out that this is required (I can think of several ambiguous cases), and because the architecture of mod_owa simply can't support it. The usual symptom of this problem is a 400 ("bad request") error (or a SQL error page if the diagnostic is enabled). A quick fix is to specify such procedures with OwaFlex directives, though it would be better to use the specified "!" prefix, or code overloads of the procedure in question to match the call signatures actually expected.

OWA gives PL/SQL errors with multi-byte databases

This is due to an incorrect implementation of the page buffer in the HTF package (pubht.sql and privht.sql). The problem arises because SQL and PL/SQL data buffers measure their maximum lengths in bytes, whereas all string operations, e.g. SUBSTR, LENGTH, etc., measure in characters. As a result, the HTBUF_LEN limit of 255 is not enforced properly with multi-byte character sets. I am trying to get Oracle to fix this by using the byte-based equivalents SUBSTRB, LENGTHB, etc. in the underlying code. Meanwhile, the simple fix is to use the OwaCharsize directive to reduce this limit based on your worst-case character size. For most multi-byte character sets, this will be 2 bytes per character, so the limit would be 127. For old UTF8 Unicode, it's 3 bytes per character, meaning the limit should be 85. For the newer AL32UTF8 Unicode, it's 4 bytes per character, and the limit should be 63. For a small number of Asian character sets it's also 4 bytes per character (you can recognize them because they will have a "32" in the Oracle character set name, e.g. "ZHT32EUC"), and the limit should be 63. OwaCharsize can be used to set the number of bytes per character N, which will cause mod_owa to force the buffer length down to floor(255/N). If in doubt, setting OwaCharsize to 4 is generally safest, although it may reduce performance.

2000-byte CGI value limit in pubowa.sql

In older versions of the OWA, the tables that hold CGI name/value pairs in PL/SQL were limited to 2000 bytes. When passing the CGI values to PL/SQL, mod_owa truncates large values to the maximum size allowed by the OCI, 3999 bytes. It is therefore possible, with an older OWA, to get a PL/SQL "value or numeric" error from a string buffer overflow. The simplest solution is to change the definition of vc_arr in pubowa.sql and increase the limit to 4000, matching more modern versions of OWA. I believe this will also work on older databases since PL/SQL has always had a 32K maximum for string size. However, it's possible that the network code won't support the 4000 maximum. If you believe you have such a problem, try using one of the backport versions of mod_owa (for example, the Oracle 8.0 version), since these impose the lower 2K limit.

32512-byte limit for PL/SQL variables

In the original version of OCI 8, the driver limited the array binding mode to arrays of standard SQL VARCHAR2 columns. This meant that they could be no larger than 2000 bytes each. This limit was increased to 4000 when SQL was improved to allow such columns, but it was still well short of the 32767 maximum size of a PL/SQL string variable. Furthermore, OCI network code had a limit of 32512 bytes on any bind variable, which meant that even simple scalars had to be limited to this lower value. It now appears that the 4000-byte limit has been corrected, allowing arrays to be up to 32512 bytes wide. This is relevant for collection-bound arguments to PL/SQL procedures, including the flexible argument mode. I've enhanced mod_owa to allow for this new maximum, but this may be incompatible with very old versions of OCI. If you get errors resulting from this, you'll have to rebuild the module with the older limit of 4000, using the OLD_MAX_STRING flag. The very latest versions of OCI appear to allow up to 32767 bytes for both scalars and arrays. I may upgrade to this new limit in a future release, but have chosen not to do so at this time because of compatibility concerns.

Database crashes passing Basic authentication

This is due to a bug in PL/SQL related to the use of RESET_PACKAGE. The symptom can be repeated challenges for re-authentication even after you've logged in, or it can take the form of "Internal Server Error"s. You will generally see many failures with Oracle status code 3113 in the mod_owa log file. The bug occurs intermittently but always when executing the two assignment statements for OWA.USER_ID and OWA.PASSWORD, which are required to support the OWA_SEC functions. Unfortunately there is no API by which the security-related package globals can be set, and mod_owa is obliged to use RESET_PACKAGE. mod_owa runs the two assignment statements as a separate PL/SQL operation, and this seems to eliminate the crash in most, but not all, cases. If you believe you have this problem, try using the SETSEC mode of the OwaAlternate flag (described below). (Oracle has fixed this bug in 8.1.7, the bug number was 1244988.)

OWA_SEC functions don't work

Users moving from OWS may find that their user authentication code doesn't work without some modification, because fundamentally mod_owa is an Apache driver for the OWA, not a replacement for OWS. In particular, the functions in OWA_SEC are not fully supported. The function OWA_SEC.SET_AUTHORIZATION_SCHEME is irrelevant; mod_owa passes all requests to your PL/SQL code and expects you to perform any necessary authentication operations. If you are using Basic authentication, you need to arrange for a challenge to be sent to browsers that haven't logged into your site; this can be done from your AUTHORIZE function or directly from each procedure, under conditions you determine. Apache will pass any Basic authentication information back to you in the HTTP headers. Please review the section on Basic authentication later in this document.

Characters garbled or incorrectly converted

This is most likely due to a misconfiguration or misunderstanding of how character sets are handled between the browser and Apache, and/or between mod_owa and the database. The quick checklist is to verify proper setting of the NLS_LANG environment variable in the environment used to launch Apache, verify proper setting of the OwaCharset (if it's needed to override NLS_LANG), verify proper setting of the browser character set, and verify the database character set by querying the value of parameter 'NLS_CHARACTERSET' from V$NLS_PARAMETERS using sqlplus. If none of this helps, read the section on character set handling later in this document.

httpd won't load mod_owa on Unix

Common reasons for this include missing the OCI library on the LD_LIBRARY_PATH and mixing incompatible versions of the module and the OCI library. The module needs to match the OCI library major version number, and you can't use a 64-bit version of mod_owa against a 32-bit OCI (and vice-versa). Thus, if mod_owa.so depends on 64-bit libclntsh.so.11, it won't run against any libclntsh.so.12 (unless a symlink is provided), nor against a 32-bit libclntsh.so.11. Use the "ldd" command, or use "readelf -d -h" on mod_owa.so, httpd, or libclntsh.so to examine dependencies and the build type. Also, ensure that httpd was linked against -lpthread, which is now required by Oracle's OCI. In the past, older versions of Apache did not link against -lpthread, and so the module would fail to load giving no useful error message. Please review the release notes above for Unix systems.

Apache unable to load mod_owa on Windows

The most common reasons for this are incorrect placement of the mod_owa.dll file versus the LoadModule directive, or a missing or incorrect version of the Oracle libraries (e.g. OCI). Make sure the path in LoadModule corresponds to the path that Apache is displaying in the error message and that this path is valid. If the error mentions that "the specified procedure could not be found" this may mean that the correct OCI library cannot be located. At least one user with multiple Oracle homes on the same Windows system encountered this problem because his 8.0.x OCI library was found first, ahead of the 8.1.x version. Note that setting ORACLE_HOME will not change the order in which Windows will search directories for dynamic libraries. Either make a global change to the path or use the 8.0.6 backport version of the the mod_owa.dll library. Finally, note that if you attempt to load a 64-bit version of the module in a 32-bit Apache, or run against a 32-bit OCI library, you'll get similar errors. Check the involved files with the DUMPBIN utility, specifically check HTTPD.EXE, OCI.DLL, and MOD_OWA.DLL with DUMPBIN/HEADERS and verify that the first header value (for machine) is consistent across them.

Apache 1.3 gives warnings/errors loading mod_owa

There are unfortunately two variants of Apache 1.3, the standard version, and the SSL version. The SSL version has the so-called EAPI module extensions. To signal modules that were compiled with the EAPI extensions, there is a new magic number that gets compiled into the code. The SSL version will load a module that it thinks is compiled the old way, but will give you a warning because the end of the module structure may be missing some necessary pointer structures, and may cause a crash. The standard version will not load an EAPI module, however; it will give you an error message claiming the module is not an Apache module. mod_owa can be compiled in several ways; it can be compiled without EAPI, it can be compiled with the EAPI extensions but using the old magic number, and it can be compiled exclusively for EAPI. By default, on Linux and Windows I build it with the EAPI extensions (thus avoiding the possibility of a crash) but using the old magic number (thus allowing it to work fine in the standard Apache). If you have an Apache with mod_ssl and you need to get rid of the warning message, rebuild the code using the EAPI and EAPI_ONLY flags.

Silent failures during RESET_PACKAGE

After processing an HTTP request by calling your PL/SQL code, and getting/relaying the results from GET_PAGE, mod_owa must call the RESET_PACKAGE procedure to clear out the PL/SQL state for the next request. This is the only SQL operation performed by mod_owa after it sends the results to the browser; because of this, any error that occurs at this point can't be displayed to the browser (even with the SQL diagnostic enabled). However, with the SQL diagnostic, mod_owa always writes the final SQL status to the mod_owa log file, so it should be possible to see if failures have/are occuring by consulting that file. Failures at this point are very unlikely, but at least one user has encountered a failure here due to a mis-configuration (using the OwaReset directive to cause mod_owa to call one of the newer reset modes against a database that did not support them).

Oracle environment variables

It's very important that ORACLE_HOME be set to point to the location where your Oracle software is installed. It's also critical that the directory containing libclntsh.so be on your LD_LIBRARY_PATH. Other important environment variables to look at are NLS_LANG (if you are trying to run a particular locale) and ORACLE_SID (if you are not using SQL*Net to connect to your database). A good way to check the Oracle setup is to run sqlplus from the environment where you launch httpd and connect to the database using the identical connect string specified in httpd.conf for mod_owa. Note that on Unix it's vital that areas of the ORACLE_HOME be readable by the Apache "run-as" user; some users have run into problems because areas of their ORACLE_HOME were not readable by the "nobody" user they set Apache up to run as (check the User and Group directives in httpd.conf). A very common symptom of this class of configuration problem is to get an -1 error on OCI connect. Another symptom is an ORA-01804 on connect. One way that users sometimes accidentally break the environment variables is with mod_env.

OCI connection issues

The OCI connect operation can fail for any number of reasons. The primary ones are not having the Oracle environment variables set properly, lack of file-system access to ORACLE_HOME from the Apache run-time user, incorrect settings for TNSNAMES.ORA, or lack of access to the Oracle Wallet. To help diagnose some of these issues, you can set environment variable MODOWA_DUMP_ENV to a file path/name, and on connect failures, mod_owa will dump information (mainly the OS environment variables) to the specified file.

Firewall disconnects

Some users have reported that firewall or other networking infrastructure sometimes kills idle sqlnet connections without notifying the OCI that the socket connection to the database is no longer valid. This leads to sqlnet "hangs" when an idle (but now dead) connection is drawn from a connection pool. I'm not aware of any solution to this type of problem that I'm able to add to mod_owa. If OCI calls the socket layer to transmit SQL to the database, and doesn't get an error code from the operating system, it will then wait for a response from the database. If the message didn't get through, it will hang waiting for a response that will never come. I suspect that either the firewall or the OS is is not configured properly when this type of failure occurs. You might be able to avoid the problem by setting SQLNET.EXPIRE_TIME on the database server side to a value that cleanly closes outstanding connections at an interval that's more frequent than the firewall kills them. Another work-around is to set OwaPool to 0 to avoid mod_owa connection reuse entirely.

SELinux issues

It's important to make sure Oracle's OCI library and associated files in ORACLE_HOME are readable by the Apache worker processes. Many users running SELinux run into problems because they forget to do this. A common symptom is to get file-system privilege errors when attempting to start Apache, often when loading libclntsh.so (the very first Oracle-supplied file to be accessed).

Ubuntu issues

Some users have reported problems getting the module to run properly with Apache on Ubuntu. The symptom is a failure to start the OCI systems, sometimes with a report of an error ORA-01804. These errors are due to the inability of OCI to read flat-files from the ORACLE_HOME area. Specifically, there are timezone and character set files that need to be loaded before the OCI can start up. In some cases, users have reported that they needed to set the ORACLE_HOME (and other) environment variables in /etc/apache2/envvars.

GLIBC compatibility

Some users have reported problems getting the module to run properly due to GLIBC incompatibilities. Specifically, if their installation has an older version of GLIBC, mod_owa's dependency on a newer version can lead to unhelpful error messages such as "GLIBC_2.14 not found". If you can't upgrade your GLIBC installation, the simplest solution is to rebuild the module from source code.

OwaLog diagnostic file is not written

This problem is almost always due to a file system security problem. Apache worker processes can be set up to run as a different user/group than the user who starts Apache, via settings in httpd.conf. If this "run-as" user doesn't have write permission on the directory where the log file needs to go, mod_owa can't create it. And if the "run-as" user doesn't have write permission on the file, mod_owa can't write messages into it.

Database connection exhaustion with Apache 2

Apache 2.0 and beyond have all but desupported child/worker-process cleanup. Thus, there is no opportunity for mod_owa to close any pooled database connections when a worker goes down. Unfortunately, this doesn't just mean that you might lose connections when a crash occurs, because it can happen if the Apache manager process decides to shut down a worker as load subsides on the system. Connection loss thus appears to be a fact of life now with Apache. Either disable pooling completely (using a pool size of 0, or via the THREADS diagnostic flag), or ensure that your database server checks for and kills inactive database processes (the server side of the dead connections).

HP/UX issues

The biggest single problem is that Oracle's libclntsh.sl, on which mod_owa depends, was shipped with some undefined symbols. The HP/UX loader will fail to start Apache but typically gives misleading error messages about the cause. Be sure that you've got the patched version of this library from Oracle before trying to use mod_owa. Another common source of trouble on HP/UX is to mix an incompatible combination of 32-bit and 64-bit executables and shared libraries. Use the HP/UX-specific "chatr" function to check httpd, mod_owa.sl, libclntsh.sl, and other key libraries. Also, make sure httpd was linked with libpthread and libcl (chatr will tell you this, too). You can add -lcl and -lpthread to the Makefile that relinks httpd and the relinked version will work.

The main task involves setting up "locations" that point into the OWA module from within httpd.conf. For example:

<Location /owa>
    AllowOverride  None
    Options        None
    SetHandler     owa_handler
    OwaUserid      owa/owa
    OwaNLS         WE8ISO8859P1
    OwaAuth        OWA_INIT
    OwaDiag        COMMAND ARGS CGIENV POOL SQL MEMORY
    OwaLog         "/usr/local/apache/logs/mod_owa.log"
    OwaPool        20
    OwaStart       "doc_pkg.homepage"
    OwaDocProc     "doc_pkg.readfile"
    OwaDocPath     docs
    OwaUploadMax   10M
    OwaCharset     "iso-8859-1"
    order          deny,allow
    allow          from all
</Location>

Each location can be thought of as "mounting" a distinct database and database context. In the above example, URLs will be directed into the PL/SQL gateway when they have the form:
http://mymachine.../owa/procedurename...
With locations, you can set up separate "mounts" for different databases, or multiple "mounts" to the same database with different NLS language settings, etc. Use of patterns (LocationMatch directives, e.g. "/owa/[^/]*") is supported (see the later section on LocationMatch support). Use of structured locations e.g. "/owa/subdir", is supported with special-case code. Use of "/" as a location (directing all web traffic to mod_owa) is also supported with special-case code. The mod_owa-specific directives in this Location example are described in next section.

A common practice is to place all the OWA-related Locations and other directives, including the LoadModule directive, in a separate .conf file (e.g. modowa.conf) and then include this file into httpd.conf with something like:

include modowa.conf

mod_owa has a number of directives that are intended for use within a Location directive and that establish settings solely for that Location. There are also two optional directives that appear outside the scope of any location to specify global (Apache-wide) settings.

When I started working on mod_owa, I was initially just building extensions to the original version, and I followed the naming convention established by the original authors. Later, after the rewrite, I found myself adding a great many new directives, but felt obliged to continue using this naming convention. In the latest versions of mod_owa, I've switched to a standards-conforming naming convention where every directive is prefixed with "Owa". The old names are still supported for backward compatibility, but will be dropped as of the Apache 2.0 release. Users are encouraged to adopt the new names in their .conf files.

Summary of directives:

These directives are described in more detail in the table below. In each case the new (2.0) directive name is given first, and the old directive name is given second. Very complex directives have additional information provided in later sections of this document.

Apache's LocationMatch directive allows you to set up a Location where a variety of incoming URLs will be routed based on regular expression matching. Unfortunately, after processing the match, Apache will split the incoming URL at the first "/" found, regardless of the template used, such that the SCRIPT_NAME and PATH_INFO variables will not be as expected by the PL/SQL gateway. (In fact, this is true even with regular Location directives that contain "/"s.) For example, here is how Apache processes this Location and URL:

Location:      /owa/subdir
URI:           /owa/subdir/mypackage.myprocedure

Apache returns:

SCRIPT_NAME =  /owa
PATH_INFO   =      /subdir/mypackage.myprocedure

Now consider this LocationMatch example:

LocationMatch: /owa/(cat|dog|horse)
URI:           /owa/horse/mypackage.myprocedure

Apache returns:

SCRIPT_NAME =  /owa
PATH_INFO   =      /horse/mypackage.myprocedure

In both cases, Apache has split the URI at the first "/" it encounters, despite what would actually be matched by the Location or LocationMatch directive.

mod_owa contains logic to detect and correct this condition before the CGI environment is passed to PL/SQL. This logic works well for the Location case. In the LocationMatch case, mod_owa uses Apache's regular expression engine to reparse the URI after first reassembling it from SCRIPT_NAME and PATH_INFO.

When matching against the regular expression, mod_owa must still break the SCRIPT_NAME and PATH_INFO at a "/". Any LocationMatch directive that does not have a trailing "/" will have one appended by mod_owa for this purpose. The regular expression processor will attempt to apply each rule as many times as possible, and this can lead to consumption of too much of the URI string for poorly-formulated expressions. For example, consider the effect of a wildcard match on a document-like URI:

LocationMatch: /owa/.*
URI:           /owa/horse/docs/images/photo.gif

mod_owa produces:

SCRIPT_NAME =  /owa/horse/docs/images
PATH_INFO   =                        /photo.gif

(the implied trailing "/" added by mod_owa forces the wildcard to stop at "/photo.gif"). This was probably not the desired split, and instead, this formulation should have been used:

LocationMatch: /owa/[^/]*
URI:           /owa/horse/docs/images/photo.gif

mod_owa produces:

SCRIPT_NAME =  /owa/horse
PATH_INFO   =            /docs/images/photo.gif

This code is still very experimental and subject to change. In particular the assumption of a trailing "/" is still open to question.

Oracle OCI allows mod_owa to connect using "external authentication". Examples include using the operating system user and using the Oracle Wallet. External authentication is triggered by supplying a blank connect string, e.g.

OwaUserid      /

or

OwaUserid      /@YOURDB

Follow the instructions in your Oracle documentation to set up external authentication. If set up properly, you should be able to connect to the database with the sqlplus tool using the same connect string.

This link may be helpful if using the Oracle Wallet as the external store: Oracle Database Security Guide: Chapter 9 - Secure External Password Store

Please note that on Windows, Apache may run as a service and may therefore run as a user other than the user you normally log into Windows as. For instance, as user SYSTEM. This may cause external authentication to fail unless you configure your windows service to run as the correct operating system user. For more information refer to the Apache documentation.

Request setup

Request execution

alter session set NLS_LANGUAGE='AMERICAN'
                                ^ Specified language goes here

alter session set NLS_TERRITORY='AMERICA'
                                 ^ Specified territory goes here

alter session set TIME_ZONE='US/Eastern'
                             ^ Specified time zone goes here

alter session set NLS_DATE_FORMAT='DD/MM/YYYY'
                                   ^ Specified format mask goes here

alter session set NLS_TIMESTAMP_FORMAT='YYYY/MM/DD HH24:MI:SS'
                                        ^ Specified format mask goes here

alter session set NLS_TIMESTAMP_TZ_FORMAT='YYYY/MM/DD HH24:MI TZH:TZM'
                                           ^ Specified format mask goes here

begin DBMS_SESSION.RESET_PACKAGE; end;

OwaAlternate  MY_OWA KEEPSTATE

begin OWA.INIT_CGI_ENV(:ecount, :namarr, :valarr); end;

ecount    Number of name/value pairs for the CGI environment
namarr    PL/SQL table of records with a list of VARCHAR2 names
valarr    PL/SQL table of records with a list of VARCHAR2 values

begin
  OWA.USER_ID := :usr;
  OWA.PASSWORD := :pwd;
end;

begin
  if <authorization_call> then
    <before_procedure_call>
    <procedure_call>(<arg1_name> => :B1, <arg2_name> => :B2, ...);
    <after_procedure_call>
    commit;
  else
    :realm := OWA.PROTECTION_REALM;
  end if;
end;

http://mymachine/owa/foobar?a=dog&b=cat

foobar(a=>:B1,b=>:B2);

http://mymachine/owa/^foobar?a=dog&b=cat

foobar(:B1,:B2);

http://mymachine/owa/!foobar?a=dog&b=cat

foobar(:B1,:B2,:B3,:B4);

:B1 is the number of name/value pairs
:B2 is an array of parameter names, in this case the array ['a','b']
:B3 is an array of values, in this case ['dog','cat']
:B4 is an array reserved for future use

foobar(:B2,:B3);

:B2 is an array of parameter names, in this case the array ['a','b']
:B3 is an array of values, in this case ['dog','cat']

http://mymachine/owa/~foobar

http://mymachine/owa/foobar?n=2&a=dog&a=cat

foobar(n=>:B1,a=>:B2);

begin OWA.GET_PAGE(:linearr, :nlines); end;

<tag>: <value><newline>

The mod_owa version of this functionality is still experimental (more so than the rest of the code). There are still numerous open issues, particularly relating to uploads and character-set issues for CLOBs. The HTTP standard for file uploads is particularly toxic, and my understanding of it is constantly being proven incorrect; as a result, the quality of mod_owa's upload parsing code is mediocre at best. These issues are noted in the descriptions that follow.

It was not possible to exactly mirror the specification of this feature in Oracle's version of the gateway, mainly because that specification required the installation and use of WebDB-related PL/SQL facilities that aren't supportable by mod_owa. The mod_owa version of this functionality attempts to provide a relatively simple, entirely programmatic interface, by means of which programmers can "wrap" their own tables, access control functions, etc.

A very limited capability that may be compatible with WebDB's file upload and download interface is available via the OwaDocTable directive. This is limited to a single interface table and column, which must be a BLOB column only. That capability may be sufficient to run Apex, though I am unable to verify it.

File download

http://mymachine/owa/docs/a/b/c/doc.gif?arg1=1&arg2=2
                     ^ OwaDocPath

begin
  <OwaDocProc>(:B1,:B2,:B3,:B4,:B5,:B6,:B7,:B8,:B9);
  commit;
end;

:B1 is an input with the number of name/value pairs
:B2 is an input array of parameter names
:B3 is an input array of parameter values
:B4 is an input array reserved for future use
:B5 is an output string for the document mime type
:B6 is an output BLOB locator for binary documents
:B7 is an output CLOB locator for textual documents
:B8 is an output NCLOB locator for Unicode textual documents
:B9 is an output BFILE locator for binary file-based content

:B1 => 3
:B2 => {"document_name",       "arg1", "arg2"}
:B3 => {"/docs/a/b/c/doc.gif", "1",    "2"   }
:B4 => {"",                    "",     ""    }

text/html; charset=iso8859-1\n
Last-Modified: xxx\n
If-Modified-Since: xxx

File download with LONG or LONG RAW

begin
  <OwaDocProc>(:B1,:B2,:B3,:B4,:B5,:B6,:B7,:B8);
  commit;
end;

:B1 is an input with the number of name/value pairs
:B2 is an input array of parameter names
:B3 is an input array of parameter values
:B4 is an input array reserved for future use
:B5 is an output string for the document mime type
:B6 is an output string for returning a SQL select statement
:B7 is an output string for returning a SQL bind variable string value
:B8 is an output string for returning the 1-character value of a RAW flag

select LONG_CONTENT from MYDOCUMENTS where KEY_COLUMN = :B1;

OwaDocLobs    CHAR LONG_FETCH_LENGTH

File download using the file system

begin
  <OwaDocProc>(:B1,:B2,:B3,:B4,:B5,:B6);
  commit;
end;

:B1 is an input with the number of name/value pairs
:B2 is an input array of parameter names
:B3 is an input array of parameter values
:B4 is an input array reserved for future use
:B5 is an output string for the document mime type
:B6 is an output string for returning a file system path

Dynamically-generated virtual files

begin
  <OwaDocProc>(:B1,:B2,:B3,:B4);
  commit;
end;

File upload

<form action="doc_pkg.writefile"
      method="POST" enctype="multipart/form-data">
...
</form>

-------------------------1234567890\r\n
Content-Disposition: form-data; name="field1_name"\r\n
\r\n
field_value\r\n
-------------------------1234567890\r\n
Content-Disposition: form-data; name="field2_name"; filename="foo.doc"\r\n
Content-Type: mime/type\r\n
...other optional header elements such as Content-Encoding...\r\n
\r\n
...file contents...\r\n
-------------------------1234567890--

begin
  <action_procedure>(:B1,:B2,:B3,:B4,:B5,:B6,:B7,:B8);
end;

:B1 is an input with the number of name/value pairs
:B2 is an input array of parameter names
:B3 is an input array of parameter values
:B4 is an input array reserved for future use
:B5 is an input/output string for the document mime type
:B6 is an output BLOB locator for binary documents
:B7 is an output CLOB locator for textual documents
:B8 is an output NCLOB locator for Unicode textual documents

select CONTENT into plob
  from MYDOCUMENTS where DOCNAME = FILEPATH for update;

insert into MYDOCUMENTS (DOCNAME, CONTENT)
     values (FILEPATH, empty_blob())
  returning CONTENT into plob;

:B1 => 3
:B2 => {"document_path", "", "content_length"}
:B3 => {"docs",          "", "123456"        }
:B4 => {"",              "", ""              }

File upload with LONG or LONG RAW

<form action="~doc_pkg.writefile"
      method="POST" enctype="multipart/form-data">
...
</form>

begin
  <action_procedure>(:B1,:B2,:B3,:B4,:B5,:B6,:B7,:B8);
end;

:B1 is an input with the number of name/value pairs
:B2 is an input array of parameter names
:B3 is an input array of parameter values
:B4 is an input array reserved for future use
:B5 is an input/output string for the document mime type
:B6 is an output string for returning a SQL update or insert statement
:B7 is an output string for returning a SQL bind variable string value
:B8 is an output string for returning the 1-character value of a RAW flag

update MYDOCUMENTS set LONG_CONTENT = :B1 where KEY_COLUMN = :B2;

insert into MYDOCUMENTS (LONG_CONTENT, KEY_COLUMN) values (:B1, :B2);

File upload using the file system

<form action="~doc_pkg.writefile"
      method="POST" enctype="multipart/form-data">
...
</form>

begin
  <action_procedure>(:B1,:B2,:B3,:B4,:B5,:B6);
end;

:B1 is an input with the number of name/value pairs
:B2 is an input array of parameter names
:B3 is an input array of parameter values
:B4 is an input array reserved for future use
:B5 is an input/output string for the document mime type
:B6 is an output string for returning a file system path

File upload/download using a document table and column

OwaDocTable WWV_FLOW_FILE_OBJECTS$ BLOB_CONTENT

0123456789ABCDEF/original_file.xml

if (WPG_DOCLOAD.IS_FILE_DOWNLOAD) then
  WPG_DOCLOAD.GET_DOWNLOAD_FILE(:p_doc_info);
  WPG_DOCLOAD.GET_DOWNLOAD_BLOB(:p_blob);
end if;

create table DEMO_DOCLOAD
             (
             NAME         varchar2(256) not null,
             MIME_TYPE    varchar2(128)         ,
             DOC_SIZE     number                ,
             DAD_CHARSET  varchar2(128)         ,
             LAST_UPDATED date                  ,
             CONTENT_TYPE varchar2(128)         ,
             BLOB_CONTENT BLOB                  ,
             constraint DEMO_DOCLOAD_PK primary key (NAME)
             );

mod_owa has logic to support the Basic authentication mode in a manner that is roughly compatible with that of OWS. Look again at the call that mod_owa will build for your procedure:

begin
  if <authorization_call> then
    <procedure_call>...
    commit;
  else
    :realm := OWA.PROTECTION_REALM;
  end if;
end;

This gives your code the opportunity, in the AUTHORIZE procedure, to accept or reject the user's credentials by returning TRUE or FALSE. If you return TRUE, the procedure is called normally, and GET_PAGE is used to retrieve the result. If you return FALSE, then the procedure is not called, and mod_owa will still call GET_PAGE to get your response, which could be a login page if you are doing your own authentication system, or a Basic authentication challenge if you want to use that scheme.

An example of issuing a Basic challenge is as follows:

OWA_UTIL.MIME_HEADER('text/html', FALSE);
HTP.PRN('WWW-Authenticate: Basic realm="myrealm"');
OWA_UTIL.HTTP_HEADER_CLOSE;
...
return(FALSE);

This allows you complete control over the header that is returned; mainly, this would allow you to set cookies if that's useful to your signon process. The other way would be to let mod_owa do this for you:

OWA_SEC.SET_PROTECTION_REALM('myrealm');
...
return(FALSE);

This call sets the value of OWA.PROTECTION_REALM (actually, you could just set it yourself if you like), and if you look at the "else" clause above you will see that mod_owa will read this value back. If mod_owa sees that this value is non-null, then it will skip the GET_PAGE operation and will generate the Basic challenge for you, using the realm that you have specified. (This is for compatibility with OWS.)

Apache returns the Basic authentication header in HTTP_AUTHORIZATION in the raw base-64-encoded form, and mod_owa will pass this along with the rest of the CGI environment. To provide minimal compatibility with OWS, mod_owa will also decode/parse this header and assign the username and password values to the appropriate global variables in OWA, so that OWA_SEC.GET_USER_ID() and OWA_SEC.GET_PASSWORD() will work. No other form of external authentication will set these variables, however. If you look again at the call mod_owa builds after passing the CGI environment:

begin
  OWA.USER_ID := :usr;
  OWA.PASSWORD := :pwd;
end;

you can see that this will set the values for OWA.USER_ID and OWA.PASSWORD, which are simply returned by the OWA_SEC functions. You can also obtain the raw HTTP header element with:

AUTHSTRING varchar2(2000);
...
AUTHSTRING := OWA_UTIL.GET_CGI_ENV('HTTP_AUTHORIZATION');

Note that the browser will return the Basic header with every request, and you must check it on every request. Remember that the PL/SQL environment is stateless and you cannot be sure of keeping state between calls from a client (unless you set a cookie). Thus, every request must be treated as if it were the first request. A few tips:

• Check the username/password on every request, and if it's successful, return TRUE. If you like, you can set a cookie, but remember that now you must also check this cookie on every return request, too, and you will need special logic to set the cookie on the first success.
• It's a bad idea to generate error pages in response to invalid usernames or passwords. Instead, treat such conditions the same as if it's the first time and there is no username or password; otherwise, users who make typing errors will not have any way to correct them during the login process. If you use a cookie to time out the session, be sure to treat this just the same, and issue a new challenge.

If you use the OwaRealm directive, mod_owa will take over the responsibility of logging the user in, using database authentication. You should therefore either disable further authorization checks for that location, or arrange to return TRUE from any AUTHORIZE procedures you may have; a simple way to do this is to check that the OWA.USER_ID is identical to the current database USER, as in:

if (upper(OWA_SEC.GET_USER_ID()) = USER) then
  return(TRUE);
end if;

If you end OwaRealm with the special string "{TIME}", mod_owa will replace the string with a generated timestamp string. This attempts to emulate a WebDB work-around for the inability to force a browser to clear/expire the Basic authentication credential. On logout, applications can set the special cookie WDB_GATEWAY_LOGOUT to "YES" to force mod_owa to re-authenticate the next request from the client. mod_owa will clear that cookie (set it to "NO") on the first re-authentication, and the challenge will seem (to the browser) to be a new realm due to the appended timestamp.

OwaRealm  myrealm+{TIME}

WWW-Authenticate: Basic realm="myrealm+2012-12-20T12:34:56.999999"

Use of the OwaSession directive doesn't have any effect on Basic authentication processing. It causes mod_owa to strongly prefer to reuse a database connection from the pool that has previously been used for requests from the same user, based on a cookie value. It is not safe to assume that the database connection is in fact the same one used previously. It is also not secure to assume that because the session identifier matched the connection pool, the user has legitimately been authenticated. OwaSession should be considered a performance-related feature only.

Use of the OwaLDAP directive alters the behavior of OwaRealm and/or OwaSession. OwaLDAP specifies a procedure to receive the contents of the basic authentication header and/or the contents of the session cookie specified by OwaSession. mod_owa will open a temporary database connection and build a call to the procedure specified in the OwaLDAP directive, of the following form:

begin <procedure_name>(:username, :password, :session); end;

The username and password arguments are IN/OUT, while the session is IN only. All three are filled in with values as/if available on the request. On output, your procedure is expected to fill in the username and password arguments with a valid database username/password pair, or with empty strings if some sort of validation failure occurs. mod_owa will then close the temporary database connection and will use the returned values instead of any values that came with the request's basic authentication header. This supports allowing the user to sign in to basic authentication using credentials from another system such as LDAP, and yet still connect to a native database account corresponding to the authenticated user.

The temporary database connection uses the OwaUserid connect string, so it must be valid for this feature to work. To reduce the inefficiency of constantly opening/closing the temporary connection, mod_owa will cache the results of calling your routine, matching first on the session cookie, and next on basic authentication username/password.

I do not recommend using OwaLDAP. A more robust method of logging in via LDAP would be to build a login page using either another technology such as Java, or using a mod_owa page designed for that purpose. The result should be a secure session cookie which can be checked in your AUTHORIZE procedure. Individual database accounts should not be used. This feature exists because some users still want to rely on database native security (e.g. database roles) for their application security.

If OwaLDAP is set to a string containing a "/", the above logic is not used, and mod_owa instead obtain the username and password from CGI environment variables, or the supplied string(s). This form of OwaLDAP is:

OwaLDAP  <env var for user>/<env var for password>

For example:

OwaLDAP  HTTP_SM_USER/HardcodedUniversalPassword

mod_owa will attempt to extract values from the variables with the specified names, then use those values as if they had come from a Basic Authentication header. If a variable is not found, the string is used "as-is". The purpose of this mode is to allow users to be authenticated by an external trusted authority that supplies credentials to the HTTP request after validating it.

This has some fairly obvious security flaws. If you cannot absolutely guarantee that the CGI environment variables aren't being forged and sent from the client, an attacker could send requests with forged headers regarding the username/password and launch a password-guessing attack on the database. Worse still, if the password is hard-coded as in the example above, the user might simply supply a valid username in a forged header without ever having to know or guess the password.

If OwaLDAP is set to "*", the above logic is not used, and mod_owa will process basic authentication normally, but with one exception: it will not override the value of the CGI REMOTE_USER parameter with the username taken from the basic authentication header. This is done to allow for an alternate means of authentication, wherein the request is first processed by another module, and the basic authentication header is set artificially. This is a cheesy hack!

In some special situations, programmers have needed access to the raw bytes of a POST request, without these bytes being parsed and unescaped by mod_owa as procedure arguments. To support this type of code, mod_owa has been extended to include a calling mode not found in the offical gateway specification. This raw request calling mode is indicated by preceding the procedure with a tilde:

http://mymachine/owa/~foobar

which mod_owa will call as:

foobar(:B1,:B2,:B3);

:B1 is a raw buffer containing the unprocessed POST data or QUERY_STRING
:B2 is an output string for the response mime type
:B3 is an output BLOB locator for a binary response

Up to 32512 bytes of raw data can be passed in this manner. The two output arguments allow you to return a RAW response directly from your procedure. If you return a non-null result for the BLOB, mod_owa will skip the normal GET_PAGE phase and use the contents of the BLOB as the response. In that event mod_owa will take the document mime type from the second argument (additional header values can also be passed in this buffer - see the previous section on file downloads for information on how to do that).

If you are running the Oracle 7.3 build of mod_owa, the call will have only the first argument containing the RAW input data, because LOBs aren't supported. You must therefore return your response via GET_PAGE or a GET_PAGE alternate (see later section).

The PL/SQL gateway allows you to return an HTTP error status code via a call to OWA_UTIL.STATUS_LINE. Example:

OWA_UTIL.STATUS_LINE(404, Your_Key||' not found', TRUE);

In general, mod_owa allows Apache to handle the generation of an error page by passing the status code back to Apache. How it gets handled depends on how you configure Apache. By default, Apache typically generates HTML error pages with boilerplate text. For example, it commonly generates an HTML page of the following form in response to a 404:

When you allow Apache to handle the errors in this manner, it effectively rewrites them; your client will receive a status code of 200 and an HTML content page, instead of the original error code and message.

mod_owa allows you to avoid this in most cases by supplying your own error page. The minimum requirement is that you supply a Content-Type header, for example:

OWA_UTIL.MIME_HEADER('text/plain', FALSE);
OWA_UTIL.STATUS_LINE(404, Your_Key||' not found', TRUE);

You can optionally render your own error page following the headers. mod_owa will take either the presence of a Content-Type header or the presence of a content page as an indication that your PL/SQL wishes to control the error response. REST applications in particular may need to do this.

The OwaDiag flags allow control over built-in diagnostic features. Most of these cause logging of information to the mod_owa log file, though a few cause enhanced (but potentially unsecure) HTML output to be returned when error conditions occur. Any or all of the flags can appear together.

The diagnostic file was designed to be used for diagnosing problems with a mod_owa application or deployment. It wasn't designed to be used as a general access log for production operation. There could be security issues with leaving diagnostic flags on for a production operation. There could also be performance issues related to locking of the file if multiple worker processes attempt to write to it simultaneously.

A few special hooks are built into mod_owa to enable control over the connection pool. These allow a user, through HTTP, to examine, close, and reopen the pool for any Location. This is done by a special convention: in the portion of the URL that is used for the PL/SQL procedure name, any name ending in an "!" mark is assumed to be a special control directive. There are currently seven such directives supported:

Note that access to these functions could represent a security problem. The current implementation requires that the database password be supplied with the request, for example:

http://mymachine/owa/showpool!?owa

You can use the OwaAdmin directive to restrict use of control functions to a range of IP addresses; for example:

OwaAdmin 123.45.67.0 255.255.255.0

restricts access to machines on the subnet 123.45.67.xxx. It is possible to use this mechanism to restrict access to a single machine if desired (subject to trusting the relevant portion of your network configuration). It is also possible to use this flag with invalid values to effectively disable the control functions, for example by setting 255.255.255.255 as the subnet value and 0.0.0.0 as the mask (because, of course, any bits that are 0s in the mask must likewise be 0s in the IP address value, too).

Also, note that the pool functions really only work for NT; on Unix, there effectively is no pool because each worker process has its own dedicated connection.

When using the file download capabilities, some users have found that caching content in the file system where Apache is running helps improve their performance. mod_owa supports this with the OwaCache directive, which has the following form:

OwaCache  <logical name> <physical name> [lifespan]

This specifies a mapping between a logical name as seen in a URL (and as seen by your PL/SQL code) and a physical file-system name. For example:

OwaCache  /docs/images  /usr/local/apache/htdocs/image_cache  "2 hours"

causes mod_owa to translate a URL such as

http://localhost/owa/docs/images/foobar.gif

into

/usr/local/apache/htdocs/image_cache/foobar.gif

You can specify multiple OwaCache directives in any Location. There are two main types of file-system caching supported

• static caches
  This assumes that you have arranged to push the content from the database out to the native file system through some external means. mod_owa will only read from a static cache, never write to it. The static cache is assumed to have a directory structure that parallels the structure found in the database.
• dynamic caches
  mod_owa will use the specified physical location as a read/write cache for files matching the pattern.

The setting for lifespan governs which of these caching modes you will get for any particular OwaCache. If you omit the lifespan, mod_owa will use static caching mode. If you specify a lifespan, mod_owa will use the dynamic mode. By default lifespan quantities are in seconds; mod_owa will recognize other units such as "minutes", "hours", and "days" (you only need to specify the first letter, thus "10d" equals 10 days). A lifespan of 0 is treated as infinite.

In dynamic caching, mod_owa will compare the timestamp on the file with the current system time and will use the file if it's within the specified lifespan. If a matching file is not found or is out-of-date, mod_owa will get the file from PL/SQL and (if possible) generate (or re-generate) the file during the content download operation. Because mod_owa cannot assume anything about the directory structure for a dynamic cache, mod_owa will create any levels of subdirectories needed by the path. For example, with the preceding OwaCache directive:

http://localhost/owa/docs/images/gifs/foobar.gif

would be translated to

/usr/local/apache/htdocs/image_cache/gifs/foobar.gif

In static caching, the path is built identically but directories are never created by mod_owa.

In either static or dynamic caching, the physical path will be built to conform to the underlying operating system (OS). Thus, on Windows the above translated path might be:

D:\apache\htdocs\image_cache\gifs\foobar.gif

Some additional notes about file system caching:

• You must make sure that the physical path you specify in the OwaCache directive is compatible with the underlying OS. Also, do not specify a trailing directory separator on either the logical or physical names.
• In both static and dynamic caching, if the file being referenced is a directory, mod_owa ignores it and just passes the request on to PL/SQL (mod_owa does not have any way to read a directory, and even if it did it has no way to know how your application would want the data formatted for display).
• For dynamic caching, mod_owa needs to be able to determine the mime type of the file from its path name (using the extension). mod_owa will check this before writing a file to the cache; if the extension doesn't match the mime type you've returned, the file won't be cached.
• If your file URL contains any arguments, mod_owa will bypass the cache completely and go directly to PL/SQL.
• mod_owa will match the logical name to the longest path prefix it can find; thus, if both "/docs/foo/bar" and "/docs/foo" are specified as logical names, "/docs/foo/bar/file.txt" will be matched to the longer prefix (but not to, say, "/docs/foo/b", which is treated as a different directory).
• mod_owa uses a case-sensitive comparison when matching the logical names (because it can't know if your underlying database file store is case-sensitive or not, and this is the more conservative assumption). It also preserves case when assembling the physical name, which can have implications when the cache is later read (if the underlying file system is case-sensitive, then it's possible a later read will miss the cache even if the database file store is not case-sensitive).
• mod_owa won't write files to the cache that exceed 1 megabyte. For file reads, mod_owa will use shared memory-mapped I/O for files below this same threshold, and normal file I/O routines above the limit.
• The whole point of the file-system cache is to avoid calling PL/SQL; this implies that any authorization code you would normally run won't get executed if the cache is hit. For this reason, you should probably cache only unsecured documents (or is there a way to use native Apache authorization to secure such content?).
• The cache will slowly fill up with files, so you should arrange for a background job to clean them up periodically (or use mod_owa's cleanup thread if it works on your platform).

To make the file system cache work, mod_owa uses a number of OS-specific interfaces that may make it somewhat less portable. The main functions used are file open/close, generation of temporary file names, file stat, and memory-mapped files.

I must note that Oracle has several technologies in iAS that are vastly superior to this technique, particularly the WebCache, a memory-based cache that can cache all forms of static content from the site (not just PL/SQL-based), as well as many forms of dynamic content.

During periods of peak load, the number of connections in the pool (on NT) will ramp up to a high-water mark. When the system is not under stress, it might be a good idea to close unnecessary connections.

If you specify a non-zero value for the global directive owa_shared_thread, mod_owa will launch a thread immediately after a worker process starts up, and this thread will remain running for the life of that process. The value you specify is taken to be the poll interval for the thread, in seconds. You may optionally include units, provided they appear together with the lone parameter to this directive, or appear in quotes. mod_owa will recognize units such as "minutes", "hours", and "days" (you only need to specify the first letter, thus "10d" equals 10 days). As an example:

OwaSharedThread  "1 hour"

The cleanup thread sleeps for the poll interval and then, upon awakening, checks each of your Locations to see if there are any connections that have not been used for the specified interval. If it finds such connections, it closes them. After performing the check, the cleanup thread goes back to sleep for the poll interval again.

If you are using dynamic file system caching, the cleanup thread will also attempt to remove any files that are too old. The cleanup thread will remove any file that is older than the expiration time set in the OwaCache command that created the dynamic cache, and is older than the cleanup thread's poll interval.

This feature was designed for Windows. It works on Unix, but since Apache uses a multiprocess architecture on Unix, it means that you have one cleanup thread per worker process. On Linux, this is particularly heavyweight because threads are implemented as cloned processes. Another problem with this feature on Unix is that it requires the use of system semaphores, which also have issues. If you intend to use this feature, especially on Unix, I urge you to review the section on system internals near the end of this document.

Apache 1.3 wasn't designed to be multithreaded on Unix. Of the Unix variants, I have used this feature successfully on Linux and Solaris. Apache 2.0 and 2.2 support threading with some MPMs. However, the prefork MPM is single-threaded only and the shutdown signal handling code is not thread-safe. I have experienced some crashes during shutdowns because of this. The crashes aren't harmful, but they're annoying, and if you can't live with them, don't use the cleanup thread with prefork.

If you specify a non-zero value for the global directive OwaSharedMemory, mod_owa will create a shared memory segment for caching pages and (on Unix) for inter-process communications. The segment is created at module load time, which on Unix means after the directives have been processed but before the children are spawned (mod_owa relies on the order of operations here so that the children inherit handles to the shared memory area and the associated semaphore -- otherwise, mod_owa would have to create a named shared area, or use a memory-mapped file, both of which would complicate matters greatly). The value you specify is taken to be the size of the desired shared segment in bytes. You may optionally include units, provided they appear together with the lone parameter to this directive, or appear in quotes. mod_owa will recognize units such as k (kilobytes) and m (megabytes). As an example:

owa_shared_memory  2M

On Unix, mod_owa takes advantage of the shared memory segment to track the state of database connections globally across all running worker processes, so that the SHOWPOOL! pseudo-command will provide an accurate picture of the resources in use by a site.

On Windows, this feature could have been implemented as a normal memory region common to all threads (in other words, only the mutex securing the shared area is needed). I've gone ahead and used an actual shared segment in anticipation of the Apache 2.0 architecture, which will combine multi-process and multi-threading on all platforms. If you intend to use this feature, especially on Unix, I urge you to review the section on system internals near the end of this document.

I have used this feature successfully on Windows, Linux, and Solaris. In the future, this feature should be used for a memory-based page cache, but I haven't implemented that yet.

All strings are bound to PL/SQL procedures using the DAD character set (or the character set specified in NLS_LANG). The database server must convert these strings to the server character set before passing them to the procedure (and from the server character set when returning them). However, there are two server character sets, the normal character set (used by CHAR and VARCHAR types) and the national character set (used by the NCHAR and NVARCHAR types). With Oracle 9i, the national character set is always Unicode-based. If you need to call a procedure that takes Unicode arguments, you may not want to take a (potentially lossy) conversion through the CHAR/VARCHAR character set. Moreover, you may want to manage the character set conversions yourself, supporting multiple client character sets from the same Location. mod_owa allows you to do this with the OwaUnicode directive, which has three settings:

Note that in any case the mod_owa side of the binding always uses the DAD (or NLS_LANG) character set. The main use cases for this feature are to avoid lossy conversions

1. when running utf-8 on the mod_owa side against a database that for whatever reason cannot use multibyte UTF8 as the CHAR/VARCHAR set,
2. when running different DAD character sets from multiple Apache servers and/or locations against a database that for whatever reason cannot use multibyte UTF8 as the CHAR/VARCHAR set, and
3. when serving clients with multiple character sets from the same Location (DAD).

Note that for RAW outputs, you will need to set the OwaAlternate directive appropriately.

mod_owa has the ability to run a describe operation on your procedure whenever binding parameters using the standard gateway rules fails. This describe operation is costly and I recommend avoiding it. It should never be necessary with correctly-written PL/SQL code. Describe modes are controlled by the OwaDescribe parameter, which consists of a mode and an optional schema name, as follows:

OwaDescribe  <mode>  [schema name]

The allowable values for mode are as follows:

The most common situation where a describe may be needed is to bind an argument as a singleton array, when normally this would be considered a scalar value. This is the situation that NORMAL is designed for. I must note that this can always be avoided, either by adding null-valued hidden form elements with the same name as the argument in question to ensure that mod_owa treats it as a collection binding, or by overloading the procedure in question with an additional entry point that has a scalar argument of the same name in place of the collection (and that typically would just create a singleton table of strings and pass it to the original implementation).

In general, use of describe requires that you be using the standard name-based binding mode. mod_owa will attempt to describe positional statements but must then rely on positionally matching the arguments to the order returned by describe. In this situation RELAXED is not useful, because it's impossible to tell which bindings do not have valid matches, so for positional bindings RELAXED has no effect beyond NORMAL. Describes are never done for flexible-argument procedures, because they should be unnecessary. However, since there are two variants of the flexible-argument calling convention, the 2-argument mode will be tried if the 4-argument mode fails.

I caution all users that the describe operation may fail to yield a valid result. In general, it is very hard to match signatures with a PL/SQL function because PL/SQL allows arguments to have default values (which means they need not be supplied) and because it allows overloading of a function name within a package. In cases of overloading, mod_owa is biased towards selecting the first function it finds (typically, it will continue past the first function only if it cannot find any variable that's a candidate for promotion).

You can also use this directive to specify a "describe schema". This can be useful in situations where you are separating the mod_owa run-time schema from the actual schema containing your database tables and procedures. In this circumstance, describes may fail if you use synonyms rather than prefixing your package names with the actual schema containing them (because describe returns a description of the synonym, not of the actual procedure). mod_owa will attempt to re-describe through the synonym, so in most circumstances this optional parameter is no longer useful. It's still supported for backward compatibility, and for situations where the synonym translation doesn't work correctly due to the awkwardness of OCI's describe API. If you specify a describe schema, mod_owa will append this string, with appropriate separator, to any package or procedure that it needs to describe, unless mod_owa can determine with certainty that there is already a schema specified. Note that there is one ambiguous case where a schema-prefixed procedure (with no package portion) will be mistaken as a package.

In order to make describe operations less costly, mod_owa can cache the results of doing a describe such that they can be used on subsequent calls. This saves not only the describe overhead, but the cost of failing the original statement. The cache is very primitive. Any described procedure will be put into the cache just once; therefore, overloading could be defeated by activating caching (overloading is not officially supported by the gateway standard, but mod_owa normally does its best). The cache is only capable of doing scalar promotion to collection binding mode (which is the main reason applications tend to rely on describe). The cache uses a simple linear search and probably won't scale well past a few 100s of procedures. Finally, the cache is never flushed, so if you are doing development and changing procedure signatures, you may need to bounce your Apache listener if you change something that only worked via the describe cache. Describe caching is activated by passing a "*" for the describe schema, as in:

OwaDescribe  NORMAL  *

In an effort to reduce work on the server, the Oracle database attempts to reuse SQL statement execution plans by maintaining a pool of recently-executed statements. This pool is checked whenever a new statement is parsed. The matching algorithm requires an exact textual match of the SQL statement itself, as well as a match of the data types of all arguments to the statement.

PL/SQL statements created by mod_owa are subject to this mechanism. In particular, it is hoped that frequently-called procedures will have identical SQL text and bind variable types, and therefore be able to take advantage of statement sharing. Based on your Location directives, mod_owa will always build the same SQL text for a given procedural request. Also, mod_owa will always bind all arguments as strings (or as collections of strings). Unfortunately, this is not always sufficient to ensure that statements will be shared, because the size of the bind parameters (in bytes) and of the collections (in elements) are also relevant factors in the matching algorithm.

To increase the likelihood of sharing statements, mod_owa has the ability to round the byte widths of scalar parameters to multiples of a specified value, and to round the element counts in collections to multiples of another specified value. Control of these rounding units is via the OwaRound directive:

OwaRound  <byte rounding factor> <collection rounding factor>

For example:

OwaRound  100  20

will cause mod_owa to round all strings up to 100-byte boundaries, e.g. 100, 200, etc., and will cause mod_owa to round collection sizes up to 20-element boundaries, e.g. 20 elements, 40 elements, etc.

Note that while use of this parameter will not change the data that your procedures see as input, it will increase the amount of memory required for binding the statement on the server side (in particular, collections will be rounded to boundaries that are a multiple of both, thus in the above example the smallest collection would be 20 elements x 100 bytes or 2000 bytes). Thus, using this parameter trades increased memory consumption for improved sharing (and therefore speed and scalability).

Besides higher memory consumption, use of this parameter has another drawback when used with incorrectly-coded PL/SQL procedures. Normally, procedures called by the PL/SQL gateway should not contain OUT parameters. If they do, then conceivably the procedure could attempt to write back information into the bound values (which never makes sense, since in the best case the gateway will simply discard the values). This writeback could overflow the buffers allocated; without rounding, this results in an Oracle error, but if rounding is used, it could result in a buffer overflow inside the OCI, and therefore crash mod_owa (and Apache). You should make sure that none of your procedures use OUT parameters before using this feature.

If not specified, the default behavior is to do no rounding; this is compatible with older versions of mod_owa.

HTTP requests from the most commonly-used browsers unfortunately do not contain a header which enables the server to detect the character set in which the request is formatted. This forces web site developers to make assumptions about the browser character set. As described elsewhere in this document, mod_owa allows you to set up different Locations with different assumed character sets using the OwaCharset directive.

In the limited case where the server's character set (set either through NLS_LANG or via OwaCharset) is a Unicode equivalent (e.g. "AL32UTF8"), mod_owa can be instructed, via the OwaBindset directive, to check that all incoming data contains only valid Unicode byte sequences. If OwaBindset is specified, mod_owa will make this check on every request. If any string data is found to contain invalid bytes, then mod_owa will use the Oracle character set specified in OwaBindset as the character set bound via OCI for marshalling of the procedure arguments.

The check adds overhead to every request, whether or not invalid bytes are actually found. The check stops as soon as any invalid bytes are found. The bind override is applied only to inbound bindings for normal procedure calls. It has no effect on document upload/download operations. Outputs continue to be produced in UTF8 (so the response page sent by the Location will still bear the "utf-8" character set).

The intended use of this feature is to enable you to support two populations of users from a single Location, one population using UTF8 and another using a single-byte Western European character set. This check is not foolproof. It will always detect invalid byte sequences, but it is possible for requests that aren't in UTF8 to nevertheless have byte sequences that appear to be valid. The chances that this will occur vary by character set and by the amount of content (the more content, the less likely it will be that the byte sequences will appear valid). Specifically with respect to the commonly-used single-byte Western European character sets ("WE8MSWIN1252" and "WE8ISO8859P1"), it's very likely that the check will be able to catch the invalid bytes and rebind them. The feature is less likely to work reliably with other multi-byte character sets, or with single-byte character sets for scripts such as Greek, Cyrillic, or Arabic. The feature will not work correctly if the Location is not running UTF8 or AL32UTF8; OwaBindset doesn't check this, though, so you should do so before using it.

Many users have asked about running Apex using mod_owa instead of modplsql. It's not clear whether mod_owa can support Apex because Apex may rely on calling/binding modes that aren't supported by mod_owa. Also, Apex relies on the WebDB file upload/download interface to receive and deliver content via a documents table. I've made some effort to partially resolve these issues:

• Calls via the multipart/form-data content type
  Apex relies on these for many of its normal procedure calls, whereas mod_owa sees that content type as exclusively triggering a file upload operation.
• Uploads to a document table, and downloads from either an in-line binding from WPG_DOCLOAD or from the document table.

Specifying the OwaDocTable argument disables mod_owa's file upload interface in favor of WebDB's. multipart/form-data calls will be brought into memory and prepared as procedure arguments. Any file arguments are written to the document table and the system-assigned name of the file is passed to the procedure in place of the original argument value.

This experimental feature is activated by using the OwaFlex directive and prepending an "@" sign on the package/procedure name. Example:

OwaFlex  @YOUR_PACKAGE.YOUR_PROCEDURE

mod_owa will call your procedure with two extra OUT arguments, the first of type SYS_REFCURSOR and the second of type VARCHAR2:

begin
  YOUR_PACKAGE.YOUR_PROCEDURE(:B1,:B2,:B3,:B4,:B5,:B6);
end;

:B1 is an input with the number of name/value pairs
:B2 is an input array of parameter names
:B3 is an input array of parameter values
:B4 is an input array reserved for future use
:B5 is an output of type SYS_REFCURSOR
:B6 is an output of type VARCHAR2

Your procedure should return any HTML headers, including the content type and request status, using the usual OWA facilities. If you need to return anything other than a standard success response, render it in the usual way and do not return a REF cursor. mod_owa will pick up your headers via the standard GET_PAGE operation, and, if necessary, any error page. However, if you return the standard success response, and a content type that is not text/html, mod_owa will expect an open cursor to be returned in the fifth argument, and mod_owa will iterate over this cursor streaming a response body to the client.

mod_owa will look at the content type you return to decide how to render the results. If the content type is text/html, mod_owa assumes you didn't return a REF cursor and expects the rest of your content to be returned by GET_PAGE. Otherwise, mod_owa expects a valid REF cursor to be returned. If no content type is returned, mod_owa defaults to using text/plain as the content type. If your content type isn't one of the types listed below, mod_owa will process your data as text/plain (but still leave the content type you set, e.g. text/richtext). Supported content types:

• text/plain
• text/csv
• text/xml
• application/json

mod_owa accepts two types of cursor return pattern:

• Cursor returns multiple columns with no LOBs
• Cursor returns a single column of type CLOB

For the multi-column return, mod_owa behaves as follows:

Note that mod_owa picks up all column values as string bindings, including any numbers, dates, timestamps, RAWs, etc. The default formatting implied by your NLS environment settings will be used. To control the formatting in your application, perform a TO_CHAR in your SQL statement.

If a CLOB is returned, the CLOB is expected to contain a pre-rendered "row" in one of the above formats. mod_owa makes no attempt to verify this, but simply streams the contents to the client. For text/csv, the rows are presumed to be CSV rows (the cursor may return a header row or not, as desired, but mod_owa won't know or care that this was done). For text/xml, mod_owa assumes the content represents a whole element, and uses it instead of creating a <row> element; effectively, each LOB is concatenated within the stream underneath the <collection> element. For application/json, mod_owa assumes the content represents a valid JSON object suitable for use as an array element; the LOB contents are concatenated with comma delimiters. In all cases, with CLOB returns, any necessary escaping and formatting is assumed to have been done on the server!

The optional OwaRefXml directive can be used to override the XML tags used for the root and row elements, including specification of an XML namespace prefix and URI. Note that if a namespace is specified for the multi-column rendering mode, it will be used for all column tags as well.

The last argument of type VARCHAR2 can be used to return content type specific information to the renderer. This is used by both the JSON renderer and the XML render, in different ways. (For other content types, it's reserved for future use.)

The JSON renderer uses the value as the name of a wrapper field for your collection return. It's useful to protect your site against a JSON scripting attack against unprotected browers. Return a non-null string to use as the name of the array that will contain your rows.

The XML renderer uses the value to override OwaRefXml, or in lieu of it. You can return a whitespace-delimited string containing the root and row tag information, along with the namespace prefix and URI, in a form similar to the OwaRefXml directive. Note that since spaces are used as the delimiter each space is significant (this allows you to return blanks for some values.

This code path is new and relatively untested. In particular error handling of bad REF cursors is not well understood, nor are the implications of cursor creation in response to requests. Badly-behaved applications or error conditions may result in cursor "leaks". The adequacy of the escaping is also not known. Use of the CLOB method has memory/scalability implications if the CLOBs are temporary. Once again, error conditions may lead to "leaks" of temporary LOB objects. Finally, if the server uses the CLOB method, the entire burden of accurately rendering a safe response rests with the server-side code.

By default, mod_owa only handles GET and POST requests. With the optional OwaHttp parameter, this can be expanded to include PUT and DELETE requests, or even the full set of DAV requests.

• NORMAL
  The mod_owa default, compatible with earlier releases.
• REST
  Enables mod_owa to handle PUT, DELETE, and PATCH to support REST services.
• DAV
  Enables all DAV operations (not yet completed).

If the request contains a content body that cannot be interpreted as HTML form arguments, and the content body is not of zero length, mod_owa will treat it as a file upload. This is enabled only if REST or DAV is specified. The body is delivered as an extra parameter, MODOWA$CONTENT_BODY. For now, this works only with the Apex-style document upload (OwaDocTable). The HTTP method can be obtained from the CGI variable "REQUEST_METHOD".

A related parameter is OwaDav, which allows you to configure a procedure to handle REST (or, eventually, DAV) requests. If configured, this parameter takes precedence over OwaDocProc (or other file-like path handlers). The configured procedure is called in the 4-parameter flexible argument mode. The REST path (if any) is delivered as an extra parameter MODOWA$REST_PATH.

Optionally, if you precede your package/procedure name in OwaDav with an "@" sign, mod_owa will call it in the 6-argument REF cursor mode described earlier.

For various reasons, some mod_owa users have wanted to write their own version of the PL/SQL side of the gateway interface, in effect replacing the OWA packages with their own implementations of similar APIs, possibly with enhanced or specialized functionality. Typical reasons for using an alternate implementation include:

• Generating and returning RAW content (Oracle's OWA only supports character data for dynamic pages).
• Keeping PL/SQL state between HTTP requests (Oracle's OWA is not designed to support this sort of reentrancy).
• Doing on-the-fly content generation during streaming (Oracle's OWA requires that you generate your page into its internal buffer before data transfer starts).

mod_owa supports alternate mechanisms via the OwaAlternate directive. When this directive is set, it specifies the name of an alternate package to use for the basic functions of INIT_CGI_ENV, AUTHORIZE, and GET_PAGE. When the package is specified, mod_owa will build

begin <package_name>.INIT_CGI_ENV(:ecount, :namarr, :valarr); end;

for the environment variable transfer,

begin
  <package_name>.USER_ID := :usr;
  <package_name>.PASSWORD := :pwd;
end;

for the Basic authentication transfer,

begin
  if (<package_name>.AUTHORIZE) then
    ...
  else
    :realm := <package_name>.PROTECTION_REALM;
  end if;
end;

for the authorization check (unless you've disabled authorization or requested the per-PACKAGE check), and

begin <package_name>.GET_PAGE(:linearr, :nlines); end;

for the final page fetch loop.

In the special case where "OWA" is passed as the package name, no change to the above calls is made (this is so that you can use some of the additional parameters below in conjunction with Oracle's official OWA).

You may also specify one or more additional parameters to switch on customized functionality:

• KEEPSTATE
  When this flag is included, it suppresses the generation of the DBMS_SESSION.RESET_PACKAGE call, thus enabling your code to keep state between requests. This is useful mainly for caching and other similar optimizations. Note that because of Apache's pooled process/thread architecture for workers, there is no guarantee that subsequent requests from the same client will be routed to the same database session and hence the same PL/SQL package state. Also, note that your OWA alternative and all of your other PL/SQL code should be written so as to be re-entrant (Oracle's OWA is not re-entrant). Use of this flag takes precedence over OwaReset.
  
  
• WITHRAW
  When this flag is included, it causes mod_owa to generate an alternate call to GET_PAGE where the content is returned in two parts:
  
  
  1. the header elements, plus the first block of character content (if any), as a single string of up to 32512 bytes, and
  2. the first block of raw content (if any) as a single buffer up to 32512 bytes.
  
  There is also a flag to indicate if more data is available than was transferred (return null on the last content transfer, any other value if more content is still waiting for transfer).
  
  The call is generated as follows:

  begin <package_name>.GET_PAGE(:cbuffer, :rbuffer, :moreflag); end;
  

  The header elements should be concatenated with newlines as separators (mod_owa will pass in a newline with the value of :cbuffer, which is an IN/OUT parameter). If returning character-typed content, an additional newline should be appended before starting to append the content values. For binary content, return the first block in the RAW buffer. For all subsequent transfers, place the next chunk of the content into either the cbuffer or rbuffer as appropriate, setting the unused buffer value to null. Do not return content in both buffers (except during the first call, when a header may be returned with the first block of raw data); if you do, mod_owa will use the raw data in preference to the character data. To signal the end of the stream, return nulls in both buffers and/or set the flag to null.
  
  
• USELOBS
  When this flag is included, it causes mod_owa to generate an alternate call to GET_PAGE where the content is returned in three parts:
  
  
  1. the header elements, as a single string of up to 32512 bytes,
  2. a binary LOB, for binary content return types, and
  3. a character LOB, for character content return types.
  
  The call is generated as follows:

  begin <package_name>.GET_PAGE(:header, :pblob, :pclob); end;
  

  The header elements should be concatenated with newlines as separators (mod_owa will pass in a newline with the value of :header, which is an IN/OUT parameter). Only one of the two LOBs should be returned with content, the other should be set to null. Note that this flag overrides WITHRAW if both are present.
  
  
• GETRAW
  When this flag is included, it causes mod_owa to generate a call that supports raw transfers, as follows:

  begin <package_name>.GET_PAGE_RAW(:rawarr, :nraw); end;
  

  This call works just like the GET_PAGE interface, except that the content is returned in an array of raws rather than an array of strings, each up to 256 bytes in length. The value of nraw is set on input to be the maximum number of rows to be returned, and on output should be the actual number of rows returned. As with the standard GET_PAGE, this is called until no more rows are available.
  
  Note that even textual content is returned via this interface; this allows you to return pages in alternate character sets and perform content-length calculations within the server code.
  
  The OWA requires that the gateway module signal that raw transfers will be done, so that during the time that your procedure is writting the page, it can buffer the data in raw form. To signal this, mod_owa will alter the security-passing statement to appear as follows:

  OWA.SET_USER_ID(:usr);
  OWA.SET_PASSWORD(:pwd);
  OWA.ENABLE_RAW_MODE;
  

  Oracle will include the new GET_PAGE_RAW interface in a future release of the official OWA, making this the preferred technique for extending the OWA for raw support. As such, you should consider the previously-described WITHRAW and USELOBS modes obsolete. This flag takes precedence over the others if inconsistent settings are present.
  
  
• CACHE
  When this flag is included, it causes mod_owa to generate a special check after the call to your routine. The operation of this check is described in the next section. In conjuction with file-system caching, this flag allows your alternate implementation to direct mod_owa to cache files on the file system. In fact, you can do it with Oracle's OWA as well -- just specify "OWA" as the package name, as in:

  OwaAlternate  OWA CACHE
  

• SETSEC
  When this flag is included, it causes mod_owa to pass the Basic authentication information via function calls, rather than via direct assignments to package global variables. Thus, where it would normally use

  OWA.USER_ID := :usr;
  OWA.PASSWORD := :pwd;
  

  it will instead use

  OWA.SET_USER_ID(:usr);
  OWA.SET_PASSWORD(:pwd);
  

  This was designed to work around a crash in PL/SQL that relates to the use of the direct assignment statements after a RESET_PACKAGE. You can use this with Oracle's OWA, but only if you've modified the code (in pubowa.sql and privowa.sql) to include the necessary functions (a future release of the code will include them). Note that if GETRAW is used, SETSEC is assumed, since the form of the statement will use the new function calls.
  
  
• NOMERGE
  When this flag is included, it causes mod_owa to skip merging of URL parameters with content arguments when processing POST requests. This mode is compatible with a bug found in older versions of mod_owa.
  
  
• CGITIME
  When this flag is included, it causes mod_owa to build an extra call into the CGI environment-passing statement. The complete call is then:

  begin
    <package_name>.INIT_CGI_ENV(:ecount, :namarr, :valarr);
    <package_name>.INIT_CGI_EXTRA(:rtime, :postargs);
  end;
  

  The second call is added to pass the elapsed time in milliseconds since the request was received by Apache. The postargs parameter is an empty string unless CGIPOST is set.
  
  
• CGIPOST
  When this flag is included, it causes mod_owa to build an extra call into the CGI environment-passing statement, similar to the statement used for CGITIME, but included up to 32k of the post arguments in the postargs parameter. If the statement is not a POST, an empty string is passed.
  
  
• IPADDR
  When this flag is included, it causes mod_owa to build extra lines into the CGI environment-passing statement that sets the value of OWA.IP_ADDRESS if a client IP address is available.
  
  
• LOGGING
  When this flag is included, it causes mod_owa to build an extra call into the GET_PAGE content retrieval statement. The extra call is used to return logging information to mod_owa from the PL/SQL environment. The LOGGING flag is incompatible with the USELOBS, GETRAW, and WITHRAW return modes. The complete call is:

  begin
    <package_name>.GET_PAGE(:linearr, :nlines);
    <package_name>.GET_LOGS(:logs, :ilogs);
  end;
  

  Though the statement is run repeatedly and makes both calls each time, only the logging content returned on the first invocation is used by mod_owa.

The flags must follow the package name, separated by spaces. For example:

OwaAlternate  MY_OWA_PKG  KEEPSTATE USELOBS

Since mod_owa has all the infrastructure necessary to cache content to the file system, I've added a special mode of operation to allow you to use mod_owa to cache your dynamically-generated pages as well. This mode is enabled by setting the value "CACHE" in the OwaAlternate directive (remember, it must follow a package name, even if the package is "OWA" itself).

When this mode is enabled, it changes the call that mod_owa generates to execute your procedure, causing mod_owa to add an additional call to check for a cache request, as follows:

begin
  if <authorization_call> then
    <package_name>.<procedure>(<arg1_name> => :B1, ...);
    <package_name>.CHECK_CACHE(:O1,:O2,:O3,:O4);
    commit;
  else
    :realm := OWA.PROTECTION_REALM;
  end if;
end;

:O1 is an output string where you can return a logical document URI
:O2 is an output string where you can return a string to be checksummed
:O3 is an output binding for the page mime type
:O4 is an output binding for the cache lifespan (in seconds)

Before the call, mod_owa will set an environment variable, "MODOWA_PAGE_CACHE", to "enabled" and pass this in the CGI environment, where your procedure can look for it to decide if it should attempt to hit the cache. If it does decide to hit the cache, then you should arrange for the routine CHECK_CACHE to return a non-null value for the logical document URI. You should also arrange for CHECK_CACHE to return the mime type that your procedure would have returned had it actually run. You can optionally also arrange for CHECK_CACHE to return a string to be checksummed and appended to the document URI (more on that later). You can also optionally return a lifespan which will take precedence over the setting in OwaCache (for this document only).

Note that the CHECK_CACHE call is generated in such a way as to be in the same package as your procedure. In this way, you can easily arrange for the procedure to return results through CHECK_CACHE by using PL/SQL package global variables. If the original operation was not a packaged procedure, then page caching is not supported.

The URI you generate should be a logical document path that matches the logical path name of one of the caches you specified with OwaCache, for example "/docs/mycache" (refer to the earlier description of logical and physical locations and the OwaCache directive). You cannot use a logical location that's mapped as a static cache, however, because mod_owa will never attempt to write to a location designated as static. If a valid logical location is found to match, mod_owa will translate the logical name to a physical file name, look for a file with the correct name, and check the lifespan versus the specified expiration time you return from CHECK_CACHE. If the file is found, that's it, mod_owa returns it using the file download mechanism described earlier.

If mod_owa doesn't find the file in the cache, then it will re-execute the same statement shown above, with the expectation that this time your procedure will actually produce some content for return via GET_PAGE. (For this reason, your procedure should set some sort of package-level flag to indicate to itself that it's already been called once in the current context, and that it should not make yet another attempt to hit the cache.) mod_owa will keep the physical name from the previous call, so on this second call you needn't return anything (other than nulls) from CHECK_CACHE.

To summarize the process:

begin
  if (OWA_UTIL.GET_CGI_ENV('MODOWA_PAGE_CACHE') = 'enabled') then
    if (FIRST_CALL) then
      ...generate values for URI, checksum, mime type, and lifespan...
      ...set them in package globals so that CHECK_CACHE returns them...
      FIRST_CALL := false;
      return;
    end if;
  end if;
  ...generate your content normally...

Note that you can completely avoid the cache mechanism in any circumstance desired by arranging for CHECK_CACHE to return a null for the URI argument, thus:

begin
  if (OWA_UTIL.GET_CGI_ENV('MODOWA_PAGE_CACHE') = 'enabled') then
    ...set globals so CHECK_CACHE returns null URI...
  end if;
  ...generate your content normally...

The keys to success with caching these dynamic pages are:

1. proper selection of the lifespan, and
2. proper uniqueness of the physical file name generated.

mod_owa can't do either of these things for you, since it has no way to know which aspects of the request (arguments, cookies, etc.) are relevant to include when generating the file name, and which are not, nor does it have any way to know when the cached content should expire. In general, you should strive to put some sort of unique identifier into the base URI, perhaps combining the procedure name with some key argument value, e.g. if ORDERS.GET_ORDER is called for order 101, generating:

/docs/mycache/orders$get_order$101$.htm

as the URI is helpful, though perhaps not sufficient. One problem you may run into is that because file system names are limited, you might not be able to pack enough information into the URI and still have a valid file name. To mitigate this problem, you can return up to 32512 bytes of information from any source desired as the second argument of CHECK_CACHE, and mod_owa will run CRC32 on the data and append an 8-digit hexadecimal string to your URI to help ensure uniqueness. If a checksum is inserted, mod_owa will place it just ahead of any file extension that's present, e.g. in the previous example you might get

/docs/mycache/orders$get_order$101$12345678.htm

As noted earlier, Oracle has many technologies that are far more capable than this one.

The OCI imposes a width limit of 4000 bytes for collection bindings. In most cases, you should be able to design your PL/SQL interfaces so that large values (up to 32512 bytes) are passed as scalars. This is not the case if you are using the flexible argument passing mode, however.

In situations where you are using the flexible argument calling mode, either directly by prefixing the call with "!" or indirectly via the OwaFlex directive, mod_owa will break any argument value larger than this 4000 byte limit into "chunks". mod_owa will signal this to your code by appending a "chunk number" to the parameter names. For example:

given:             MYPARAMETER=<6000 byte string>

mod_owa generates: ["MYPARAMETER.1",   "MYPARAMETER.2"  ]
                   [<3999 byte chunk>, <2001 byte chunk>]

Note that each chunk is slightly smaller than 4000 to allow space for the string's trailing null terminator.

Please note that this mode of operation is invoked only when using the flexible argument calling mode from a normal request; it is not used for collection bindings that are created for other calling modes, nor is it used when performing the flexible argument call for document operations.

This mode of operation may not respect multi-byte character boundaries. Some logic has been added to attempt to break the chunks on even character boundaries, but hasn't been tested and probably won't work with all character sets. Oracle's character-handling logic has real trouble with strings containing odd bytes (fractional characters), so beware! This feature is here primarily because the alternative is to generate an error.

On modern versions of the OCI, the array width limit is now 32512, so chunking may not be relevant anymore. mod_owa will still run the above chunking logic, but it will do so for values larger than the 32k limit.

Creating a database connection involves a login-like operation that can cost significant time if the database is located on a machine other than that of the Apache server (and even if on the same machine). Also, parsing statement handles is somewhat costly especially when they involve PL/SQL anonymous blocks. To avoid these costs, mod_owa keeps the database connections and cursors it uses to process a request, and reuses them on subsequent requests.

On single-threaded implementations (currently all 1.3 Unix ports including Linux and Solaris), there is no point in having more than one connection per Location, because any particular httpd worker process can only be servicing a single user request at a time. So, in these cases, the connection "pool" has a single entry, which is filled on the first successful request and thereafter reused for every other request.

On multi-threaded implementations (currently only Windows for 1.3, but any platform for 2.0), the process may have to handle multiple requests at once. During virtually the entire time a request is being processed, a database connection will be in use (because the database side of the operations is where all the time goes). Since it would be undesirable to have user requests single-thread through a solitary database connection, a pool of reusable connections is needed. Each Location gets such a pool with up to 255 available "slots". Initially the pool will be empty; the first successful request for a PL/SQL call will fill the first slot with a reusable connection. Afterwards, this connection will be reused unless it is in use (locked) by another thread, in which case the next slot is examined/filled, and so on. The maximum pool size is tunable per Location in the httpd.conf file. Each pool has a mutex (sometimes called a "latch") to ensure that the process of obtaining a connection from the pool is orderly. The code keeps the time window during which a thread must be latched as small as possible, since this represents a potential bottleneck. Also, each pool has a semaphore that is decremented whenever a connection is drawn from the pool, and incremented when connections are returned to the pool. In situations where the pool is at maximum capacity and every connection is in use, threads requiring a connection will be blocked and queued for the first available resource. The blocking mechanism is timed out after 1/2 second since at that point it's probably faster to create a new connection for one-time use.

A special value can be supplied for OwaPool to enable operation without the use of a semaphore, "THREADS". If this keyword is supplied, mod_owa will use 255 for the maximum number of connections in the pool, and additionally will skip creation and use of any semaphore for that location. This mode can be useful in situations where you are certain that the number of threads cannot exceed the number of connections in the pool (in other words, that the pool size is thread-count limited and not actually limited by OwaPool). This mode is particularly useful when running with Apache 2.0 using the "prefork" mode, since it avoids the unnecessary creation of a semaphore for a pool of only 1 connection. It's also useful when running any multithreaded Apache configuration where the number of threads has been limited to a value less than or equal to the desired pool size (note: do not use this flag if you are going to set the number of threads to a value greater than 255!).

The connection pool normally uses a first-available search strategy, minimizing the time spent in the latched state. If the OwaSession directive is used, and the specified cookie is seen, mod_owa uses a more complex three-pass algorithm to find a connection, preferring first a connection with a session identifier matching the cookie value, then an unsessioned connection or pool slot, and finally reuse of any available connection even if marked with a different session identifier.

No particular effort has been made to make mod_owa secure, and mod_owa cannot ensure that a user-written PL/SQL application is secure. Developers of any web application are well advised to become conversant in common web vulnerabilities and secure application coding and deployment practices. The list below notes a few issues that have occurred to me.

• Hiding .conf files
  Since database passwords are present in the Location directives, you need to make sure that not only are httpd.conf and its dependencies secure against writes, they should be secure against read by unprivileged users. A better practice is to use external database authentication via the Oracle Wallet or OS.
• Diagnostic file
  If you turn on diagnostics, lots of potentially sensitive information may get written to the log file. The log file must be writable by the user that Apache is running the worker processes as, too.
• Use of https
  mod_owa works with SSL and https on Apache 2.x. I am not able to test mod_owa with SSL on Apache 1.3, but several users have reported that it works fine.
• Control functions
  The control functions create a potential exposure based on how you convey the password that enables them. If this is passed in the clear in either the URL or in POST parameters, you risk exposing the database password. Probably you should just avoid using the control functions completely except during development; at a minimum you should use https when issuing control requests.
• Control displays
  The control displays show potentially sensitive information; another reason to avoid them, use https, or restrict access to machines you control (and whose IP addresses are local to your network and cannot be spoofed).
• Control password
  Because the control functions use the database password as the key to the location, they're vulnerable to attack by sending repeated requests with generated passwords in the URL. You should make sure that your database password is not something that will be easily discovered by such a brute-force technique, and/or restrict the IP addresses that are allowed to perform control functions.
• Protecting database procedures
  Through mod_owa, any URL could conceivably attempt to run any procedure in your database account, or even procedures from the SYS account (e.g. DBMS_ and UTL_ packages, the packages of the OWA_ itself, etc.). If this is a concern, you need to protect these procedures through use of the AUTHORIZE function. The simplest technique is to specify the PACKAGE authorization mode, and put this function into only those packages you wish to expose. (Protect regular procedures by coding the OWA_CUSTOM.AUTHORIZE or OWA_INIT.AUTHORIZE to disallow all other operations.) Another technique would be to check the procedure about to be executed in OWA_CUSTOM.AUTHORIZE or OWA_INIT.AUTHORIZE by looking at the CGI, and allow only those procedures you desire. The OwaReject directive can be used to exclude packages/procedures by prefix, though this requires you to list every class of procedures to be rejected; it is not as easy to be certain your code is secure using this technique.
• Protecting database tables
  It can be useful to separate the schema containing your application objects (tables and procedures) from the schema against which you will run mod_owa. This way, the user that mod_owa connects as can be prevented from any direct access to your tables and other database objects, except through APIs that are granted to that user. Synonyms can be used to make the procedures runnable without schema prefixes. An even cleaner technique would separate the user-interface logic from any data access logic, such that the user-interface logic could be installed in the mod_owa schema without needing synonyms.
• Trojan horses via US7ASCII
  Oracle's character-set conversion logic has a peculiar behavior when 8-bit data is passed from a client that's supposed to be using a 7-bit character set (such as US7ASCII, the default if you don't set NLS_LANG). The behavior is that strings are bit-stripped down to 7-bit codes. This provides an opportunity for a false "procedure" to slip past the normal checks against spaces, punctuation, etc. that are done by the gateway when building a statement. The database will see the code as ASCII characters, folded down from the 8-bit range. It might be possible to get malicious code fragments through the gateway in this manner. I strongly recommend always running an 8-bit or higher character set to prevent this (in addition to checking procedure names in the AUTHORIZE procedure, of course).
• SQL injection
  Although mod_owa uses bind variables for all arguments to your procedures, the package.procedure name itself is taken from the input URL. Moreover, because the gateway is case-insensitive, mod_owa isn't able to surround the name components in double quotes to protect against malicious code. Instead, mod_owa strictly limits the characters that can be used in the package and procedure name portion of the URL, and truncates it at the first disallowed character. In practice, this means that package and procedure names are limited to the alpha-numeric characters, the underscore, pound sign, dollar sign, and period.
• Caches
  The file system cache, and, eventually, the shared memory segment, are potential security holes. These areas are read/written by the user that Apache runs as, and are no more secure than that user. The shared memory segment is especially vulnerable. Either don't use them or use them only for publically-viewable information. Also, make sure that the file system directories used for caching can't be written by unprivileged users, otherwise someone could substitute fake content for real content.
• Basic authentication
  This venerable web standard isn't terribly secure, and most sites that really care about security have their own login page and session-management logic. mod_owa doesn't particularly make the security of Basic worse, but it doesn't improve it, either. mod_owa will pass the value of the basic authentication header to PL/SQL in the CGI environment; this header is base-64-encoded but is not encrypted in any way.
• OCI traffic
  You may want to take steps (via Oracle's technology) to ensure the security of your OCI network traffic.
• WebDB file upload/download table
  The WebDB style of file transfer could have security issues if not handled carefully. On download, for example, it seems as if a file staged in the table could be visible to another user/session if that user was able to guess the name/key to the table and type it into his/her URL. The document download procedure will have to guard against this by checking every request, and in addition it would seem wise to generate secure random keys. Even better would be to avoid the table completely and always return content via the WPG_DOCLOAD interface. On upload, there are similar problems; the inbound file is staged to the document table prior to calling the action procedure. mod_owa will prepend a random value to the file name as part of the key, but there is no assurance that this is completely unguessable. The called procedure should ideally rename the staged file to a secure name, or move it to another table, as part of the overall transaction associated with the request.
• Cross-site scripting
All web applications that present dynamic content are potentially vulnerable to users who put scripts or tags into their data with the intent of having the application play this back to a browser and reveal sensitive information available on the browser. A simple example is a short piece of JavaScript that extracts a session cookie from DOM and then forms and sends an HTTP request to another web site where the attacker can capture the cookie value. Your PL/SQL application should guard against this by properly escaping any responses. Note that the ability to upload files with content types, and the ability to download them, creates the potential for users to upload HTML files and JavaScript sources that could be sent back to the browsers of other users. Consider disabling file upload/download, limiting its use to administrators, and limiting files to whitelisted content types.

Little analysis has been done regarding the scalability of Apache with mod_owa. For what they're worth, here are some observations made by myself and other users (many thanks to Nate Neely for helping to flush out these issues):

• DBMS_SESSION.RESET_PACKAGE
  Flushing the PL/SQL package state on every request is costly of database resources, and it also defeats attempts to cache results in PL/SQL for performance. If you have a recent version of the database (8.1.7.2 or higher), you can use the OwaReset "LAZY" mode to defer the reset work until actually needed for a particular package. This mode also eliminates the needless flushing of cached cursors for PL/SQL static SQL statements. An even more efficient mode of operation is to eliminate state flushing entirely, which you can do via the KEEPSTATE option of the OwaAlternate directive. This requires that all PL/SQL code (including yours) be re-entrant. Since Oracle's OWA is not re-entrant, this assumes that you have your own re-entrant OWA implementation. The latest version of Oracle's OWA can be reset independently using HTP.INIT, so if your PL/SQL code is re-entrant, you can set the "INIT" mode of OwaReset to cause flushing of only the OWA packages.
• Statement sharing
  The Oracle database maintains a list of statements and attempts to reuse them if they are re-executed later. Oracle's matching criteria require that the statement texts be identical, and also require that the bind variable data types match. Unfortunately, the type match for strings is sensitive to the exact byte size specified, and for collection bindings is also sensitive to the number of elements in the collection. Since mod_owa builds statements dynamically, the odds of hitting the shared cache are low, and it may fill up with near-duplicates and lead to contention for the latch on the shared area. Consider using the OwaRound directive to reduce the effect of this.
• Connection exhaustion on Unix
  Some users of mod_owa on Unix have reported that mod_owa's connection pooling (really, connection reusing) feature has caused exhaustion of available connections against their data server. This could happen if, for example, the number of Apache worker processes exceeds the number of database connections available, and each worker has serviced an OWA request. Unfortunately, because Apache is not multithreaded on Unix, there isn't a good way to handle this problem. As far as I can tell Apache worker processes are undifferentiated, so any particular request might get handled by any of the workers; thus, attempting to limit the number of active connections to a number lower than the number of workers will eventually result in a set of workers that are holding connections for reuse while other workers are unable to get a connection with which to service an OWA request. If you must set the number of workers to a value larger than the available database connections, you will have to disable the connection reuse feature, by setting OwaPool to 0 in httpd.conf. Even this doesn't guarantee safety, since it's still possible that a number of requests for OWA service exceeding the data server's connection limit might arrive simultaneously. Forwarding OWA-related traffic via proxy to a dedicated Apache server with worker count limited by available connections is another possibile solution.
• Connection thrashing on Unix
  As load increases on an Apache site, Apache spins up additional worker processes to handle it. If this load includes OWA traffic, these workers will acquire database connections, which mod_owa will attempt to hang on to for reuse. Once load subsides, Apache is very aggressive at tearing down the additional workers; this process begins within seconds and completes within a minute or so. The effect is to tear down all the database connections for those workers, too. If the load on your site is bursty in nature, this could be a problem. One possible solution is to set the worker process floor (MaxSpareServers in httpd.conf) to a high value, perhaps even to the same level as the worker limit (MaxClients in httpd.conf).
• Consumption of semaphores on Unix
  When a multithreaded Apache becomes available on Unix (Apache 2.0), mod_owa needs a semaphore to control access to the connection pool for each Location. Thus, if there are 10 workers each with 2 Locations, that's a total of 20 semaphores potentially needed. OSes may limit the total number of semaphores allowed; if you run out, mod_owa falls back to serializing database operations by creating and destroying a connection for each OWA request (basically, the behavior coded by the original authors). The latest release of mod_owa uses process-bounded pthread condition variables to eliminate the dependency on semaphores, and to ensure cleanup on process exit; however, the underlying OS may implement this using semaphores anyway.
• Loss of database connections
  If Apache workers are not shut down cleanly, it is possible to "lose" system resources that were being used by those processes. The chief danger is severing connections to the database when a hard "kill -9" (or the NT equivalent) is done on Apache. The database has its own worker processes (called "shadow" processes) that are created whenever a client (such as a mod_owa-based Apache) connects. Unless the shadow was doing a network operation at the time Apache was killed (the normal state is they're just hanging on a socket waiting for requests), it won't know that the client has been shut down. Eventually Oracle may reclaim an inactive shadow, though DBAs typically set this timeout to a large value (or not at all). Eventually the OS networking code may deliver an error on the socket, but don't hold your breath for that, either. For this reason, avoid using kill scripts (such as RedHat's /etc/rc.d/init.d/httpd) to shut down your server; use apachectl stop instead. Note that older versions of mod_owa did not close database connections cleanly on Apache exit (it was documented but perhaps overlooked), because I had not found a means by which to do so reliably. The current 1.3 version will close all database connections (except perhaps a long-running in-flight transaction) when a process undergoes an orderly shutdown. However, thanks to changes in termination processing for Apache 2, this no longer works reliably.
• Loss of system resources
  In addition to losing database connections, it's possible to lose system resources such as shared memory segments and semaphores due to an unclean shutdown (and, on some platforms, despite a clean shutdown). mod_owa uses these resources on Unix only if you use the shared memory and/or cleanup thread options; otherwise, there's no issue. Shared memory is particularly problematic because Apache 1.3 doesn't deliver an event whereby mod_owa can close down the shared segment in an orderly fashion. On Linux and HP/UX, it gets around this problem by marking the segment for deletion immediately after attaching it, thus ensuring that the segment is reclaimed when the last attached process exits. However, this is not possible on Solaris, so the segment is "lost" each time the server is started and stopped (you can reclaim it manually with the ipcs and ipcrm utilities, but it's annoying). A semaphore is used for latching the shared memory area, too, and this semaphore is also lost every time the server is cycled. Semaphores can also be reclaimed manually with ipcs and ipcrm.
• Windows
  Many of the above issues aren't much of a problem on Windows, because there Apache uses only one worker and multiple threads. This architecture ensures that your total number of connections can be limited to the pool size, despite a larger number of worker threads (under stress, some OWA requests may be queued waiting for connections from the pool). This architecture also means you won't be creating and destroying connections as worker processes are created and destroyed. This architecture also means that per-process system resources such as mutexes and semaphores will be limited in number. Thus, the only real issue is to ensure that resources and database connections are cleaned up, which they will be if you perform an orderly shut down.

A full discussion of character-set handling via HTTP and by Oracle is beyond the scope of this document. In this section I'll try to explain the basic theory of operation regarding how character data is handled by mod_owa and Oracle, so that it may serve as an aid to users trying to diagnose character-set-related problems.

Oracle character sets

Oracle has a long list of supported character sets, each of which is given a unique name. You'll need to consult your Oracle documentation for more information on them. Some commonly-used character sets include US7ASCII (standard 7-bit ASCII), WE8ISO8859P1 (which is the ISO Latin-1 set commonly used in Western Europe and the Americas), and AL32UTF8 (which is multi-byte Unicode). Note that these names may or may not have mappings to the so-called IANA character sets that HTTP uses. For example, the IANA set "iso-8859-1" is the same as WE8ISO8859P1.

Database character sets

Every database has two character sets that are determined at the time the database is created. These character sets are the database character set and the national character set. The database character set is the character set used by all CHAR, VARCHAR, and VARCHAR2 columns and PL/SQL buffers. The national character set is the character set of the NCHAR, NVARCHAR, etc. types. For brevity, I will call these the VARCHAR set and the NCHAR set, respectively. For the purposes of the OWA, only the VARCHAR set is relevant, because all the PL/SQL interfaces use VARCHAR2 data types (unless you use the OwaUnicode directive described previously). The VARCHAR set is the character set that all string data will be stored on disk in, and it's the character set that all string data is stored in while in memory (for example, in a buffer within a PL/SQL function. If you're uncertain what character sets the database is using, you can find out by selecting them from V$NLS_PARAMETERS with this command:

select PARAMETER||'='||VALUE from V$NLS_PARAMETERS
 where PARAMETER in ('NLS_CHARACTERSET','NLS_NCHAR_CHARACTERSET');

The database character sets are, in a very real sense, "baked in". Once you create a database with certain sets, you're stuck with them, because (obviously) you will have row data stored in the database ("bits on disk") that are in that character set, whose meaning would be jeapordized by after-the-fact changes to the character set used.

Client character set

Every OCI program is, from the perspective of the database, a client. sqlplus is a database client, and so is Apache with mod_owa installed. While the database sets are fixed after creation, clients can run any character set they like. The Oracle OCI code determines the client character set by looking for the value of NLS_LANG, which it gets either from the environment or (on Windows) from the registry. The NLS_LANG contains a specification for your desired language, territory, and character set. If you do not specify an NLS_LANG, Oracle assumes you are running US7ASCII. This can be a source of much trouble, as we'll see shortly.

Network conversions

The networking layers below the Oracle OCI allow clients to run their own character sets by converting client string data to/from the database character set. These layers perform no conversion, and hence are most efficient, when client and server are running the same character set. As an example, suppose that a database was running the UTF8 character set, while a client was running WE8ISO8859P1. The OCI will, effectively, convert from the Latin-1 to the Unicode set whenever the client transmits strings, including SQL statements and procedure arguments, and will convert results back from Unicode to Latin-1 for any outputs.

It is also possible, when binding an argument with the OCI, to override the default character set with another one, effectively marking that argument as being in a character set other than that specified by the NLS_LANG.

mod_owa DAD character set

All SQL statements built and transmitted by mod_owa will be bound with the default NLS_LANG character set. However, if you specify an OwaCharset, and this character set is different from that of the NLS_LANG, mod_owa will use the per-argument OCI bind mode just described to ensure that the string in question is interpreted in a manner consistent with the DAD chararcter set, not the NLS_LANG set. mod_owa provides you with this capability so that you can have multiple Locations within your Apache server that each use and expect a different character set (the reason you might want to do this will be clear in the next section).

Note that the OwaCharset never affects the SQL, only the input and output arguments (the OCI does not provide a way to override the NLS_LANG character set for SQL - in practice this isn't needed anyway since procedure names should not contain unusal characters).

Also note that the DAD character set is always specified using the IANA character set name. The reason for this will be clear in the next section.

Browser character set

Just as character set conversions may be necessary between Apache/mod_owa and the database, it may be necessary to perform conversions between the working character set of the middle tier and a browser. For downloaded documents or generated pages, the HTTP protocol allows the server to attach a character set specifier as part of the content type, so that the browser will know what character set the document is in. The character set specifier must be an IANA name. mod_owa will do this automatically whenever it can, using the OwaCharset you specify, or an OwaCharset inferred from the NLS_LANG (if you've omitted it). Note that it's not possible for the OWA to do this in PL/SQL, because at that stage the database doesn't know what character set the data is eventually going to be converted to in the client (Apache/mod_owa).

In theory, the browser will make sense of the response even if it's not in the "default" character set of the browser. For example, if you send back a document and mark it as utf-8, the browser will commonly render it properly, even if it contains (for example) Chinese, despite the fact that your browser default is some other character set (like iso-8859-1). Thus, there is a relatively reliable way to ensure that transmitted data is interpreted correctly by the browser.

Unfortunately, there is no reliable way to be sure of the browser's desired character set for a GET or POST request. The HTTP protocol provides for a way to signal this to the server, but none of the browsers has properly implemented this. Instead, they send a list of character sets that they will accept a response in, which gives the server no information about what character set the transmitted data is in. This could be a serious problem for a POST request containing form data.

To get around this last problem, mod_owa relies on the OwaCharset. mod_owa simply assumes that all data from your browser sent to the Location in question will be in the OwaCharset. This is a clumsy workaround but so far no one's come up with anything better. You can see how this might be inconvenient for a site that has one set of users desiring to run Latin-1 while another set wants to run (say) a Japanese set. The workaround for this is to have different Locations, one for the Latin-1 users and one for the Japanese users. However, since by definition the NLS_LANG can only be set to one value, in this circumstance it is useful that mod_owa allows you, on a per Location basis, to override the NLS_LANG with a Location-specific OwaCharset. If not for this feature, you'd be forced to run different Apache instances on different ports or different machines so that each could have a different NLS_LANG setting (fortunately, they can still all use the same database per the earlier discussion).

Non-byte-uniuqe character sets

A character set that is ASCII-compatible is considered a byte-unique character set. UTF-8 Unicode is byte-unique, as are certain Asian character sets. Some character sets are non-byte-unique, such as the Shift-JIS (SJIS) variants. These character sets use byte values from the ASCII range as follower bytes in double-byte pairs. mod_owa likely cannot support such character sets due to internal parsers that scan for byte valued delimiters such as file path separators, double-quote character delimiters, etc.

There are many ways to get into trouble with character sets, and I'm only going to mention a few of the more common ones here.

Browser character set doesn't match DAD

This one should be obvious -- if your browser is running some character set that doesn't match the OwaCharset, mod_owa won't know it and will just bind the raw bytes for transmission to the database. It might even seem to work, since when you fetch it back out, assuming there was not a conversion required between Apache and the database itself, it will likely look just like it did when it went in. However, a user with a correctly-configured browser will, on accessing that same data, most likely see the raw bytes as being entirely different characters. Worse yet, if Apache and the database are not running the same character set, the OCI will attempt to convert your inbound data to the database character set, but will assume (incorrectly) that it's coming from the DAD character set, not your browser set.

As an example, suppose a user is running an Eastern European browser character set, and uploads data via a form to an Apache Location that is set to iso-8859-1. Suppose further that the actual database is UTF8 Unicode. mod_owa will take the data from the browser, bind it as Latin-1, and it will get converted incorrectly to Unicode. The reverse conversion may or may not result in the same raw binary values; if it does not, then the browser could see strange values reflected back.

NLS_LANG not set correctly

This one is subtle, because if you don't set NLS_LANG, Oracle behaves as if you had set it to AMERICAN_AMERICA.US7ASCII by default. Suppose that you start up Apache without setting NLS_LANG, and neglect to specify an explicit OwaCharset. Then you attempt to access the Location from a browser running iso-8859-1. Because you did not specify an OwaCharset, mod_owa will use the NLS_LANG character set as the OwaCharset, in this case US7ASCII. Now you are in the same situation as the previous example where the browser and DAD sets are mismatched!

Please be aware that despite some similarities, the OwaNLS directive cannot be used to avoid setting NLS_LANG. Oracle packs a lot of information into NLS_LANG, including two attributes (language and territory) that can be set at run-time on a per-session basis, and one (the character set) that is global to the entire process and cannot be changed once the program starts. The OwaNLS directive allows you to tell mod_owa to set the language and territory, but it does not direct mod_owa to establish the character set, because this is not possible. The only reason OwaNLS allows you to specify the character set at all is because in older versions of the OCI (8.0.x), there is no API by which mod_owa can determine the NLS_LANG character set, and so you must use the OwaNLS directive to inform mod_owa of your character set choice (but not to set it).

Incorrect database character set

In theory, the OCI will ensure that all data passing to/from the database is converted to the database character set. However, what if the database character set isn't the one you think it is? In the past, many Oracle customers have mistakenly created their databases and forgotten to specify the character set that they really want. They then use the database, via sqlplus, as if it were in the character set that they want, but with an incorrect NLS_LANG that happens to match the incorrect database character set. This is a recipe for real trouble.

A classic example of this is to mistakenly create the database using the US7ASCII character set, when in fact the user intends to store 8-bit data. This was, unfortunately, the Oracle default (until recently when it was changed to WE8ISO8859P1) if you failed to specify a character set at creation time. Users would then compound this error by neglecting to set NLS_LANG, and would run sqlplus to create stored procedures with accented characters or populate table data with accented data. You might think this would fail, but remember that the OCI will skip any character-set conversion in the particular case where the client and server character sets match. Because, in this example, both appear to be running US7ASCII, the invalid 8-bit data is allowed in. It even seems to work, as long as you consistently keep forgetting to properly set the NLS_LANG. The trouble comes later, when a program like mod_owa is used, and the client character set is properly specified. For example, again assuming you neglect to set NLS_LANG, but you do specify the DAD character set to make sure some set of your users get Latin-1, you will get very strange results as the database attempts to "convert" the 8-bit data that it thinks should be US7ASCII into the WE8ISO8859P1 character set.

Very similar problems can arise if you use any character set on both client and server but enter data as if it were in another character set. For example, suppose the database were created with Latin-1 and the client's NLS_LANG was likewise set to Latin-1, but the user was (by whatever means) entering Chinese in the Unicode character set. This might appear to work for that user, but in reality the database is storing away the raw bytes of the Unicode strings as if they were just odd strings of European characters!

Unescaped URLs

Programmers generating dynamic pages sometimes forget that URLs cannot contain non-ASCII characters, and even some ASCII characters, unless they are escaped. For example, the Latin-1 character y-diaeresis, which is byte value 255, should not appear directly in a URL, but should be escaped as %FF. Many ASCII characters require similar escaping, and in fact the exact escaping needed depends on which portion of the URL is being escaped. For example, spaces are not valid in the URL, but should be escaped as %20. If a URL is going to contain arguments, the arguments may need different escaping.

Some browsers will nevertheless attempt to use an invalid URL, and will simply escape the URL prior to transmitting it. IE will do this, for example, though it's common for IE to do this using the utf-8 character set (the browser has to make some assumption about what character set the invalid byte values are in). If the code that generated the URL used Latin-1, obviously there's going to be trouble as the byte codes are misinterpreted.

Variants of this problem sometimes arise when JavaScript code attempts to assign default values to form fields or build URLs based on strings that were not escaped but that appear in the code, because again the browser must make an assumption about the character set of the JavaScript code itself, and this is not necessarily the same assumption it makes about the page or form field values.

Lossy conversions

Even when character sets are properly configured all along the path from browser to mid-tier to database, it's still the case that when converting between character sets, some loss of fidelity may result. For example, no amount of configuration correctness will help the Russian user that uploads Cyrillic data into a database that's running WE8ISO8859P1. In some cases, the losses may be subtle and go unnoticed for a while. This would be most likely to occur between different Asian character sets, which have many but not all of the same character code points.

Two modes of lossy conversion are worth special mention because they very commonly result from misconfigurations where the NLS_LANG is not specified, and hence US7ASCII is used as the default. If you use US7ASCII as the client character set, and read out from the database accented data in a character set such as WE8ISO8859P1, Oracle will do its best to down-convert the data as it's sent through OCI. The effect of this is that accents appear to be stripped off as (for example) a y-diaeresis is converted to a plain y, etc. Going the other direction, if you bind 8-bit data through to the OCI, then because these byte values do not represent valid US7ASCII characters, the OCI doesn't know what to do with them, and bit-strips them down to 7 bits, thus the a-diaeresis becomes the letter d, the e-diaeresis becomes a k, the o-diaeresis a v, etc.

Another form of lossy conversion can occur as a result of string expansion or contraction. For example, an accented German word takes more bytes to represent in multibyte UTF8 Unicode than it does in Latin-1. If a word of maximum size (versus a hypothetical database column) were entered into a form field, it could appear to be of valid length and yet still overflow the width of either a PL/SQL buffer or a database column all of which are specified in bytes, not characters. The symptoms of such an error could range from database overflow errors to application-level truncations. The amount of exposure to this problem depends entirely on the character sets and languages involved.

There are some additional considerations for Oracle 9i and beyond.

NCHAR and character-semantic VARCHARs

In Oracle 9i, there will be several significant changes to the way string data is handled by the database. One is that the NCHAR set will now always be Unicode. Thus, a programmer writing code that he or she desires to run with Unicode semantics regardless of customer deployment can now do so reliably. Another is that the database will offer the ability to specify column widths and PL/SQL buffer sizes using character storage units (of course specification in bytes will always be supported, too, for backward compatibility).

RAW transfer modes

Oracle is considering adding support for raw transfers to the PL/SQL gateway (see the previous descriptions of the OwaUnicode RAW binding mode and the OwaAlternate GETRAW setting). If this is done, it will allow you to receive arguments to your procedures in raw form, giving you control over the character set conversion. It will also provide you a means to return content in any desired character set, regardless of the database or mod_owa character set, by allowing results to be transferred back in raw form. (As a side-effect, you will also finally be able to generate raw content types, for example content of mime type image/gif, etc.) If this support is added, it will mean that in any situation where the target character set doesn't match the database character set, the HTP functions will convert the content to the target character set and return it to mod_owa as raw data.

New AL32UTF8 character set

Oracle's UTF8 character set was created prior to the adoption of the extensions that take Unicode beyond its 16-bit origins. As a consequence, the Oracle character set known as UTF8 is incapable of handling the new 4-byte sequences used to encode the extended characters (those beyond U+FFFF). Compatibility considerations required Oracle to support the official Unicode standard with a new character set; in Oracle 9i, this is the character set known as AL32UTF8. If you have a 9i client environment in which to run Apache, you can use this character set against 9i databases. It's settable globally via NLS_LANG, and mod_owa will be able to make use of it if set in this manner.

One caveat, however, is that it is not possible to set mod_owa to use this character set at the level of a specific Location (via the OwaCharset directive). OwaCharset is specified in terms of IANA names, and, again for compatibility reasons, mod_owa is forced to map the IANA "utf-8" to UTF8 (otherwise, mod_owa might not work in 8.x environments). In practice this isn't really a problem; just set AL32UTF8 as the NLS_LANG character set, and use OwaCharset for all Locations that do not use AL32UTF8.

Please be aware of the following size limits of mod_owa:

maximum argument size

A scalar argument can be up to 32512 bytes in size (an OCI maximum close to, but not quite as large as, the PL/SQL maximum of 32767). However, when present in an array, older versions of OCI may limit the size of an individual argument to 4000 bytes. Also, note that this can result in a very large memory structure (4000 * array_size) being required. It's best to limit array arguments to 256 bytes each if the number of elements in the array is going to be large.

maximum number of arguments

When the flexible argument mode is used for file operations, all arguments are passed in a single array, and there is a limit of 256 total elements. Since mod_owa adds some arguments of its own, it's best to limit the number of arguments to 250 or less.

maximum return SQL statement length

32512 bytes, the PL/SQL maximum. Character-set issues might cause expansion of strings when transferred to mod_owa, so either stay well below this limit or ensure that your SQL is mostly ASCII.

maximum return SQL bind length

The buffer is 4000 bytes in size. However, due to character-set conversion issues, it's best to limit returned bind values to 2000 characters unless you're sure the characters are ASCII.

maximum return mime type length

256 characters.

maximum upload/download size

2 gigabytes per file for downloads, 2 gigabytes total (across all files being transferred) for uploads.

maximum file size for cache

2 gigabytes per file.

maximum connection pool size

255 connections per Location on NT, 1 per Location per worker process on Unix.

This section is mainly for programmers and diagnosticians who need to know about the process architecture of Apache, and how mod_owa uses mutexes/semaphores to implement the connection pool, the cleanup thread, and the shared memory segment.

Apache Process Architecture

Critical Events

Latches

Here are a few notes on outstanding bugs and incompletely-implemented features:

• Intermittent browser hangs against Unix server
  I've traced this problem to an odd interaction between the Apache keepalive processing logic and the handling of Oracle shadow processes when direct database connections are being used. Details are at modowabug.htm. For now, the problem is worked around by marking the Apache socket connection with the close-on-exec flag, so that it's not carried over into any Oracle shadow process that might be spawned. This is a good work-around but unfortunately it won't work under Apache 2.0 (revisit this issue).
• Shadow-process crashes related to use of RESET_PACKAGE
  This is a flat-out bug in PL/SQL, but it causes the statement used by mod_owa to pass the Basic authentication information into OWA to crash the shadow process with a 3113 error. The only robust work-around requires modifying the OWA PL/SQL package to include APIs for setting the username/password; the crash seems related to the fact that, lacking such APIs, mod_owa must directly assign their values using an anonymous block. Oracle's official OWA will include these APIs in a future release. Details of the bug are at plsqlbug.htm.
• Worker process grows large over time
  Hard to pin down because, except for the OCI calls, mod_owa uses the request pool for all allocations and assumes Apache will clean things up. I do not believe this is an actual memory leak, though it's possible OCI-related memory is not being cleaned up. It's also possible that, because mod_owa needs some relatively large blocks, poor implementations of the storage allocator could result in fragmentation-related heap growth. On Unix, where Apache is single-threaded, mod_owa attempts to reuse a static buffer to reduce/eliminate this.
• Mime types for file uploads/downloads
  Right now, mod_owa relys on the upload action procedure to do whatever is necessary to compute a mime type for files being stored. On download, it assumes that the read procedure will supply the mime type, and if it doesn't get one has a hard-coded set of file extensions that it checks to infer the mime type. It would be much better if Apache provided an interface to derive mime types from file extensions, but I can't find one.
• Character set issues for LOBs/LONGs
  As described above, there are some problems with character versus byte semantics that aren't fully sorted out. Mainly this is because I lack any support for determining character boundaries in byte-streams when using multi-byte character sets, except for the UTF8 Unicode set for which there is a simple algorithm (included in mod_owa but untested).
• No way to know browser character set
  The whole DAD character set system is a hack; it would be much much better if there was some way to know what character set a browser was transmitting content in, and conversely what character set it would like the response in.
• Support for non-byte-unique character sets
  mod_owa's support for multi-byte character sets is limited in a few areas. One of these is in the procedure name portion of the URL, where the string is assumed to be in a byte-unique ASCII-based character set. A byte-unique set is one where multi-byte characters are always represented by sequences of bytes that have the 8th bit set. Non-byte-unique sets may set the 8th bit only for the leading byte, while the following byte may resemble an ASCII character. When mod_owa scans the string to parse it for a ".", or to eliminate invalid characters such as spaces, it does so using simple string functions that are not aware of multi-byte character boundaries. Many multi-byte sets are byte-unique, including UTF8. A major non-byte-unique set is Shift-JIS, a Japanese set common on windows. Note that you can still use your non-byte-unique set for arguments via the OwaCharset, the only restriction is on procedure names, which are interpreted using the NLS_LANG character set.
• Bugs in OCI8
  A few minor bugs in OCI8 required rather awkward work-arounds. One is that for array-bound variables, the string buffers must be at least two bytes wide, even if the array consists entirely of one-byte "empty" strings (e.g. the unused "reserved" argument to the flexible parameter mode). Another is that LOB data transfers must be closed with an OCI_LAST_PIECE flag, yet during a streaming operation mod_owa doesn't necessarily know that a block being transferred is the last block it will see. Unfortunately the OCI won't let you write a 0-length block, so when this situation occurs (only for large files, and then only about 1 in a 1000 times) mod_owa has to write an extra byte to the LOB and then truncate the LOB back to the correct size.
• End of content upload
  mod_owa uses ap_bread() to read content from the incoming stream. Unfortunately ap_bread() will return with content whenever it's available, rather than returning only when it's satisfied the requested number of bytes or seen the end of the incoming stream. This means that mod_owa is forced to assume that the CONTENT_LENGTH is correct and continue calling ap_bread() until either that number of bytes has been received, or until an error (-1) is returned. Another related problem is interpretation of 0-length return values. In theory this could occur if mod_owa is reading faster than data is available on the pipe (likely), and is therefore not an error. However, some users have reported that they get 0-length returns when a user aborts an in-progress POST operation from his/her browser. mod_owa is therefore forced to treat the 0-length return as if it were an error, to avoid an infinite loop.
• Initializing OCI might fail after startup
  The only way for a module to stop the Apache startup is to exit from the module startup procedure. Unfortunately this procedure is only called once, whereas the OCI initialization must be done for each child process (on Unix). mod_owa must therefore perform the OCI initialization from the child startup procedure, where, if a failure occurs, there is no opportunity to abort startup (instead, an error message is silently written to the error log). Also, because the child startup is called multiple times on NT from within the same process, a kludgey flag is used to ensure that the OCI is initialized exactly once per worker process.
• Open-source version of PL/SQL side
  The PL/SQL side of the gateway is not open-source. It would be best if an equivalent were built and bundled with mod_owa. The code in the sample file modowa.sql has a bare-minimum implementation, but a tremendous amount of functionality is still missing.
• IIS and Netscape versions
  The code is architected so that all the Apache-specific linkage is encapsulated (in modowa.c). It should be possible to implement a replacement linkage for the Microsoft or Netscape web servers.
  Morten Braten has independently implemented a PL/SQL gateway for IIS in C#. It's called the Thoth Gateway: https://github.com/mortenbra/thoth-gateway
• Shared memory cache
  The shared memory segment was added to support a memory-based cache to augment the file-system cache. The feature isn't finished yet, in fact I don't even really have a design.
• Cleanup shared resources
  As noted, Apache doesn't give me an event where the shared memory segment and shared semaphore can be reclaimed. This is a problem only on Apache 1.3 on Unix. Another problem is that a superfluous shared resource is created by the Apache starter process, because the module initialization event doesn't allow me to distinguish the start of the real worker template process from the start of the manager.
• OWS-compatible authentication
  There are some nuances of OWS that aren't mimiced well by mod_owa with respect to basic authentication. There is a question about how to convey the values for username and password in HTTP_AUTHORIZATION. Should they be base-64 decoded? Should they be assigned to OWA.USER_ID and OWA.PASSWORD as part of the anonymous block? Should the Apache check_auth and/or check_user_id callback functions be added? Should the setting of the OWA_SEC mode be sensed in some way? Should the false return of an authorization check be examined by mod_owa? Currently, handling any/all of these issues are left to the client PL/SQL code for maximum flexibility. The interfaces in OWA_SEC won't work without some code that you'd have to have in your PL/SQL.
• URL unescaping issues
  The character set used to escape arguments in URLs is difficult to determine accurately. The standard calls for iso-8859-1, though browsers will often use utf-8 instead. Under some circumstances, including situations where a GET method is used for a form submission, the browser may use the page character set, or the user-selected default character set. URLs constructed by JavaScript code may use utf-8. Finally, Microsoft IE encodes some values as UCS2 with %uXXXX, which it's not clear Apache's native unescape functions will properly handle. It's a mess. For now, mod_owa assumes that the URL parameters are in the same character set as post arguments, which will generally be true for submission operations. For other links on a page, the application should probably pre-escape them on the server when generating them. The JavaScript issue will remain a problem, though - applications that need to do that should probably just run exclusively in utf-8.
• Administration interfaces
  There should be some built-in code to generate pages that support administration of the httpd.conf files remotely via a web browser.
• DAV services
  It would be very useful if the code were extended to provide hooks for supporting some level of the Web-DAV standard. This would require picking up a dependency on an XML parser, though I believe I could use Oracle's which is public and should be available in the same library that supplies OCI.
  Also, the OPTIONS verb should probably be supported as a REST method.
• Stateful sessions
  Some users have requested that mod_owa support stateful applications, wherein database connections would be bound to particular user sessions rather than pools. One reason I didn't implement this originally was that Apache's architecture on Unix is multi-process. In Apache 2.0, the architecture flexibly supports multi-process/multi-threaded deployments, even on Windows. Database sessions cannot be shared across process boundaries, and Apache provides no mechanism for ensuring that any particular request from a client will get routed to the same worker process. Still, in the limited case where a deployment was single-process, multi-threaded (all 1.3 Windows deployments, and potentially any 2.0 deployment that was configured that way), it could probably be supported, likely by adopting a model similar to that of Java servlet sessioning (cookie-based).
• OAS-compliant document operations
  Partial support for WebDB-style document uploads and downloads has been added. Only the BLOB mode is supported, which may be sufficient to run Apex (HTML-DB). These operations run to and from a documents table that can be specified with OwaDocTable.
• Alias Procedure
  mod_owa doesn't implement this, though the combination of either OwaDocGen or OwaDocPath along with OwaDocProc or OwaDocGen provides similar functionality.