Tuesday, November 13, 2012

Deploying Oracle Forms Applications 11g

Basics of Deploying Oracle Forms Applications

This chapter describes how Forms Services run in Oracle Fusion Middleware, and describes the steps to deploy Forms applications. This chapter also describes the basic configuration files. After installation is completed, you can use the information in this chapter to change your initial configuration or make modifications as your needs change.
This chapter contains the following sections:

3.1 Oracle Forms Services in Action

This section describes how Forms Services run in Oracle Fusion Middleware, and how the configuration files are used, with the assumption that the Forms servlet is used to generate the initial HTML page. For example, assume the Web server is running on port 8888 on a computer called "example.com". Also assume no modifications have been made to the standard configuration created during the Oracle Fusion Middleware installation process.
When a user runs an Oracle Forms Services application, the following sequence of events occur:
  1. The user starts the Web browser and goes to a URL such as:
    In this example, the top level form module to be run is called "hrapp" using the configuration section called "myapp".
  2. Oracle HTTP Server listener receives the request. It finds /forms path in the URL and forwards the request to the correct Oracle WebLogic Managed Server based on the WebLogic handler mappings. The mapping is defined in forms.conf.
  3. Oracle WebLogic Managed Server maps the request to the Oracle Forms Services application that has a context root named /forms. It maps the request to the Forms servlet using the frmservlet mapping specified in the web.xml file.
  4. The Forms servlet running on the Oracle WebLogic Managed Server processes the request. The Forms servlet:
    • Opens the servlet configuration file (formsweb.cfg by default), which is located in$DOMAIN_HOME/config/fmwconfig/servers/WLS_FORMS/applications/formsapp_11.1.1/config.
    • Determines which configuration section to use in the formsweb.cfg file. In this example, the URL contains the query parameter config=myapp, therefore, the [myapp] section is used.
    • Determines which baseHTML file to use, based on (a) what browser (user-agent) made the request, (b) what platform the browser is running on, and (c) the settings of various parameters in the formsweb.cfg file (specifically, basejpi.htm, and base.htm).
    • Reads the baseHTML file, and returns the contents as an HTML page to the user's Web browser, after performing variable substitutions as follows:
      Whenever a variable (like %myParam%) is encountered, the Forms servlet looks for a matching URL query parameter (for example, &myParam=xxx), or, failing that, looks for a matching parameter in the formsweb.cfg file. If a matching parameter is found, the variable (%myParam%) is replaced with the parameter value.
      In this example, the baseHTML file contains the text %form%. This is replaced with the value "hrapp".
  5. Depending on which baseHTML file the Forms servlet selected, the HTML page returned to the Web browser contains an applet, object or embed tag to start the Forms applet (thin client). The Forms client runs in the JVM environment provided by Sun's Java plug-in.
  6. In order to start the Forms applet, its Java code must first be loaded. The location of the applet is specified by the applet codebase and archive parameters.
    The virtual path definition in the weblogic.xml file for /forms/java allows the applet code to be loaded from the Web server.
    Note: The Forms applet code is only loaded over the network the first time the user runs an Oracle Forms Services application or if a newer version of Oracle Forms Services is installed on the Web server. Otherwise, it is loaded from the cache of the Java plug-in on the local disk.
  7. Once the Oracle Forms Services applet is running, it starts a Forms session by contacting the Forms Listener servlet at URLhttp://example.com:8888/forms/lservlet.
  8. The Oracle HTTP Server listener receives the request. It forwards the request to Oracle WebLogic Managed Server, since the path /forms/lservlet matches a servlet mapping in the web.xml file (the one for the Forms Listener servlet).
  9. The Forms Listener servlet (lservlet) starts a Forms run-time process (frmweb.exe or frmweb) for the Forms session.
  10. Communication continues between the Forms applet and the Forms run-time process, through the Listener Servlet, until the Forms session ends.
  11. The attribute value in a URL (such as the name of the form to run) is passed to the Forms run-time process. Part of the serverArgs value in the baseHTML file is%form%, which is replaced by "hrapp". Therefore, the run-time process runs the form in the file "hrapp.fmx".
    This file must be present in any of the directories named in the FORMS_PATH environment setting, which is defined in the environment file (default.env by default). You can also specify the directory in formsweb.cfg (for example, form=c:\<path>\myform).
  12. The Forms sessions end when either of the following occurs:
    • The top-level form is exited (for example, by the PL/SQL trigger code which calls the "exit_form" built-in function). The user is prompted to save changes if there are unsaved changes. exit_form(no_validate) exits the form without prompting.
    • If the user quits the Web browser, any pending updates are lost.

3.2 Configuration Files

This section introduces the basic files used to configure Forms applications. For more advanced configuration topics, see Chapter 4, "Configuring and Managing Forms Services."
This section contains the following:

3.2.1 Oracle Forms Configuration Files

Oracle Forms configuration files allow you to specify parameters for your Forms. You can manage these files through the Oracle Enterprise Manager Fusion Middleware Control. These configuration files include:
For a list of Forms configuration files and their respective locations, refer to Table C-1. default.env

Location: $DOMAIN_HOME/config/fmwconfig/servers/<MANAGED_SERVER>/applications/<appname>_<appversion>/config
Typically, this location is $DOMAIN_HOME/config/fmwconfig/servers/WLS_FORMS/applications/formsapp_11.1.1/config
This file contains environment settings for Forms run time. On UNIX and Linux, default.env includes the PATH and LD_LIBRARY_PATH.
For a sample default.env file, see Appendix C, "Platform Specific default.env Files."
For more information about default.env, see Chapter 4, "Managing Environment Variables." formsweb.cfg

Location: $DOMAIN_HOME/config/fmwconfig/servers/<MANAGED_SERVER>/applications/<appname>_<appversion>/config
Typically, this location is $DOMAIN_HOME/config/fmwconfig/servers/WLS_FORMS/applications/formsapp_11.1.1/config
This Forms configuration file contains the following:
  • Values for Forms run-time command line parameters, and the name of the environment file to use (envFile setting).
  • Most of the servlet configuration parameter settings that you set during installation. You can modify these parameters, if needed.
Variables (%variablename%) in the base.htm file are replaced with the appropriate parameter values specified in the formsweb.cfg file and from query parameters in the URL request (if any).
For a sample formsweb.cfg file, see Appendix C, "Default formsweb.cfg."
For more information about formsweb.cfg, see Chapter 4, "Configuring Parameters with Fusion Middleware Control." ftrace.cfg

Location: $ORACLE_INSTANCE/config/FormsComponent/forms/server
This file is used to configure Forms Trace. Forms Trace replaces the functionality that was provided with Forms Runtime Diagnostics (FRD) and Performance Event Collection Services (PECS), which were available in earlier releases of Oracle Forms. Forms Trace traces the execution path through a form (for example, steps the user took while using the form).
For more information about ftrace.cfg, see Chapter 12, "Tracing and Diagnostics."

3.2.2 Forms Java EE Application Deployment Descriptors

The Forms Services Java EE application EAR (Enterprise Archive) file formsapp.ear is deployed to the WLS_FORMS (Oracle WebLogic Managed Server) when you configure Oracle Forms.
This results in the creation of a directory structure under $DOMAIN_HOME /servers/WLS_FORMS/tmp/_WL_user/formsapp_11.1.1/<random_string1>/APP-INF directory that is similar to the following:










This following directory structure is created under $DOMAIN_HOME/servers/WLS_FORMS/tmp/_WL_user/formsapp_11.1.1/<random_string2>/war/WEB-INF directory.





The sub-directories in $DOMAIN_HOME/servers/WLS_FORMS/tmp/_WL_user/formsapp_11.1.1 are created by the nostage deployment process of Oracle WebLogic Server. They are named with a random string. For example, e18uoi, wb1h9e and so on.
Deployment descriptors:
  • application.xml and weblogic-application.xml define the structure of the EAR file.
  • web.xml defines the aliases frmservlet and lservlet for the Forms servlet and the Forms Listener servlet.
  • weblogic.xml defines the context parameters and any user defined virtual directory mappings.
For a sample web.xml file, see Appendix C, "web.xml."

3.2.3 Oracle HTTP Listener Configuration File

This section describes the file used to configure Oracle HTTP Listener for Oracle Forms Services.
Location: $ORACLE_INSTANCE/config/OHS/<OHS INSTANCE NAME>/moduleconf
forms.conf is the Oracle HTTP listener configuration file for Oracle Forms Services. forms.conf defines WebLogic handler mappings for the Managed Server where the Forms Services applications are deployed. About Editing forms.conf

forms.conf is an Oracle HTTP Server directives file. In Oracle Fusion Middleware, the forms.conf file is included in the Oracle HTTP Server configuration directory at$ORACLE_INSTANCE/config/OHS/<OHS INSTANCE NAME>/moduleconf.
If you add any custom Oracle HTTP Server directives to forms.conf, you must restart the Oracle HTTP Server node where it resides.
For more information about forms.conf, see Appendix C, "forms.conf." Configuring OHS on a Separate Host

If you choose to configure Oracle HTTP Server on a separate host, then perform the following tasks:
  1. Copy the Forms OHS directives file, forms.conf.backup from the tier hosting Forms to the tier hosting OHS and rename it to forms.conf.
    Source location (on Forms tier):
    Destination location (on OHS tier):
    $ORACLE_INSTANCE/config/OHS/<OHS Component Instance>/moduleconf/forms.conf
  2. Specify the appropriate managed server cluster or the managed server for the default forms Java EE application context root (/forms).
    Example of cluster entry:
    <Location /forms>
            SetHandler weblogic-handler
            WebLogicCluster    <HOSTNAME>:<WLS_PORT>
            DynamicServerList OFF
    Example of non-cluster entry:
    <Location /forms>
            SetHandler weblogic-handler
            WebLogicHost = <HOSTNAME>
            WebLogicPort = <PORT>
  3. Make sure that any directories referenced in user-added directives are accessible on the OHS tier.
  4. Restart OHS instance on the OHS tier.

3.2.4 Standard Fonts and Icons File

Registry.dat is the file that contains the default font, font mappings, and icon information that Forms Services uses.
Location: $DOMAIN_HOME/config/fmwconfig/servers/WLS_FORMS/applications/formsapp_11.1.1/config/forms/registry/oracle/forms/registry
For a sample of the default Registry.dat, see Appendix C, "Registry.dat."
For more information about Registry.dat, see Chapter 4, "Deploying Fonts, Icons, and Images Used by Forms Services."

3.2.5 baseHTML Files

Location: $ORACLE_INSTANCE/config/FormsComponent/forms/server/
The base.htm and basejpi.htm are used as templates by the Forms servlet when generating the HTML page used to start an Oracle Forms application.
Oracle recommends that you make configuration changes in the formsweb.cfg file using Enterprise Manager and avoid editing these files. To change the baseHTML files, create your own versions and reference them from the formsweb.cfg file by changing the appropriate settings.
For a sample baseHTML file, see Appendix C, "base.htm and basejpi.htm Files."

3.2.6 WebUtil Configuration Files

This section describes the files used to configure WebUtil at run time. For information about using WebUtil at design time, see the Oracle Forms Developer Online Help. WebUtil configuration files include: Default webutil.cfg

Location: $ORACLE_INSTANCE/config/FormsComponent/forms/server.
This file provides all of the configuration settings for WebUtil, including:
  • Logging Options
  • Installation Options
  • File Upload and Download Options
  • Server Side Logging Options for logging errors and log messages
For a sample of the webutil.cfg file, see Appendix C, "Default webutil.cfg." Default webutilbase.htm

Location: $ORACLE_INSTANCE/config/FormsComponent/forms/server/
This is the default baseHTML file for running a form on the Web using a generic APPLET tag to include a Forms applet with a certificate registration for WebUtil.
For a sample of the webutilbase.htm file, , see Appendix C, "Default webutilbase.htm." Default webutiljpi.htm

Location: $ORACLE_INSTANCE/config/FormsComponent/forms/server/
This is the default baseHTML file for running a form on the Web using the JDK Java Plugin. For example, this file can be used when running a form on the Web with Firefox on UNIX and a certificate registration for WebUtil.
For a sample of the webutiljpi.htm file, , see Appendix C, "Default webutiljpi.htm."

3.3 Application Deployment

Once you have created your application in Forms Developer, you are ready for application Web deployment. Oracle Forms Services accesses an application in Oracle Fusion Middleware through a specified URL. The URL then accesses the HTTP Listener, which communicates with the Listener Servlet. The Listener Servlet starts a Forms run-time process (frmweb.exe on Windows or frmweb on UNIX and Linux) for each Forms Services session.
For more information about how Forms Services run, see Section 3.1, "Oracle Forms Services in Action."

3.3.1 Deploying Your Application

To deploy a basic form with the default parameters set up by the installer:
  1. Create your application in Forms Developer and save it.
    The .fmb file is a design time file that can only be opened in Forms Developer. The .fmx file is the run-time file created when you compile the .fmb and is used for Web deployment.
    For more information about Forms Developer, see the Help menu in Forms Developer.
  2. Modify the formsweb.cfg file so that Oracle Forms Services can access your application module. You edit this file in the Web Configuration page of Fusion Middleware Control. For more information, see Section 4.2, "Configuring Forms Services".
    Table 3-1 shows the configuration of an application called "my_application" with a form module called "form=hrapp.fmx":
    Table 3-1 Example of Configuration Section Parameter Values
    Configuration Section NameForms Module Name Value
    When configured, the Oracle Forms Services module hrapp.fmx is accessible on the Web by entering "...?config=my_application" in the browser URL (the name of the Web Configuration section in formsweb.cfg).
    The name of the configuration section must not include spaces and must contain only alphanumeric characters.
  3. Make sure the .fmx file location is specified in the FORMS_PATH environment variable.
    For example, in Windows, if your .fmx file is located in d:\my_files\applications, in the FORMS_PATH, include d:\my_files\applications. On Windows, use semi-colons to separate directory locations if specifying multiple locations. On UNIX/Linux, use colons for separators. Specify this information in the Environment Configuration page for the environment file.
  4. To modify an environment file, select the file in the Environment Configuration page of Fusion Middleware Control and add or edit environment variables as needed by your application. For example, you can add the environment variable shown in Table 3-2.
    Table 3-2 Example of Environment Variable Values
    Environment Variable NameEnvironment Variable Value
    If you specified these environment variables in an environment file, specify this environment file in the respective configuration section of the formsweb.cfg in theWeb Configuration page.
  5. Enter the name of your application in the URL as shown:
    where "example" is the name of your computer and "8888" is the port used by your HTTP Listener.
    Once you have created a configuration section, add "config=" and the name of the configuration section. In this example, the URL to access hrapp.fmx is:

3.3.2 Specifying Parameters

There are two ways to predefine parameter values for your Oracle Forms Services applications. You can define parameters by:
  • Editing your application settings in the default section of the Web Configuration page of Fusion Middleware Control. The default configuration section displays the default values that are used by Oracle Forms Services.
  • Managing (adding, editing, copying, deleting) other system and user parameter values in the named application configuration section (see Section 3.3.3, "Creating Configuration Sections in Fusion Middleware Control"). For example, in the configuration section you create for myApp, you can add or change these parameters and their values, as shown in Table 3-3.
    Table 3-3 Example Configuration Section: Parameter Values for myApp
    Parameter NameParameter Value
Parameters specified in the named configuration section of a Web Configuration override the settings in the default section.
System Parameters cannot be overridden in the URL, while user parameters can.

3.3.3 Creating Configuration Sections in Fusion Middleware Control

Under the configuration sections you created in step 2 of Section 3.3.1, "Deploying Your Application", you can specify parameters for your Oracle Forms Services applications. You can specify any application and system parameters that are available in the default section for Web Configuration page.
For example, you can set the look and feel of the application to the Oracle look and feel by setting the lookAndFeel parameter to the value of oracle and clicking Apply.
You can also override the default parameter values in the named configuration section. For example, to predefine the connect information of an application toscott/tiger@orcl, the parameter value for userid must be set in the named configuration section by changing the parameter value of userid to scott/tiger@orcl.
For other parameters that you can edit, see Chapter 4, "Forms Configuration Parameters." Editing the URL to Access Oracle Forms Services Applications

You can directly type parameters in the URL that accesses your Oracle Forms Services application. Using the previous example, instead of specifying the form parameter in your configuration file, you could also type it into the URL as follows:

You can use the ampersand (&) to call a combination of a form and named configuration parameters. In the above example, you are calling the form "hrapp" with the parameter settings you specified in "my_application".
Parameters specified in the URL override the parameters set in the configuration section. See Chapter 4, "Managing URL Security for Applications" for more information.

3.3.4 Specifying Special Characters in Values of Runform Parameters

Certain considerations apply if values passed to runform parameters contain special characters. This section describes these considerations, and compares the default behavior in this release with the behavior in prior releases.
Runform parameters are those that are specified in the serverArgs applet parameter of the template HTML file. The value specified for the serverArgs parameter in the template HTML file, after variable substitution, is sometimes referred to as the command-line parameters string. It consists of a series of blank-separated name=value pairs. The name must consist solely of alphanumeric or underscore characters. The value portion of a name=value pair can be an arbitrary string. Default Behavior in the Current Release

The value of a runform parameter can be specified in one of three places:
  1. In the value of the serverArgs parameter in the template HTML file (for example, base.htm).
  2. In the value of a variable specified in the configuration file (for example, formsweb.cfg), which is substituted (directly or recursively) for a variable reference in (1). Such values are typically maintained using Fusion Middleware Control; see Chapter 4, "Configuring Forms Services."
  3. As an attribute value in a URL, which is substituted directly for a variable reference in (1) or (2).
For case (3), URL syntax rules (as enforced by the browser and the application server) require that certain characters be entered as URL escape sequences ('%' followed by 2 hexadecimal digits representing the ASCII value of the character, for a total of three characters).
This requirement includes the % character itself (which must be entered as %25). In addition, Oracle Forms Services currently requires that the quote character ('"') be entered as %22, even if the browser and the application server allow a quote to be entered without escaping.
URL syntax rules also allow a space to be entered as a + (as an alternative to the URL escape sequence %20). However in the value of the otherparams configuration parameter, a + is treated specially; it separates name=value pairs as opposed to indicating a space embedded in the value of a runform parameter.
For example, if a runform application has user parameters param1 and param2, and you want to assign them the values 'a b' and 'c d', you do so by incorporating the following into a URL:
When specifying runform parameters in the template HTML files or in the configuration files (cases (1) and (2)), Forms requires URL escape sequences in some circumstances, allows them in others, and forbids them in still others.
Outside of the values of runform parameters, URL escape sequences must not be used. For example, the = in a name=value pair must always be specified simply as =, and the space that separates two adjacent name=value pairs must always be specified simply as " " (a single space character).
Within the value of a runform parameter, space (' ') must be specified as a URL escape sequence (%20). The HTML delimiter character (specified in the configuration file) must also be specified as a URL escape sequence. And when the runform parameter is specified in the template HTML file (case (1)), quote ('"') must also be specified as a URL escape sequence (%22).
Any other 7-bit ASCII character may also be specified as a URL escape sequence, although this is not required (except possibly for %, as noted below). Certain additional restrictions apply to the % character. These include:
  • If the HTML delimiter is % (the default), then an occurrence of % within the value of a runform parameter must be escaped (specified as %25). (This actually follows from the requirement stated above, that the HTML delimiter character be escaped). Furthermore, variable names must never begin with two hexadecimal digits that represent a 7-bit ASCII value (that is, two hexadecimal digits, the first of which is in the range 0-7).
  • If the HTML delimiter is not %, then an occurrence of % must be escaped if it is immediately followed by an octal digit and then a hexadecimal digit. It is recommended that other occurrences of '%' also be escaped; but this is not a requirement.
(You might choose to ignore this recommendation if you have existing template HTML files or configuration files created in prior releases, which use an HTML delimiter other than '%', and which contain '%' in runform parameter values). Behavior in Previous Releases

Release 9.0.4 and later behave the same as the current release except that a quote must be escaped (%22) within the value of a runform parameter in a configuration file, and in the template HTML file.
Releases before 9.0.4 did not allow URL escape sequences in runform parameter values specified in the template HTML file or the configuration file (cases (1) and (2) above). In all three cases, it was difficult or impossible to specify certain special characters, notably space, quote, and apostrophe. Also, certain transformations were applied to the parameter value before passing it to runform. Most notably, if a value began and ended with an apostrophe, these were typically stripped off. However, these transformations were not well-defined, and they differed between the Web and client/server environments. Obtaining the Behavior of Prior Releases in the Current Release

If your applications are dependent on the behavior of prior releases, you can obtain that behavior in the current release, by simply setting the value of the escapeparamsvariable to False in the configuration file (this can be accomplished using Fusion Middleware Control).
If you want to obtain the old behavior only for selected applications, you can specify different values for the escapeparams variable in different configuration sections. Applications that require the old behavior can specify a configuration section in which the escapeparams variable is set to False; applications that require (or tolerate) the behavior in the current release can specify a configuration section in which the escapeparams variable is set to True. Considerations for Template HTML Files

If you are creating your own template HTML files, then bear in mind the following:
It is recommended that a reference to the escapeparams variable (the string %escapeparams%, if '%' is the HTML delimiter character) appear at the beginning of the value of the serverArgs applet parameter, followed by a space. See the shipped base.htm file for an example.
References to the escapeparams variable must appear nowhere else in the template HTML file. If you choose to enclose the value of the serverArgs applet parameter in apostrophes instead of quotes, then within the value of a runform parameter in your template HTML file, apostrophes must be escaped (%27). Quotes do not require escape sequences.
It is permissible to omit the reference to the escapeparams variable from the beginning of the value of the serverArgs applet parameter. This results in the behavior of prior releases, regardless of the value specified in the configuration file for the escapeparams variable. Considerations for Static HTML Pages

If you are invoking the runform engine using static HTML, and you want to obtain the behavior in the current release, then you must take certain steps.
The basic rule is that your static HTML must look like the HTML generated by the Forms servlet. Specifically, the value of the serverArgs applet parameter must begin with the string escapeparams=true (case-insensitive).
Also, in the value portion of each name=value pair, in the value of the serverArgs applet parameter, certain characters must be specified by a URL escape sequence, as listed in Table 3-4:
Table 3-4 URL Escape Sequences for Static HTML pages
Characters that must be escapedURL Escape Sequence
newline ' \n '%0a
space ' '%20
quote ' " '%22
percent ' % '%25
apostrophe ' ' '%27
left parenthesis ' ( '%28
right parenthesis ' ) '%29
It is also permissible to escape other 7-bit ASCII characters in the value portion of a name=value pair.
Here's an example of what the serverArgs applet parameter might look like in static HTML. This is for a form named "my form" (quotes not included), which is being passed the value "foo'bar" (quotes again not included) to the user-defined parameter named myparam.
<PARAM NAME="serverArgs" VALUE="escapeparams=true module=my%20form userid=scott/tiger@mydb myparam=foo%27bar">

3.3.5 Accessing the Listener Servlet Administration Page

You can display a test page for the Listener Servlet by accessing the following URL:
The information displayed depends on the value of the initialization parameter TestMode. This parameter is set in the$DOMAIN_HOME/servers/WLS_FORMS/tmp/_WL_user/formsapp_11.1.1/<random_string>/war/WEB-INF /web.xml file. An example is shown below:

<!-- Display sensitive options on the /admin page ? -->




3.4 Client Browser Support

Users can view Oracle Forms applications on the Web using Sun's Java Plug-in. In future patch releases other virtual machines may be supported.
For more information about client browser support, including the latest supported platforms, go to the Forms Developer menu and choose Help | Forms on OTN... to locate the Client Platform Statement of Direction.

3.4.1 How Configuration Parameters and BaseHTML Files are Tied to Client Browsers

When a user starts a Web-enabled application (by clicking a link to the application's URL), the Forms servlet:
  1. Detects which browser is being used.
  2. Selects the appropriate baseHTML file using Table 3-5:
    Table 3-5 baseHTML file descriptions
    Detected BrowserBase HTML file used
    Internet Explorerbasejpi.htm
    Mozilla FireFox 3.0basejpi.htm
    All other browsers and Macintosh clientsbase.htm
  3. Replaces variables (%variablename%) in the baseHTML file with the appropriate parameter values specified in the Forms servlet.initArgs file, formsweb.cfg file, and from query parameters in the URL request (if any).
  4. Sends the HTML file to the user's browser.

3.4.2 Forms Single Sign-On on Mozilla 3.x

Ensure that you have enabled cookies from Oracle site when using Forms and Single Sign-On on Mozilla 3.x. To enable the cookies, perform the following steps:
  1. Open Mozilla Firefox, select Tools.
  2. Select Options and then Privacy.
  3. Select the Accept Cookies from site box.
    These steps are not required for other browsers.
    For more information on default browser settings in Mozilla, refer to http://www.mozilla.com.

No comments:

Post a Comment