8
Migrating Legacy Applications to the Web

8.1 Introduction

If you are currently using the client/server version of Forms Server, migrating applications to Forms Server for the Web is straightforward. This chapter briefly describes the differences between client/server and Web implementations, and then gives guidelines to migrate your current applications from client/server-based to Web-based Forms Server.

Traditionally, load balancing services in Oracle Forms Server were supplied via an Oracle Application Server (OAS) cartridge. If you wanted to deploy forms on the Web via a servlet implementation in lieu of an OAS cartridge, load balancing was not an option.

With the release of Oracle Forms Server 6i, you can now use load balancing with forms applications that are deployed on the Web via a servlet implementation. With load balancing, when you approach the usage limits of your hardware, rather than upgrading or replacing a machine, you can simply add more machines to run your application and balance the load of server traffic across several machines.

If you have already deployed Web-based Forms Developer applications via an OAS cartridge and you wish to switch to servlet, you will need to install Oracle Forms Server 6i and configure it for servlets. The purpose of this chapter is to help those with existing cartridge-based implementations install or reconfigure Oracle Forms Server 6i from OAS cartridges to servlets.

8.1.1 Client/Server-Based Architecture

In the client/server-based implementation, shown in Figure 8-1, the Forms Server Runtime Engine and all application logic are installed on the user's desktop machine. All user interface and trigger processing occurs on the client, except for database-server-side triggers and logic that may be included in some applications.

Figure 8-1 Forms Server client/server-based architecture

8.1.2 Web-Based Architecture

In a Web-based implementation, shown in Figure 8-2, the Forms Server Runtime Engine and all application logic are installed on application servers, and not on client machines. All trigger processing occurs on the database and application servers, while user interface processing occurs on the Forms client, located on users' machines.

Figure 8-2 Forms Server Web-based architecture

8.1.3 Who Should Read this Chapter?

This chapter will be useful to you if the following statements apply to your deployment environment:

• You currently deploy Web-based Oracle Forms Developer applications.

• You use OAS for Web server support.

• You deploy Web-based Oracle Forms Developer applications using OAS cartridges.

• You want to move from cartridge deployment to servlets.

8.2 Comparing Cartridge and servlet Implementations

Cartridge and servlet implementations both require that you set server operational parameters that define values for such things as port numbers and locations of relevant files. The difference is in where you set them. In OAS, you open the OAS Manager and navigate to various destinations to set parameters for different deployment entities. In Oracle Forms Server, configuration complexity is more centralized. You set many operational parameters automatically through configuration choices you make during installation. You can revise and set additional operational parameters in Oracle Forms Server's formsweb.cfg file, which is created during installation.

Cartridge and servlet implementations both produce an HTML file on-the-fly that is rooted in a standard base HTML file. In a cartridge implementation, the HTML file is created through a combination of the cartridg.html file, cartridge configuration settings, and the application's URL. In a Forms servlet implementation, the HTML file is created through a combination of the base.htm or basejini.htm file, the formsweb.cfg file, and the application's URL.

In both cartridge and servlet base HTML files, you can define a parameter with a variable and then define the variable value in the application's cartridge settings (OAS), the formsweb.cfg file (Oracle Forms Server 6i), or via a query string in the application's URL (both OAS and Oracle Forms Server).

The major differences between cartridge and servlet implementations are in the types of services and level of performance offered through your non-OAS Web server (as compared to those offered through OAS), the broader range of operational parameters now available through Oracle Forms Server 6i, and the vastly simplified process of setting forms parameters via Oracle Forms Server installation and the formsweb.cfg file.

8.3 Reconfiguration Strategies

This section provides a high-level overview of the reconfiguration process. It is suitable for users who have a technical understanding of OAS, Oracle Forms Server, base HTML files, and the like.

There are two basic strategies for reconfiguring cartridge deployments to servlets:

• Keep everything the same, replicating cartridge parameters in the formsweb.cfg file.

• Use the default Oracle Internet Application Server installation.

The first strategy is appropriate for users with complex base HTML files, that is, files that contain much extraneous text, images, and other objects in addition to the Forms applet tags. The second strategy is appropriate for users with simple base HTML files.

8.3.1 Strategy for Users with Complex Base HTML Files

The strategy for users with complex base HTML files is to keep everything the same.

1. Stop all instances of OAS you will no longer use.

2. Install Oracle Internet Application Server.

3. In the formsweb.cfg file, reproduce the parameters that were used for cartridge configuration.
   To locate current OAS cartridge parameters, launch OAS and navigate to each forms application's Cartridge Configuration folder. Within each folder, click Cartridge Parameters. This displays the OAS cartridge parameter settings. Additionally, you will find parameter settings in the base HTML file(s) you created for Forms cartridge applications.
   If you were using several OAS cartridge definitions for the Forms cartridge (that is, you were using several base HTML files), define separate configuration sections in the formsweb.cfg file-one for each cartridge. (With both strategies, the better practice is to create new configuration sections for cartridge parameters in the formsweb.cfg file rather than specify the parameters at the start of the formsweb.cfg file, outside a named section.)

   For a non-OAS Web listener, define the same virtual paths you used with OAS. Add a new virtual path for scripts that point to the directory containing the servlet, as follows:

   virtual_path_name = /servlet/

   physical_path = <ORACLE_HOME>/6iserver/forms60/java/oracle/forms/servlet
   

   Change all the URL's you use to run forms to point to the servlet rather than the cartridge. For example, if the original URL was:

   http://servername.my.domain.com/developerforms/forms60cart?module=emp.fmx 
   

   It should become:

   http://server:port/servlet/f60servlet?config=emp
   
   

Note:

If you are using the HTTPS communication mode, use "https" rather than "http" in the examples above. (This is optional for Oracle JInitiator.)

In this example, "myconfig" is the name of the configuration section you defined in the formsweb.cfg file that contains the parameters equivalent to your old cartridge parameters.

8.3.2 Strategy for Users with Simple Base HTML Files

The strategy for users with simple base HTML Files is to use the default Oracle Internet Application Server installation.

If your cartridge implementation used simple base HTML files, your reconfiguration to servlets can easily benefit from the default configuration that is created automatically during the installation.

1. Stop all OAS instances you will no longer use.

2. Install Oracle Internet Application Server.

3. Adapt the URLs you used to run your forms to achieve the same effect as you had with the cartridge. Use the parameters that are defined for you in the formsweb.cfg file. These allow you to change just about every conceivable HTML and Forms Applet parameter value by specifying the value in the application's URL. The same URL will work for users of the AppletViewer, a Web browser in combination with Oracle JInitiator, or Internet Explorer 5.0.

4. Use the runform.htm file to experiment with different parameter settings in the application's URL. For example, this might be the URL you would use to run a form with a page title "My Form," a page width of 400, and a page height of 550:

   http://server:port/servlet/f60servlet?pagetitle=
   My+Form&width=400&height=550
   
   

Note:

If you are using the HTTPS communication mode, use "https" rather than "http" in the examples above. (This is optional for Oracle JInitiator.)

In these examples, the question mark signals the start of the query string in the application URL. The query string specifies the values for the pagetitle, width, and height parameters.

8.4 Reconfiguring Forms Web Cartridge to Servlets

Take these steps to reconfigure forms deployments from OAS cartridge to servlets:

1. Stop the OAS Web Listener instances you will no longer use.

2. Install Oracle Internet Application Server.

3. Configure the Oracle Forms Server formsweb.cfg file.

4. Optionally, configure the Oracle Forms Server base.htm and basejini.htm files.

5. Broadcast the application's URL.

8.4.1 Stopping OAS Web Listener Instances

There are two scenarios for stopping OAS:

• Stop it completely.

• Stop only specific instances while OAS continues to support other instances.

8.4.1.1 Stopping OAS Completely

Use this technique if you wish to stop using all services offered through OAS:

1. Launch OAS.

2. Open the OAS Manager.

3. Navigate to the top-level site of the OAS installation.

4. Select All.

5. Click the Stop button.

8.4.1.2 Stopping Specific Instance of OAS

Use this technique if you wish to stop only some OAS HTTP Listeners and leave others running:

1. Launch OAS.

2. Open the OAS Manager.

3. Navigate to HTTP Listeners.

4. Select those HTTP Listeners running on ports you are planning to convert from cartridge to servlets.

5. Click the Stop button.

8.4.2 Configuring the formsweb.cfg File

The formsweb.cfg file is a powerful new convenience included with Oracle Forms Server 6i. Use it as a repository for all the settings you need to run Oracle forms on the Web in a servlet implementation. The installer places this file in <ORACLE_HOME>/6iserver/forms60/server.

The formsweb.cfg file is a text file that contains configuration parameters for running Forms applications on the Web in a servlet implementation. The configuration parameters in the formsweb.cfg file are the equivalent of the cartridge parameters used with the Forms cartridge. The formsweb.cfg file is divided into three main sections:

• System Parameters

• User Parameters

• Specific Configurations

Refer to Chapter 5.5.2, "formsweb.cfg" for more specific information about configuring the formsweb.cfg file.

8.4.2.1 System Parameters

The System Parameters section provides information required by the Forms servlet. Unlike many other parameters in formsweb.cfg, System Parameters cannot be specified in a URL query string. However, you can override their values by placing an alternate parameter/value set in a Specific Configuration section in formsweb.cfg, then calling that configuration in the application URL.

8.4.2.2 User Parameters

The User Parameters section is where you specify the actual values for parameters that are defined with variables in the base HTML file. For example, in the base.htm file you might have:

<PARAM NAME="separateFrame" VALUE="%separateFrame%">

In the formsweb.cfg you would set the specific value for the variable %separateFrame%:

separateFrame=false

You can override specified User Parameter values in a Specific Configuration section in formsweb.cfg or in a query string in the application's URL.

For example:

http://server:port/servlet/f60servlet?separateFrame=true

Note:

If you are using the HTTPS communication mode, use "https" rather than "http" in the examples above. (This is optional for Oracle JInitiator.)

In these examples, the query string ?separateFrame=true will override the value for separateFrame that is specified in the formsweb.cfg file.

When a specific value for a parameter is defined in both the formsweb.cfg file and the application's URL, the value defined in the URL is used.

8.4.2.3 Specific Configurations

If you want to run the same form with multiple configurations, you can define custom configurations with custom values in the Specific Configurations section of the formsweb.cfg file.

When you call the custom configuration with a query string in the application's URL, the custom values will override the parameters defined in the User Parameters section of formsweb.cfg. When you set up a Specific Configurations section, you need only specify the parameters you want to change. The default values that are specified in the User Parameters section will be used for all other parameters.

Use the "config" parameter in the application's URL to call a particular Specific Configuration section. For example, the following URLs call the Specific Configuration section [myconfig]:

http://server:port/servlet/f60servlet?config=myconfig

Note:

If you are using the HTTPS communication mode, use "https" rather than "http" in the examples above. (This is optional for Oracle JInitiator.)

Refer to Chapter 5.5.2, "formsweb.cfg" for more specific information about configuring the formsweb.cfg file.

8.4.3 Configuring the base.htm or basejini.htm File

When you start a Web-enabled application (by clicking a link to the application's URL), the Forms servlet reads a special file that contains all necessary applet tags, parameters, and parameter values (or variables for those values) that are required to run the selected application on the Web. This is the base HTML file.

The Oracle Universal Installer places two base HTML files in the following directory: <ORACLE_HOME>/6iserver/FORMS60/server

• basejini.htm
  This file contains the tags required to run the Forms applet using a combination of the user's Web browser and Oracle JInitiator.

  base.htm

  This file contains the tags required to run the Forms applet in the AppletViewer or in any Web browser certified by Oracle whose native JVM is certified to work with Forms.

Refer to Chapter 5.5.3, "base.htm, basejini.htm, and baseie.htm" for more specific information about the base.htm and basejini.htm files.

In a Forms Web servlet implementation, as the application launch process gets started, any variables (%variablename%) in the base HTML file are replaced with the appropriate parameter values that are specified either in the formsweb.cfg file or in a query string included in the application's URL. Once all values are defined, the HTML file is generated and then downloaded to the user's Web browser, and the selected forms application launches.

When a specific value for a parameter is defined in both the formsweb.cfg file and the application's URL, the value defined in the URL is used.

In most cases, you will not need to modify the default base HTML files. Instead, you can define their parameters with variables. Then you can define the actual values for the variables in formsweb.cfg or in the application's URL.

For example, you can define the parameter splashScreen in the base HTML file as:

<PARAM NAME="splashScreen" VALUE="%splashScreen%">

Then define the actual value in the formsweb.cfg file as:

splashScreen=virtual_path/mysplashscreen.gif

Note:

If you are using the HTTPS communication mode, use "https" rather than "http" in the examples above. (This is optional for Oracle JInitiator.)

Using variables instead of values in the base HTML file allows you to use the same generic base HTML file for all your forms applications and to manage configuration complexity from one location: formsweb.cfg (or the application's URL).

If you decide to specify parameter values in the base HTML file, do not modify the original base HTML file that is provided by Oracle. Instead, modify a renamed copy. Be sure to update the baseHTML (or the basejiniHTML) parameter in the formsweb.cfg file to point to the location of the modified file.

8.4.4 Broadcasting the Applications's URL

To broadcast the application's URL, simply notify your intended users. Your users can contact the URL with their Java-enabled Web browsers and run the corresponding application. For example, to announce the availability of its new Order Tracking application, ABC Corp. might notify employees via e-mail of the following URL:

http://server:port/servlet/f60servlet?config=myconfig&form=tracker.fmx

Note:

If you are using the HTTPS communication mode, use "https" rather than "http" in the examples above. (This is optional for Oracle JInitiator.)

ABC's URL consists of the following components:

http or https	Connection protocol
server:port	Name of the machine that hosts the application server
servlet	The virtual path, defined in the Web server, that points to servlets
f60servlet	Forms servlet
?config=myconfig&form=tracker.fmx	The query string that points to a custom configuration defined in the user-created "myconfig" section of the formsweb.cfg file and to the form module tracker.fmx The parameter "form" is used here because "form" was defined as the variable value for "module" in the base HTML file. That is: <PARAM NAME="serverArgs" VALUE="module=%form%"> The syntax is slightly different in the base HTML JInitiator file: serverArgs="module=%form%"

8.5 Guidelines for Migration

When migrating your applications from client/server deployment to the Web, note that a Web-based application:

• Supports JPEG and GIF image types only, so convert existing images to these formats.

• Supports the use of compressed JAR (Java Archive) files for file transfer, so use JAR files whenever the transfer of large files is required between the Forms Server and Java client.

• Does not support ActiveX, OCX, OLE, or VBX controls in the user interface. Instead, use JavaBeans to duplicate functionality in the user interface. Any other Microsoft Windows user interface dependencies should also be replaced with JavaBeans.

• Does not support MouseMove triggers, such as When-Mouse-Enter, When-Mouse-Leave, and When-Mouse-Move.

• Does not natively support write access to the client hard drive. This can be accomplished by writing a JavaBean for the pluggable Forms user interface.

• Supports Java fonts only, so check applications for the types of fonts used. If necessary, switch to Java fonts. Java uses a font alias list, located in the Registry.dat file. The font aliases described in Table 8-1 are supported:

  Table 8-1 Font support for Web-based applications

  Java font	Windows font	XWindows font	Macintosh font
  Courier	Courier New	adobe-courier	Courier
  Dialog	MS San Serif	b&h-lucida	Geneva
  DialogInput	MS San Serif	b&h-lucidatypewriter	Geneva
  Helvetica	Arial	adobe-helvetica	Helvetica
  Symbol	Wingdings	itc-zapfdingbats	Symbol
  Times Roman	Times New Roman	adobe-times	Times Roman

In this chapter we have provided information about reconfiguring forms cartridge implementations to servlets. We've kept to a fairly narrow path of configuration options to ensure a smooth and successful migration.