Forms Builder Configuration

Forms: How to Configure Forms Builder to run forms locally

Introduction I wrote this document because so many people in the Oracle Technology Network (OTN) Forms Forum have asked “How do I run a form from the Forms Builder?” or “I just installed Forms 10g and all I get is a blank browser window when I run a form.” After I responded to numerous posts (always writing the instructions from scratch) I decided to write this document. As they say, “It is always better to reuse then to recreate!” Disclaimer First and foremost, this document targets the following Oracle Developer Suite (Forms/Reports) versions:  10g R1 (9.0.4.x.x) and 10g R2 (10.1.2.x.x).  Many of the concepts apply to the Oracle Fusion Middleware (FMw) 11g suite (Forms and Reports), but this document is not intended to help you with FMw configuration.    The information in this document could be adapted to Oracle Forms 9i, but I do not currently have access to this version of Forms so there is no guarantee that these methods will work for Forms 9i.   Secondly, this document is NOT all inclusive – meaning it is not a full reference to all setup options available.  This document is meant only to get you up and running.  If you need to use features that are not listed in this document, please refer to the appropriate Oracle document available at the Oracle Technology Network (OTN).   Lastly, this article assumes you have successfully installed the Oracle Developer Suite (ODS) 10g R2 (10.1.2.x.x).  If you have not already installed the ODS then you will need to do this before you can proceed. Background If you have used Oracle Forms long enough, you will remember the day when you could run a Form locally from the Forms Builder with the Forms Runtime.  This was a very nice feature that enabled you to perform incremental development and testing; the Forms Debugger utility; not to mention the Forms Runtime Diagnostics (FRD).  With the advent of Forms 9i – when Oracle made Forms web deployed only – many developers thought the ability to run a form from the Forms Builder was lost.  This is not true; it is just a little harder to do now and requires some configuration setup on your workstation to make it work.  Forms 10g use the OC4J Forms Servlet to emulate a Forms Service web process on your workstation that allows you to “serve” a web form from the Forms Builder.  This is a very generic description of what OC4J is and what it does, but it will suffice for the purpose of this document.  In order to run a form from the Forms Builder, Oracle has included two new program items (among others) in Oracle Developer Suite Program group of the installed Oracle Developer Suite 10g.  These two program items are the “Start OC4J Instance” and “Stop OC4J Instance.”  Both are critical to the running of forms from the Forms Builder.  Let’s get started… There are two parts to configuring Forms Builder to run forms.  The first relates to Forms Builder and the second relates to the OC4J Forms Servlet.  Most forms developers will be familiar with configuring the Forms Builder as this involves setting up key environment/registry variables so the Forms Builder can find libraries (PL/SQL libraries [.pll] and Forms Object Libraries [.olb]).  However, fewer developers are familiar with setting up the OC4J environment variables which enable you to run a form from the Forms Builder.   There are two Java Runtimes (JREs) supported by Forms Builder;  Oracle Jinitiator and the Oracle (Sun) Java Runtime Environment (Sun JRE).  By default, Forms Builder is configured to use the Oracle Jinitiator and in most cases this should be sufficient for your needs.  Configuration is simply to install the Oracle Jinitiator (make sure you install the right version because each Forms version defaults to different version.  For example, Oracle Forms 10g R2 (10.1.2.0.2) defaults to using Oracle Jinitiator 1.3.1.22.  If you install the version found in your Oracle DevSuite home directory (\%DEV_SUITE_HOME%\jinit) you should be OK.  If you decide to use the Sun JRE, again, you will need to install the appropriate version as the Forms Builder ships configured to a specific version of the Sun JRE.  For example, Oracle Forms 10g R2 (10.1.2.0.2) defaults to Sun JRE version 1.4.2 update 6 (1.4.2_06).  Most likely, you will have to update the default settings as you likely do have the Sun JRE installer for 1.4.2 and it is no longer available for download.  Therefore, you will likely be installing the latest version of the Sun JRE which is Java 6 (1.6.0).    Which JRE you use is also dependent on your Operating System (OS) version and your Internet Browser version.  This document focuses on setup for the Microsoft Windows Operating System and Internet Explorer and Mozilla Firefox browsers.  The following is the Oracle certified supported configurations.    OS  Java Runtime  Windows  Jinitiator  Sun JRE  Internet Explorer      version 5  1.3.1.x+   1.4.1+  version 6  1.3.1.22+  1.4.2_06+  version 7  1.3.1.28  1.5.0_06+  version 8  1.6.0_16+  1.6.0_16+  FireFox 3.5+  NS  1.6.0_16+ + = indicates a higher version can be used NS = Not Supported   This list is an abbreviated list.  For a complete list – review the appropriate Oracle Certification Matrix document on OTN.   Alright, enough background.  It’s time to get the heart of this document.    This document will be focused into three sections:  Forms Builder config, OC4J with Jinitiator, and OC4J with Sun JRE.   Forms Builder Configuration Forms Builder is dependent on the following variables (there are others, but these are the most important): • FORMS_PATH • FORMS_BUILDER_CLASSPATH • TNS_ADMIN FORMS_PATH is used by Forms Builder to record the location of attached libraries (.pll) and subclassed objects (such as items from a Template.fmb or Object Library [.olb]).  You can also include your Forms working directory in this variable and Forms runtime will be able to find your compiled Forms binaries when you run a form from the Forms Builder.  This saves you having to modify the “formsweb.cfg” file to include a configuration for each form you develop (I’ll include a brief discussion of custom configurations at the end of this document).   This variable is mandatory if you use attached libraries or subclassed objects.   FORMS_BUILDER_CLASSPATH is used by Forms Builder to record the location of any Java Pluggable Components or Java Beans that are implemented in a form.    This variable is optional, but you will receive a Forms Builder error during design time indicating that Forms Builder can’t find the implemented Java source.  This is a design time error only and does not affect runtime.   TNS_ADMIN is used by Forms Builder to find your TNSNAMES.ora and SQLNET.ora files.  This variable is handy if you have multiple Oracle Homes installed because it allows you to share a single set of TNS configuration files.   This variable is optional, but if you have multiple Oracle homes you will have to maintain separate copies of the TNS files for each Oracle home.   These variables can be set in either the Windows Registry (Windows XP) through the Windows System Environment Variables.  This document will describe both methods of setting these variables.   Windows Registry 1. Open the Windows Registry Editor (regedit.exe or reged32.exe) 2. Navigate to the appropriate Oracle Home • HKEY_LOCAL_MACHINE • SOFTWARE • Oracle • HEY_DevSuiteHome10g 3. FORMS_PATH: In the Key listing, scroll through and find the FORMS_PATH string variable and double-click or right-click and select “Modify” to edit the variable. a. DO NOT delete the existing value.  Add directory information by separating it with semicolons “;”.  b. Example:         FORMS_PATH=C:\DevSuiteHome10g\cgenf61\admin;C:\Forms_Dev\*;           Note: I have found that I can include a wildcard reference in the FORMS_PATH.  This allows me organize all of my Forms development into a         single directory.  In my Forms_Dev directory, I have a Forms_Lib directory where I store all of my referenced items such as; attached libraries (.pll),         object libraries (.olb) and object referenced from a Forms Template file (template.fmb).  Additionally, if I am working on different projects, I can         create a subdirectory for each project.   4. FORMS_BUILDER_CLASSPATH:  find the existing entry for this key and open the key editor.  a. Again – DO NOT delete any existing values b. Add to the exiting directory and .jar file listing by separating each entry with a semicolon. 5. TNS_ADMIN:  This entry does not exist, you will have to create this entry in each of the Oracle Homes.  a. In the key listing, right-click somewhere and New => String Value from the context menu b. This will create an empty string entry. c. Open the editor for the string and enter the full path to your TNS configuration files.  Eg: C:\DevSuiteHome10g\NETWORK\Admin   Windows Environment Variables 1. Open the System Properties control panel applet. (Start Menu => Control Panel => System) 2. Click on the Advanced tab. 3. Click on the Environment Variables button towards the bottom. 4. If more than one person uses the workstation, I recommend you add the FORMS_PATH variable to the set of User Variables rather than add it to the list of System Variables.  This allows each user to set their own preferences. a. Click on the New button and enter the Variable Name and Variable Value i. Variable Name = FORMS_PATH ii. Variable Value = full path to your working and library directories iii. You do not have to worry about the default value of this variable in the registry as this environment variable augments the registry. 5. Do the same thing for the FORMS_BUILDER_CLASSPATH and TNS_ADMIN variables.   This completes the Forms Builder setup. OC4J Servlet setup The OC4J Servlet setup is a bit more complex in that all of the variables are stored one of two files.  These files are: • DEFAULT.ENV • FORMSWEB.CFG These file can be found in the \%DEV_SUITE_HOME%\forms\server directory.  I strongly recommend you make a back up copy of the original file before you modify these files.   Note:  These files should only be modified on the application server using the Oracle Enterprise Manager (OEM).  The Developer Suite installation does not include the OEM so modifications must be made manually with a text editor. DEFAULT.env – This file is used to set Forms runtime environment parameters.  There are only two parameters that I have had to modify to enable running a form from the Forms Builder. They are:  FORMS_PATH and CLASSPATH. The FORMS_PATH needs to have the same directories listed as stated above for the equivalent Registry or Environment variable. The CLASSPATH only need to be modified if you implement a PJC or Java Bean in your form.   You will need to list the full path, to include the file name, in this parameter listing.  This parameter has a maximum character length of 256 characters.   FORMSWEB.cfg – This file contains the parameter values used by the Forms Servlet.  There are two types of parameters: SYSTEM and USER defined.  System parameters are static in that they can not be overridden at run time.  User parameters have an entry in the baseHTML file and can be overridden in the URL query string.    This file is where the bulk of changes are needed the enable running a form from the Forms Builder.  I will not list all of the parameters as there are too many.  Refer to the Application Server Forms Services Deployment Guide (see references) for a complete listing of all parameters and more detailed information.   Configuration will be separated by Java Runtime used.  I’ll list Sun JRE first and Jinitiator second.  Bear in mind, that Oracle has retired the Jinitiator and no longer supports its use.    The formsweb.cfg is broke up into separate defined configurations.  Each configuration is named and can be identified by the name in square brackets.  For example, the ‘Default” configuration is listed as: [default].  This is the configuration that is used unless it is overridden through the URL query string.    I’ll list later in the document how you can override a User parameter or specify a custom configuration later in the document.   Conventions used:Settings listed in Green are code comments Settings listed in Blue are original settings Settings listed in Red are recommend changes Settings listed in Purple are optional changes   Sun JRE Modify the following settings to use a JRE version different from the default if 1.4.2.  The following JRE changes instruct the Forms Runtime to use the JRE version 1.6.0 update 22 (1.6.0_22).  The following settings are all found in the [default] configuration section. # System parameter: base HTML file for use with JInitiator client # baseHTMLjinitiator=basejini.htm baseHTMLjinitiator=basejpi.htm Oracle Forms is hardwired (so to speak) to use the Oracle Jinitiator. Therefore, to instruct the Forms Runtime to use the JRE without passing a URL query string parameter, it is recommended you change the “baseHTMLinitiator” parameter to point to the Java Plug-In (JPI) html file. You could also expand the existing [jpi] section and instruct the Forms runtime to use this configuration in the URL. Personally, I find this to be the easier solution. # Page displayed to users to allow them to download Sun's Java Plugin. # Sun's Java Plugin is typically used for non-Windows clients. # (NOTE: you should check this page and possibly change the settings) # Original setting #jpi_download_page=http://java.sun.com/products/archive/j2se/1.4.2_06/index.html # New – points to the generic ( non-version specific) JRE download web site jpi_download_page=http://www.oracle.com/technetwork/java/javase/downloads/index.html # Parameter related to the version of the Java Plugin # Original setting #jpi_classid=clsid:CAFEEFAC-0014-0002-0006-ABCDEFFEDCBA # This setting is specific to JRE 1.6.0_22 jpi_classid=clsid:CAFEEFAC-0016-0000-0022-ABCDEFFEDCBA # Optional – Generic to any version of JRE 1.6.0.   Note the difference between these two settings. jpi_classid=clsid:CAFEEFAC-0016-0000-FFFF-ABCDEFFEDCBA # Parameter related to the version of the Java Plugin # Original setting #jpi_codebase=http://java.sun.com/products/plugin/autodl/jinstall-1_4_2-windows-i586.cab#Version=1,4,2,06 # New – specific to JRE 1.6.0_22 jpi_codebase=http://java.sun.com/update/1.6.0/jinstall-6-windows-i586.cab#Version=1,6,0,22 # Optional – Generic to JRE 1.6.0 jpi_codebase=http://java.sun.com/update/1.6.0/jinstall-6-windows-i586.cab#Version=1,6,0 # Parameter related to the version of the Java Plugin # Original Setting #jpi_mimetype=application/x-java-applet;jpi-version=1.4.2_06 # New – specific to JRE 1.6.0_22 jpi_mimetype=application/x-java-applet;jpi-version=1.6.0_22 # Optional – Generic to JRE 1.6.0 jpi_mimetype=application/x-java-applet;jpi-version=1.6.0 Oracle JinitiatorModify the following settings to use a Jinitiator version different from the default if 1.3.1.26.  There  are no optional settings for Jinitiator. # Page displayed to Netscape users to allow them to download Oracle JInitiator. # Oracle JInitiator is used with Windows clients. # If you create your own page, you should set this parameter to point to it. # jinit_download_page=/forms/jinitiator/us/jinit_download.htm # Parameter related to the version of JInitiator jinit_classid=clsid:CAFECAFE-0013-0001-0026-ABCDEFABCDEF jinit_classid=clsid:CAFECAFE-0013-0001-0028-ABCDEFABCDEF # Parameter related to the version of JInitiator # jinit_exename=jinit.exe#Version=1,3,1,26 jinit_exename=jinit.exe#Version=1,3,1,28 # Parameter related to the version of JInitiator # jinit_mimetype=application/x-jinit-applet;version=1.3.1.26 jinit_mimetype=application/x-jinit-applet;version=1.3.1.28 Default URL Query String and parameters The default URL query string used by the Forms Builder is: http://myhost.mydomain.com/forms/frmservlet? With reference to the aforementioned JPI change for the “baseHTMLjinitiator=” parameter, alternatively, you could pass the JPI configuration in the URL query string.  To do this, simply add “config=jpi” to the default URL query string.  Passing this additional parameter, the default URL would look like: http://myhost.mydomain.com/forms/frmservlet?config=jpi However, I prefer to make the change in the formsweb.cfg file as this is a more permanent change. Custom Configurations If you have installed the Oracle Demo’s you will find that Oracle modifies the formsweb.cfg to add a configuration for each form included in the demo.  While this works fine for demo’s, it is a real pain in everyday development to add a configuration section for each form you work on (which is why I edit all of my forms in a directory that is in my FORMS_PATH).  However, there are times when it is good to create a configuration for a specific form.  For example, if I want to run a form with the Forms Runtime Diagnostics (FRD) enabled, I have created a configuration that enables this.  Then I simply add the parameter to the url to enable FRD (?config=my_frd). To create a custom configuration, open the formsweb.cfg file and scroll to the bottom of the file.  Always add additionally configurations to the end of the file.  Custom configurations will use all of the variables in the [default] section and then override any you specify in your custom configuration.  The following is based on my reference to use Forms Runtime Diagnostics (FRD).  The configuration listed below also uses a configuration specific environment file (default.env) as well. [my_frd] otherparams=record=collect log=my_frd.txt envFile=my_frd.env form=<YOUR_FORM_NAME_HERE.fmb> To create a specific environment file, I simply copied the default.env to my_frd.env and added the following variable:   FORMS_TRACE_DIR=C:\DevSuiteHome10g\NETWORK\log   References: - Oracle® Application Server Forms Services Deployment Guide – 10g Release 2(10.1.2) (B14032-03 – Feb 2006) - Oracle® Application Server Certification Information - 10 g Release 2 (10.1.2)  (B25703-62 - April 30, 2010) - Using the Java Plug-in (JRE/JPI) with Oracle Forms (ID 794710.1) - How Do the Jinitiator and JPI Parameters Work In a Forms Configuration (ID 444105.1)