Skip Headers

Oracle® Application Server Forms Services Deployment Guide 10g Release 2 (10.1.2) B14032-03 |
| Library | Product | Contents | Index

Previous | Next |

# 11.3 OracleAS Forms Services Upgrade Tasks

This section explains how to perform the Oracle Application Server 10g Forms Services upgrade. It is divided into the following sub-sections:

- Section 11.3.1, "Upgrade Recommendations and Troubleshooting Tips"

- Section 11.3.2, "Upgrading OracleAS Forms Services Application Modules"

- Section 11.3.3, "Upgrading Common Gateway Interface (CGI) to the Oracle Forms Servlet"

- Section 11.3.4, "Upgrading Static HTML Start Files to Generic Application HTML Start Files"

- Section 11.3.5, "Upgrading the Forms 6i Listener to the Forms Listener Servlet"

- Section 11.3.6, "Upgrading the Forms Listener Servlet Architecture to OracleAS Forms Services"

- Section 11.3.7, "Upgrading Load Balancing"

- Section 11.3.8, "Usage Notes"

## 11.3.1 Upgrade Recommendations and Troubleshooting Tips

Consider the following recommendations and considerations while upgrading Forms applications to Oracle Application Server 10g:

- Keep the Oracle6i Forms Services installation available until successful deployment and testing of applications to Oracle Application Server 10g.

- Upgrade source files first, and back up and secure all application files.

- Replace `Run_Product` calls to integrated Reports with `Run_Report_Object` calls to Oracle Reports (or use the PL/SQL conversion utility, Forms Migration Assistant in Oracle Forms).

- Install Oracle Application Server and configure the `forms/server/formsweb.cfg` file with the information used by your applications.

- Copy the environment files used by the applications to the same relative directory.

- Copy the upgraded Oracle Forms application module files to the computer on which Oracle Application Server is installed, if it is not the same computer.

- After starting Oracle Application Server, access the Forms Services Listener Servlet test page with this URL:

  `http://<``hostname``>:<``port``>/forms/frmservlet?form=test.fmx`

- Verify that any application settings are added to the `formsweb.cfg` file and that the environment variable `Forms_Path` contains the directory of the application modules.

- Verify that you can connect to the database using SQL*Plus.

- Use the following URL to invoke upgraded applications:

  `http://<``hostname``>:<``port``>/forms/frmservlet?config=<``your application name``>`

## 11.3.2 Upgrading OracleAS Forms Services Application Modules

This section provides instructions for upgrading from Forms Application Modules (`fmb` files) that were deployed in Oracle 6i Forms Services. Follow these steps to upgrade Forms Application Modules (`fmb` files) deployed in Oracle 6i Forms Services to an OracleAS Forms Services installation.

1. Copy the Forms application files to a new directory.

2. Use the Forms Migration Assistant to upgrade the Forms Application Modules (`.fmb` files).

3. Use the Forms Migration Assistant to upgrade the Forms menu modules (`.mmx` files).

4. Use the Forms Migration Assistant to upgrade the library modules (`.pll` files) and Menu modules (`.mmb` files).

5. Use the Forms Migration Assistant to upgrade to upgrade the library modules (`.plx` files)

6. Use the Forms Compiler (`frmcmp.sh` on Unix or `frmcmp.exe` on Windows) to regenerate the Forms Application executable files (`fmx` files).

For more information, see Migrating Forms Applications from Forms 6i at:

`http://www.oracle.com/technology/documentation/`

## 11.3.3 Upgrading Common Gateway Interface (CGI) to the Oracle Forms Servlet

This section provides instructions to upgrade Forms CGI to the Forms Servlet deployment. Follow these steps if you are using the Oracle 6i Forms Services Common Gateway Interface to dynamically render the Forms Applet start HTML file for applications.

CGI deployment for Forms applications was introduced in Oracle Forms Services Release 6i to enable the Forms Applet Start HTML file to render dynamically. Forms CGI uses the `formsweb.cfg` configuration file and an HTML template to create the start HTML file for an application. The CGI interface is configured by an entry in the Forms HTTP configuration file `6iserver.conf` (it is referenced by an `Include` directive in the Oracle HTTP Server `oracle_apache.conf` file), which contains a `ScriptAlias` directive identifying `dev60cgi` for the directory structure containing the `ifcgi60.exe` file.

The Forms servlet renders the HTML in the same manner as the CGI, but also provides an automatic browser type detection. The Forms servlet is configured when you install OracleAS Forms Services, and is named `frmservlet`.

To access the Forms Servlet, request the URL:

`http://<``hostname``>:<``port``>/forms/frmservlet`

This URL is similar to the URL used with the CGI Interface in Oracle 6i Forms Services. To call an application configured as `myapp` in the custom configuration section of the `forms/server/formsweb.cfg` file, request the URL:

`http://<``hostname``>:<``port``>/forms/frmservlet?config=myapp`

The Forms Servlet is automatically configured during installation. The installer creates a virtual path `/forms/` pointing to the OracleAS Forms Services configuration, `formsapp` and `formsweb`, in the Oracle Application Server Containers for J2EE Business Intelligence and Forms instance (`<``destination_MT_OH``>/j2ee/oc4j/OC4J_BI_Forms`).

Follow these steps to upgrade an Oracle 6i Forms Services Release 6i CGI environment to an OracleAS Forms Services servlet environment:

1. Copy all of the application-specific configurations from `<``source_MT_OH``>/Forms60/Server/formsweb.cfg` and append them to `<``destination_MT_OH``>/forms/server/formsweb.cfg`.

   Note: Do not copy and replace the entire `formsweb.cfg` file in `<``source_MT_OH``>` to `<``destination_MT_OH``>`. The file in Release 6i is different from the OracleAS Forms Services file. Copy only the application configuration to `<``destination_MT_OH``>/forms/server/formsweb.cfg`.

2. Configure `Forms_Path` in the `forms/server/default.env` file to point to the upgraded OracleAS Forms Services application modules.

   Note: You can create a new environment file by copying `default.env`, modifying it for use with a particular application, and adding `envFile=<``created environment file``>` to the custom application section in the `formsweb.cfg` file.

3. If you changed the Oracle 6i Forms HTML template files, then make the same changes to the OracleAS Forms Services HTML template files.

   Note: You must make these changes in `basejini.htm` and `basejpi.htm` because the servlet supports JInitiator and Java plug-ins.

## 11.3.4 Upgrading Static HTML Start Files to Generic Application HTML Start Files

Each application deployed to OracleAS Forms Services has a custom application definition, configured in the `formsweb.cfg` configuration file. It automatically inherits the general system settings, such as the JInitiator version used or the names and locations of the base HTML template files.

The name of the custom application definition becomes part of the Forms application URL. The following custom settings define two different applications:

    [MyHR_app]
    serverURL=/forms/lservlet
    Form = hr_main.fmx
    lookAndFeel=oracle
    Otherparams=myParam1=12
    Userid=scott/tiger@orcl

The following URL invokes this application:

`http://<``hostname``>:<``port``>/forms/frmservlet?config=MyHR_app`

Another custom application definition might look like this:

    [booking_app]
    ServerURL=/forms/lservlet
    Form = book.fmx
    lookAndFeel=oracle
    Otherparams=
    Userid=

The following URL invokes this application:

`http://<``hostname``>:<``port``>/forms/frmservlet?config=booking_app`

For each static HTML file, you must create a custom application definition. Part of the static HTML file is the `archive` parameter directive, specifying at least the `frmall.jar` file in OracleAS Forms Services. If you added a custom archive file, then the `archive` parameter directive would resemble the following: `Archive=frmall.jar,custom.jar`. Using the Forms servlet and the `formsweb.cfg` file, the archive settings are defined under the User Parameter section. All custom application settings inherit these values, so you don't have to explicitly set this parameter, unless you add a `custom.jar` file as required by an application.

If `custom.jar` was added, then you can add the following lines to the custom application definition. The example below assumes that you are using JInitiator or another VM, but not Internet Explorer native.

    [booking_app]
    archive_jini=frmall_jinit.jar, custom.jar
    archive=frmall.jar, custom.jar
    ServerURL=/forms/lservlet
    Form = book.fmx
    lookAndFeel=oracle
    Otherparams=
    Userid=

Follow these steps to upgrade applications:

1. Edit the `forms/server/default.env` file, adding the location of the OracleAS Forms Services application modules to the `Forms_Path`.

2. Edit the `forms/server/formsweb.cfg` file, appending a custom application section for each static HTML application that you want to replace.

3. Name each custom application section, using a name that contains no spaces and is enclosed in square brackets, for example: `[booking_app]`, `[MyHR_app]`.

4. Start the application using this URL:

   `http://<``hostname``>:<``port``>/forms/frmservlet?config=<``name``>`

### 11.3.4.1 Using Static HTML Files with OracleAS Forms Services

If you need to, you can continue to use static HTML files in OracleAS Forms Services. However, with static HTML files, some features (such as Oracle Application Server Single Sign-On) are not available for use by Forms applications.

The Forms Listener servlet by default points to `/forms/lservlet` after installation. To use static HTML files in OracleAS Forms Services, you must modify each static start HTML file to include a value for the `serverURL` parameter. The `serverPort` and `serverHost` parameters are no longer used, and can be left undefined. OracleAS Forms Services uses JInitiator version 1.3.x, so you must also change those settings. The required values are found in the `forms/server/formsweb.cfg` file.

Follow these steps to use static HTML files with OracleAS Forms Services:

1. Configure `Forms_Path` in the `forms/server/default.env` file to point to the upgraded OracleAS Forms Services application modules.

2. Create virtual directories in the `<``destination_MT_OH``>/forms/server/forms.conf` file to point to the location of the static HTML start files.

3. Modify the application start HTML files as follows:

   1. Add the `serverURL` value `/forms/lservlet`.

   2. Change the JInitiator version number.

4. Change the `codebase` parameter to `forms/java`.

5. Navigate to `<``destination_MT_OH``>/j2ee/OC4J_BI_Forms/applications/formsapp/formsweb/WEB-INF` and edit the `web.xml` file.

6. Set the envFile initialization parameter for the Listener Servlet to point to the environment file (usually `<``destination_MT_OH``>/forms/server/default.env`).

After editing, the entry in the `web.xml` file for the Forms listener servlet should resemble the following:

    <!--Forms listener servlet-->
    <servlet>
      <servlet-name>lservlet</servlet-name>
         <servlet-class>oracle.forms.servlet.ListenerServlet</servlet-class>
      <init-param>
         <param-name>envFile</param-name>
         <param-value>destination_MT_OH/forms/server/default.env</param-value>
      </init-param>
    </servlet>

## 11.3.5 Upgrading the Forms 6i Listener to the Forms Listener Servlet

The Forms 6i Listener is a C program that starts a Forms runtime process on behalf of an incoming Forms Web request. The Forms Web runtime process is then directly accessed by the Forms client applet, using a direct socket or an HTTP socket connection. The Forms Listener is then no longer involved in the application Web client-server communication process, and is free to handle other incoming Web requests.

The Forms Listener Servlet, a Java program, also takes incoming Web requests for a Forms application and starts the Forms server-side Web runtime process. Unlike the Forms 6i Listener, the Forms Listener Servlet remains between the Forms application applet-server communication.

While the Forms 6i Listener listens on a specific port (by default, 9000), the Forms Servlet doesn't need an extra port, and is accessed by the HTTP listener port. The Forms Listener Servlet was introduced in the Forms 6i patch 4, and is the only listener supported in Forms Services.

The Forms Listener Servlet is automatically configured during the Oracle Application Server installation. The installer creates a virtual path `/forms/` pointing to the OracleAS Forms Services configuration, `formsapp` and `formsweb`, in the Oracle Application Server Containers for J2EE Business Intelligence and Forms instance (`<``destination_MT_OH``>/j2ee/oc4j/OC4J_BI_Forms`).

To access the Forms Listener Servlet test form, request the following URL:

`http://<``hostname``>:<``port``>/forms/frmservlet?form=test.fmx`

Ability to access this page means that the Forms Listener Servlet is configured and ready to use. `frmservlet` is the access name configured for the Forms Servlet during installation. The name of the Listener Servlet is `lservlet`.

If the Forms Listener Servlet is accessed with the Forms servlet, then only the custom application settings from the `Forms60/server/formsweb.cfg` file need to be appended to the `forms/server/formsweb.cfg` file. All application configurations automatically inherit the `serverURL` parameter value `/forms/lservlet` from the global system parameter settings.

Note: Do not copy and replace the entire `formsweb.cfg` file in `<``source_MT_OH``>` to `<``destination_MT_OH``>`. The file in Release 6i is different from the OracleAS Forms Services file in 10g Release 2 (10.1.2). Copy only the application configuration to `<``destination_MT_OH``>/forms/server/formsweb.cfg`.

To change a Forms application deployment from the Forms Listener architecture to the Listener Servlet architecture, you need only supply a value for the `serverURL` parameter in the `formsweb.cfg` file. During installation, this parameter is set to `/forms/lservlet`.

Follow these steps to upgrade to the Forms Listener Servlet:

1. Copy the Forms application files to a new directory and upgrade them to OracleAS Forms Services modules as described in Section 11.3.2, "Upgrading OracleAS Forms Services Application Modules". .

2. Edit the `forms/server/default.env` file to add the location of the upgraded Forms application modules to the `Forms_Path` variable.

3. Copy all of the custom application settings from `<``source_MT_OH``>/Forms60/Server/formsweb.cfg` and append them to `<``destination_MT_OH``>/forms/server/formsweb.cfg`.

   Note: Do not copy and replace the entire `formsweb.cfg` file in `<``source_MT_OH``>` to `<``destination_MT_OH``>`. The file in Oracle 6i Forms Services is different from the OracleAS Forms Services file. Copy only the application configuration to `<``destination_MT_OH``>/forms/server/formsweb.cfg`.

4. If an application requires its own environment file, then instead of defining a separate servlet alias for the Listener Servlet, set the `envFile` parameter in the custom application definition section in `<``destination_MT_OH``>/forms/server/formsweb.cfg` to point to the new environment file. For example:

       envFile=myEnvFile.env

   where `myEnvFile.env` is located in the `forms/server` directory.

5. If you changed the Oracle 6i Forms Services HTML template files, then make the same changes to the OracleAS Forms Services HTML template files.

   Note: If you need to change the underlying HTML files, you should make a copy of the provided template files before editing them. Save the edited HTML files under a different name, and leave the default templates provided with the installation unchanged. This prevents overwriting of your customized HTML template files when patch sets are applied to the application. To use your own template files with applications, use these parameters in the system section, or one of your custom application definitions:
       baseHTML=<your base template>.htm
       baseHTMLJinitiator=<your base jinit>.htm

6. Start the application with this URL:

   `http://<``hostname``>:<``port``>/forms/frmservlet? config=<``application``>`

## 11.3.6 Upgrading the Forms Listener Servlet Architecture to OracleAS Forms Services

In Oracle9iAS Forms Services Release 6i, the Listener Servlet, if not aliased, is accessed by the `oracle.forms.servlet.ListenerServlet`. The Listener Servlet configuration exists in the `jserv.properties` file and the `zone.properties` file.

In OracleAS Forms Services, the Forms Listener servlet is the same except for the servlet names, which are `frmservlet` and `lservlet`, and the servlet container, which is now Oracle Application Server Containers for J2EE (OC4J). As in Oracle9iAS Release 1 (1.0.2.2.x), the configuration is performed during installation. The Listener Servlet configuration in OC4J is stored in `ORACLE_HOME/j2ee/OC4J_BI_Forms/applications/formsapp/formsweb/WEB-INF/web.xml`. Some initialization parameters, like the `envFile` parameter, need no longer be configured with the servlet engine, because they are moved to the `formsweb.cfg` file.

The Forms Listener Servlet is automatically configured during the Oracle Application Server installation. The installer creates a virtual path `/forms/` pointing to the OracleAS Forms Services configuration, `formsapp` and `formsweb`, in the Oracle Application Server Containers for J2EE Business Intelligence and Forms instance (`<``destination_MT_OH``>/j2ee/oc4j/OC4J_BI_Forms`).

To access the Forms Listener Servlet test form, request the following URL:

`http://<``hostname``>:<``port``>/forms/frmservlet?form=test.fmx`

Ability to access this page means that the Forms Listener Servlet is configured and ready to use. `frmservlet` is the access name configured for the Forms Servlet during installation. The name of the Listener Servlet is `lservlet`.

Follow these steps to upgrade the Listener Servlet architecture to OracleAS Forms Services:

1. Copy the Forms application files to a new directory and upgrade them to OracleAS Forms Services modules.

2. Edit the `forms/server/default.env` file, adding the location of the upgraded Forms application modules to the `Forms_Path` variable.

3. Copy all of the custom application settings from `<``source_MT_OH``>/Forms60/Server/formsweb.cfg` and append them to `<``destination_MT_OH``>/forms/server/formsweb.cfg`.

   Note: Do not copy and replace the entire `formsweb.cfg` file in `<``source_MT_OH``>` to `<``destination_MT_OH``>`. The file in Release 6i is different from the OracleAS Forms Services file in 10g Release 2 (10.1.2). Copy only the application configuration to `<``destination_MT_OH``>/forms/server/formsweb.cfg`.

4. If an application requires its own environment file, then instead of defining a servlet alias for the Listener Servlet, set the envFile parameter in the custom application definition section in `<``destination_MT_OH``>/forms/server/formsweb.cfg` to point to the new environment file. For example:

       envFile=myEnvFile.env

   where `myEnvFile.env` is located in the `forms/server` directory.

5. If you changed the Forms Services Release 6i HTML template files, then make the same changes to the OracleAS Forms Services HTML template files.

   Note: If you need to change the underlying HTML files, you should make a copy of the provided template files before editing them. Save the edited HTML files under a different name, and leave the default templates provided with the installation unchanged. This prevents overwriting of your customized HTML template files when patch sets are applied to the application. To use your own template files with applications, use these parameters in the system section, or one of your custom application definitions:
       baseHTML=<your base template>.htm
       baseHTMLJinitiator=<your base jinit>.htm

6. Start the application with this URL:

   `http://<``hostname``>:<``port``>/forms/frmservlet? config=<``application``>`

## 11.3.7 Upgrading Load Balancing

The method of upgrading the load balancing in Forms Services 6i depends on the deployment method used.

- With the Forms 6i listener, the Metrics Server (a separate process) performs load balancing.

- With the Forms 6i servlet, load balancing is configured with the JServ servlet engine, using round robin load balancing among JServ engines.

- In OracleAS Forms Services, load balancing is managed by `mod_oc4j`, an Oracle HTTP Server module. It binds Web requests to the servlet container processing the Forms Servlet and the Forms Listener servlet.

## 11.3.8 Usage Notes

This section contains hints and tips that may be useful in the upgrade.

### 11.3.8.1 Deploying Icon Images with the Forms Servlet

Using static HTML start files in Forms Services Release 6i allowed storage of images in a location relative to the start HTML file. The Forms Servlet in OracleAS Forms Services does not support this.

The alternative is to use the `imagebase` parameter with the value of `codebase` as the location for the icon images used by applications. The `codebase` value refers to the `forms/java` directory, which contains all of the Forms client Java archive files. For performance reasons, it is not a good idea to store images here.

Instead, you should bundle the icons into a separate archive file, which improves performance because archives are cached permanently on the client. Follow these steps to create this archive file.

1. Verify that the `jar` command succeeds. If it does not, then you need to ensure that there is a JDK installed on your system with a correct PATH environment variable entry (pointing to the `JDK_HOME/bin` directory).

2. Navigate to the directory containing the application images and issue the command:

   `jar -cvf <``application``>_images.jar *.<``extension``>`

   where:

   - `application` is the name of the application

   - `extension` is the extension of the image file (e.g.,.gif)

   A jar file, `<``application``>_images.jar`, is created in the current directory.

3. Copy `<``application``>_images.jar` to the `forms/java` directory.

4. Edit the `formsweb.cfg` file, adding the `imageBase=codebase` parameter to the custom application section for the application.

5. Add the `<``application``>_images.jar` file to the archive path used by the application by adding the following lines to the custom application section:

       archive_jini=frmall_jinit.jar,<application>_images.jar
       archive_frmall.jar,<application>_images.jar

See Section 4.9, "Deploying Icons and Images Used by Forms Services" for more information on deploying custom icon files with OracleAS Forms Services.

### 11.3.8.2 Upgrading Integrated Calls to Oracle Reports to use Oracle Reports

In Oracle Application Server, integrated calls to Oracle Reports in Forms are no longer handled by a client-side background engine. OracleAS Forms Services requires that applications use the `RUN_REPORT_OBJECT` Built-in, calling Oracle Reports to process integrated reports. Oracle Reports is set up as part of the Business Intelligence and Forms installation.

Follow these steps to upgrade the call:

1. Change all occurrences of `RUN_PRODUCT (Reports,...)` to the equivalent call using `RUN_REPORT_OBJECT()`.

2. Add the location of the application's Reports modules to use the `Reports_Path` of Oracle Reports.

3. Change `RUN_REPORT_OBJECT` to reference Oracle Reports.

   For more information, see Oracle Application Server Reports Services Publishing Reports to the Web and `http://www.oracle.com/technology/products/forms/pdf/10g/frmrepparamform.pdf`

### 11.3.8.3 Creating Forms Listener Servlet Alias Names in OC4J

In Forms Services Release 6i, before patch 8, it was necessary to create alias names for the Forms servlet in the `ORACLE_HOME/Apache/Apache/JServ/conf/zone.properties` file in order to use individual environment files for different applications. The Forms servlet in OracleAS Forms Services does not require this. You can set the environment file name in the `formsweb.cfg` file using the `envFile` parameter, shown below:

`envFile=myApp.env`

Alias names for the Forms servlet are no longer created in `ORACLE_HOME/Apache/Apache/JServ/conf/zone.properties`. Instead, they are created in `<``destination_MT_OH``>/j2ee/OC4J_BI_Forms/applications/formsapp/formsweb/WEB-INF/web.xml`.

To create the alias names, copy the content between the `<servlet>` and `</servlet>` tags and change the servlet's name. To create a URL mapping for the new servlet alias name, add the following to the file:

    <servlet-mapping>
    <servlet-name>new servlet name</servlet-name>
    <url-pattern>/new url name*</url-pattern>
    </servlet-mapping>

### 11.3.8.4 Accessing the Listener Servlet Administration Page

You can display a test page for the Listener Servlet in Oracle9iAS Forms Services Release 6i by accessing the following URL:

`http://<``hostname``>:<``port``>/servlet/oracle.forms.servlet.ListenerServlet`

The information displayed depends on the value of the initialization parameter `TestMode`. This parameter is set in the `<``source_MT_OH``>/Apache/Apache/JServ/conf/zone.properties` file.

You can display the test page for OracleAS Forms Services with the following URL:

`http://<``hostname``>:<``port``>/forms/frmservlet/admin`

The information displayed depends on the value of the initialization parameter `TestMode`. This parameter is set in the `<``destination_MT_OH``>/j2ee/OC4J_BI_Forms/applications/formsapp/formsweb/WEB-INF/web.xml` file. An example is shown below:

    <init-param>
    <!-- Display sensitive options on the /admin page ? -->
        <param-name>TestMode</param-name>
        <param-value>true</param-value>
    </init-param>