2 Using the Oracle Forms Migration Assistant

This chapter contains the following sections:

Go to http://www.oracle.com/technology/products/forms/ for the latest version of the tool.

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.

      Note:

      The Oracle 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.

  • 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.1 Multiple 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:

Table 2-1 Oracle 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, 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.

DESTYPE (default.destype)

The type of destination device that receives the report output. See the Oracle Fusion Middleware Reports Services Publishing Reports to the Web for details.

DESFORMAT (default.desformat)

The printer driver to be used when DESTYPE is FILE. See the Oracle Fusion Middleware Reports Services Publishing Reports to the Web for details.

DESNAME (default.desname)

The name of the file, printer, e-mail ID, or distribution list to which the report output is sent. See the Oracle Fusion Middleware Reports Services Publishing Reports to the Web for details.

Reports Server Host (default.reportshost)

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 Editing the search_replace.properties File

The search_replace.properties file contains the strings that the Oracle Forms Migration Assistant searches for and replaces. It also contains a list of obsolete built-ins that generate warnings.

2.3.1 Adding Search-and-Replace Strings

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

  1. Open the search_replace.properties file in a text editor.

  2. Go to the end of the list of search-and replace strings.

  3. Add a string to search for and replace using the following syntax:

    SearchString|ReplaceString
    
    
  4. Save the search_replace.properties file.

2.3.2 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 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:

  1. Open the search_replace.properties file in a text editor.

  2. Go to the end of the list of warning messages.

  3. Add a warning to an existing class or create classes and warnings using the syntax described.

  4. 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.

Table 2-2 Oracle Forms Migration Assistant Command Line Parameters

Parameter Description

module (required in batch mode only)

Specifies the module to upgrade. The module name parameter can take only one value. For more information on upgrading multiple modules at a time, see "Running the Wizard Version of the Forms Migration Assistant".

log (optional)

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=%%f userid=<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.

  1. 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:

    setenv FORMS_PATH $ORACLE_HOME/forms

  2. On Windows computers, from the Start menu, select ORACLE_HOME | Forms Developer |Oracle Forms Migration Assistant (GUI Mode), or at the command line, start the conversion utility by entering: frmplsqlconv.bat mode=wizard.

    in UNIX, enter frmplsqlconv.sh mode=wizard.

    The Conversion Wizard Welcome dialog displays.

    Note:

    You can get help by typing -h after the command, for example, frmplsqlconv -h
  3. Click Next.

  4. In the Modules dialog, click the Add Module(s) button.

  5. Select the modules that you want to convert.

  6. Click Next.

  7. In the Converter options dialog, enter the location and name of the log file that is generated. A browse button is provided to assist in choosing a location.

  8. If you have Forms that include embedded reports, fill in the remaining fields. Otherwise, you may ignore these fields.

  9. For more information about the Reports fields, see Oracle Fusion Middleware Reports Services Publishing Reports to the Web. For more information about advanced converter options, see the following section, "Setting Advanced Converter Options".

  10. Click Next.

  11. In the Finish dialog, the modules you selected are listed. Click Finish to start the conversion.

  12. Progress displays in the Log window. (Log output is stored with the log file name(s) that you specify in the Options dialog. See the following section for information about setting options.)

  13. Check the log file(s) for information about required conversion steps that the tool did not modify. Manually make these changes to your application.

2.4.3.2 Setting Advanced Converter Options

Note:

For information about setting the search_replace.properties file, see "Editing the converter.properties File".

You can set conversion options before running the wizard:

  1. In the Converter options dialog (step 2 of the wizard), click Advanced Options.

  2. Converter properties display in the left column of the dialog. Edit the property values as needed, as described in Table 2-3, "Converter Properties":

    Table 2-3 Converter Properties

    Property Value Description

    Display Backup Warning

    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).

    Default DESTYPE

    Type of destination device that receives the report output (cache, printer, file).

    Default DESNAME

    Name of the file, printer, e-mail ID, or distribution list to which the report output is sent

    Default Browser

    For UNIX, the browser used to display help for the Migration Assistant. This setting is either netscape or iexplore. In Windows, the system default browser is used.


  3. Click OK to save the configuration. The data is saved to the converter.properties file, and the settings you specify are used in the current and future sessions of the utility.