3
Migrating Oracle Application Server Cartridges

This chapter compares Oracle Application Server cartridge functionality to corresponding functionality in Oracle Application Server 10g, and discusses considerations for migrating cartridges to Oracle Application Server 10g.

Topics discussed are:

• Cartridge Types and Corresponding Oracle Application Server 10g Modules

• PL/SQL Migration

• Perl Migration

• LiveHTML Migration

• CWeb Migration

Cartridge Types and Corresponding Oracle Application Server 10g Modules

Table 3-1 presents the equivalent Oracle Application Server cartridge types and their Oracle Application Server 10g components.

Table 3-1 Cartridge Types

Oracle Application Server Cartridge Type	Oracle Application Server 10g Equivalent
PL/SQL	mod_plsql
Perl	mod_perl
LiveHTML	Apache SSI and JSP
CWeb	Custom Apache Modules, FastCGI, CGI, Java JNI and PL/SQL Callouts

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

Note: Oracle Application Server uses Perl version 5.004_01, while Oracle Application Server 10g uses Perl version 5.6.1. When code modification is required, use the appropriate Perl version.

PL/SQL Migration

You can migrate Oracle Application Server PL/SQL cartridge applications to Oracle Application Server 10g mod_plsql. Both mod_plsql and PL/SQL cartridge applications provide similar support for building and deploying PL/SQL-based applications on the Web.

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

See Also: Oracle Application Server 10g mod_plsql User's Guide if you are planning to migrate PL/SQL applications from Oracle Application Server to Oracle Application Server 10g.

Support for several Oracle Application Server PL/SQL cartridge features has changed in Oracle Application Server 10g PL/SQL. The rest of this section provides details on how to migrate Oracle Application Server applications that use these features.

File Upload and Download

Table 3-2 summarizes the file upload and download features supported by Oracle Application Server and Oracle Application Server 10g.

Table 3-2 Comparison of File Upload and Download Features  

File Upload/Download Features	Oracle Application Server Support	Oracle Application Server 10g 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 or download	Yes	No
Upload multiple files per form submission	Yes	Yes

Uploaded File Document Format

Oracle Application Server PL/SQL cartridge and Oracle Application Server 10g mod_plsql both support uploading files. However, they use different document table schemas. Table 3-3 shows how the columns in the Oracle Application Server 10g document table derive their values from Oracle Application Server.

Table 3-3 Derived Column Values

Column in Oracle Application Server 10g 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 is always be stored in the BLOB_CONTENT column of the Oracle Application Server 10g document table. The tool also ensures that the data loaded into the Oracle Application Server 10g document 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 Application Server 10g.

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 also supports custom authentication.

See Also: Oracle Application Server 10g mod_plsql User's Guide

Flexible Parameter Passing

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

Both Oracle Application Server and Oracle Application Server 10g support flexible parameter passing. To use flexible parameter passing in the mod_plsql, 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 mod_plsql procedure will be:

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

See Also: Oracle Application Server 10g mod_plsql User's Guide

Positional Parameter Passing

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

See Also: Oracle Application Server 10g mod_plsql User's Guide

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.

Oracle Application Server 10g does not support this feature. You must 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 you can migrate them to Oracle Application Server 10g. Topics include:

• Perl Applications under Oracle Application Server

• Migrating Perl Cartridge Scripts

• Variations from Oracle Application Server Perl Cartridge

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_01. The interpreter is built as the following:

• UNIX: libperlctx.so: a shared object

• Windows: 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 input/output (for example, 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 input/output.

• supports error logging.

• supports performance instrumentation.

You can run your Perl scripts developed for Oracle Application Server under the CGI environment in Oracle Application Server 10g CGI environment, as well, after modifying the interpreter line of your Perl scripts. You may also modify your Perl scripts for Perl cartridge in Oracle Application Server in order to run under Oracle Application Server 10g.

Migrating Perl Cartridge Scripts

This section discusses Oracle Application Server and Oracle Application Server 10g Perl implementations, and code modifications for migrating Perl scripts to Oracle Application Server 10g.

Oracle Application Server 10g Perl Environment

Oracle Application Server 10g Perl environment is based on mod_perl. Like 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.

Perl Modules

Table 3-4 presents comparisons of the third party Perl modules associated with both Oracle Application Server and Oracle Application Server 10g. In order to migrate applications that use these modules from Oracle Application Server to Oracle Application Server 10g, you must acquire these modules and install them. The files are available from:

http://www.cpan.org

Table 3-4 Comparison of Third Party Perl Modules  

Perl Module	Version in Oracle Application Server	Version in Oracle Application Server 10g
DBI	0.79	1.20
DBD::Oracle	0.44	1.12
LWP or libwww-perl	5.08	5.53_94
CGI	2.36	2.752
MD5	1.7	2.14
IO	1.15	1.20
NET	1.0502	1.0703
Data-Dumper	2.07	NA
Apache DBI	NA	0.88
Devel::Symdump	NA	2.01
Digest::HMAC	NA	1.01
Digest::MD2	NA	2.00
Digest::SHA1	NA	2.00
HTML::Parser	NA	3.25
MIME::Base64	NA	2.12
PlRPC	NA	0.2015
Storable	NA	1.0.12
Net::Daemon	NA	0.35
Time::HiRes	NA	1.20
URI	NA	1.15

Variations from Oracle Application Server Perl Cartridge

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

Namespace Collision

Both Oracle Application Server and Oracle Application Server 10g cache compiled Perl scripts. If not properly handled, the caching of multiple Perl scripts can lead to namespace collisions. To avoid this, both Oracle Application Server and Oracle Application Server 10g 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 Application Server 10g form the package name differently. Oracle Application Server cannot cache subroutines with the same name. Oracle Application Server 10g 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 Oracle Application Server 10g.

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.

The corresponding pre-load script for Oracle Application Server 10g is startup.pl.

See Also: http://perl.apache.org for more information on mod_starup.pl

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, or by using Perl for scripting. If you are migrating LiveHTML applications to Oracle Application Server 10g, you must migrate LiveHTML SSI to Apache SSI. Currently the only equivalent to LiveHTML embedded scripts in Oracle Application Server 10g is JSP.

SSI

Table 3-5 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	not available
set	not available
not available	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 Oracle HTTP Server by default.

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

Scripts

In Oracle Application Server, you can use the LiveHTML cartridge to embed Perl scripts in HTML files. There is no equivalent functionality in Oracle Application Server 10g. However, you have the following choices to do so.

1. Keep the logic in Perl and use mod_perl, for example, you can change the HTML piece to printf().

2. Keep the HTML, but change the programming language to PL/SQL.

3. Download tools from the Web that allow using Perl as a scripting language with HTML, for example at http://perl.apache.org.

   Note: The tools run on top of mod_perl. Therefore, this migration approach is the easiest, comparing to other three approaches listed in this section.

4. Keep the HTML, but change the programming language to Java, for example JSP. Oracle Application Server 10g complies with JSP 1.2 specifications. To migrate your LiveHTML application to Oracle Application Server 10g, you must do the following:
   1. Migrate from the LiveHTML application model to the JSP application model.

   2. Migrate LiveHTML tags to JSP tags.

   3. Rewrite the Perl code as Java code.

   Note: 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 JSP.

   See Also: Oracle Application Server Containers for J2EE Support for JavaServer Pages Developer's Guide

   Note: Oracle Application Server 10g does not provide WRB APIs.

CWeb Migration

In Oracle Application Server, you can use the CWeb cartridge to

• create custom cartridges.

• develop applications that other cartridges invoke.

The migration paths from Oracle Application Server CWeb cartridges to Oracle Application Server 10g include

• using FastCGI.

• creating a custom Oracle Application Server 10g module.

Using FastCGI

CWeb cartridge is essentially a .dll or a .so library. You can integrate it into the Oracle Application Server environment by specifying the entry point of this library in an administration page and map it to a Web URL. The Oracle Application Server infrastructure invokes the entry point of the library (CWeb cartridge) when a browser requests that URL. In addition, the CWEB cartridge makes several API from the WRB infrastructure available to access the client information, and other environment information.

CGI is a standard supported by all Web servers, including Oracle Application Server 10g. When a URL that maps to the "CGI program" is accessed, the Web server starts that program and return its results to the browser.

Therefore, one simple way to migrate CWeb is to write a simple C program that invokes the entry point of the CWeb cartridge during the start-up.

The WRB API and other Oracle Application Server infrastructure dependencies will, of course, not be available in the new Oracle Application Server 10g environment. If these WRB API or capabilities were used, the CWeb cartridge must be modified to use alternative API.

From an infrastructure standpoint, the CWeb cartridges were load balanced. New instances were not started on each request.

FastCGI is an "overloaded" term referring to the specifications, protocol, API, and also the implementation. In summary, it spawns a separate process and keeps it alive and independent of the life-style of the requests. FastCGI programs must conform to certain standards for starting point and events to listen to, which is similar to a Java servlet specification. Their life-cycle can, then, be controlled by the infrastructure.

Migrating a CWeb cartridge is similar to writing a FastCGI program, which conforms to the specifications, and in turn calls the entry point of the CWeb cartridge.

See Also: http://www.fastcgi.com for FastCGI examples

Creating a Custom Oracle Application Server 10g Module

If you used CWeb to create custom cartridges, you can also consider creating a custom Oracle Application Server 10g module.

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

• CGI scripts: stand-alone C programs generating Web content with println statements.

• Java JNI: Java Servlets or JSP that call CWeb routines from OC4J

• PL/SQL Callouts: PL/SQL applications that call CWeb routines from Oracle 10G.

  Note: Oracle Application Server 10g does not provide WRB and CWeb APIs.