3
Migrating Oracle Application Server Cartridges

This chapter compares Oracle Application Server cartridge functionality to corresponding functionality, and discusses considerations for migrating cartridges to the Oracle9i Application Server infrastructure. The topics include:

Cartridge Types and Corresponding Apache Modules

The table below shows the Oracle HTTP Server equivalent for each Oracle Application Server cartridge type:

Table 3-1 Cartridge Types and Apache Modules

Oracle Application Server Cartridge Type	Oracle HTTP Server Equivalent
Perl	mod_perl
LiveHTML	Apache SSI and OracleJSP
PL/SQL	PL/SQL Gateway
CWeb	Custom Apache Modules, CGI, Java JNI and PL/SQL Callouts

The migration strategy for each application cartridge is detailed in the following sections.

PL/SQL Migration

Oracle Application Server PL/SQL Cartridge applications can be migrated to Oracle9i Application Server PL/SQL Gateway, which provides similar support for building and deploying PL/SQL based applications on the web.

mod_plsql is bundled into the PL/SQL Gateway and runs as an Oracle HTTP Server module. It delegates the servicing of HTTP requests to PL/SQL programs which execute their logic inside of Oracle databases.

Users who are planning to migrate PL/SQL applications from Oracle Application Server to Oracle9i Application Server are encouraged to read Using the PL/SQL Gateway in the Oracle9i Application Server Documentation Library and familiarize themselves with the features in this module.

Support for the following Oracle Application Server PL/SQL Cartridge features has changed in Oracle9i Application Server PL/SQL Gateway. The rest of this section provides details on how to migrate Oracle Application Server applications that use these features.

File Upload/Download

The following table lists the file upload/download features supported by Oracle Application Server and Oracle9i Application Server.

Table 3-2 File Upload/Download Features Comparison

File Upload/Download Feature	Oracle Application Server Support	Oracle9i Application Server Support
Upload/Download of file as raw byte streams without any character conversion	Yes	Yes
Upload of file into column type: `LONG RAW`	Yes	Yes
Upload of file into column type: `BLOB`	No	Yes
Upload of file into column type: `CLOB`, `NCLOB`	No	Yes
Specify tables for upload of file for each database access descriptor (DAD)	No - Uploads into WEBSYS schema only	Yes
Compression/Decompression of file during file upload/download	Yes	No
Upload multiple files per form submission	Yes	Yes

Note that all Oracle Application Server features except file compression/decompression are supported in Oracle9i Application Server. Users with compressed uploaded files in Oracle Application Server do not need to decompress their files manually. They will be automatically decompressed and uploaded in uncompressed format into the Oracle9i Application Server document table by the oas2ias file migration tool that is documented in "Using the oas2ias Tool".

See Also:
Using the PL/SQL Gateway in the Oracle9i Application Server Documentation Library for more information on additional file upload features.

Uploaded File Document Format

Oracle Application Server PL/SQL Cartridge and Oracle9i Application Server PL/SQL Gateway both support uploaded files. However, they use different document table schemas. Users with uploaded files on Oracle Application Server who wish to migrate to Oracle9i Application Server will need to convert their files using the oas2ias migration tool.

The oas2ias tool performs two functions:

Mapping data from the Oracle Application Server tables to the Oracle9i Application Server tables while maintaining the uploaded content and the content description.
Deflating compressed content in Oracle Application Server before migrating to Oracle9i Application Server. This version of Oracle9i Application Server does not support compression/decompression for uploaded files (see the previous section for further details).

The oas2ias tool is implemented in C, using the OCI library. The tool reads all the rows from the OWS_CONTENT table and populates the content and all it's attributes to a document table specified by the user.

Table 3-3 shows how the columns in the Oracle9i Application Server document table derive their values from Oracle Application Server.:

Table 3-3 Derived Column Values

Column in Oracle9i Application Server Document Table	Oracle Application Server table.column Value
`NAME`	`ows_object.name`
`MIME_TYPE`	`ows_fixed_attrib.content_type`
`DOC_SIZE`	`ows_content.length`
`DAD_CHARSET`	`ows_fixed_attrib.character_set`
`LAST_UPDATED`	`ows_object.last_modified`
`CONTENT_TYPE`	`"BLOB"`
`CONTENT`	`NULL`
`BLOB_CONTENT`	`OWS_CONTENT.content`

The content from Oracle Application Server will always be stored in the BLOB_CONTENT column of the Oracle9i Application Server document table. The tool will also ensure that the data loaded into the Oracle9i Application Server doc table is always uncompressed data. To do this, if the data is compressed (this is verified by checking the entries in the OWS_ATTRIBUTES table), the data is uncompressed using the zlib library, and then loaded to the document table in Oracle9i Application Server.

Using the oas2ias Tool

The oas2ias tool need only be run once to convert all Oracle Application Server files to Oracle9i Application Server format. The following steps should be followed:

Make sure you have a current backup of all Oracle Application Server uploaded files.

Create the document table for Oracle9i Application Server. You can create this under any database user.

SQL> CREATE TABLE my_doc_table (
       NAME         VARCHAR2(128) UNIQUE NOT NULL,
       MIME_TYPE    VARCHAR2(128),
       DOC_SIZE     NUMBER,
       DAD_CHARSET  VARCHAR2(128),
       LAST_UPDATED DATE,
       CONTENT_TYPE VARCHAR2(128),
       CONTENT LONG RAW,
       BLOB_CONTENT BLOB);

Verify the environment
- Oracle Application Server Release 4.0.7.1 or later
- Oracle9i Application Server Release 1.0.0 or later
- Oracle database version 8.1.x
- ORACLE_HOME is set to Oracle9i Application Server
  ORACLE_HOME
- (Windows only) The system path contains %ORACLE_HOME%\bin
- (UNIX only) The PATH environment variable contains
  $ORACLE_HOME/bin
- (UNIX only) The LD_LIBRARY_PATH environment variable contains both $ORACLE_HOME/lib and /usr/java/lib
Create TNS aliases to the Oracle Application Server database (where the websys schema exists) and the Oracle9i Application Server database (where the Oracle9i Application Server user schema with the my_doc_table table exists). Store the aliases in $ORACLE_HOME/network/admin/tnsnames.ora (UNIX) or %ORACLE_HOME%\network\admin\tnsnames.ora (Windows NT). The format for a TNS alias in this file is:
```
<alias> =
```
```
(DESCRIPTION =
```
```
(ADDRESS = (PROTOCOL = TCP)(Host = <hostname>)
(Port = <port_number>))
(CONNECT_DATA = (SID = <sid>))
```
```
)
```
See your database documentation for more information on TNS aliases.

Run the oas2ias tool which can be found in the bin directory under ORACLE_HOME in your Oracle9i Application Server installation. The tool will prompt for the following parameters:

Parameter Description

websys_password

password for the websys user

websys_connstr

connect string for the Oracle Application Server database

ias_user_name

database user name for the schema containing the Oracle9i Application Server document table created in step 2

ias_password

password for <ias_user_name>

ias_connstr

connect string for the PL/SQL Gateway database

ias_doc_table

name of the Oracle9i Application Server doc table created in step 2

Parameter	Description
websys_password	password for the `websys` user
websys_connstr	connect string for the Oracle Application Server database
ias_user_name	database user name for the schema containing the Oracle9i Application Server document table created in step 2
ias_password	password for <ias_user_name>
ias_connstr	connect string for the PL/SQL Gateway database
ias_doc_table	name of the Oracle9i Application Server `doc` table created in step 2

The following is a sample run of oas2ias:

Welcome to the OAS to iAS migration Utility
Please enter the following parameters:
WEBSYS password: manager
OAS database connect string (<ENTER if local database>: orc8
iAS database user: oracle
iAS database user's password: welcome
iAS database connect string <ENTER if local database>: orc8
iAS doc table: my_doc_table

Transferred file : C:\TEMP\upload.htm
Length of file : 422
Transferred file : C:\Tnsnames.ora
Length of file : 2785
Transferred file : C:\rangan\mails1.htm
Length of file : 717835
Freeing handles ...

This completes the transfer of the files to an Oracle9i Application Server document table and the files are now available for access using Oracle9i Application Server PL/SQL Gateway.

Custom Authentication

Custom Authentication is used in Oracle Application Server for applications that want to control the access themselves (that is within the application itself). The application authenticates the users in its own level and not within the database level.

The PL/SQL Gateway also supports custom authentication.

See Also:
Using the PL/SQL Gateway in the Oracle9i Application Server Documentation Library for more information on authentication

Flexible Parameter Passing

The flexible parameter passing scheme allows you to overload PL/SQL procedures. This allows you to reuse the same procedure name but change the procedure's behaviour depending on how many parameters a form passes to the procedure.

Both Oracle Application Server and Oracle9i Application Server support flexible parameter passing. To use flexible parameter passing in the PL/SQL Gateway, prefix the procedure name with an exclamation point (!) in the invoking URL.

For example, if the following URL invokes your Oracle Application Server procedure:

http://<host>/<virtual_path>/procedure?x=1&y=2

Then the URL that invokes your PL/SQL Gateway procedure will be:

http://<host>/<virtual_path>/!procedure?x=1&y=2

See Also:
Using the PL/SQL Gateway in the Oracle9i Application Server Documentation Library for more information flexible parameter passing

Positional Parameter Passing

The Oracle Application Server PL/SQL cartridge supports a positional parameter passing scheme. This feature is not supported in Oracle9i Application Server and cannot be used.

See Also:
Using the PL/SQL Gateway in the Oracle9i Application Server Documentation Library for more information on supported parameter passing schemes

Executing SQL Files

In addition to running PL/SQL procedures stored in the database, the Oracle Application Server PL/SQL cartridge can run PL/SQL source files from the file system. The source file contains an anonymous PL/SQL block that does not define a function or procedure. This feature enables users to execute PL/SQL statements without storing them in the database. This is useful when prototyping PL/SQL code since it saves having to reload procedures into the database each time they are edited.

This feature is not supported in Oracle9i Application Server. Users will need to assign names to the anonymous blocks and compile them as stored procedures in the database.

Perl Migration

This section explains how Perl cartridge applications are implemented in the Oracle Application Server, and how they can be migrated to Oracle9i Application Server.

Perl Applications under Oracle Application Server

There are two types of Perl applications that can run under Oracle Application Server:

Perl scripts running as a CGI scripts
Perl scripts using the Perl cartridge

Perl scripts that run under Oracle Application Server as CGI scripts use a standard Perl interpreter that must be installed on the system as a Perl executable, separate from the Oracle Application Server installation.

Perl scripts that run under Oracle Application Server using the Perl cartridge use a Perl interpreter contained in the cartridge, and based on standard Perl version 5.004. The interpreter is built as either:

(UNIX only) libperlctx.so, a shared object
(Windows only) perlnt40.dll, a shared library

The Perl cartridge links with the shared object or library at runtime.

Differences between Cartridge Scripts and CGI Scripts

Scripts written for the Perl cartridge differ from scripts written for a CGI environment, because of how the cartridge runs the interpreter. The Perl cartridge:

Maintains a persistent interpreter, and pre-compiles and caches Perl scripts (thus achieving better performance).
Redirects stdin and stdout to the WRB client I/O (i.e., the browser).
Redirects stderr to the WRB logger.
Returns additional CGI environment variables to the Perl interpreter whenever it calls for system environment variables.
Supports the system call instead of the fork call. The system call modifies the implementation of the Perl interpreter to redirect child process output to the WRB client I/O.
Supports error logging.
Supports performance instrumentation.

Perl scripts developed under Oracle Application Server to run as CGI scripts can run in Oracle9i Application Server as CGI scripts without modification. However, Perl scripts developed to run under the Perl cartridge in Oracle Application Server may need to be modified to run under Oracle9i Application Server.

Migrating Perl Cartridge Scripts

This section includes a discussion of Oracle Application Server and Oracle9i Application Server Perl implementations, and code modifications for migrating Perl scripts to Oracle9i Application Server.

The Oracle9i Application Server Perl Environment

The Oracle9i Application Server Perl environment is based on the Apache Perl distribution (mod_perl). Like the Oracle Application Server implementation, mod_perl provides a persistent Perl interpreter embedded in the server and a code caching feature that loads and compiles modules and scripts only once, serving them from the cache. Like the Oracle Application Server Perl cartridge, mod_perl redirects stdout to the listener.

See Also:
the mod_perl documentation in the Oracle9i Application Server Documentation Library

Installation Requirements

The Perl DBI and DBD modules are not part of the standard Oracle9i Application Server distribution, and must be installed separately. Refer to the Release Notes for details on version requirements, download sites, and installation instructions.

Perl Modules

Table 3-4 lists Perl modules shipped with Oracle Application Server. These modules are not a part of the standard Oracle9i Application Server distribution. In order to migrate applications that use these modules from Oracle Application Server to Oracle9i Application Server, you must acquire these modules and install them. The files are available from:

http://www.cpan.org

Table 3-4 Perl Modules in Oracle Application Server

Module	Version
DBI	0.79
DBD::Oracle	0.44
LWP or libwww-perl	5.08
CGI	2.36
MD5	1.7
IO	1.15
NET	1.0502
Data-Dumper	2.07

Variations from Oracle Application Server Perl Cartridge

The following points should be noted between the Oracle Application Server Perl cartridge and Oracle9i Application Server mod_perl.

Namespace Collision

In Oracle Application Server and Oracle9i Application Server, compiled Perl scripts are cached. If not properly handled, the caching of multiple Perl scripts can lead to namespace collisions. To avoid this, both Oracle Application Server and Oracle9i Application Server translate the Perl script file name into a unique packaging name, and then compile the code into the package using eval. The script is then available to the Perl application in compiled form, as a subroutine in the unique package name.

Oracle Application Server and Oracle9i Application Server form the package name differently. Oracle Application Server cannot cache subroutines with the same name. Oracle9i Application Server creates the package name by prepending Apache::ROOT:: and the path of the URL (substituting "::" for "/").

Using cgi-lib.pl

Oracle Application Server Perl scripts that use cgi-lib.pl must be modified to use a version of the library customized for the Perl cartridge. This is not necessary for Oracle9i Application Server.

See Also:

http://cgi-lib.stanford.edu/cgi-lib for more information on cgi-lib.pl

Oracle9i Application Server Release Notes for information about modifying cgi-lib.pl

Pre-loading modules

Oracle Application Server Perl scripts may contain instructions that need not be executed repetitively for each request of the script. Performance improves if these instructions are run only once, and only the necessary portion is run for each request of the Perl script.

In Oracle Application Server, perlinit.pl pre-loads modules and performs initial tasks. This file is executed only once when the cartridge instance starts up. By default, there are no executable statements in this file. This file is specified by the Initialization Script parameter in the Perl Cartridge Configuration form.

There is no corresponding functionality in Apache mod_perl.

LiveHTML Migration

In Oracle Application Server, you can generate dynamic content using the LiveHTML cartridge by embedding Server-Side Includes (SSI) and scripts in HTML pages. If you are migrating LiveHTML applications to Oracle9i Application Server, you need to migrate LiveHTML SSI to Apache SSI. Currently the only equivalent to LiveHTML embedded scripts in Oracle9i Application Server is JavaServer Pages.

SSI

SSIs provided by Apache and LiveHTML do not have equivalent elements. The following table lists the SSIs available in Apache and LiveHTML.

Table 3-5 List of SSIs in Apache and LiveHTML

Apache SSIs	LiveHTML SSIs
config	config
echo	echo
exec	exec
fsize	fsize
flastmod	flastmod
include	include
printenv	-
set	-
-	request

The syntax for specifying an SSI in Apache or LiveHTML is the same. For example:

<!--#config sizefmt="bytes" -->

Note:
The space before the closing terminator (-->) is required.

SSI in Apache is implemented by the mod_include module. This module is compiled into the Apache Server by default.

In addition to the elements shown in the table above, Apache SSI also includes variable substitution and flow control elements.

See Also:
the Apache Server documentation in the Oracle9i Application Server Documentation Library

Scripts

In Oracle Application Server, you can use the LiveHTML cartridge to embed Perl scripts in HTML files. Because LiveHTML is a proprietary Oracle Application Server component, it does not have equivalent functionality in Oracle9i Application Server. However, JavaServer Pages allow you to embed Java code in HTML files. The JavaServer Pages 1.0 (JSP) model is implemented in Oracle9i Application Server as OracleJSP.

To migrate your LiveHTML application to Oracle9i Application Server, you must do the following:

Migrate from the LiveHTML application model to the JSP application model.
Migrate LiveHTML tags to JSP tags.
Rewrite the Perl code as Java code.

If your LiveHTML application uses Web Application Objects in Oracle Application Server, you must implement this functionality as embedded Java code, or as JavaBean classes, and declare them with the <jsp:useBean> tag in JSPs.

See Also:
Oracle JavaServer Pages Developer's Guide and Reference in the Oracle9i Application Server Documentation Library

CWeb Migration

In Oracle Application Server, you can use the CWeb (or C) Cartridge to:

create custom cartridges
develop applications that other cartridges invoke

There is no simple migration path from Oracle Application Server CWeb Cartridges to Oracle9i Application Server. If you used CWeb to create custom cartridges you should consider creating a custom Apache module.

If you use CWeb to invoke C programs, you have the following options:

CGI scripts: standalone C programs generating web content with println statements.
Java JNI: Java Servlets or JavaServer Pages that call C routines from Apache JServ or Oracle8i JVM
PL/SQL callouts: PL/SQL applications that call C routines from Oracle Database Cache or Oracle8i.

The Web Request Broker (WRB) and C APIs are not available in Oracle9i Application Server.

3 Migrating Oracle Application Server Cartridges