Skip Headers

Oracle9i Application Server Migrating from Oracle Application Server
Release 2 (9.0.2)

Part Number A95108-01
Go To Documentation Library
Home
Go To Table Of Contents
Contents
Go To Index
Index

Go to previous page Go to next page

3
Migrating Oracle Application Server Cartridges

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

Cartridge Types and Corresponding Oracle9iAS Modules

Table 3-1 presents the equivalent Oracle Application Server cartridge types and their Oracle9iAS components:

Table 3-1 Cartridge Types
Oracle Application Server Cartridge Type Oracle9iAS 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 following sections.


Note:

Oracle Application Server uses Perl version 5.004_01, while Oracle9iAS uses the uses Perl version 5.6.1. When code modification is required, please use the appropriate Perl version.


PL/SQL Migration

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

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

If you are planning to migrate PL/SQL applications from Oracle Application Server to Oracle9iAS, you should read Oracle9i Application Server mod_plsql User's Guide in the Oracle9iAS Documentation Library to be familiar with the features in this module.

Support for the several Oracle Application Server PL/SQL Cartridge features has changed in Oracle9iAS 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 Oracle9iAS.

Table 3-2 File Upload and Download Features Comparison
File Upload/Download Features Oracle Application Server Support Oracle9iAS 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


Note:

All Oracle Application Server features are supported in Oracle9iAS, except file compression/decompression. Users with compressed uploaded files in Oracle Application Server do not need to decompress their files manually. These files will be automatically decompressed and uploaded in an uncompressed format into the Oracle9iAS Document Table (see Table 3-3). This process is performed by the oas2ias file migration tool (see "Using the oas2ias Tool").


See Also:

Oracle9i Application Server mod_plsql User's Guide in the Oracle9iAS Documentation Library

Uploaded File Document Format

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

The oas2ias tool performs two functions:

The oas2ias tool reads all the rows from the OWS_CONTENT table and populates the content and attributes to a document table you specify.

Table 3-3 shows how the columns in the Oracle9iAS 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 Oracle9iAS document table. The tool will also ensure that the data loaded into the Oracle9iAS 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 Oracle9iAS.

Using the oas2ias Tool

You only need to run the oas2ias tool once to convert all Oracle Application Server files to Oracle9iAS format with the following steps:

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

  2. Create the document table for Oracle9iAS. You can create this as 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);
    
    
  3. Verify the environment

    • Oracle Application Server Release 4.0.7.1 or later

    • Oracle9iAS Release 2 (9.0.2) or later

    • Oracle database version 9.x or later

    • ORACLE_HOME is set to the Oracle9iAS Oracle Home directory.

    • For Windows, the system path contains ORACLE_HOME\bin

    • For UNIX, the PATH environment variable contains ORACLE_HOME/bin

    • For UNIX, the LD_LIBRARY_PATH environment variable contains both ORACLE_HOME/lib and /usr/java/lib

  4. Create TNS aliases to the Oracle Application Server database (where the websys schema exists) and the Oracle9iAS database (where the Oracle9i Application Server user schema with the my_doc_table table exists). Store the aliases in the following directory:

    • (UNIX) ORACLE_HOME/network/admin/tnsnames.ora

    • (Windows) 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.

  5. Run the oas2ias tool which can be found in the bin directory under ORACLE_HOME in your Oracle9iAS 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 Oracle9iAS 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 Oracle9iAS 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>: db
    iAS database user: oracle
    iAS database user's password: welcome
    iAS database connect string <ENTER if local database>: db
    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 ...
    
    
  6. This completes the transfer of the files to an Oracle9iAS document table and the files are now available for access using Oracle9iAS 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.

The mod_plsql also supports custom authentication.

See Also:

Oracle9i Application Server mod_plsql User's Guide in the Oracle9iAS Documentation Library

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 behavior depending on how many parameters a form passes to the procedure.

Both Oracle Application Server and Oracle9iAS 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:

Oracle9i Application Server mod_plsql User's Guide in the Oracle9iAS Documentation Library

Positional Parameter Passing

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

See Also:

Oracle9i Application Server mod_plsql User's Guide in the Oracle9iAS Documentation Library

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.

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

Perl Applications under Oracle Application Server

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

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:

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

You can run your Perl scripts developed for Oracle Application Server under the CGI environment in Oracle9iAS 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 Oracle9iAS.

Migrating Perl Cartridge Scripts

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

The Oracle9iAS Perl Environment

The Oracle9iAS Perl environment is based on 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:

Oracle9i Application Server mod_plsql User's Guide documentation in the Oracle9iAS Documentation Library

Perl Modules

Table 3-4 presents comparisons of the third party Perl modules associated with both Oracle Application Server and Oracle9iAS. In order to migrate applications that use these modules from Oracle Application Server to Oracle9iAS, 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 Oracle9iAS

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

Namespace Collision

Both Oracle Application Server and Oracle9iAS 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 Oracle9iAS 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 Oracle9iAS form the package name differently. Oracle Application Server cannot cache subroutines with the same name. Oracle9iAS 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 Oracle9iAS.

See Also:

http://cgi-lib.stanford.edu/cgi-lib for more information on 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.

The corresponding pre-load script for Oracle9iAS 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 Oracle9iAS, you must migrate LiveHTML SSI to Apache SSI. Currently the only equivalent to LiveHTML embedded scripts in Oracle9iAS is JSP.

SSI

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

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 the OC4J 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 Oracle9iAS. 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 from the Web for tools that allow using Perl as a scripting language with HTML, for example at http://perl.apache.org/#appservers.


    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--Oracle9iAS complies with JSP 1.1 specifications. To migrate you LiveHTML application to Oracle9iAS, you must do the following:

  5. Migrate from the LiveHTML application model to the JSP application model.

  6. Migrate LiveHTML tags to JSP tags.

  7. 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 JavaServer Pages Developer's Guide and Reference in the Oracle9iAS Documentation Library


    Note:

    Oracle9iAS does not provide WRB APIs.


CWeb Migration

In Oracle Application Server, you can use the CWeb Cartridge to:

The migration paths from Oracle Application Server CWeb Cartridges to Oracle9iAS include:

Using FastCGI

CWeb cartridge is essentially a .DLL or a .so library. You can integrate 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 Oracle9iAS. When a URL that maps to the "CGI program" is accessed, the Web server will start 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 Oracle9iAS 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.

However, CGI causes the invocation of a new program on each request and does not support program reuse. Beginning Oracle9iAS v1.0.2.2, this problem is solved with the introduction of FastCGI.

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. For FastCGI examples, refer to http://www.fastcgi.com.


Note:

The same limitations of WRB API mentioned earlier still apply, since the Oracle9iAS does not provide WRB APIs.


Creating a Custom Oracle9iAS Module

If you used CWeb to create custom cartridges you can also consider creating a custom Oracle9iAS module.

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


Go to previous page Go to next page
Oracle
Copyright © 2002 Oracle Corporation.

All Rights Reserved.
Go To Documentation Library
Home
Go To Table Of Contents
Contents
Go To Index
Index