3 Basics of Deploying Oracle Forms Applications

3.2.1.1 default.env

Location: forms/server

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

3.2.1.2 formsweb.cfg

Location: forms/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 Console.

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

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

Location: forms/server.

The baseHTML files (base.htm, basejini.htm, and basejpi.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 C, "base.htm, basejini.htm, and basejpi.htm Files".

3.2.1.4 ftrace.cfg

Location: forms/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 Console.

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

3.2.2.1 web.xml

Location: j2ee/OC4J_BI_FORMS/applications/formsapp/formsweb/WEB-INF/web.xml.

Once Forms Services has been installed and configured, the web.xml file is located in the directory j2ee/OC4J_BI_FORMS/applications/formsapp/formsweb/WEB-INF in ORACLE_HOME. It defines the aliases frmservlet and lservlet for the Forms Servlet and the Forms Listener Servlet.

For more information about web.xml, see Appendix C, "web.xml".

3.2.2.2 Directory structure for Oracle Forms OC4J files

During Oracle Application Server installation and configuration, the Forms EAR file (formsapp.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/formsapp 

+META-INF 

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

+formsweb 

+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 
       -frmsrv.jar (contains the Forms Servlet and Listener Servlet code)

3.2.3.1 forms.conf

Location: forms/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). forms.conf defines virtual directories (aliases) and servlet mount points to map URL requests to the Forms Servlets running in the OC4J servlet engine.

For more information about forms.conf, see Appendix C, "forms.conf".

3.2.4.1 Registry.dat

Location: forms/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 Appendix C, "Registry.dat".

3.2.5.1 Default webutil.cfg

Location: 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 more information, see Appendix C, "Default webutil.cfg".

3.2.5.2 Default webutilbase.htm

Location: forms/server.

This is the default base HTML 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 more information, see Appendix C, "Default webutilbase.htm".

3.2.5.3 Default webutiljini.htm

Location: forms/server.

This is the HTML template file for running a form on the Web using JInitiator-style tags to include the Forms applet with a certificate registration for WebUtil.

For more information, see Appendix C, "Default webutiljini.htm".

3.2.5.4 Default webutiljpi.htm

Location: forms/server.

This is the default base HTML file for running a form on the Web using the JDK Java Plugin. This is used for example when running a form on the Web with Netscape on Solaris and a certificate registration for WebUtil.

For more information, see Appendix C, "Default webutiljpi.htm".

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://mycomputer.com:7777/forms/frmservlet?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://mycomputer.com:7777/forms/frmservlet?config=myapp&form=hrapp

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

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 Console; 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 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:

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">