3
Basics of Deploying Oracle Forms Applications

3.1 Introduction

This chapter describes the basic files you need to configure Oracle Forms, provides an overview of how Forms Services run in Oracle Application Server, and describes the steps you need to follow to deploy Forms applications. After installation is complete, 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:

• Configuration Files

• Application Deployment

• OracleAS Forms Services in Action

• Client Browser Support

3.2 Configuration Files

This section introduces the basic files you need to configure Forms applications. For more advanced configuration topics, see Chapter 4, "Configuring Forms Services with Enterprise Manager".

This section contains the following sub-sections:

• Oracle Forms Configuration Files

• Oracle Application Server Containers for J2EE (OC4J) Configuration Files

• Oracle HTTP Listener Configuration Files

• Standard Fonts and Icons File

Note: Location of files are given relative to the <ORACLE_HOME> directory. Forward slashes should be replaced by back slashes on Windows.

3.2.1 Oracle Forms Configuration Files

Oracle Forms configuration files allow you to specify parameters for your Forms, which you manage through the Application Server Control. This section contains the following sub-sections:

• default.env

• formsweb.cfg

• base.htm, basejini.htm, basejpi.htm, and baseie.htm

• ftrace.cfg

Note: If you manually edit any of the configuration or environment files, you'll need to restart Enterprise Manager so that Enterprise Manager can read all changes. If you do not restart Enterprise Manager, any changes that you make through Enterprise Manager will overwrite any manual changes you've made to these files.

3.2.1.1 default.env

Location: forms90/server

This file contains environment settings for Forms runtime and can be found in the <ORACLE_HOME>/forms90/server directory. On UNIX, default.env should include the PATH and LD_LIBRARY_PATH.

3.2.1.2 formsweb.cfg

Location: forms90/server.

This is the Forms Servlet configuration file that contains the following:

• Values for Forms runtime command line parameters, as well as 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 baseHTML file are replaced with the appropriate parameter values specified in the formsweb.cfg file and from query parameters in the URL request (if any).

You manage the formsweb.cfg file through Enterprise Manager Application Server Control.

For more information about formsweb.cfg, see, Chapter 4.3.1, "Configuring Parameters with Application Server Control".

3.2.1.3 base.htm, basejini.htm, basejpi.htm, and baseie.htm

Location: forms90/server.

The baseHTML files (base.htm, basejini.htm, basejpi.htm, and baseie.htm) are used as templates by the Forms Servlet when generating the HTML page used to start up an Oracle Forms application.

We recommend that you make configuration changes in the formsweb.cfg file and avoid editing the baseHTML files. If you need to change the baseHTML files, create your own versions and reference them from the formsweb.cfg file by changing the appropriate settings.

For a look at a sample baseHTML files, see Appendix B.3, "base.htm, basejini.htm, basejpi.htm, and baseie.htm Files".

3.2.1.4 ftrace.cfg

Location: forms90/server.

This file allows you to configure Forms Trace. Forms Trace allows you to replace 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 allows you to trace the execution path through a form (for example, steps the user took while using the form).

You manage Forms Trace through Enterprise Manager Application Server Control.

For more information about ftrace.cfg, see Chapter 7, "Tracing and Diagnostics".

3.2.2 Oracle Application Server Containers for J2EE (OC4J) Configuration Files

By default Forms Services is configured for OC4J by deploying it as a J2EE compliant application packaged in an EAR (Enterprise Archive) file called forms90app.ear. This EAR file is deployed during the Oracle Application Server installation process (if you choose to configure Oracle Forms). During deployment, the EAR file is unpacked into the applications directory of the OC4J instance.

This section describes:

• web.xml

• Directory structure for Oracle Forms OC4J files

3.2.2.1 web.xml

Location: j2ee/OC4J_BI_FORMS/applications/forms90app/forms90web/WEB-INF/web.xml.

Once Oracle Application Server Forms Services has been installed and configured, the web.xml file is located in the directory j2ee/OC4J_BI_FORMS/applications/forms90app/forms90web/WEB-INF underneath <ORACLE_HOME>. It defines the aliases "f90servlet" and "l90servlet" for the Forms Servlet and the Forms Listener Servlet.

For more information about web.xml, see Chapter B.4, "web.xml".

3.2.2.2 Directory structure for Oracle Forms OC4J files

During Oracle Application Server installation and configuration, the Forms EAR file (forms90app.ear) is deployed to the "OC4J_BI_FORMS" OC4J instance. This results in the following directory structure.

Names with a + sign are directories:

<ORACLE_HOME>/j2ee/OC4J_BI_FORMS/applications/forms90app 

+META-INF 


-application.xml (defines the structure of the ear file)


+forms90web 


+WEB-INF 


-web.xml (forms & listener servlet definitions, including servlet 
parameters) 
-orion-web.xml (virtual directory mappings and context parameter, 
only used in iDS) 
+lib 
       -f90srv.jar (contains the Forms Servlet and Listener Servlet 
code)

3.2.3 Oracle HTTP Listener Configuration Files

This section describes the file used to configure Oracle HTTP Listener for Oracle Application Server Forms Services.

3.2.3.1 forms90.conf

Location: forms90/server.

This is the Oracle HTTP listener configuration file for Oracle Application Server Forms Services. It is included into oracle_apache.conf, which in turn is included into httpd.conf (the master HTTP listener configuration file). Forms90.conf defines virtual directors (aliases) and servlet mount points to map URL requests to the Forms Servlets running in the OC4J servlet engine.

For more information about forms90.conf, see Chapter B.5, "forms90.conf".

3.2.4 Standard Fonts and Icons File

This section describes the file used to configure font and icon settings for Oracle Application Server Forms Services.

3.2.4.1 Registry.dat

Location: forms90/java/oracle/forms/registry

This file allows you to change the default font, font mappings, and icons that Forms Services uses.

For more information about Registry.dat, see Chapter B.6, "Registry.dat".

3.3 Application Deployment

Once you have created your application in Forms Developer, you are ready for application Web deployment. Oracle Application Server Forms Services accesses an application in Oracle Application Server through a specified URL. The URL then accesses the HTTP Listener, which communicates with the Listener Servlet. The Listener Servlet starts up a new Forms runtime process (ifweb90.exe on Windows or f90webm on Solaris) for each new Oracle Application Server Forms Services session.

For more information about how Forms Services run, see OracleAS 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.

   .fmb is a design time file that can only be opened in Forms Developer. .fmx is the runtime file created when you compile the .fmb and is used for Web deployment.

   For more information about Forms Developer, go to the Help menu in Forms Developer

2. Create a configuration section in the Forms Web Configuration page of Oracle Enterprise Manager Application Server Control so that Oracle Application Server Forms Services can access your application module.
   The following table shows you what you would need to configure for an application called "application" with a form module called "form=hrapp.fmx":
   

   Table 3-1 Example New Configuration Section Parameter Values

   Configuration Section Name	Application Name	Forms Module Name Value
   my_application	application	hrapp.fmx

   
   When configured, the Oracle Application Server Forms Services module hrapp.fmx will be accessible on the Web by entering "...?config=my_application" in the Browser URL (the name of the Forms Web Configuration section in formsweb.cfg).

   Note: You can name the configuration section anything you want, as long as it does not include spaces.

3. Make sure the .fmx file location is specified in the FORMS90_PATH environment variable. For example, if your .fmx file is located in d:\my_files\applications, in the FORMS90_PATH you would include d:\my_files\applications (separated by semi-colons if listing more than one location). You specify this information in the Forms Edit Environment File page for that environment file.

To modify an environment file, select it in the Environment page of Enterprise Manager and add or edit environment variables as needed by your application. For example, you'd add the following environment variables for the previous example:

Table 3-2 Example New Environment Variable Values

Environment Variable Name	Environment Variable Value
form	hrapp.fmx

If you specified these environment variables in a new environment file, you will need to specify this environment file in the respective Forms Web configuration section.

Enter the name of your application into the following URL:

http://mymachine.com:7777/forms90/f90servlet?

where "mymachine" is the name of your machine and "7777" is the port used by your HTTP Listener.

Since you create a configuration section, you will need to add "config=" and the name of the configuration section. So, using the example in step 2, the URL to access hrapp.fmx would be:

http://mymachine.com:7777/forms90/f90servlet?config=application

3.3.2 Specifying Parameters

There are three ways to predefine parameter values for your Oracle Application Server Forms Services applications. You can define parameters by:

• Editing your application settings in the default section of the Forms Web Configuration page of Enterprise Manager Application Server Control.

  The default configuration section displays the default values that will be used by Oracle Application Server Forms Services.

  For example, the default value of the system parameter that specifies how to execute the Forms applet under Microsoft Internet Explorer 5.x or above is defined as follows:

  IE=JInitiator
  

  If you want the Forms applet to run in the browser's native JVM, edit the parameter in the IE Value column to read:

  native
  

  and click Apply.

• You can manage (add, edit, delete) other system and user parameter values in the named application configuration section (see "Creating configuration sections in Enterprise Manager"). For example, in the configuration section you create for my_application, you can add or change these parameters and their values:

  Table 3-3 Example Configuration Section Parameter Values for my_application

  Parameter Name	Parameter Value
  baseHTML	mybase.htm
  baseHTMLjinitiator	mybasejini.htm
  baseHTMLjpi	mybasejpi.htm
  baseHTMLie	mybaseie.htm
  form	myapp.fmx
  userid

• Override system parameter settings if your application requires modifications to the underlying HTML templates or another value set for the Internet Explorer virtual machine. Change the system parameter setting only if the modification must be adopted by all applications run by the server.

  Note: System Parameters cannot be overridden in the URL, while User Parameters can.

3.3.3 Creating configuration sections in Enterprise Manager

Under the configuration sections you created in step 2 of Deploying Your Application, you can specify parameters for your Oracle Application Server Forms Services applications. You can specify any application and system parameters that are available in the default section for Forms Web configuration.

For example, you can make the look and feel of the application to be 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 to scott/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 you can edit, see "Default Forms Configuration Parameters".

Note: Parameters specified in the configuration section will override your application default settings.

3.3.3.1 Editing the URL to access Oracle Application Server Forms Services applications

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

http://mymachine.com:7777/forms90/f90servlet?config=hr&pageTitle="My Company"

You can use the ampersand (&) to call a combination of a form and named configuration parameters. For example, in the following URL:

http://mymachine.com:7777/forms90/f90servlet?config=ienative&form=hrapp

you are calling the form "hrapp" with the parameter settings you specified in "ienative".

Note: Parameters specified in the URL will override parameters set in the configuration section. See Chapter 4.6, "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.

Note: 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.

3.3.4.1 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 (e.g. base.htm).

2. In the value of a variable specified in the configuration file (e.g. formsweb.cfg), which is substituted (directly or recursively) for a variable reference in (1). Such values are typically maintained using Application Server Control; see Chapter 4.3, "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 hex 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 Application Server 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 wish to assign them the values `a b' and `c d', you do so by incorporating the following into a URL:

&otherparams=param1=a%20b+param2=c%20d

When specifying runform parameters in the template HTML files of 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 (' ') and quote ('"') must be specified as a URL escape sequence (%20 and %22, respectively). The HTML delimiter character (specified in the configuration file) must also be specified as a URL escape sequence.

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.

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 hex digits that represent a 7-bit ASCII value.

Put another way, variable names must never begin with two hex digits, the first of which is in the range 0-7. Put still another way, variable names must never begin with an octal digit followed by a hex digit.

If the HTML delimiter is not %, then an occurrence of % must be escaped if it's immediately followed by an octal digit and then a hex 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).

3.3.4.2 Behavior in previous releases

Prior releases 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 3 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.

3.3.4.3 Obtaining the behavior of prior releases in the current release

If your applications are counting on the behavior of prior releases, you can obtain that behavior in the current release, by simply setting the value of the escapeparams variable to False in the configuration file (this can be accomplished using Enterprise Manager).

If you wish 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 will tolerate) the new behavior can specify a configuration section in which the escapeparams variable is set to True.

3.3.4.4 Considerations for template HTML files

If you are creating your own template HTML files (or modifying existing ones, such as base.htm), 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.

It is permissible to omit the reference to the escapeparams variable from the beginning of the value of the serverArgs applet parameter, but then you will always obtain the behavior of prior releases, regardless of the value specified in the configuration file for the escapeparams variable.

3.3.4.5 Considerations for static HTML pages

If you are invoking the runform engine using static HTML, and you wish to obtain the new behavior, 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

Character that must be escaped	URL 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.4 OracleAS Forms Services in Action

This sections describes how Forms Services run in OracleAS, and how the configuration files are used, assuming that the Forms Servlet is used to generate the initial HTML page. For simplicity, we assume the Web server is running on port 7777 on a machine called "mymachine.com". We also assume no modifications have been made to the standard configuration created during the Oracle Application Server installation process.

When a user runs an Oracle Application Server Forms Services application, the following sequence of events occurs:

1. The user starts up their Web browser and goes to a URL like the following:

   http://mymachine.com:7777/forms90/f90servlet?config=ienative&form=hrapp
   

   In this case, the (top level) form module to be run is called "hrapp" using the configuration section called "ienative"

2. Oracle HTTP Server listener receives the request. It forwards the request to OC4J, since the path /forms90/f90servlet matches one of the OC4J mount directives in the forms90.conf file (the one for the Forms Servlet).

3. OC4J maps the request to the Oracle Application Server Forms Services application (whose context root is /forms90). It maps the request to the Forms Servlet (using the f90servlet servlet mapping specified in the web.xml file).

4. The Forms Servlet (running in OC4J) processes the request as follows:
   • Opens the servlet configuration file (formsweb.cfg by default). If that parameter is not set, the default configuration file (<ORACLE_HOME>/forms90/server/formsweb.cfg) is used.

   • Determines which configuration section to use in the formsweb.cfg file. Since the URL contains the query parameter "config=ienative", the [ienative] section will be used.

   • Determines which baseHTML file to use, based on (a) what browser made the request, (b) what platform the browser is running on, and (c) the settings of various parameters in the formsweb.cfg file (specifically, baseHTMLie, baseHTMLjinitiator, baseHTMLjpi, baseHTML, and IE).

   • Reads the baseHTML file, and sends the contents back as an HTML page to the user's Web browser, after doing variable substutions 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.

     For example, the baseHTML file contains the text %form%. In our example, this is replaced with the value "hrapp".

5. Depending on which baseHTML file the Forms Servlet selected, the HTML page sent back to the Web browser will contain an Applet, Object or Embed tag to start up the Forms applet (thin client). The Forms applet runs in a JVM (either the Web browser's native JVM, or a "plugged in" JVM like Oracle JInitiator or Sun's Java plug-in).

6. If the baseHTML file selected was for a plug-in (Oracle JInitiator or Sun's JDK Java plug-in), and if the user does not already have that plug-in installed on their machine, they are prompted to install the plug-in. In the case of JInitiator, the download location is under the virtual path /forms90/jinitiator (a virtual path defined in the forms90.conf file).

7. In order to start up the Forms applet, its Java code must first be loaded. The location of the applet is specified by the applet codebase and archive parameters. For example, if the user is running with Oracle JInitiator, the applet code is loaded from the file http://mymachine.com:7777/forms90/java/f90all_jinit.jar

   The virtual path definition in the forms90.conf file for "/forms90/java" allows the applet code to be loaded from the Web server.

   Note: The Forms applet code (for example, f90all_jinit.jar) is only to be loaded over the network the first time the user runs an Oracle Application Server Forms Services application (or if a newer version of Oracle Application Server Forms Services is installed on the Web server). Otherwise, it is to be loaded from the Web browser's (or the Java plug-in's) cache on the local disk.

8. Once the Oracle Application Server Forms Services applet is running, it starts up a Forms session by contacting the Forms Listener Servlet at URL http://mymachine.com:7777/forms90/l90servlet.

9. The Oracle HTTP Server listener receives the request. It forwards the request to OC4J, since the path "/forms90/l90servlet" matches one of the OC4J mount directives in the forms90.conf file (the one for the Forms Listener Servlet).

10. The Forms Listener Servlet (l90servlet) starts up a Forms runtime process (ifweb90.exe or f90webm) for the Forms session.

11. Communication continues between the Forms applet (running in the user's Web browser) and the Forms runtime process, via the Listener Servlet, until the Forms session ends.

12. The command line (such as giving the name of the form to run) is passed to the Forms runtime process. It is given as the applet parameter "serverArgs". Part of the serverArgs value in the baseHTML file was %form%, which was replaced by "hrapp". Therefore the runtime process actually runs the form in the file "hrapp.fmx".

    This file must either be present in the workingDirectory (which is specified in the Forms Web Configuration page of Application Server Control), or in one of the directories named in the FORMS90_PATH environment setting, which is defined in the environment file (default.env by default). You can also specify the directory in the Forms Web Configuration page (for example, form=c:\<path>\myform).

13. The Forms sessions end when one of the following occurs:
    • The top level form is exited (for example, by PL/SQL trigger code which calls the "exit_form" built-in function). In this case, the user is prompted to save changes if there are unsaved changes. exit_form(no_validate) exits the form without prompting.

    • The user quits their Web browser. In this case, any pending updates are lost.

3.5 Client Browser Support

Users can view Oracle Forms applications on the Web using Oracle JInitiator plug-in (using Netscape Navigator or Internet Explorer). In future patch releases other virtual machines will 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...

3.5.1 Oracle JInitiator

Oracle JInitiator runs within a Web browser and is based on Sun's JDK/JRE 1.3. It provides the ability to specify a specific Java Virtual Machine (JVM) on the client rather than using the browser's (native) default JVM. Oracle JInitiator does not replace or modify the default JVM provided by the browser. Rather, it provides an alternative JVM in the form of a plug-in for Netscape Navigator and as an ActiveX component for Internet Explorer.

Oracle provides two JAR files (f90all.jar and f90all_jinit.jar) that group and zip classes together for efficient delivery across the network to the client. f90all_jinit.jar is an extra-compressed JAR file that can be used only with Oracle JInitiator to provide increased performance at download time. Once on the client, the files are cached for future use.

For more information about Oracle JInitiator, see Appendix A, "JInitiator".

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

When an 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. Reads the formsweb.cfg file to determine the Internet Explorer parameter setting if the user is using Internet Explorer 5.5 or higher;

3. Selects the appropriate baseHTML file using the following table:

   Browser detected	IE parameter setting	Base HTML file used
   Internet Explorer 5.x or 6*	native VM**	baseie.htm
   Internet Explorer 5.x or 6*	jinitiator	basejini.htm
   Netscape Navigator or Internet Explorer version preceding version 5	not applicable	basejini.htm
   All other browsers	not applicable	base.htm

* Internet Explorer 6 that has been upgraded from 5.5 only (IE 6 is not certified in the base release)

** Internet Explorer running on Windows with the Microsoft Native VM.

4. 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).

5. Sends the HTML file to the user's browser.