Web-enabling Oracle Developer Applications

Bonnie Vermillion, Dulcian, Inc.

Introduction

The Web has become an important mechanism in providing non-client/server business application solutions. For this reason, it is important for corporations to further reduce the cost of implementing Web solutions by Web-enabling existing business applications. More applications would be running on the Web both as Intranet and Internet applications if current client server applications could be Web-enabled.

Oracle’s Web Application Server, now known as Oracle Application Server (OAS), makes it possible to Web-enable Oracle forms and reports. This process becomes easier with each new release of the Oracle Application Server.

This paper explains how to implement a Web forms solution for Oracle Forms applications. It covers issues that need to be addressed in the Application Server and in the form. Also included is an explanation of how the Application Server and Developer work together to Web-enable forms. Additional tips and issues regarding the installation and configuration of the Web Server will also be covered.

Developer Versions 2.1 (Forms 5) and Forms 6 are discussed although, as of this writing, version 6 is only in beta release and Oracle Application Server 4 is not yet compliant with Developer 6 architecture.

Factors to Consider

There are three important factors to consider in deploying Web forms:

5. Architecture
6. Software versions
7. Performance

Each will be discussed in turn.

1. Architecture

The architecture of Web forms is a three-tier solution. The first tier is the user interface or client, which consists of a Java-enabled browser. The second tier is the application server . The third tier is the database server. Developer resides on the Application Server and consists of a Forms Client and Forms Server. At runtime, the Forms Client, a Java applet, is downloaded to the client displaying the form and manages the connection between the client and application server. The Forms Server consists of a listener and a runtime engine. The Forms Server Listener starts the runtime session and connects the Forms Client to the Forms Server runtime session. Thus, the client handles the user interface while all processing occurs on the application server.

The Oracle Application Sever also resides on the application server. All versions following 4.0.6.4 of the Oracle Application Server (OAS) require their own ORACLE_HOME, separate from the database and therefore must physically reside on a machine separate from the one where the database resides.

2. Software versions

Software versions must be compatible. To avoid confusion, it is important to read the release notes in the Developer documentation. For example, the following software requirements differ based on the database and Developer version deployed:

Software requirements for Oracle RDBMS 7.3.4 or 8.0.4:

• Developer 2.1 (server version)
• Internet Explorer 4.0 or Netscape 4.04
• Web Application Server 3.0.1

Software requirements for Oracle RDBMS 8.0.4:

• Developer 2.1 (server version)
• Internet Explorer 4.0 or Netscape 4.04
• Oracle Application Server 4.0

Software requirements for Oracle RDBMS 8.05

• Developer 6 (server version) (beta at the time of this document)
• Internet Explorer 4.0 or later, or Netscape 4.04 or later
• Oracle Application Server 4.6.4* or later

*Note – Netscape 4.05 will not work with OAS4.0.6.4 unless it is the international version

3. Performance

Performance is a major concern in implementing Web forms because all processing is handled by the application server instead of the client. The developer needs to be aware that any action in the form requires processing on the application server. There are a number of ways to improve performance with Web forms. Oracle goes into much detail regarding performance in the Oracle Developer Guidelines for Building Applications section of the documentation that is provided with Developer. Important performance issues to be aware of include:

• Upgrading to the latest releases of Developer, Web Server and browsers
• Upgrading hardware for clients, servers and network connections
• Database Server array processing to retrieve records in batches instead of one by one
• Increasing the ARRAYSIZE parameter to the highest value in Developer runtime
• Efficient SQL and PL/SQL code
• Moving the logic up to the block level

Read the Oracle documentation carefully since there are many other useful performance tips specific to Forms, Reports and Graphics.

Images, background images, and timers also degrade performance. It is best to eliminate such items wherever possible in Web forms. Images such as company logos can be called within the HTML file that loads at startup. This retains them in the Forms application and improves performance.

Forms Issues

The documentation that comes with Developer is very clear regarding form features that will not convert to the Web. This documentation is available after installing Developer 2.1 and can be accessed by selecting START/PROGRAMS/DEVELOPER DOC. Once you have access to the documentation, select "Guidelines for Building Applications" and then select "Deploying Applications on the Web." This section of the documentation will specify of the form restriction details.

The major items to be concerned with are the following:

• MDI windows and toolbars that will need to be attached to other canvases
• WHEN_MOUSE_ENTER/LEAVE/MOVE triggers which need to be removed for performance reasons
• Combo boxes which will work once Java implements a combo box widget
• 3^rd party controls that control output on the application server which are thus not usable by clients such as ACTIVEX, OCX, OLE, and VBX controls

In order to run an .FMX as a Web form, the .FMX must be the same version as the Developer Server version. If a Forms 4.5 .FMX is to be run as a Web form under Developer Server 2.1, the .FMX must first be converted to a Forms 5.0 .FMX.

Implementation

In order to implement Web forms, some specific installation requirements for Developer 2.1 are necessary including :

• Ensuring that Oracle RDBMS version 7.3.4 or 8.0.4 or future version is installed and operational. This includes SQL*NET. A TNS names entry will need to be added to the tnsanmes.ora file for this database.
• Installing or having available either Internet Explorer 4.0 (or later) or Netscape 4.04 (or later) Internet browser on the client machines.
• Installing Developer 2.1 (Server Version) or future Developer version on the server where WAS 3.0.1 will be installed.
• Following the installation instructions for either WAS 3.0.1 or OAS 4.0 or future version using the Oracle Installer. When installing the Oracle Web Server , a username and password for ADMIN will be required. The default username of ADMIN should be used with any password desired. The ADMIN user is the only user permitted to configure the Oracle Application Server and the password given at installation will be required upon configuration.
• Download JInitiator, Oracle’s version of JavaSoft’s Plug-In that allows the Internet Explorer or Netscape browser to use Oracle’s Java Virtual Machine (JVM) definitions, on the Application Server. JInitiator can be obtained from the www.oracle.com Web site. Follow the installation directions.

Once all of the above products are installed, select "Start/Programs/Developer 2000 R2.1." Select "Forms Server Listener." This only takes a second to start and will quickly return to the menu. It is important to note that anytime the WebServer box is shutdown, upon startup this process will need to be invoked. Later, when configuring cartridges for the Web Application Server, a ServerPort parameter will be defined in the cartridge and linked to the value of 9000. This definition relates to the Forms Server Listener. If an attempt is made to run Web forms without starting the Forms Server Listener, a message to the effect that "ServerPort 9000 is invalid" will be displayed. The solution is to start the Forms Server Listener from the Designer 2000 R2.1 menu.

In order for Web Forms to be deployed the Oracle Application Server (OAS) must be configured. The steps for configuring OAS 3.1 are as follows:

1. Start the Application Server:

Each time the Server is booted one of the two methods described below will need to be performed.

• Verify that the Web Application Server has been started. There are two ways to accomplish this. The first way is to log into Services by going to the Control Panel and selecting "Services." Ensure that the OracleStartORCL and the OracleTNSListener automatic processes are running. The OracleWRBPrimaryService should also be started. If any automatic processes are not running, reboot the server and check again or attempt to manually start them by selecting the process in the server window and pressing the START button. Next, select the "ORACLEWWWListener30ADMIN" manual service and click on START. This will also start the services controlled by the Web Request Broker indicated by service names beginning with OraWeb_WRB. The OracleWWWListener30WWW service should be the only process not yet started. Select the OracleWWWlistener30WWW service and press the start button to start the WWW Listener.
• The second way to start the Oracle Application Server is to click on the Control Panel to get to the DOS prompt. At the DOS prompt, type in OWSCTL START WRB to start the Web Request Broker. When this process completes then type OWSCTL START ADMIN. This starts the ADMIN process and the ADMIN listener. It is recommended that this method only be used if the Services method described above is unsuccessful.

2. Log on as the ADMIN user. This step also verifies that the Web Application Server successfully started.

3. Connect to either the Internet Explorer 4.0 (or later) or the Netscape 4.04 (or later) Internet browser. In the address field enter: http://hostname:8888/ as the URL. The number 8888 indicates the port used. This URL will bring up a username/password box. Enter ADMIN as the user and enter the password given for the ADMIN user during installation of the Oracle Application Server.

4. Configure the Listener.

• Select the Web Application Server Manager to move to the OAS Administration Home Page.
• Click on the Oracle Web Listener selection to configure the listener. Scroll down to where the listeners are listed. Initially there will be two: admin and www. The admin listener was started when the Web Application Server was started. The admin listener should not be touched! This listener controls the ability to configure the Web Application Server and is started and shutdown along with the Web Application Server’s starting and stopping processes.
• A new listener can be created or the www listener can be further configured for use with Web forms. This listener is connected to port 80. To connect to this listener from the Internet browser, enter http://hostname:80/. The Web Application Server Home Page will be displayed if the listener is running.
• New listeners can be created and attached to any port not already used by an existing listener. Ports range from 1 to 65535. Oracle documentation states that ports less than 1024 require superuser privileges such as the admin user. Thus, any listener used in the administration process should be identified with a number less than 1024. The only requirement for assigning port numbers is that they not already be assigned to a process.
• To configure the www listener for Web forms, go back to the Listener Administration page. Click on the "Stop" button to stop the listener if it is running. Next, click on the "Configure" button and the Listener Administration Advanced Configuration page will be displayed.
• As you scroll down through the Listener Administration page, you will see many areas already configured. None of the existing settings will be changed for the www listener in order to configure Web forms. The addition of virtual directories is the requirement. Scroll toward the bottom of the Listener Administration page to find the Directory Mappings section. Enter the following directory mappings in the first available (blank) directory mapping fields. Keep in mind that the local directory of d: may be different on the server being configured. Make the adjustment if different.

File-System Directory	Flag	Virtual Directory
D:\orant\forms50\Java\	NR	/w50_code/
D:\apps\Web\HTML\	NR	/Web_HTML/
D:\apps\Web\jars\	NR	/Web_jars/
D:\apps\Web\tmp\	NR	/Web_temp/

Please note that all of the above file system directories should exist on the physical drive indicated. If the directories do not exist, create the ones needed. The jar directory needs to contain copies of the jar files from the forms50/Java directory. The HTML directory will contain the HTML files that will be created to pass the form information to the Oracle Application Server.

The www listener is now configured for Web Forms. Click on the "Modify Listener" button. A success message will appear. Scroll down the page to verify that the Modify process also started the listener. If the listener did not start, but was successfully modified, click on the "Start" button. If the listener does not start then either the directory does not exist or there is a spelling or syntax error in one of the file system or virtual directory mappings.

5. Configure the Cartridge

Configuration of a cartridge for Web forms is not required to enable Web forms. A non-cartridge implementation is possible and is described in the next section . The creation of a cartridge permits parameters to be passed from the URL to the Web Application Server instead of having to hard code information such as User Name and Password in a static HTML file. This allows one HTML file to pass in information via the URL instead of a static file for each form.

Click on the "ADMIN" button from the Listener Administration page to get back to the Web Application Server Administration page. From this page, click on the "Oracle Web Application Server" icon. From the next page, click on "Cartridge Administration." Click on "Add a New Cartridge." From the Cartridge Administration page click on "Add New Cartridge with Manual Configuration."

The page will now be labeled "New Cartridge Configuration." Enter the following information:

Cartridge Name	w50_cart
Object Path	d:\orant\bin\f50Webc.dll
Entry Point	form_entry
Min # Instances	0
Max #	10
Services	TRANSACTIONS
	CONTENT
Protocol
List of Hosts
Custom config URL
Cartridge Description	Forms 50 Cartridge
Cartridge Icon
Valid mime types
Client certificate	Disabled
Client sessions	Disabled
Max Session Idle Time	0
Error Page	%ORAWEB_HOME%/admdoc/wrberr.HTML

Next under Virtual Paths enter:

Virtual Path**	Physical path
/w50_cart	d:\orant\bin

**Note that there is no slash after the virtual path.

Click on "Register New Cartridge." Go back to the Cartridge Administration Page and select the Forms 50 Cartridge that was just created . Click on "w50_cart Cartridge specific Parameters" and enter the following:

Parameters	Values
BaseHTML	d:\apps\Web\HTML\w50_cart.HTML
HTMLdelimeter	%
Code	oracle.forms.uiClient.v1_4.engine.Main
Codebase	/w50_code/
Archive	/Web_jars/f50Web.jar
ServerPort	9000
module
userid

Click on "Modify Cartridge Configuration." Note that the ServerPort 9000 definition above is connected to the forms listener process. This step concludes the Web Application Server Configuration process.

6. ICON configuration

Icons need to be converted to GIFs and physically located in the directory indicated by the /Web_temp/ virtual directory in the OAS listener.

Modify the NT REGISTRY:

FORMS50_MAPPING /Web_temp

FORMS50_OUTPUT D:/’server image file temp directory’

or

Modify registry.dat:

Default.icons.iconspath=http://servername.com:listenerport/Web_temp/

Default.icons.iconextension=gif

HTML examples

An example of the HTML file used to pass the form and user information is shown below and another HTML file example shows how hard coding information within the HTML file will bypass use of the cartridge.

Cartridge HTML file example:

<HTML>

<HEAD>

<TITLE>Developer Forms 50 Cartridge: form50cart</TITLE>

</HEAD>

<BODY>

<OBJECT classid="clsid:9F77a997-F0F3-11d1-9195-00C04FC990DC"

WIDTH=%Width%

HEIGHT=%Height%

codebase="http://mymachine/jinit1110f.exe">

<PARAM NAME="CODE" VALUE="%Code%">

<PARAM NAME="CODEBASE" VALUE="%Codebase%">

<PARAM NAME="ARCHIVE" VALUE="%Archive%">

<PARAM NAME="type" VALUE="application/x-jinit-applet;version=1.1.1.0f">

<PARAM NAME="serverHost" VALUE="%ServerHost%">

<PARAM NAME="serverPort" VALUE="%ServerPort%">

<PARAM NAME="serverArgs" VALUE="Module=%Module%">

<COMMENT>

<EMBED type="application/x-jinit-applet;version=1.1.1.0f"

Java_CODE="%Code%"

Java_CODEBASE="%Codebase%"

Java_ARCHIVE="%Archive%"

WIDTH=%Width%

HEIGHT=%Height%

serverHost="%ServerHost%"

serverPort="%ServerPort%"

serverArgs="Module=%Module%"

pluginspage="http://mymachine/jinit_download.htm">

<NOEMBED>

</COMMENT>

</NOEMBED></EMBED>

</OBJECT>

</BODY>

</HTML>

NON-Cartridge HTML file example:

<HEAD><TITLE>Developer Server and Oracle Jinitiator</TITLE></HEAD>

<BODY>

<P>

<OBJECT classid="clsid:9F77a997-F0F3-lldl-9195-00C04FC990DC"

WIDTH=180

HEIGHT=20

codebase="http://mymachine/Web_HTML/jinit1110f.exe"

>

<PARAM NAME="CODE" VALUE="oracle.forms.uiClient.v1_4.engine.Main">

<PARAM NAME="CODEBASE" VALUE="/form50code/">

<PARAM NAME="ARCHIVE" VALUE="/form50code/f50all.jar">

<PARAM NAME="serverPort" VALUE="9000">

<PARAM NAME="serverArgs" VALUE="module=d:\orant\forms50\emp.fmx userid=Web_user/Web_user">

<PARAM_NAME="serverApp" VALUE="default">

<COMMENT>

<EMBED Java_CODE="oracle.forms.uiClient.v1_4.engine.Main"

Java_CODEBASE="//"

Java_ARCHIVE="/form50code/f50all.jar"

WIDTH=180

HEIGHT=20

serverPort="9000"

serverArgs="module=d:\orant\forms50\emp.fmx"

pluginspage="http://mymachine:mylistener/Web_HTML/jinit_download.htm">

<NOEMBED>

</COMMENT>

</NOEMBED></EMBED>

</OBJECT>

</BODY>

</HTML>

URL Examples

The following examples show differences between URLs with and without the cartridge.

Example with the cartridge:

http://hostname/w50_cart?Module=form&userid=username/password@database

Example without the cartridge:

http://hostname /Web_HTML/filename.HTML

Test

To test a form, set up the HTML file. You may want to try both types. Use the URL examples to enter a URL from the Browser. The form will need to be recompiled using Developer 2.1 and the .FMX will need to be physically put in the \APPS\WEB\FORMS directory.

Developer 6 and OAS4

As of this writing Developer 6 exists in beta only. Upon its production release, it will be compatible with OAS 4.07. According to Oracle, changes need to be made in Developer 6 and in OAS 4.0.7 in order for Web Forms to work. Some important OAS 4 concepts to be aware of are outlined below.

OAS4 brings a new look and feel to the Oracle Application Server, but does not contain the required application type to produce a Forms Web cartridge at the time of this writing.

The components of OAS 4 are similar to prior versions, but the concepts and interface are different. There are 3 layers to OAS4. These layers work together to pass requests from the client to the database and back:

1. HTTP layer: The HTTP layer consists of Listeners (HTTP Servers) that handle client requests and pass them to a dispatcher via adapters (API’s). The dispatcher then forwards the request to the virtual path manager where the request is mapped to the cartridge type. Examples of cartridge types include PL/SQL, JWEB, and C Cartridge. D2KWEB is the cartridge type that will be used to deploy Web forms with OAS 4 and Developer 6. As of OAS 4.0.6.4 this cartridge type does not exist.
2. Oracle Application Server layer: The Oracle Application Server layer manages requests on the server by using various components such as load balancing.
3. Application layer: The Application layer is composed of applications, cartridges and cartridge servers. Applications contain one or more cartridges of the same cartridge type and exist within one or more cartridge server processes. A cartridge server can only run one application, but can spread the processing over multiple cartridge servers for one application consisting of one or more cartridges. As the number of users increases, the number of cartridge servers and cartridges should increase to improve performance. Load balancing can be used to further increase performance by distributing client requests across cartridges. Configuration of load balancing occurs in the cartridge.

Configuring OAS4

Configuration of OAS 4 for Web Forms is not performed in isolation, but becomes part of an expanded function of configuration of the Forms Server that now contains a listener and a modified Forms runtime engine. OAS 4.0.6.4.0 is the most recent OAS 4 release at the time of this writing. This release is compatible with Developer version 6 beta release for the non-cartridge release only. As stated above, the Developer 6 production release will be compatible with OAS 4.0.7. Be sure to read the Release Notes option on the Welcome page when logging into OAS as ADMIN.

OAS4 and Developer 6 can be loaded on a standalone machine, but in order to be used properly should be loaded on separate machines. Configuration for a standalone machine on NT does not require entries in the TNSNAMES.ORA file and configuration areas requiring a connect string should be left blank.

Configuration of the Forms Server is similar to configuring 3.0.1 with a few exceptions and includes the following steps:

1. Install the Oracle Developer Server (Developer 6)
2. Install the Oracle Web Server. OAS 4.07 can be installed over 4.0.6.4. to retain existing server configuration. However, when installing on multiple servers, use different Oracle homes. The upgrade will overwrite existing cartridges with the same name. Check for naming conflicts prior to running the upgrade and change the cartridge names in the 4.0.6.4 version.
3. After installation use the URL http://machine_name:8888 to log onto the OAS 4 Welcome Page. The OAS Manager port number is assigned the value of 8888. OAS 4 will also assign the 8889 port to the Admin listener. The OAS 4 Manager will also retain the port number of 8890. The OAS 4 WebServer should always be started by the OAS MANAGER interface. If unsuccessful, use the command line method.
4. Configure a listener and Web cartridge (create an application of D2KWEB type first) within OAS.

• Configuring a listener needs a node, a listener name and a port number. The host name and route directory are the defaults.
• Once created, modify the listener to enter virtual directory definitions and create the cartridge after creating the application.
• If a non-cartridge implementation is being used, a DAD (Database Access Descriptor) must be created. If the non-cartridge implementation is on a standalone machine, no connect string is entered.

1. Create a base HTML file to launch the form.

• Follow sample CARTRIDG.HTM for a cartridge implementation or STATIC.HTM files in creating a base HTML file for your application. These sample files are found after loading the samples for the D2KWEB application type and are located in the ORACLE_HOME\TOOLS\DEVDEMO6.WEB directory. The sample HTML files are also listed in the online documentation.

1. Create a Forms Server NT service.

• Instead of starting the Forms Server Listener process from a menu option as in OAS version 3.0.1, create an NT service that can be started automatically or manually.

1. Create Forms Server Environmental Variables.

• FORMS60_MAPPING, FORMS60_OUTPUT, and FORMS60_REPFORMAT are required environment variables. These environment variables allow Reports Builder or Graphics Builder to be called from a Web Form using the Form Builder built-in RUN_PRODUCT. A created report specified as a file is stored in the physical directory specified by FORMS60_OUTPUT. A report specified for preview or screen will be put in the physical directory defined by FORMS60_OUTPUT. The report will also create a temporary file as defined in FORMS60_MAPPING and the browser format will be determined by FORMS60_REPFORMAT.

1. Optional customization of the Forms Server can be done by configuring load balancing and creating custom JAR files.

Oracle has included online documentation with Developer 6 for easy configuration of each step.

Recompile .FMX’s using Developer 6 and run the form by launching the base HTML file from a Java enabled browser . The HTML file must point to the correct directory where the .FMX resides.

Conclusion

Using Web Forms is becoming a more viable option for application deployment as performance is improved and more features within forms can be Web-enabled. The Oracle documentation within each version has also improved and is easier to understand and follow. Specifically, the online documentation provided with Developer and the Oracle Application Server explains the methodology used as well as the specific installation steps.

Web-enabling Oracle Developer Forms applications provides cost effective reuse of existing business applications, allowing customers to take full advantage of their Intranet in application deployment. Reduction in maintenance, client hardware and Web application design and deployment costs are the main benefits of this approach.

About the Author

Bonnie Vermillion is a Senior Developer with Dulcian, Inc. She has been an Oracle Developer for over 10 years with the Federal Government including 3 years with the Federal Trade Commission. She has 4 years experience working with Designer/2000 (now Oracle Designer) and serving as CASE administrator. Bonnie has given presentations at ECO, ODTUG, and numerous local Oracle user group meetings. She can be contacted at bvermillion@dulcian.com or through Dulcian’s Website at www.dulcian.com.