2.1 What Does the Oracle Forms Migration Assistant Do?

The Oracle Forms Migration Assistant updates obsolete usage in your PL/SQL code in order to upgrade your Forms 6i applications to Oracle Forms 11g. The tool issues warnings when it cannot make the required changes automatically. This tool has a command line and a wizard version. The Oracle 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 upgrade, for example:

Provides warnings when specific obsolete built-ins are used at run time, such as ITEM_ENABLED.

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.

Replace simple one-for-one code strings such as OHOST to HOST, MENU_CLEAR_FIELD to CLEAR_ITEM, and MENU_FAILURE to FORM_FAILURE.

Performs more complex substitutions such as CHANGE_ALERT_ MESSAGE to SET_ALERT_PROPERTY built-in, DISABLE_ITEM to SET_MENU_ITEM_PROPERTY built-in, ITEM_ENABLED to GET_ ITEM_PROPERTY built-in, and ENABLE_ITEM to SET_MENU_ITEM_ PROPERTY built-in.

Raises a warning in the Form module's log if V2-style triggers are found.

Raises a warning in the Form module's log if built-ins related to obsolete object types are found such as VBX.FIRE_EVENT, VBX.GET_ PROPERTY, and VBX.GET_VALUE_PROPERTY.

You run the Oracle Forms Migration Assistant in batch mode. You can re-enter the utility as needed to run the upgrade process on a Forms application more than once. You can also use the wizard version of the Migration Assistant to upgrade multiple modules.

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 Oracle Forms Migration Assistant searches for and replaces, 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.

2.1.1Multiple Log Support

The Forms Migration Assistant allows you either to write all log information into a single log file or span multiple log files. If the Forms Migration Assistant spans multiple log files, the Forms Migration Assistant generates individual log files for each module that is processed.

You must specify the directory in which the Forms Migration Assistant writes the log files. The name of the log file which is generated is modulename_moduletype.log.

For example, if you process a module by name, such as test.fmb, the name of the log file is test_fmb.log. If you select test.fmb and test.mmb for upgrade, the Forms Migration Wizard does not overwrite the log files. However, if you converted two modules test.fmb from two different directories, the log files are overwritten. The Forms Migration Assistant generates two log files: test_fmb.log and test_mmb.log.

2.2 Editing the converter.properties File

To change upgrade options, edit the converter.properties file in a text editor. You can set the following upgrade options:

When using web-based reports, these queue tables are used to monitor queued and processed reports. When used with the Oracle 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 system running the Reports Server. This setting is required when converting Run_Product calls to Run_Report_Object.

2.3.2 Modifying Warnings for Obsolete Built-Ins

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 Oracle 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 included in the search_replace.properties file are:

obsoleteItemTypeBuiltin

obsoleteBuiltin

obsoleteMenuParam

obsoleteItemTypeConstantProp

obsoleteConstantProp

obsoleteConstant

obsoleteHardCodedUserExit

obsoleteComplexBuiltin

DataParameterWithReports

NoErrorOrWarningFromForms

You can add more built-in warnings to an existing class, or create 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 classes and warnings using the syntax described.

Save the search_replace.properties file.

Note:

Do not delete the last two commands in the search_replace.properties file.

2.4 Starting the Oracle Forms Migration Assistant

You should upgrade the common modules (such as OLB files) and Libraries (PLL files) that a Form relies upon and ensure that these are available in the FORMS_PATH, before running the migration assistant.

Note:

For UNIX, an xterm display is required to run the Oracle Forms Migration Assistant.

Note:

The forms\rp2rro.pll and forms\EnableDisableItem.pll files should be in the FORMS_PATH in order to convert RUN_PRODUCT to RUN_REPORT_OBJECT.

In UNIX, set the variable FORMS_PATH, such as setenv FORMS_PATH $ORACLE_HOME/forms.

Specifies the log file to which the upgrade results are written. If not specified, the default values from the converter.properties file are used.

mode (optional)

This option has two values (batch and wizard). Use mode=batch to run the Migration Assistant in Batch mode, mode=wizard to run the wizard.

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

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

2.4.1 About the Migration Assistant in Batch Mode

You can convert multiple applications by running the Forms Migration Assistant in batch mode from the command line. Batch mode is useful for converting multiple Forms applications. For example, on Windows, create a batch file (for example upgrade.bat) that contains the following:

for %%f in (%1) do frmplsqlconv module=%%fuserid=<connect_string>

Then run the batch file as follows:

upgrade *.fmb

or

upgrade foo*.mmb

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

for file in $*

do

frmplsqlconv.sh module=$ff

done

Then run the shell script as follows:

or

upgrade.sh foo*.mmb

2.4.2 Starting the Migration Assistant in Batch Mode

You can run the Migration Assistant in batch mode on Windows and UNIX computers.

2.4.2.1 Starting the Migration Assistant in batch mode in Windows

In a Command window, issue the following command:

frmplsqlconv mode=batch module=<filename> log=<logname>

Note:

A dialog window appears recommending that you backup your files before converting them. Select the Show me this again box to enable this warning in the future.

where <filename> is the name of the file you want to convert, and <logname> is the name of the log file that is generated.

The Forms Migration Assistant looks for the file test.fmb in the d:\temp directory and names the generated log file test.log and places it in the d:\temp directory. You can give the log file any name you want and specify any location you want. By default the log file is written in ORACLE_HOME\bin. The module parameter can take only one value.

In the following example,

frmplsqlconv mode=batch module=d:\temp\test.fmb log=d:\temp\test.log

the output of the conversion is displayed on the screen. It is also saved to the default log file. Note that in batch mode, all converter options are taken from the converter.properties file. To change the converter options, see "Editing the converter.properties File".

2.4.2.2 Starting the Migration Assistant in Batch Mode in UNIX

In a UNIX shell, issue the following command:

frmplsqlconv.sh mode=batch module=<filename> log=<logname>

The output of the conversion is displayed on the screen. It is also saved to the default log file. Note that in batch mode, all converter options are taken from the converter.properties file. To change the converter options, see "Editing the converter.properties File".

2.4.3 Running the Wizard Version of the Forms Migration Assistant

You can run the wizard version of the Forms Migration Assistant and edit converter options.

2.4.3.1 Starting the Wizard Version of the Forms Migration Assistant

This section describes how to start the Forms Migration Assistant on Windows and UNIX computers.

On Windows computers, set the FORMS_PATH environment variable :

SET FORMS_PATH=%ORACLE_HOME%\forms

On UNIX computers, set the variable FORMS_PATH as in the following example:

Determines whether the warning dialog displays to back up files when the application starts.

Log File Name

Specifies the log filename in Single Log mode.

Log Dir

The destination directory to write the log files in multilog mode

Reports Servlet Virtual Directory

Specifies the name that has been defined for the virtual path used to define 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

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

The name or IP address of the system running the Reports Server. This setting is required when converting Run_Product calls to Run_Report_Object.

Default DESFORMAT

Printer driver to be used when DESTYPE is PRINTER (XML, HTML, HTMLCSS, PDF, RTF, delimited).