This chapter describes the upgrade process from Forms 6i. For information about changed or obsolete features, see the Oracle Forms Upgrading Oracle Forms 6i to Oracle Forms 11g Guide.
This chapter contains the following sections:
For upgrading from Oracle Forms 10g and prior releases, you can use the Upgrade Assistant. Refer to the following documents for more information.
Table 13-1 describes the items that are upgraded. These items include files, executables, or settings that you must add, change, delete, or replace in the Oracle Forms Services installation.
Table 13-1 Oracle Forms Services Upgrade Items
| Upgrade Item | Location in 6i Oracle home | Location in 11g (11.1.1) Oracle home | Description and Notes |
|---|---|---|---|
|
Oracle HTTP Server configuration file: |
|
|
Contains virtual path mappings. |
|
|
|
Contains environment variables settings for the Forms servlet Runtime Process. |
|
|
Configuration files with Forms servlet alias: |
|
|
|
|
Application configuration file: |
|
|
Contains Forms Services application configuration information. |
|
Forms servlet template html files: ( |
|
|
Default and user defined Forms servlet template HTML files. |
|
Forms application modules ( |
Forms modules ( |
This section explains how to perform the Oracle Forms Services upgrade. It is divided into the following sub-sections:
Section 13.2.1, "Upgrade Recommendations and Troubleshooting Tips"
Section 13.2.2, "Upgrading Oracle Forms Services Application Modules"
Section 13.2.3, "Upgrading Common Gateway Interface (CGI) to the Oracle Forms Servlet"
Section 13.2.4, "Upgrading Static HTML Start Files to Generic Application HTML Start Files"
Section 13.2.5, "Upgrading the Forms 6i Listener to the Forms Listener Servlet"
Section 13.2.6, "Upgrading the Forms Listener Servlet Architecture to Oracle Forms Services"
Consider the following recommendations and considerations while upgrading Forms applications:
Keep the Oracle6i Forms Services installation available until applications are successfully deployed and tested.
Back up and secure all files, then upgrade the source 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 Fusion Middleware and configure the 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 WebLogic Server is installed, if it is not the same computer.
After starting Oracle WebLogic Server, access the Forms Services Listener Servlet test page with this URL (default port 8888):
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>
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 Oracle Forms Services installation.
Copy the Forms application files to a new directory.
Optionally, use the Forms Migration Assistant to upgrade the Forms Application Modules (.fmb files), Forms menu modules (.mmb files), and the Library modules (.pll files).
Use the Forms Compiler (frmcmp.sh on Unix or frmcmp.exe on Windows) to regenerate the Forms Application executable files (fmx, mmx, and plx files).
For more information, see Oracle Forms Upgrading Oracle Forms 6i to Oracle Forms 11g at:
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 Oracle 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 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 Oracle Forms Services configuration, formsapp and formsweb.
Follow these steps to upgrade an Oracle 6i Forms Services Release 6i CGI environment to an Oracle Forms Services servlet environment:
Copy all of the application-specific configurations from <source_OH>/Forms60/Server/formsweb.cfg and append them to <destination_Domain_Dir>/config/fmwconfig/servers/WLS_FORMS/applications/formsapp_11.1.1/config/formsweb.cfg.
Note:
Do not copy and replace the entireformsweb.cfg file in <source_OH> to <destination_Domain_Dir>. The file in Release 6i is different from the Oracle Forms Services file. Copy only the application configuration to <destination_Domain_Dir>/config/fmwconfig/servers/WLS_FORMS/applications/formsapp_11.1.1/config/formsweb.cfg.Configure Forms_Path in the default.env file to point to the upgraded Oracle Forms Services application modules.
If you changed the Oracle 6i Forms HTML template files, then make the same changes to the Oracle Forms Services HTML template files.
Each application deployed to Oracle Forms Services has a custom application definition, configured in the formsweb.cfg configuration file. It automatically inherits the general system settings, such as 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 Oracle 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 another VM.
[booking_app] archive=frmall.jar, custom.jar ServerURL=/forms/lservlet Form = book.fmx lookAndFeel=oracle Otherparams= Userid=
Follow these steps to upgrade applications:
Edit the default.env file, adding the location of the Oracle Forms Services application modules to the Forms_Path.
Edit the formsweb.cfg file, appending a custom application section for each static HTML application that you want to replace.
Name each custom application section, using a name that contains no spaces and is enclosed in square brackets, for example: [booking_app], [MyHR_app].
Start the application using this URL:
http://<hostname>:<port>/forms/frmservlet?config=<name>
If you need to, you can continue to use static HTML files in Oracle Forms Services. However, with static HTML files, some features (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 Oracle 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.
Follow these steps to use static HTML files with Oracle Forms Services:
Configure Forms_Path in the default.env file to point to the upgraded Oracle Forms Services application modules.
Create virtual directories in the $ORACLE_INSTANCE/config/OHS/<OHS Instance>/moduleconf/forms.conf file to point to the location of the static HTML start files.
Modify the application start HTML files as follows:
Add the serverURL value /forms/lservlet.
Change the codebase parameter to forms/java.
Navigate to $DOMAIN_HOME/servers/WLS_FORMS/tmp/_WL_user/formsapp_11.1.1/<random_string>/war/WEB-INF and edit the web.xml file.
Set the envFile initialization parameter for the Listener Servlet to point to the environment file (usually 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_Domain_Dir/forms/server/default.env</param-value>
</init-param>
</servlet>
The Forms 6i Listener was a C program that starts a Forms runtime process on behalf of an incoming Forms Web request. The Forms Web runtime process was then directly accessed by the Forms client applet, using a direct socket or an HTTP socket connection. The Forms Listener was then no longer involved in the application Web client-server communication process, and was 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 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 listened on a specific port (by default, 9000), the Forms servlet does not 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 installation. The installer creates a virtual path /forms/ pointing to the Oracle Forms Services configuration, formsapp and formsweb.
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 formsweb.cfg file. All application configurations automatically inherit the serverURL parameter value /forms/lservlet from the global system parameter settings.
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:
Copy the Forms application files to a new directory and upgrade them to Oracle Forms Services modules as described in Section 13.2.2, "Upgrading Oracle Forms Services Application Modules". .
Edit the forms/server/default.env file to add the location of the upgraded Forms application modules to the Forms_Path variable.
Copy all of the custom application settings from <source_OH>/Forms60/Server/formsweb.cfg and append them to <destination_Domain_Dir>/config/fmwconfig/servers/WLS_FORMS/applications/formsapp_11.1.1/config/formsweb.cfg.
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_Domain_Dir>/config/fmwconfig/servers/WLS_FORMS/applications/formsapp_11.1.1/config/formsweb.cfg to point to the new environment file. For example:
envFile=myEnvFile.env
where myEnvFile.env is located in the forms/server directory.
If you changed the Oracle 6i Forms Services HTML template files, then make the same changes to the Oracle 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
Start the application with this URL:
http://<hostname>:<port>/forms/frmservlet? config=<application>
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 Oracle Forms Services, the Forms Listener servlet is the same except for the servlet names, which are frmservlet and lservlet, and the servlet container. The configuration is performed during installation. The Listener Servlet configuration in Oracle WebLogic Managed Server is stored in $DOMAIN_HOME/servers/WLS_FORMS/tmp/_WL_user/formsapp_11.1.1/<random_string>/war/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 WebLogic Server installation. The installer creates a virtual path /forms/ pointing to the Oracle Forms Services configuration, formsapp and formsweb.
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 Oracle Forms Services:
Copy the Forms application files to a new directory and upgrade them to Oracle Forms Services modules.
Edit the forms/server/default.env file, adding the location of the upgraded Forms application modules to the Forms_Path variable.
Copy all of the custom application settings from <source_OH>/Forms60/Server/formsweb.cfg and append them to <destination_Domain_Dir>/config/fmwconfig/servers/WLS_FORMS/applications/formsapp_11.1.1/config/formsweb.cfg.
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_Domain_Dir>/config/fmwconfig/servers/WLS_FORMS/applications/formsapp_11.1.1/config/formsweb.cfg to point to the new environment file. For example:
envFile=myEnvFile.env
where myEnvFile.env is located in the forms/server directory.
If you changed the Forms Services Release 6i HTML template files, then make the same changes to the Oracle 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
Start the application with this URL:
http://<hostname>:<port>/forms/frmservlet? config=<application>
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 Oracle Forms Services, load balancing is managed by Oracle WebLogic Managed Server process. It binds Web requests to the servlet container processing the Forms servlet and the Forms Listener servlet.
This section contains hints and tips that may be useful in the upgrade.
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 Oracle 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.
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).
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 (for example,.gif)
A jar file, <application>_images.jar, is created in the current directory.
Copy <application>_images.jar to the forms/java directory.
Edit the formsweb.cfg file, adding the imageBase=codebase parameter to the custom application section for the application.
Add the <application>_images.jar file to the archive path used by the application by adding the following line to the custom application section:
archive=frmall.jar,<application>_images.jar
See Section 4.7, "Deploying Fonts, Icons, and Images Used by Forms Services" for more information on deploying custom icon files with Oracle Forms Services.
Integrated calls to Oracle Reports in Forms are no longer handled by a client-side background engine. Oracle 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:
Change all occurrences of RUN_PRODUCT (Reports,...) to the equivalent call using RUN_REPORT_OBJECT().
Add the location of the application's Reports modules to use the Reports_Path of Oracle Reports.
Change RUN_REPORT_OBJECT to reference Oracle Reports.
For more information, see Oracle Fusion Middleware Publishing Reports to the Web with Oracle Reports Services.
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 Oracle 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 $DOMAIN_HOME/servers/WLS_FORMS/tmp/_WL_user/formsapp_11.1.1/<random_string>/war/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>
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_OH>/Apache/Apache/JServ/conf/zone.properties file.
You can display the test page for Oracle 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 $DOMAIN_HOME/servers/WLS_FORMS/tmp/_WL_user/formsapp_11.1.1/<random_string>/war/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>
After you complete the upgrade tasks, ensure that the upgraded version of the Oracle Forms Services is working as expected. You must devise and perform specific tests for applications and configuration elements that are unique to your site. Compare the performance and characteristics of each application in the source and destination installations.
In Oracle9iAS Release 1 (1.0.2.2.x), the forms application URL is typically:
http://<hostname>:<port>/servlet/<forms servlet alias>?<forms application name>
In Oracle Forms 11g, the forms application URL is typically:
http://<hostname>:<port>/forms/<forms servlet alias>?form=<forms application name>