Apache PL/SQL Gateway Module

The arguments arrive via either the GET or POST methods in a single tokenized string. GET passes them in the URL, while POST makes them available in the content body (and therefore can accomodate much larger data sets). The arguments are parsed and unescaped by searching through the argument string, assumed to be in the following format:

<param1_name>=<param1_value>&<param2_name>=<param2_value>...

The un-escaping is done after each name/value pair is parsed off.

Note that for POST requests, any arguments found in the URL are merged with the arguments from the content body. URL arguments are processed first.

0. Create database connection

This is generally done only if a previous connection is not available in the pool for reuse. (More on the connection pool below.) On creation, the connection is set to the NLS parameters (if specified) with the following commands:

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

1. Initialize PL/SQL state

This operation is required because the OWA leaves state from previous request executions lying around after a return. A better design would make it unnecessary, and probably be much more efficient. For now, all PL/SQL package state must be zeroed on every request, and this is done with the following PL/SQL anonymous block:

begin DBMS_SESSION.RESET_PACKAGE; end;

Note that this command is always the same on every request. mod_owa will keep a statement handle open for this operation and reuse it whenever the connection is reused. (This is sometimes called a database "cursor".) It's the first of five statement handles that are held on every connection in the connection pool.

In the latest version of mod_owa, I've moved this operation to the end, so it now occurs after the final GET_PAGE or other content transfer occurs. In effect, I've gone from a model where the connection is cleaned up prior to every request to a model where the connection is cleaned up after every request. I did this to improve perceived performance, because the cost of the RESET_PACKAGE operation will now be incurred after the user has received his/her content, not while he/she is waiting for it. The difference is largely theoretical: so far I haven't noticed any actual improvement (but then, I don't have a high-volume site where RESET_PACKAGE becomes costly, either).

Via the OwaAlternate directive, you can switch off this operation via a directive such as:

OwaAlternate  MY_OWA KEEPSTATE

This can greatly decrease the load on your database for high-volume sites. To use this mode, you must ensure that all of your application's PL/SQL code is re-entrant, meaning that it leaves no information in PL/SQL package globals that would prevent the servicing of a subsequent HTTP request for a different client. As an example, code that performed a one-time initialization of globals for the particular user involved in a request would not be re-entrant, whereas similar code that kept such information in a global cache that was resettable (or that could hold the information for multiple users) could be re-entrant. Unfortunately the code of the OWA itself is not yet re-entrant, so this requires that you supply your own OWA-equivalent implementation.

Short of disabling the reset operation entirely, you can use the OwaReset flag to alter the nature of the reset call performed, as follows:

2. Set up the CGI environment

mod_owa must pass the name/value pairs from the CGI environment into the OWA before it can execute your procedure, so that their values will be available to your code. This is done by executing the following PL/SQL anonymous block:

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

The arguments are as follows:

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

Note that the last two arguments to the procedure are actually arrays, while the first is a scalar binding.

This statement is always the same on every call, though the values in the binding buffers are obviously different. mod_owa keeps this statement handle open so that it can reuse it whenever the connection is reused. This is the second of five statement handles held on pooled connections.

3. Pass basic authentication information

mod_owa will pass the username and password from any Basic authentication header received by Apache using the following PL/SQL anonymous block:

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

Like the previous statements, this statement is always the same on every call, but with different values bound for username and password. mod_owa keeps this statement handle open so that it can reuse it whenever the connection is reused. This is the third of five statement handles held on pooled connections.

These assignments could (and should) be executed as part of the call to INIT_CGI_ENV, but a bug in PL/SQL has forced me to do this in a separate operation.

4. Execute the requested procedure

This is the only truly dynamic SQL in the entire process. The code that must be executed is normally of the following form:

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;

The authorization call has three forms. In older versions of OWA, it was OWA_INIT.AUTHORIZE(), while in newer versions it's OWA_CUSTOM.AUTHORIZE(). If PACKAGE is specified for the Location, the check is <package name>.AUTHORIZE(). mod_owa will build one of these based on what you tell it in the httpd.conf Location. It will also simply skip the check if that's what you specify.

The essential part of the call is of course the procedure and argument bindings. There are four supported modes of argument passing:

The procedure name is taken from the URL, it's the name appearing right after the "mount point". For example,

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

is a call to PL/SQL procedure foobar (with two arguments). This call requests the default passing mode, which is named arguments, and would produce something like the following:

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

Bind variables are used for the arguments so that the internal cursor sharing mechanisms of the database can match this with other requests for the same function.

Special characters in the procedure name signal which type of argument passing to use. To get positional argument passing, precede the procedure name with a circumflex as in:

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

which results in:

foobar(:B1,:B2);

To get flexible argument passing, precede it with an exclamation mark:

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

which always results in the same call regardless of the number of arguments:

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

Note that OAS supported another flexible argument mode, which mod_owa will try if the 4-argument mode fails (and if you have not used the STRICT setting for OwaDescribe):

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']

To get the raw argument data without any escaping or interpretation by Apache and/or mod_owa, precede the call with a tilde, as in:

http://mymachine/owa/~foobar

This mode is not part of the official OWA specification, and is described in a later section.

Binding of arguments is done as a series of string values sized based on the actual data. In a request it is possible to pass multiple elements with the same name (typically this happens with POST requests where form elements are repeated on multiple lines). For example:

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

seems to provide two values for "a". mod_owa treats this as an array-bound parameter to the PL/SQL routine, and will pass it in as a table of records of VARCHAR type. Thus, the above URL results in:

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

where :B1 is a scalar string "2" and :B2 is the array ['dog','cat'].

Special notes on bind modes:

• Unless you pass multiple values for an argument name, mod_owa will assume it should be bound as a scalar, not an array. The OWA spec doesn't support such singleton bindings because there's no good way for the gateway to determine what the binding mode should be. The suggested work-around is to add a hidden field to your form with a blank value to ensure that the array bound quantity is seen as such by the gateway. If the normal call fails, mod_owa will use OCIDescribeAny() and will attempt to figure out if any scalar bindings should be "promoted" to singleton array bindings. This adds overhead to the call and I don't recommend relying on the feature, but it can't hurt since the alternative is issuing an error message.
  
  
• In certain circumstances, browsers may generate form input arguments that are structured in nature. For example, consider the following form:

  <form action="/owa/myprocedure" method="GET">
  <input type="image" name="mybutton" src="mybutton.gif">
  </form>
  

  which, when the mouse is clicked inside the image item, results in this transmission to the web server:

  myprocedure?mybutton.x=123&mybutton.y=321
  

  This is not a problem in the flexible argument mode, where mod_owa will simply bind {"mybutton.x", "mybutton.y"} in the names array and {123, 321} in the values array. However, in the other argument modes, particularly the named argument mode, this presents a problem because "." is not typically valid in the argument name. In response to this situation, mod_owa will build an array-bound argument with the name of the structure prefix, e.g.

  myprocedure(mybutton=>:B1);
  

  where :B1 is bound to an array containing the structure elements in the order received. Unfortunately, there is no way to tell which is "x" and which is "y" except positionally in the array, but this binding is required for compatibility with Oracle's implementation of the OWA. I advise users to use the flexible argument mode instead.
  
  
• Please note that the bind variables are only guaranteed to be suitable for IN parameters, never for IN OUT parameters. If you try to call a procedure passing an argument to an IN OUT parameter, the OCI may crash.

The final clause of the statement retrieves a protection realm which can optionally be used to drive HTTP Basic authentication. This value is retrieved only if the AUTHORIZE function fails, and it is not bound if authorization is disabled. You can optionally set this value directly (or via OWA_SEC.SET_PROTECTION_REALM), and this will cause mod_owa to skip the GET_PAGE operation (described below) and send back a Basic authentication challenge for the realm provided. (This mode of operation is provided for compatibility with OWS.) If you do not set this value, mod_owa proceeds with the GET_PAGE operation and assumes that you've generated an appropriate error or login page during the AUTHORIZE call.

The procedure call should result in the creation of HTTP content for transmission back to the client. This call is therefore usually the most time-consuming part of handling a request. Another statement handle is needed for this operation, though because the SQL changes from request to request, mod_owa must reparse the statement each time (however, by using bind variables, mod_owa expects to hit the data server's shared cursor cache most of the time anyway). This is the fourth of the five statement handles held for pooled connections.

5. Get and return data

After the execution, mod_owa is ready to retrieve the HTML output data, which is held in PL/SQL global memory in a table of records. This is done by repeated calls to the following PL/SQL anonymous block:

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

The first argument is an OUT-only table of records, holding up to 256 lines of output, while the second argument is an IN/OUT count of the number of lines available/returned by the call.

This is the fifth statement handle held on every connection in the pool, and, like the first three, it never changes, so it's kept parsed and ready for re-execution on subsequent requests. It's called repeatedly to get the output until the number of lines returned is less than 256, signalling the end of the HTTP result.

The output returned is streamed to the Apache request response. However, it is necessary to parse it for an HTTP header, since OWA unfortunately doesn't separate the header return from the content (as demanded by Apache itself). Header elements are of the form:

<tag>: <value><newline>

Of course, some lines of content may also have this form. The header is separated from the content by a blank line, so mod_owa looks for this blank line when examining the return from GET_PAGE. Unfortunately the OWA doesn't always return a header, and since content can also have blank lines, there is no absolutely reliable way to separate the two. mod_owa uses a heuristic technique that seems to work well. In cases where OWA does return a header, it always returns a CONTENT-TYPE: tag. mod_owa looks for this tag anywhere in the first 256 lines it fetches, and, if found, assumes there's a header and proceeds to process all lines as header lines until it sees the blank-line separator. If, however, it doesn't find this tag, then mod_owa assumes there's no header and it's all content.

Header elements include the CONTENT-TYPE tag, cookies, etc. They are all intercepted and merged with the request response header. After the header is exhausted, the remaining content is simply streamed to the request output.

Under certain special conditions, the OWA can return a header with no content. Moreover, these headers don't have a CONTENT-TYPE marker (because, of course, they have no content!). The three that I am aware of are the redirection header (signalled by the lone LOCATION: tag), the refresh header (signalled by the lone REFRESH: tag), and the authentication challenge (signalled by the WWW-AUTHENTICATE: tag). mod_owa has special-cased code to handle all these cases.

Binary content types should, in general, not be returned via this interface. It is possible in most cases to convey such content back via the file download interface (discussed below). The main problem with binary content types is simply that the OWA.GET_PAGE interface, as well as all PL/SQL-side processing done by the OWA, is character-based, exposing attempts to transmit binary data to the following problems:

1. Binary values representing invalid character codes can cause trouble in the PL/SQL code of the OWA, which performs SQL operations such as LENGTH, SUBSTR, etc., on the data. This is especially problematic for multi-byte character sets, where not all binary sequences represent valid character values.
2. Character data passed through the OCI is subject to character-set conversion from the data server to the client -- such conversions can change the byte values and corrupt the binary data stream.
3. Binary null byte values can cause code in both PL/SQL and C to incorrectly believe the end of a character string has been encountered.

Despite these problems, some users still return binary data through the OWA interface, using the CHR() function to set specific byte values. This will generally work under the following conditions:

• The character set of the data server is a single-byte set, thus avoiding the first problem listed above in all known cases.
• The character set of the Apache client (e.g. the OwaCharset or NLS_LANG character set for mod_owa) is identical to that of the data server, thus avoiding the second problem listed above.
• (mod_owa itself avoids the third problem by using a length-returning OCI bind mode, and using the length instead of searching for a null terminator.)

This is by far the simpler and more robust portion of the implementation, particularly if you use only the BLOB (binary) files. The functionality is governed by six parameters:

1. OwaDocProc
   a procedure to be called whenever a document is being requested
2. OwaDocPath
   a path prefix which signals that a request should be routed to the document procedure
3. OwaDocLong
   a path prefix which signals that a request should be routed to the document procedure but use LONG or LONG RAW processing logic
4. OwaDocFile
   a path on the file system to use for document storage and retrieval, instead of the LONG or LONG RAW method
5. OwaDocGen
   a path prefix which signals that a request should be routed to the document procedure but that the content will be dynamically generated and returned through GET_PAGE
6. OwaDocLobs
   specifies which of the LOB handles to bind for read and write requests (see below)

I will describe the operation of OwaDocLong, OwaDocFile, and OwaDocGen in the next sections, so what follows here pertains to the LOB-based interface.

When a URI is received prefixed by the OwaDocPath, the entire URI (minus any query string) is considered to be a logical file path, and this file path is passed to the OwaDocProc, along with any other arguments specified by the query string. For example, consider the following URI:

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

• http://mymachine/owa
  This prefix routes the request into mod_owa (/owa is the Location)
• /docs/a/b/c/doc.gif
  This is the logical file path that will be sent to the OwaDocProc
• arg1=1&arg2=2
  Any remaining arguments follow the logical file path in the arrays

To keep the interface standard despite the possibility that the arguments may not be pre-determined, the call is always made using the flexible argument mode (described previously). In addition, 2-5 extra arguments are added, so the call becomes similar to the following:

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

The first element in the array of values will contain the logical file path (it's also available in the CGI environment). Any other arguments found in the query string will follow this one in the arrays.

For example, with the URI shown previously, the following arguments would be passed as inputs to the OwaDocProc:

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

The call is made without the usual authorization check being built into the anonymous block. The presumption is that any necessary access control is done by this procedure. If authorization fails and/or the document cannot be found, or if any other failure occurs, return NULLs for all LOB locators to signal an error to mod_owa. The module will then assume that the OwaDocProc has written a response page in the normal manner and will use OWA.GET_PAGE in the normal manner to retrieve and display it.

If the call succeeds, then return a mime type string (if possible) and return a LOB locator selected from the underlying storage table. The mime type string can be up to about 4000 bytes long. The procedure should return a non-null value in one of the LOB handles, and nulls in the others (if multiple non-null LOBs are returned, mod_owa will use the first one it finds in sequence starting from the BLOB, and ignore the others).

The setting of OwaDocLobs governs which of these arguments mod_owa will bind. The settings are as follows:

If you do not return a mime type, mod_owa will assume a type of "application/octet-stream" for binary LOBs and "text/plain" for character LOBs.

Also, mod_owa will attempt to determine the mime type based on the file extension, if it can find one. Right now this is a hack because I can't find any native Apache API for this, so there's a hard-coded table in mod_owa for some of the more common extensions. If you want to be sure to avoid this, return a mime type from the OwaDocProc.

BLOBs (and BFILEs) will be streamed down in a straightforward fashion. For CLOBs and NCLOBs, mod_owa will convert the content to the DAD character set in a manner similar to the way it handles OWA.GET_PAGE requests. Because LOB semantics work in characters, it is not always possible to determine the "Content-Length" for a character-based download. mod_owa will use the character length of the LOB as the content length only if you are running a single-byte character set (such as "iso-8859-1").

The semantics of the mime type argument have been extended to allow your code to return additional header elements for the document, up to 4000 bytes total. To return such elements, separate them from the mime type (and each other) with newlines. If there is no mime type being returned, you must still begin the buffer with a newline. The last header element need not be terminated with a newline. As an example:

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

This optional mode is signalled by any document path whose prefix matches the value set for OwaDocLong. The operation is in most respects similar to that for the LOB read, so in this section I will describe only the differences. The main difference is that the read procedure call is built as follows:

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

Note that the same OwaDocProc name will be used for this mode; the implementation can either overload the function (recommended) or make this the only mode of operation by setting OwaDocLong = OwaDocPath in the configuration.

The function is expected to return a SQL statement suitable for use by mod_owa to fetch back the LONG or LONG RAW value. The SQL statement should be a SELECT statement with a single column return value of type LONG or LONG RAW. The statement may optionally contain a single bind variable, typically the value for the primary key of the underlying table, or a ROWID. If the SQL statement requires this bind, return a value for it in the appropriate argument, otherwise return a NULL value. The SQL statement can be up to about 32512 bytes in length (the PL/SQL maximum). The bind value can be up to about 2000 characters long. The last argument is a flag to indicate whether the returned column is a character-based LONG or a binary LONG RAW type. Return a NULL for the character-based type, otherwise return any single-character value (typically, a 'Y'). The mime type argument is used in a manner similar to that for the LOB case; as with LOBs, the mime type can be up to about 4000 bytes long.

As an example, the SQL statement you return should be of the following form:

select LONG_CONTENT from MYDOCUMENTS where KEY_COLUMN = :B1;

The module will run the statement you specify, with the bind variable (if any), and perform a piecewise fetch of the result, streaming this back to the requestor. To signal an access control failure or other error, return a null for the SQL statement; as with LOB-based downloads, mod_owa will then assume that your code has written an OWA response page in the normal fashion, and attempt to display it using OWA.GET_PAGE. The returned contents can be up to 2 gigabytes in length.

As with LOBs, LONG RAWs work without any character set issues because they are transferred entirely in binary. (If a return character set is needed, it can be attached to the mime type value you return, as described earlier.) For LONGs, the transfer mode causes the character data to be converted to the character set of the Apache server prior to transfer, so no special handling is performed.

There may, however, be issues with the way the piecewise functions count lengths; it's not clear whether they always count in bytes, which the current code assumes, or whether some return lengths are in characters, in which case these transfers will have the same issues as CLOBs. Because of the way the code is written, any single-byte character set should work OK, without the data stripping done for CLOBs. It might be more flexible to implement this using the REF CURSOR mechanism. With this mechanism, PL/SQL can return a statement in an already-executed state, such that mod_owa need only run the piecewise fetch to stream the result. Unfortunately, this technique wouldn't work on older versions of the database (the main target of this legacy-mode feature). Also, REF CURSORs can't be used for INSERT/UPDATE operations, so mod_owa's support for uploads to LONG or LONG RAW targets would be forced to have an interface similar to this one anyway.

Unlike LOBs, Oracle's LONG and LONG RAW types don't provide any means for determining the length of the content, so the above linkage unfortunately doesn't support the transmission of a Content-Length for the request. For these legacy types, mod_owa has two special modes of operation, governed by additional parameters on the OwaDocLobs directive:

• LONG_RETURN_LENGTH
  
  If set this mode changes the PL/SQL call mod_owa generates to contain 9 arguments, as follows:

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

  The difference is in the last two arguments; the RAW flag is still the last argument, so it moves from B8 to B9, while argument B8 is an output binding that allows you to return the content length (it should be a numeric value suitable for an integer binding).
  
  This interface is useful if as a side-effect of processing the document lookup you already have the content length readily available, or if the content length is not stored in the same table as the content itself.
  
  
• LONG_FETCH_LENGTH
  
  If set, this mode causes mod_owa to bind the SQL statement you return with an additional select-list argument for the content-length. The PL/SQL portion of the interface is call-compatible with the normal operating mode (8 arguments). The SQL you return, however, must look as follows:

  select LONG_CONTENT, CONTENT_LENGTH from MYDOCUMENTS where KEY_COLUMN = :B1;
  

  As before, the exact column names and table names are unimportant, only the position matters; the long column appears first, followed by the length, which should be a numeric (integer) value. Also as before, the bind variable is optional.
  
  This mode is preferable if the length is not computed as a side-effect of the PL/SQL OwaDocProc call, but is readily available as a column in the same table as the long content.

You can specify this setting in combination with the LOB-related settings for OwaDocLobs, as in:

OwaDocLobs    CHAR LONG_FETCH_LENGTH

This mode is an override of the legacy LONG and LONG RAW mode. It is signalled by setting OwaDocFile. The operation is in most respects similar to that for the LONG reads, so in this section I will describe only the differences. The main difference is that the read procedure call is built as follows:

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

Note that the same OwaDocProc name will be used for this mode; the implementation can either overload the function (recommended) or make this the only mode of operation by setting OwaDocLong = OwaDocPath in the configuration. Also note that you must set OwaDocLong, since that parameter is still needed to distinguish this read mode from the standard LOB-based mode.

The function is expected to return a file path name that mod_owa can use to retreive the contents of the document. mod_owa will prepend the directory from OwaDocFile - mod_owa expects that the path name returned by the procedure begins with a path separator (e.g. "/") and that the path in OwaDocFile does not end with such a separator.

Unlike the LONG/LONG RAW mode, there is no distinction between binary and text data with file system operation.

If the path prefix matches the value of the optional parameter OwaDocGen, then this signals mod_owa to call your OwaDocProc with just the normal flexible arguments, and no output arguments, as shown here:

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

You then write the content using the normal OWA facilities, and mod_owa will retrieve it with GET_PAGE as per any normal request. The main difference versus a standard request is that the URL transmitted by the browser appears to be a normal file path (unless you allow arguments).

It is possible to use temporary LOBs to achieve a similar effect using the LOB-based transfer mode described earlier. However, there is no similar concept for LONG or LONG RAW types, so this method is the only way to do dynamic virtual files on an older (pre-8i) data server,

Another possible use for this directive is for streaming generation of the content via an alternate OWA interface. With Oracle's OWA, you must complete all of the output operations before returning to mod_owa, because once the GET_PAGE loop begins, you will not have any further opportunity to generate content. However, with an alternate OWA, you could simply save the page-generation context during the call to OwaDocProc, and then generate portions of content on demand during the GET_PAGE phase.

A file upload operation is triggered whenever the CONTENT_TYPE for a request is "multipart/form-data". The module assumes that the incoming stream contains a series of arguments and file streams delimited by the "boundary" string generated. This is typically accomplished by adding the enctype attribute to the form tag in the page generating the upload operation, as shown here:

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

Note that upload processing takes precedence over any alternative handling that might be implied by other mod_owa directives. For example, if the incoming URL matches the structure for a document download, the document download procedure will not be called.

Unfortunately, HTTP mixes both the form arguments and the file contents into a single stream. It provides no lengths for individual portions of the stream, and mixes binary information with textual information. In short, it's a mess, difficult to parse reliably. An example of an incoming stream might be as follows:

-------------------------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--

The incoming stream will be parsed in the order elements are received. The stream may contain both normal arguments and files. To avoid the need to buffer the entire stream before calling the action procedure, mod_owa will call the action procedure whenever a file is encountered in the stream, passing whatever arguments it has accumulated to that point. Users would therefore be well-advised to ensure that all non-file arguments in the form appear before the file input types.

The action procedure will be called once per file found in the stream, plus one additional time to generate a response page to the request. The action procedure will be called even if the file input element is blank. The module builds the call to the action procedure using the flexible argument model, with additional arguments for LOB handles, as shown here:

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

The action procedure should return a valid LOB handle in one of the LOB output arguments. If nulls are returned for all of them, mod_owa assumes that an authorization problem or other error has occurred, and will skip that file in the incoming stream. Otherwise, mod_owa will stream the file to the first non-null LOB handle in sequence and commit the transaction.

The LOB arguments bound are also subject to the value of OwaDocLobs, as described in the section on file downloads. The only difference is that a BFILE locator is never bound, so the FILE setting causes only 8 arguments to be built for writes (this is because Oracle doesn't support writes to BFILEs).

Note the following differences versus the OwaDocProc described for reading files, and versus other calling modes:

• No authorization check - like the file read case, the writer is assumed to do any necessary checking.
• No commit after the call; this is because the LOB must be returned in a writable state, so mod_owa will do the commit from OCI after writing data to the LOB.
• An IN OUT argument for the mime type; mod_owa will pass the value of the "Content-type:" (if any); the return value is ignored.
• Output arguments for up to three types of LOB.

The name/value argument arrays will contain every argument found in the content stream to that point. The first element in the values array will always be the value of "OwaDocPath" (to support programmers that want to use a single implementation of the code against multiple mod_owa locations), and the second element in the array will always be the name of the fi