What is the CAST Oracle Forms Extractor?

Background information

CAST AIP has provided support for analyzing Oracle Forms/Reports source code via its Oracle Forms and Reports Analyzer (provided out-of-the-box in CAST AIP) for some time now. In previous releases of CAST AIP, delivery of Oracle Forms data via the CAST Delivery Manager Tool (DMT) required that Oracle Forms was installed on the workstation on which the CAST Delivery Manager Tool (DMT) was being run from, i.e. the DMT required certain Oracle Forms runtime components in order to package the source code for analysis.

This requirement sometimes presented significant difficulties for the process of on-boarding an Oracle Forms application into CAST AIP. As a direct result of this and wanting to simplify the approach, CAST developed the standalone CAST Oracle Forms Extractor to decouple the extraction process from the CAST Delivery Manager Tool.

When do I use the CAST Oracle Forms Extractor?

If you want to analyze your Oracle Forms source code, you must use the standalone CAST Oracle Forms Extractor first:

• The extractor takes the raw Oracle Forms files (.fmb, .olb, .mmb, .pll) in a local or network folder as input, it then uses the Oracle Forms runtime to interpret these raw files and finally transforms them into a format that can be understood by the analyzer provided in CAST AIP.
• The output of the CAST Oracle Forms Extractor is then fed into the CAST Delivery Manager Tool/AIP Console, packaged and delivered for analysis.

How does the standalone Oracle Forms extractor work?

The standalone extractor is a Java based tool which does not require installation. You can run it in GUI mode or via batch scripts in CLI mode. You can specify:

• the folder containing the raw Oracle Forms files (.fmb, .olb, .mmb, .pll)
• the location where you want to save the output results

Once the extractor has successfully completed, the results need to be fed into the CAST Delivery Manager Tool/AIP Console. Subsequent analysis of the delivered source code is undertaken as normal.

What about Oracle Reports?

Oracle Reports do not need to be extracted by the standalone CAST Oracle Forms Extractor. You can therefore place the raw .rex files in the same folder as the output of the CAST Oracle Forms Extractor, ready for delivery with the CAST Delivery Manager Tool/AIP Console.

When working with Oracle Reports, the CAST Delivery Manager Tool/AIP Console can only handle .rex files. If you have Oracle Reports .rdf files and would like to include them in the delivery, you can convert them to .rex files as follows:

• Using Oracle Reports Builder
• Using the Oracle command line utility rwconverter.exe (for Windows) or rwconverter.sh (for Linux) - see http://docs.oracle.com/cd/E16764_01/bi.1111/b32121/pbr_cla002.htm, for example using the following script:

@@Echo on
REM set the REPORTS_PATH Oracle Environment Variable to point to the reports and templates required by rwconverter.exe. This environment variable is
REM used to locate reports and external objects that you use in your reports, such as PL/SQL libraries, external queries, and external boilerplate.
REM see https://docs.oracle.com/cd/B14099_19/bi.1012/b14048/pbr_rfap.htm#i648209 for more information.
set REPORTS_PATH=<path_to_reports>;<path_to_dependencies>

REM change directories and move to the location of your *.rdf files
cd D:\path_to\some_folder\

REM loop through all .rdf files in the current folder and convert into .rex files
for %%f in (*.rdf) do C:\path_to\rwconverter.exe source=%%f userid=<userid> stype=rdffile dtype=rexfile dest=..\rex1%%f.rex batch=yes
pause

Where can I obtain the CAST Oracle Forms Extractor?

You can download the extractor from CAST Extend. One identical (in functionality) extractor is available for both the 32bit Oracle Forms runtime and the 64bit Oracle Forms runtime:

com.castsoftware.aip.extractor.forms.<version>\x86\CASTFORMSGUI.jar
com.castsoftware.aip.extractor.forms.<version>\x64\CASTFORMSGUI.jar

Prerequisites

To use the CAST Oracle Forms Extractor, the following is required:

Oracle Forms runtime

Oracle Forms 32bit or 64bit must be installed on the workstation on which the extraction is being run from (i.e. the workstation on which you are running the standalone CAST Oracle Forms Extractor). The extractor will use the runtime to access and convert the Oracle Forms files:

• You must ensure that the following two Windows environment variables are correctly configured for your installation of Oracle Forms. If this is not the case, you may find that the extractor will stop during the extraction phase and will not be able to continue due to an invalid Forms module. If this occurs, the log will contain the name of the Forms module which caused the error. You can then remove this module and re-run the package action:
  
  • The path to the Oracle Forms Builder installation must be configured in the PATH environment variable
  • The FORMS_PATH environment variable must point to the correct Forms source code directory
• You must ensure that you install the same version of Oracle Forms as was used to develop the source code you are extracting.
• Oracle Forms does NOT need to be installed on the machine running the analysis (i.e. the machine running the CAST Management Studio/AIP Console/AIP Node).
• Recommended language for NLS_LANG global parameter: CAST highly recommends that the installation of Oracle Forms uses an NLS_LANG global parameter set to ENGLISH (United Kingdom or United States) to avoid issues with resolving references between Forms objects.
• CAST recommends organizing your raw Oracle Forms source code as follows:
  
  • All the source code must be stored in a single folder (PLL / FMB all in one folder), or:
  • All the PLLs must be stored in a dedicated folder and the FMBs in different dedicated folder.

Supported Oracle Forms releases for extraction

See list of supported releases in Oracle Forms and Reports - Covered technologies.

Supported Operating Systems

The CAST Oracle Forms Extractor can be run on the following Operating Systems:

Operating System	Supported	Supported by reference
Microsoft Windows 7 SP1 64-bit
Microsoft Windows 8 64-bit
Microsoft Windows 8.1 64-bit
Microsoft Windows 10 64-bit
Microsoft Windows Server 2008 R2 SP1 64-bit (Standard edition)
Microsoft Windows Server 2012 64-bit (Standard edition)
Microsoft Windows Server 2012 R2 64-bit (Standard edition)
Unix based (Linux/MacOS X)

Supported releases of CAST AIP / AIP Console for analysis of output data

The output of the CAST Oracle Forms Extractor can be analyzed with any of the following:

Application	Release	Supported
CAST AIP	≥ 8.3.x
AIP Console	≥ 1.17.x

Java JRE

A Java JRE must be installed on the machine on which you want to run the CAST Oracle Forms Extractor:

JRE version	Supported	Notes
≥ 1.6.x (32bit or 64bit)		Note: this is a minimum requirement - the CAST Oracle Forms Extractor will work with more recent versions of the Java JRE. if you are running the 32bit CAST Oracle Forms Extractor, you must ensure that you use a 32bit Java JRE if you are running the 64bit CAST Oracle Forms Extractor, you must ensure that you use a 64bit Java JRE

Launching the CAST Oracle Forms Extractor

The CAST Oracle Forms Extractor is provided as an executable JAR file, which can be launched by double-clicking it. However when doing so you will likely encounter Java "out of memory" exceptions especially when extracting large Oracle Forms source files. CAST therefore highly recommends that the executable JAR file is launched via a batch file containing the following commands:

java -Xmx1024M -jar D:\Extractor\CASTFORMSGUI.jar

The java -XMX1024M command allows you to configure the Maximum Java Heap Size of your JVM. Change the figure to match the number of MB you want to allocate to the process – i.e. increase the memory allocation until you no longer receive errors (CAST recommends starting at a minimum of 1024MB).

CAST Oracle Forms Extractor GUI

Below are links to explanation of each section in the GUI:

How to run the extractor

Extraction/Delivery actions

The extraction process is a two-step action:

• Extraction > data is extracted from the raw input file and saved as raw extraction files
• Delivery > the raw extraction files are transformed into UAXDIRECTORY, UAX and SRC files

These two steps can be run together, or separately in the CAST Oracle Forms Extractor and shown by the menu option below (for the GUI):

Use the following information to help you decide how to proceed:

• In the vast majority of circumstances, CAST recommends that you run the two steps together
  
• If your source files are large, you may want to run the Extraction action first and then run the Delivery action later. The advantage of this is that you can view the log of the Extraction action before you start the Delivery action.
• The CAST Delivery Manager Tool/AIP Console will ONLY accept extractor output where the Delivery action has been run:

Example for the CAST Delivery Manager Tool

How to run an extraction/delivery with the GUI

• Launch the CASTFORMSGUI.jar file using your batch file. The following will be displayed (click to enlarge):

Once launched, you need to:

• Define the location of the source input Oracle Forms files (.fmb, .olb, .mmb, .pll) in the General panel
• Define the location of the extraction action output in the Options panel
• Define the location of the delivery action output in the Target panel
• Click Run Application on the toolbar to commence the process.

Output

If the process is successful, you should see the following output:

• Extraction action - output stored in raw files as specified in the Extraction File Path field located in the Options panel.
• Delivery action - a set of files in the folder specified in the Target Folder Path field in the Target panel. You should expect the following if you have extracted one file of type .fmb, .olb, .mmb, .pll:
  • one DatabaseExtraction.uaxdirectory file
  • various .uax files
  • various .src files

How to run an extraction/delivery with the CLI

The CAST Oracle Forms Extractor can be run in CLI mode should you wish to automate the extraction/delivery process.

When using the command line, the process consists of a set of instructions and commands contained in a batch file (.bat) file. When the batch file is executed, the Java tool (CASTFORMSGUI.jar) is launched and the process begins. If you are extracting a large amount of data (i.e. multiple raw Oracle Forms files), you must use a batch file that contains specific Java Heap Space configuration commands (the -Xmx command), otherwise you will likely receive out of memory exceptions. Below is an example batch file for launching the .JAR tool.

Example batch file for Extraction + Delivery option

REM ===============================
REM EXTRACTION ACTION
REM ===============================
java
-Xmx1024M
-cp CASTFORMSGUI.jar com.castsoftware.extractor.cli.FormsExtractor
-rootpath <location of the folder that contains your Oracle Forms and Oracle Reports source code>
-target <path to extraction output location folder>
-l <path to log file>

REM ===============================
REM EXAMPLE 
REM java -Xmx1024M -cp CASTFORMSGUI.jar com.castsoftware.extractor.cli.FormsExtractor -rootpath D:\OracleForms -target D:\OracleForms\ExtractionResults -l D:\OracleForms\output_extractor.txt
REM ===============================

REM ===============================
REM DELIVERY ACTION
REM ===============================
java
-Xmx1024M
-cp CASTFORMSGUI.jar com.castsoftware.extractor.cli.Importer
-source <path to output location from extraction step>
-target <path to output folder>
-relativepaths
-l <path to log file>

REM ===============================
REM EXAMPLE
REM java -Xmx1024M -cp CASTFORMSGUI.jar com.castsoftware.extractor.cli.Importer -source D:\OracleForms\ExtractionResults -target D:\OracleForms\DeliveryResults -relativepaths -l D:\OracleForms\output_delivery.txt
REM ===============================

Output

If the actions are successful, you should see the following output:

• Extraction action - output stored in raw files as specified in the -target parameter
• Delivery action - a set of files in the folder as specified in the -target parameter.
• You should expect the following if you have extracted one file of type .fmb, .olb, .mmb, .pll:
  • one DatabaseExtraction.uaxdirectory file
  • various .uax files
  • various .src files

Command line parameters

The following table lists all available commands for the CAST Oracle Forms Extractor when run direct from the command line:

Extraction action

Parameter	Mandatory	Description
java or C:\path\to\java.exe		This command specifies the location of your JRE. You should not need to specify the path, however, if you do, replace the C:\path\to with the location of the Jave exe file. Note that if it is installed in a path containing spaces, you must surround the path with quotation marks.
-Xmx1024M		This is an optional but recommended parameter for the extract action that allows you to configure the Maximum Java Heap Size of your JVM. Change the figure to the number of MB you want to allocate.  This parameter is necessary if you are getting Out of memory exceptions for the Java Heap Space when you execute the batch file. Please increase the memory allocation until you no longer receive errors. Please see the JRE documentation for more information about this.
-cp D:\path\to\CASTFORMSGUI.jar com.castsoftware.extractor.cli.FormsExtractor		This parameter specifies the location of the CASTFORMSGUI.jar. Replace the D:\path\to with the location of the jar file.
-rootpath <Forms Root Path> []		This parameter specifies the location of the folder that contains your Oracle Forms source code (.fmb, .olb, .mmb, .pll files). See CAST Oracle Forms Extractor - General panel for more information. Info Note that if you have already run an extraction and delivered/analyzed the results and you subsequently decide to perform another code extraction (because your source code has changed since the last analysis) you should be aware of the following: if the location of the source code is different to the location used in the previous extraction, the analysis results will reflect this: the objects will be recorded as deleted and then added. This is due to the fact that the source code root path is used to form the GUID for each Forms/Reports object, therefore when the root path changes, the GUID of the object will change resulting in objects being recorded as deleted and then added.
-target <Extraction  File Path> [exportResults]		This parameter specifies the location you would like the extraction action to output the results to (the results will be raw files in the specified file). See CAST Oracle Forms Extractor - Options panel for more information.
-l <Log File> []		This parameter specifies an output file for logging purposes. Specify a .TXT file to contain the log of the entire extract action. You can name the file anything you like. If omitted, the output will be displayed in the command line window.
-platform <Platform> [Forms]		See CAST Oracle Forms Extractor - General panel for more information.
-config <Configuration File Path> [CASTDatabase.config]		See CAST Oracle Forms Extractor - Options panel for more information.
-format <Export Format> [text]		See CAST Oracle Forms Extractor - Advanced panel for more information.
-idcachefolder <Internal ID Cache Folder Path> []
-slicing <Slicing Extraction> [true]
-slicesize <Number of module per slice> [1]
-checkconfig <Verbose Configuration> [false]		See CAST Oracle Forms Extractor - Expert panel for more information.
-zip <Zip Packaging> [false]
-internalid <Internal ID> [true]
-checkmodules <Checks the Modules to extract> [false]
-abortonfatal <Abort on Fatal Error> [false]
-metaMode <Meta Mode> [true]
-v <Verbose> [true]		See CAST Oracle Forms Extractor - General panel for more information.
-h <Display Help> [false]		Use this command to display a list of available command line options - you may need to output the list to a text file.

Initialize action

Parameter	Mandatory	Description
java or C:\path\to\java.exe		This command specifies the location of your JRE. Note that if it is installed in a path containing spaces, you must surround the path with quotation marks.
-Xmx1024M		This is an optional but recommended parameter for the extract action that allows you to configure the Maximum Java Heap Size of your JVM. Change the figure to the number of MB you want to allocate.  This parameter is necessary if you are getting Out of memory exceptions for the Java Heap Space when you execute the batch file. Please increase the memory allocation until you no longer receive errors. Please see the JRE documentation for more information about this.
-cp D:\path\to\CASTFORMSGUI.jar com.castsoftware.extractor.cli.Importer		This parameter specifies the location of the CASTFORMSGUI.jar. Replace the D:\path\to with the location of the jar file.
-source <Extraction File Path> [exportResults]		This parameter specifies the folders containing the output of the extraction action.
-target <Target Folder Path> [deliveryResults]		This parameter specifies the folder you would like the delivery files to output to. Note that this action will create a large number of files.
-relativepaths <UAX Relative Paths> [true]		This parameter will force the creation of relative paths (instead of absolute paths) in the resulting .UAX files that point to the location of the source code (this is used in the CAST dashboards and in CAST Enlighten). This allows you to move the results of the Delivery action and not lose the accompanying source code. See CAST Oracle Forms Extractor - Expert panel for more information.
-l log_file.txt		This command specifies an output file for logging purposes. Specify a .TXT file to contain the log of the entire Initialize action. You can name the file anything you like. If omitted, the output will be displayed in the command line window.
-dispatch <Target Folders Dispatching> [true]		This option will force the results of the Delivery action to be placed in multiple folders within the location defined with the -target option. The uaxdirectory file will be placed at the root of the location defined with the -target option. CAST highly recommends using this option if you are planning to deliver a large number of files: the files generated by the deliver action will be spread over multiple folders, thus avoiding a situation where the host file system becomes overloaded the time taken to deliver the results of the extract action can be greatly reduced (anything up to ten times quicker) See also CAST Oracle Forms Extractor - Advanced panel for more information.
-logtime <Log Time> [true]		See CAST Oracle Forms Extractor - Advanced panel for more information.
-zip <Source Zip Packaging> [true]		See CAST Oracle Forms Extractor - Expert panel for more information.
-config <Configuration File Path Override> []		See CAST Oracle Forms Extractor - Options panel for more information.
-ziptarget <Target Zip Packaging> [false]		See CAST Oracle Forms Extractor - Expert panel for more information.
-unicode <Unicode Encoding> [true]
-platform <Platform> [Forms]		See CAST Oracle Forms Extractor - General panel for more information.
-uaxcode <UAX Code Information Generation> [true]		See CAST Oracle Forms Extractor - Expert panel for more information.
-shortids <IDs Compression in UAX File> [false]
-checkconfig <Verbose Configuration> [false]
-v <Verbose> [true]		See CAST Oracle Forms Extractor - General panel for more information.
-h <Display Help> [false]		Use this command to display a list of available command line options - you may need to output the list to a text file.

What to do with the output from the CAST Oracle Forms Extractor

Once you have successfully run the CAST Oracle Forms Extractor to extract the Oracle Forms source code, the next step is to deliver this output.

AIP Console

AIP Console expects either a ZIP/archive file or source code located in a folder configured in AIP Console. You should include in the ZIP/source code folder all the output from the CAST Oracle Forms Extractor and any Oracle Reports files:

• .uaxDirectory
• .uax
• .src
• .rex

CAST highly recommends placing the files in a folder dedicated to Oracle Forms/Reports. If you are using a ZIP/archive file, zip the folders in the "temp" folder - but do not zip the "temp" folder itself, nor create any intermediary folders:

D:\temp
	|-----OracleFormsReports
	|-----OtherTechno1
	|-----OtherTechno2

CAST Delivery Manager Tool

Create a new Version and add a Package of the type Oracle Forms and Reports:

Click Next to continue. You should now do the following in the next screen:

Then click Next to continue. You should now enter the location of the output from the standalone CAST Oracle Forms Extractor in the Package Configuration tab:

You are now ready to run the Package action. On completion you can use the Deliver action to deliver the packages ready for analysis in the CAST Management Studio.