2
Using the Oracle9i Forms Migration Assistant

Oracle9i Forms provides a tool that updates obsolete usage in your PL/SQL code in order to migrate your Forms6i applications to Oracle9i Forms. The tool issues warnings when it cannot make the required changes automatically.

This chapter contains the following sections:

Go to http://otn.oracle.com for the latest version of the tool.

What Does the Oracle9i Forms Migration Assistant Do?

The Oracle9i Forms Migration Assistant does the following for all Forms module types (including object libraries and PL/SQL libraries):

Updates PL/SQL code where possible, for example:
- Updates RUN_PRODUCT to the RUN_REPORT_OBJECT built-in when used to call Reports.
- Updates CHANGE_ALERT_MESSAGE to the SET_ALERT_PROPERTY built-in.
Provides a list of obsolete code usage, including code that the tool cannot change when there is not a straight-forward equivalent for migration, for example:
- Provides warnings when specific obsolete built-ins are used at runtime, such as DISABLE_ITEM, ENABLE_ITEM, and ITEM_ENABLED.

Note: :

The Oracle9i Forms Migration Assistant replaces built-ins and issues warnings about built-ins that exist within code comments.

Provides warnings when obsolete functionality is encountered, such as when obsolete item types are included in the code.
Provides warnings about triggers defined at incorrect levels.

You run the Oracle9i Forms Migration Assistant in batch mode. You can re-enter the utility as needed to run the migration process on a Forms application more than once.

By editing the converter.properties file, you can set options before you start the batch migration. By editing the search_replace.properties file you can specify the strings that the Oracle9i Forms Migration Assistant will search for and replace, and edit the warnings that are issued when an obsolete built-ins is encountered.

The tool creates a log file so that you can navigate to problem areas in the application and make modifications manually.

Editing the converter.properties File

To change migration options, edit the converter.properties file in a text editor.

You can set the following migration options:

Table 2-1 Oracle9i Forms Migration Assistant converter.properties File Options

Option	Description
Log File Name (default.logfilename)	Specifies the file name and location for log information.
Reports Queue Table Installed (default.usequeuetables)	When using web-based reports or ORARPP (Oracle Reports Remote Printing), these queue tables can be used to monitor queued and processed reports. When used with the Oracle9i Forms Migration Assistant, the queue table provides detailed error messages when installed in the application schema. (For example, if a report cannot run due to uncompiled PL/SQL, you can use the queue table to query for full error messages.) The resulting report is automatically printed. See the Reports Services documentation for more information about the Reports Queue Table.
Reports Servlet Directory (default.servletdir)	Specifies the name that has been defined for the virtual path used for the Reports Servlet, which is used for running reports on the web. This setting is required when converting Run_Product calls to Run_Report_Object.
Reports Servlet Name (default.servletname)	Specifies the name for the Reports Servlet used for running reports on the web. This setting is required when converting Run_Product calls to Run_Report_Object.
Reports Server Host (default.reports_servername)	The name or IP address of the machine running the Reports Server. This setting is required when converting Run_Product calls to Run_Report_Object.
User Name (default.connectusername)	The username to connect to the database.
Password (default.connectpassword)	The password to connect to the database.
Database (default.connectdb)	The database name.
Connect to Database (default.connecttodb)	If true, database connection is established. If false, then database connection is not established.
Compile After Conversion (default.generateruntime)	If true, the module is compiled after conversion (for example, an .fmx, .mmx, or .plx is generated).
DESTYPE (default.destype)	The type of destination device that will receive the report output. See the Reports Developer Reference for details.
DESFORMAT (default.desformat)	The printer driver to be used when DESTYPE is FILE. See the Reports Developer Reference for details.
DESNAME (default.desname)	The name of the file, printer, e-mail ID, or distribution list to which the report output will be sent. See the Reports Developer Reference for details.
Oracle Reports Remote Printing (default.use_orarrp)	ORARPP is a utility available on OTN for printing report output created by the Reports Server. See the Reports Developer Reference for details.
ORARPP Virtual Directory (default.orarrp_virtual_directory)	Web Server virtual directory mapped to the directory defined in Orarrp Physical Directory.
ORARPP Physical Directory (default.orarrp_physical_directory)	Web Server physical directory where Reports output files are created.
Reports Server Host (default.reportshost)	The name or IP address of the machine running the Reports Server. This setting is required when converting Run_Product calls to Run_Report_Object.

Editing the search_replace.properties File

The search_replace.properties file contains the strings that the Oracle9i Forms Migration Assistant will search for and replace. It also contains a list of obsolete built-ins that will generate warnings.

Adding Search-and-Replace Strings

You can edit this file to add your own search-and-replace strings, as follows:

Open the search_replace.properties file in a text editor.
Go to the end of the list of search-and replace strings.
Add a string to search for and replace using the following syntax:
```
SearchString|ReplaceString
```
Save the search_replace.properties file.

Note::

Do not delete the last two commands in the search_replace.properties file. See the release notes for more information.

Modifying Warnings for Obsolete Built-Ins

The warnings for built-ins have the following syntax:

<class>.Message=<WarningMessage>
<class>.Warning1=<BuiltIn1>
<class>.Warning2=<BuiltIn2>
<class>.Warning3=<BuiltIn3>
etc.

For example, for the class obsoleteMenuParam, the warnings are coded as follows:

obsoleteMenuParam.Message=Menu Parameters are no longer supported, the parameter 
and usage of %s should be replaced using a Forms parameter or global variable.
obsoleteMenuParam.Warning1=MENU_PARAMETER
obsoleteMenuParam.Warning2=QUERY_PARAMETER
obsoleteMenuParam.Warning3=TERMINATE

<class> is a group of built-ins that have a common warning. <WarningMessage> can contain one variable string (%s).

When the Oracle9i Forms Migration Assistant finds a built-in for which a warning should be issued, it logs the warning and replaces the variable string (%s) with the built-in name.

Classes that have already been created in the search_replace.properties file are:

obsoleteItemTypeBuiltin
obsoleteBuiltin
obsoleteMenuParam
obsoleteItemTypeConstantProp
obsoleteConstantProp
obsoleteConstant
obsoleteHardCodedUserExit
obsoleteComplexBuiltin
obsoleteCallBuiltin

You can add more built-in warnings to an existing class, or create new classes and warnings:

Open the search_replace.properties file in a text editor.
Go to the end of the list of warning messages.
Add a warning to an existing class or create new classes and warnings using the syntax described above.
Save the search_replace.properties file.

Note::

Do not delete the last two commands in the search_replace.properties file. See the release notes for more information.

Starting the Oracle9i Forms Migration Assistant

It is recommended that you first migrate common modules that other modules depend on.

Note:

For Solaris, an xterm display is required to run the Oracle9i Forms Migration Assistant.Note: :

The forms90\rp2rro.pll file should be in the FORMS90_PATH in order to convert Run_Product to Run_Report_Object.

To start the Oracle9i Forms Migration Assistant on Windows, type

ifplsqlconv90 module=<modulename> userid=<userid> log=<log>

To start the Oracle9i Forms Migration Assistant on Solaris, type

f90plsqlconv module=<modulename> userid=<userid> log=<log>

Table 2-2 Oracle9i Forms Migration Assistant Command Line Parameters

Parameter	Description
modulename (required)	Specifies the module to migrate. The modulename parameter can take only one value. See Migrating Multiple Files if you want to migrate more than one file at a time.
userid (optional)	Specifies a database connect string (for example, scott/tiger@db). If not specified, default values from the converter.properties file are used. If the syntax of the userid is incorrect, database connection information is taken from the converter.properties file.
log (optional)	Specifies the log file to which the migration results are written. If not specified, the default values from the converter.properties file are used.

Information about the progress of the migration process is displayed on the screen. It is also saved to the log file that you specify in the converter.properties file. (To change migration options, see Editing the converter.properties File.)

Check the log file for information about required migration steps that the tool did not modify. Manually make these changes to your application.

Migrating Multiple Files

On Windows NT, create a batch file (for example upgrade.bat) that contains the following:

for %%file in (%1) do call ifplsqlconv90 module=%%file

Then run the batch file as follows:

upgrade *.fmb

upgrade foo*.mmb

On Solaris, create a shell script (for example upgrade.sh) that contains the following:

for file in $*
do
   f90plsqlconv.sh module=$file
done

Then run the shell script as follows:

upgrade.sh *.fmb

upgrade.sh foo*.mmb

2 Using the Oracle9i Forms Migration Assistant