Skip Headers

Oracle® Forms Migrating Forms Applications From Forms 6i 10g (10.1.2.0.2) for Windows and UNIX B15572-01 |
| Library | Product | Contents | Index

Previous | Next |

# 2 Using the Oracle Forms Migration Assistant

This chapter contains the following sections:

- Chapter2, "What Does the Oracle Forms Migration Assistant Do?"

- Chapter2, "Editing the converter.properties File"

- Chapter2, "Editing the search_replace.properties File"

- Chapter2, "Starting the Oracle Forms Migration Assistant"

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

## What Does the Oracle Forms Migration Assistant Do?

The Oracle Forms Migration Assistant updates obsolete usage in your PL/SQL code in order to migrate your Forms 6i applications to Oracle Forms. 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 migration, for example:

  - Provides warnings when specific obsolete Built-ins are used at runtime, 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 migration process on a Forms application more than once. You can also use the wizard version of the Migration Assistant to migrate 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 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.

### 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'll need to 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 migration, 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 will be overwritten. The Forms Migration Assistant generates two log files: test_fmb.log and test_mmb.log.

## 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 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 can be 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 machine 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 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.
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 Oracle 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:

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.

### 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 that have already been created 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 new 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 new classes and warnings using the syntax described above.

4. Save the search_replace.properties file.

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

## 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 migrate. The module name parameter can take only one value. See "Running the Wizard Version of the Forms Migration Assistant" if you want to migrate multiple modules at a time.
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.
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 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.

### 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 %%ff in (%1) do call frmplsqlconv module=%%ff

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:

    upgrade.sh *.fmb

or

    upgrade.sh foo*.mmb

### Starting the Migration Assistant in Batch Mode

To start the Migration Assistant in batch mode in Windows:

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

Note: A dialog window will appear recommending that you backup your files before converting. Select the Show me this again check box to enable this warning in the future.

To start the Migration Assistant in batch mode in UNIX:

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

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

In the following example:

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

Forms Migration Assistant will look for the file Òtest.fmbÓ in the d:\temp directory and will name the generated log file Òtest.logÓ and place 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.

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

### Running the Wizard Version of the Forms Migration Assistant

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

To start the wizard version of the Forms Migration Assistant:

1. On Windows systems, set the environment variable FORMS_PATH:

   SET FORMS_PATH=%ORACLE_HOME%\forms

   On UNIX systems, set the variable FORMS_PATH as in the example below:

   `setenv FORMS_PATH $ORACLE_HOME/forms`

2. In Windows, 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`.

   or

   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 will be 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 Reports Developer Reference. For more information about advanced converter options, see the following section, "Setting Advanced Converter Options".

10. Click Next.

11. In the Finish dialog, you will see the modules you selected. Click Finish to start the conversion.

12. Progress displays in the Log window. (Log output is written to 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.

#### 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

   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 machine 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 will receive the report output (cache, printer, file).
   Default DESNAME | Name of the file, printer, e-mail ID, or distribution list to which the report output will be 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 will be used in the current and future sessions of the utility.