3
Migrating OAS Cartridges to Apache Modules

This chapter compares OAS cartridge functionality to corresponding functionality, and discusses considerations for migrating Oracle Application Server cartridges to the Apache Web Server infrastructure.

Cartridge Types and Corresponding Apache Modules

The table below shows the Apache infrastructure for each OAS cartridge type:

Table 3-1 Cartridge Types and Apache Modules

OAS Cartridge Type	Apache Module
Perl	mod_perl
LiveHTML	mod_php
PL/SQL	mod_plsql

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

PL/SQL Migration

OAS 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 as mod_plsql and is run as an Oracle HTTP Server module. It executes PL/SQL logic inside an Oracle database and delegates the servicing of HTTP requests to PL/SQL programs.

Users who are planning to migrate PL/SQL applications from OAS to Oracle Internet Application Server are encouraged to first read the Using mod_plsql documentation on the CD-ROM and familiarize themselves with the features in this product.

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

File Upload/Download

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

Table 3-2 File Upload/Download Features Comparison

File Upload/Download Feature	OAS 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 per-application tables for upload of file	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 OAS features except file compression/decompression are supported in Oracle Internet Application Server. Users with compressed uploaded files in OAS 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 the next section.

For more information on the additional file upload features supported by Oracle Internet Application Server, refer to the Using mod_plsql documentation on your CD-ROM.

Uploaded File Document Format

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

Map data from the OAS tables to the Oracle Internet Application Server tables while maintaining the uploaded content and the content description.
Deflate compressed content in OAS before migrating to Oracle Internet Application Server. This version of Oracle Internet Application Server does not support compression/decompression for uploaded files (see previous section).

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.

The columns in the Oracle Internet Application Server document table will derive their values from OAS in the following way:

Table 3-3 Derived Column Values

Column in Oracle Internet Application Server doc table	OAS 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 OAS will always be stored in the BLOB 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 OAS files to Oracle Internet Application Server format. The following steps should be followed:

Make sure you have a current backup of all OAS 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
- OAS version 4.0.7.1 or later
- iAS v1
- Oracle database version 8.1.x
- ORACLE_HOME is set to Oracle Internet Application Server ORACLE_HOME
- ORACLE_HOME/bin is in the system path (on NT) or in the PATH environment variable (on UNIX)
- LD_LIBRARY_PATH contains $ORACLE_HOME/lib:/usr/java/lib
Setup TNS connect strings to the OAS 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). Edit $ORACLE_HOME/network/admin/tnsnames.ora and setup the connect strings
```
<name> =
```
```
(DESCRIPTION =
```
```
(ADDRESS = (PROTOCOL = TCP)(Host = <hostname>)
(Port = <portno>))
(CONNECT_DATA = (SID = <sid>))
```
```
)
```

Run the oas2ias tool which can be found in $ORACLE_HOME/bin in your Oracle Internet Application Server installation. The tool will then prompt for the following parameters:

Parameter Description

websys_password

password for the "websys" user

websys_connstr

connect string for the OAS 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 OAS 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 OAS 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 OAS 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 the Using mod_plsql documentation on your CD-ROM 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 OAS 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 OAS

There are two types of Perl applications that can run under OAS: a Perl script run as a CGI script, and a Perl script run using the Perl cartridge.

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

Perl scripts that run under OAS 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 a shared object in UNIX, libperlctx.so, and a shared library in NT, perlnt40.dll. 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 OAS 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 OAS may need to be modified to run under Oracle Internet Application Server.

Migrating Perl Cartridge Scripts from OAS to Oracle Internet Application Server

This section includes a discussion of OAS 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 OAS 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 OAS Perl cartridge, mod_perl redirects stdout to the listener.

See www.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 links, and installation instructions.

Perl Version

Perl version 5.004_04 or higher must be installed before mod_perl can be installed.

Perl Modules

The table below lists Perl modules shipped with OAS. These modules are not a part of the standard Oracle Internet Application Server distribution, so in order to migrate applications that use these modules from OAS to Oracle Internet Application Server, you must acquire these modules from the listed sources and install them.

Table 3-4 Perl modules in OAS

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 OAS Perl Cartridge

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

Namespace Collision

In OAS 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 OAS 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.

OAS and Oracle Internet Application Server form the package name differently. OAS 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

OAS 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

OAS 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 OAS, 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 and LiveHTML embedded scripts to mod_php scripts.

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 that a space is required before the closing terminator "-->".)

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

Scripts in LiveHTML are written in Perl. For PHP scripts, the syntax used takes from C and Perl. As a detailed discussion of the differences between these two types of scripts is outside the scope of this document, refer to the appropriate documentation for LiveHTML/Perl and PHP.

PHP information can be found at http://php.apache.org and Perl at http://www.perl.com.

3 Migrating OAS Cartridges to Apache Modules

Contents