This chapter contains the following sections:
The Oracle Forms Migration Assistant updates obsolete usage in your PL/SQL code to upgrade your Forms 6i applications to Oracle Forms 12c. 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 again 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.
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.
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 helps 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 RSPUB for details. |
DESFORMAT (default.desformat) |
The printer driver to be used when DESTYPE is FILE. See the RSPUB 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 RSPUB 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. |
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.
You can edit this file to add your own search-and-replace strings, as follows:
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:
You should upgrade the common modules that a form relies upon and, ensure that these are available in the FORMS_PATH, before running the migration assistant. The following should be upgraded in this order using the FMA:
olb
.pll
.mmb
.fmb
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 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.
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
You can run the Migration Assistant in batch mode on Windows and UNIX computers.
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. Notice 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".
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. Notice 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".
You can run the wizard version of the Forms Migration Assistant and edit converter options.
This section describes how to start the Forms Migration Assistant on Windows and UNIX computers.
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: