A Procedural Guide for Upgrading Forms6i

Applications to Forms10g

Introduction
Upgrading Oracle Forms applications from 6i to 10g is achievable once you know what
to do. In this document I will explain the process I followed when upgrading the
Automated Lands Project (ALP) at the USFS. I will not go into great detail regarding
application specific issues encountered when upgrading, such as the use of OLE or
Mouse Triggers. Covering this subject would quickly balloon this paper into a short story
and neither you nor I want that! It is my hope that this document will provide you with
an understanding of what is involved in the upgrade process and some specifics for
configuring Oracle Components for Java (OC4J) and Internet Application Server (iAS)
that you will need to be able to deploy your application.

Step 1: Source Code Verification and Version Control

You might wonder why I listed this as the first step in the process, but it is very important
to make sure you have the current version of the Application source code in a Version
Control system. I will avoid giving a lecture on the importance of using Version Control
software, but suffice it to say that you will likely need to restore a file more than once
during the upgrade process or you will need it to compare the version dates of “suspect”
files.

When completing this step, I recommend creating an inventory of the Application source
code. I create a spreadsheet that contains all of the files sorted by category (Forms,
Libraries, Menus, Graphics, Utilities and Reports). I then open all the forms, libraries,
menus and reports and note their library attachments. You may think this is a lot of work,
but the couple of hours you spend doing this up front will eliminate wasted time
downstream when you realize that you are missing files or when you are debugging
problems with library attachments. You’ll find this document useful in the future so
check it into your Version Control system.

Step 2: Upgrade your Application using the Forms Migration Assistant

Assuming that you have installed Oracle Internet Application Development (iAD) suite
10g on your Windows based PC, use the Forms Migration Assistant to upgrade your
application. This utility can be found one of two ways; 1.) Click on the Start button then
Oracle Developer Suite - Client 10g then Forms Developer and then double clicking on
Oracle Forms Migration or 2.) Open a command window and running C:\<oracle
home>\bin\ifplsqlconv90.bat mode=wizard .

The order that you upgrade your application is important! You will run into the least
amount of errors if you upgrade your application in the following sequence:

1. Library files (.pll/plx): Starting with library files that do not have attachments and
then preceding to those that do have library attachments.

Digital Visions Enterprise Unit 1 of 8 10/19/04

Paul Dirksen pdirksen@fs.fed.us
 2. Menu files (.mmb/.mmx): Starting with menu files that do not have attachments
and then preceding to those that do have library attachments.
3. Form files (.fmb/.fmx): Starting with form files that do not have attachments and
then proceeding to those that do have library attachments.

The Forms Migration Assistant logs what it does to each of your files, so it is a good idea
to review the log as you run your files through.

Step 3: Preparations on Windows for Deployment on AIX

There are number of tasks that can be completed on the Windows platform that will
greatly reduce the amount of time required once you port to AIX for compilation, testing,
and deployment using Internet Application Server (iAS). Below is a listing of tasks that
you can complete using 10g iAD and then test using Oracle Components for Java (OC4J)
on your PC.

Libraries
Forms libraries require a fair amount of work to prepare for deployment on a platform
other than Windows. Below is an overview of the tasks to be completed.
 Rename the Libraries to Uppercase: Starting with the easiest task, forms
attachments are implicit in nature – meaning that you can not edit the name
referenced in the Forms Builder once you attach a library to a form. The name of
the library is attached in uppercase. So at runtime if you want your attached
libraries to be successfully referenced, you need to make sure the file names are
uppercase.
 Consolidate Infrastructure Libraries: While nesting libraries is a great object
oriented development technique, it is only minimally support in 10g deployments.
Libraries can only be referenced by a form if they are 2 levels removed, for
example:

o Valid: Form A has Lib1 as an attached library. Lib1 has Lib2 and Lib3 as
attached libraries. Lib2 and Lib3 do not have attached libraries.
o Invalid: Form B has Lib1 as an attached library. Lib1 has Lib2 and Lib3
as attached libraries. Lib2 does not have an attached library. Lib3 has
Lib4 as an attached library.

Refer to the Inventory document that you created as part of Step 1. If you
determine that you have nested-libraries that are more the 2 levels removed from
the form, you will need to spend some time consolidating and reorganizing your
libraries.
 Convert the Contents of Libraries to Uppercase: This step will ensure that
referenced code functions all the time. This is not as tedious a process as you
might expect if you follow this procedure:
o Use 10g Forms Builder to convert the library files to text from binary
 File Menu – Convert
o Use TextPad to convert the case to Uppercase
 Open the file

Digital Visions Enterprise Unit 2 of 8 10/19/04

Paul Dirksen pdirksen@fs.fed.us
  Select all of the Text
 Edit – Change Case – Uppercase
 Save
o Use 10g Forms Builder to convert the library files to binary from text.
 File – Convert
o Compile and Save
 Detach and Reattach libraries throughout the Application: This may seem
like overkill, but you will be assured not to run into library related problems if
you detach and reattach libraries throughout the application. Start with libraries,
then menus and finish with forms. Once complete, be sure to compile and save.

Graphics
To make sure you iconic buttons remain, well, “iconic”, we need to do a little work to
prepare them for the web. There are currently two graphic file types that can be used for
iconic buttons, .gif and .jpeg. In your 6i application you probably had .ico files though,
unless you happened to be deployed in motif in which case you have .xpm files. So we
know that you need to convert your icon files to .gif or .jpeg format for sure. These will
be used at runtime (OC4J or iAS). What you probably don’t know is that 10g Forms
Builder does not use this file format. To see the graphics on your iconic buttons in Forms
Builder you will need to maintain those .ico files as well.

So your first task is to convert your icon files to .gif or .jpeg. Below is a procedure which
should help reduce the time to complete this task:
 Download and install irfanview from www.irfanview.com (it’s free)
 Using irfanview convert you icon files
o File – Batch Conversion
 If you have .xpm files convert to .ico
 Be sure to click on options and use the transparent
background. Click on the black area around the image to
have it be transparent
 Convert .ico files to .gif (or .jpeg)
 Be sure to click on options and use the transparent
background. Click on the black area around the image to
have it be transparent.

Now that you have .gif files, you next need to create a .jar file that contains all of the .gif
files. To do this:
 Open a command window on your PC
 Navigate to the directory where your .ico files are located
 Then run this command:
c:\<Oracle Home>\jdk\bin\jar.exe –cvf <new file name>.jar *.gif

Next you need to move the .jar file to your application home directory and you will be
ready to configure OC4J on your PC to use this file at when running your Forms.

Digital Visions Enterprise Unit 3 of 8 10/19/04

Paul Dirksen pdirksen@fs.fed.us
OC4J Configuration
The last thing you need to do is configure you OC4J runtime environment so that you can
simulate iAS deployment. This will allow you to test your Application in a web
environment on your PC using nearly same configuration files that you will use when you
deploy on the Application Server. It is important to note, however, that unless you are
using the same operating system on your PC and the Application Server, you will not be
able to complete 100% of your testing here. That doesn’t make testing any less important
here though.

If you haven’t already, now is a good time to do some reading on Deploying 10g
applications. Oracle has some excellent documentation to assist you with this task
available at http://www.oracle.com/technology/documentation/9i_forms.html. There are
two documents that I highly recommend:

 Oracle Application Server Form Services 10g Deployment Guide

http://download-west.oracle.com/docs/cd/B10464_01/web.904/b10470.pdf
This document will bring you up to speed on deployment issues on iAS – most of
which translate to OC4J deployment as well.

 Oracle 9iAS Form Services How to Deploy Icons

http://www.oracle.com/technology/products/forms/pdf/webicons.pdf
This document is specific to graphics deployment for both OC4J and iAS.

In the remainder of this section, I will refer to the modifications required for testing in
OC4J.

Formsweb.cfg (c:\<oracle home>\forms90\server\formsweb.cfg).

This is the Forms Servlet configuration file. It contains default settings for the Forms
Servlet, but more importantly, it provides the capability to add specific named
configurations that you can build that can do things such as:
 Call a given Form (like the startup form in a traditional client/server application)
 Set the working directory
 Set the file name that contains your environment variables
 Pass in authentication credentials
 Set display characteristics such as height, width, color, etc.
 Set path variables to include your application graphics files.

Below is the named configuration that I created for the ALP project. This configuration
is used when calling all Forms in the Application.

Digital Visions Enterprise Unit 4 of 8 10/19/04

Paul Dirksen pdirksen@fs.fed.us
#ALP
#08/31/04 Paul Dirksen - Digital Visions
[alp]
userid=pdirksen/dvcontractor@cell2.idb.pnw
workingDirectory=c:\env\alp
envfile=alp.env
imageBase=codebase
width=883
height=857
archive_jini=f90all_jinit.jar,/forms90/alp/alpicons.jar

Default.env (c:\<oracle home>\forms90\server\default.env)

This file contains the environment variables for runtime processing, similar to those that
were used in the Windows Registry in client server deployment. Don’t think of them as a
1:1 match though. There is one very important environment variable that needs to be
modified in this file, FORMS90_PATH. This is the search path that Oracle Forms uses to
find your files at runtime. See the edit made for the ALP application below.

# 8/30/03 Paul Dirksen - Added Alp to path

FORMS90_PATH=C:\oracle\client10g\forms90;C:\env\alp

Now you have a choice in how you implement this change. You can modify the
Default.env file directly adding the directory of your application to the end of the
FORM90_PATH variable. The directory you add will then be immediately available in
your runtime environment. The problem is that all applications that use the default.env
will also have that directory added to the search path. If two applications happen to have
the same file name in their application you will run into problems.

An alternative and recommend approach is to create an application specific copy of the

default.env, naming it <your application acronym>.env and making the modification
there. You will need to use the envfile parameter in the formsweb.cfg (see above
example formsweb.cfg) to specify that you want to use this file instead of the default.env,
but that is a small price to pay to keep your search path specific to your application.

Orion-web.xml(c:\<oracle home>\j2ee\devsuite\application-deployments\forms\forms90web\orion-web.xml )
This is the listener configuration file specific to OC4J. You can define a virtual directory
path for your application’s graphics .jar file here. The example below show the edit made
for the ALP application. The customization for ALP is the last entry in BOLD red font.
Note: “/forms90/” is automatically added to the prefix of your virtual path.
<virtual-directory virtual-path="/html" real-path="C:\oracle\client10g/tools/web90/html" />
<virtual-directory virtual-path="/java" real-path="C:\oracle\client10g/forms90/java" />
<virtual-directory virtual-path="/jinitiator" real-path="C:\oracle\client10g/jinit" />
<virtual-directory virtual-path="/alp" real-path="C:\env\alp" />

Digital Visions Enterprise Unit 5 of 8 10/19/04

Paul Dirksen pdirksen@fs.fed.us
Testing
Once your configuration tasks are complete, you then need to test your application in
OC4J independent of Form Builder. This will test your configuration, most of which will
be repeated when configuring for iAS deployment. In the ALP upgrade, we did this be
creating 3 bookmarked URLs that test the 3 launch points for the application.
http://pc060300205.f3.r6.fs.fed.us:8889/forms90/f90servlet?config=alp&form=ALPCASE.fmx
http://pc060300205.f3.r6.fs.fed.us:8889/forms90/f90servlet?config=alp&form=ALPDOC1.fmx
http://pc060300205.f3.r6.fs.fed.us:8889/forms90/f90servlet?config=alp&form=ALPOWN.fmx

Step 4: Compilation and Testing on a development Application Server platform

We are now ready to leave the Windows world behind and move to the deployment
platform. This step in the process includes:

 Installing the application on an iAS machine that is designated for development

and testing. Do NOT perform this step on a Production iAS machine.
 Recompiling the Application
 iAS Configuration
 Testing

Installing the Application on the Development iAS machine

First things first, you are going to need an account on the development iAS machine.
Next create two directories for your application. One will be used to complete the
compilation on the iAS platform, the other will be used for the executables to test
deployment on iAS. In the ALP upgrade we used $HOME/alpdev for the conversion
and /fsapps/fsprod/alp for the iAS testing.

When you have created the two directories copy your application into the directory you
are planning to use for the compilation. Copy over all of the application binary (.fmb, .pll
and .mmb) files and the application graphics .jar file.

Recompile the Application

Next you need to recompile the Application on AIX.
 Make sure the TNSNAMES.ORA located at <Forms Services
$Oracle_Home>/network/admin directory includes an entry for your
target database.

 Navigate to the directory where your binary files are located. In the ALP
Upgrade this was $HOME/alpdev. Note: You must be in the directory where
your binary files (.fmb, ,mmb, .pll) are located when you compile the application.

 Start a Terminal Emulator (Exceed or VNC). You need to do this whether you
plan to upgrade your application interactively or in batch mode.

 Export your DISPLAY variable

export DISPLAY=<your PCs IP address:0.0>

 Export ORACLE_HOME
Digital Visions Enterprise Unit 6 of 8 10/19/04
Paul Dirksen pdirksen@fs.fed.us
 export ORACLE_HOME=<Form Services $ORACLE_HOME>

 Compile the application. This can be interactively or in batch mode depending

on your preference. Regardless of your choice, it is recommended that you begin
with library files (.pll) then menu files (.mmb) and finally forms (.fmb).
o Interactive:
./ <Form Services $ORACLE_HOME>/bin/f90genm.sh
o Batch:
We created a utility called compileit that will complete this task. It
accepts to parameters:
 Connect String: The username/password@database that should be
used when compiling the application.
 Directory: The location of the files to be compiled.
The script loops through the directory listed and compiles the application
starting with library files (.pll), then menu files (.mmb) and finally form
files (.fmb). All information is logged in the working directory.

 Move the executables (.fmx, .plx, .mmx) and the graphics (.jar) to the testing
directory. In our upgrade we move the files to /fsapps/fsprod/alp. You are
now ready to configure iAS.

iAS Configuration
Many of the steps here are similar, if not the same, as configuring OC4J on your PC. In
that sense, the tasks involved here should go more fairly quickly due to your familiarity.
If you do not have the ability to edit these files as the user ORACLE you will need to
involve you iAS Administrator. The edits described below can be made using OEM of
iAS or directly editing the files listed. In the examples below, I will be providing
examples editing the files directly.

Formsweb.cfg (<Form Services $ORACLE_HOME>/forms90/server/formsweb.cfg)

Add the named configuration section created in the OC4J environment to the iAS
Formsweb.cfg. The workingDirectory parameter will need to be modified to point to the
directory that contains your applications executables on the Application server. Below is
the named configuration used for the ALP application:

#ALP
#08/30/04 Paul Dirksen - Digital Visions
[alp]
userid=pdirksen/dvcontractor@cell2.idb.pnw
workingDirectory=/fsapps/fsprod/alp
envfile=alp.env
imageBase=codebase
width=883
height=857
archive_jini=f90all_jinit.jar,/forms90/alp/alpicons.jar

Digital Visions Enterprise Unit 7 of 8 10/19/04

Paul Dirksen pdirksen@fs.fed.us
Default.env (Form Services $ORACLE_HOME>/forms90/server/default.env)
Create a copy of the default.env file and name it <your application acronym>.env.
Modify the FORMS90_PATH variable adding your deployment directory to the search
path. Below is the modification made for the ALP application.
# 8/30/04 Paul Dirksen - Added Alp to path
FORMS90_PATH=/var/lpp/oraias/forms90:/fsapps/fsprod/alp

Forms90.conf (Form Services $ORACLE_HOME>/forms90/server/forms90.conf)

This is the Oracle Apache HTTP listener configuration file. We need to define the virtual
path for the application graphics .jar file here. At the bottom of the file insert your
modification. Below is the modification made for the ALP application.

#ALP Application virtual path for Images

# 8/30/04 Paul Dirksen
AliasMatch ^/forms90/alp/(..*)“/fsapps/fsprod/alp/$1”

After completing this modification, you need to restart the HTTP Server for this
modification to take effect.

Testing
The last task here is to thoroughly test the application. You will be looking for problems
in the upgrade and/or your configuration. Be sure to allow yourself sufficient time to
complete this step. If problems are found in the Forms, you will need to go back and
work on those in the Windows environment. When you are satisfied with your work
there, you will need to recompile on AIX and test again. Configuration problems will
require you to work closely with your System Administrator to resolve the problems.

Step 5: Production Deployment

When you are ready to deploy your Application into production there are 4 key things
that you will need to provide:
1. A copy of the named configuration that you wish to add to the formsweb.cfg
2. A copy of your application specific .env file
3. A copy of the edit to be made to the forms90.conf file
4. Your application executables with instructions for where to install them.

This information will need to be supplied with the other normal IRM information for
deploying applications.

Conclusion
Upgrading application from 6i to 10g is detailed, but not a daunting process. Like most
things, with experience comes proficiency. At first the steps outlined in this document
may seem tedious, but once you have completed an upgrade you will find that your next
experience will be much smoother. Each application will likely have it own unique
application specific upgrade challenges, but the process of getting there will likely remain
fairly constant. Thanks for taking the time to read this document.

Digital Visions Enterprise Unit 8 of 8 10/19/04

Paul Dirksen pdirksen@fs.fed.us