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 Oracle Internet Application Server infrastructure.

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	mod_plsql

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 Oracle Internet Application Server mod_plsql, which provides similar support for building and deploying PL/SQL based applications on the web.

mod_plsql is bundled into Oracle Internet Application Server and is run 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 Oracle Internet Application Server are encouraged to first read Using mod_plsql in the Oracle Internet 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 Oracle Internet Application Server mod_plsql. 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 Oracle Internet Application Server.

Table 3-2 File Upload/Download Features Comparison

File Upload/Download Feature	Oracle Application Server Support	Oracle Internet 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 DAD	No - Uploads into WEBSYS scheme 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 Oracle Internet 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 Oracle Internet Application Server document table by the oas2ias file migration tool that is documented in "Using the oas2ias Tool".

For more information on the additional file upload features supported by Oracle Internet Application Server, refer to Using mod_plsql in the Oracle Internet Application Server Documentation Library.

Uploaded File Document Format

Oracle Application Server PL/SQL Cartridge and Oracle Internet Application Server mod_plsql both support uploaded files. However, they use different document table schemas. Users with uploaded files on Oracle Application Server who wish to migrate to Oracle Internet 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 Oracle Internet Application Server tables while maintaining the uploaded content and the content description.
Deflating compressed content in Oracle Application Server before migrating to Oracle Internet Application Server. This version of Oracle Internet 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 Oracle Internet Application Server document table derive their values from Oracle Application Server.:

Table 3-3 Derived Column Values

Column in Oracle Internet 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 Oracle Internet Application Server document table. The tool will also ensure that the data loaded into the Oracle Internet 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 Oracle Internet Application Server.

Using the oas2ias Tool

The oas2ias tool need only be run once to convert all Oracle Application Server files to Oracle Internet 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 Oracle Internet 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
- Oracle Internet Application Server Release 1.0.0 or later
- Oracle database version 8.1.x
- ORACLE_HOME is set to Oracle Internet 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 Oracle Internet Application Server database (where the Oracle Internet Application Server user schema with the my_doc_table table exists). Store the aliases in $ORACLE_HOME/network/admin/tnsnames.ora. 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 Oracle Internet 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 Oracle Internet Application Server document table created in step 2

ias_password

password for <ias_user_name>

ias_connstr

connect string for the mod_plsql database

ias_doc_table

name of the Oracle Internet 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 Oracle Internet Application Server document table created in step 2
ias_password	password for <ias_user_name>
ias_connstr	connect string for the mod_plsql database
ias_doc_table	name of the Oracle Internet 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 Oracle Internet Application Server document table and the files are now available for access using Oracle Internet Application Server mod_plsql.

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.

mod_plsql supports custom authentication. See Using mod_plsql in the Oracle Internet Application Server Documentation Library for more information.

Positional Parameter Passing Scheme

The Oracle Application Server PL/SQL cartridge supports a positional parameter passing scheme. This feature is not supported in Oracle Internet Application Server and cannot be used. Refer to Using mod_plsql in the Oracle Internet Application Server Documentation Library for more information on the parameter passing schemes supported in Oracle Internet Application Server mod_plsql.

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 Oracle Internet 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 Oracle Internet 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 NT 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 Oracle Internet 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 Oracle Internet Application Server.

Migrating Perl Cartridge Scripts

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

The Oracle Internet Application Server Perl Environment

The Oracle Internet 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 http://perl.apache.org for more information on mod_perl.

Installation Requirements

The Perl DBI and DBD modules are not part of the standard Oracle Internet 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 Oracle Internet Application Server distribution. In order to migrate applications that use these modules from Oracle Application Server to Oracle Internet Application Server, you must acquire these modules from http://www.cpan.org and install them.

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 Oracle Internet Application Server mod_perl.

Namespace Collision

In Oracle Application Server and Oracle Internet 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 Oracle Internet 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 Oracle Internet Application Server form the package name differently. Oracle Application Server cannot cache subroutines with the same name. Oracle Internet 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. (For more information on cgi-lib.pl, see http://cgi-lib.stanford.edu/cgi-lib.) This is not necessary for Oracle Internet Application Server.

Refer to the Release Notes to find out how to modify these Perl scripts to run in Oracle Internet Application Server.

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, the $ORAWEB_HOME/../cartx/common/perl/lib/perlinit.pl file is used to pre-load modules and perform 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 Oracle Internet Application Server, you need to migrate LiveHTML SSI to Apache SSI. Currently the only equivalent to LiveHTML embedded scripts in Oracle Internet 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. Refer to the documentation at http://www.apache.org.

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 Oracle Internet Application Server. However, JavaServer Pages allow you to embed Java code in HTML files. The JavaServer Pages 1.0 (JSP) model is implemented in Oracle Internet Application Server as OracleJSP. For more information on OracleJSP see the OracleJSP Developer's Guide in the Oracle Internet Application Server documentation library.

To migrate your LiveHTML application to Oracle Internet 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.

3 Migrating Oracle Application Server Cartridges

Contents