Skip Headers

Oracle® Application Server Forms Services Deployment Guide 10g Release 2 (10.1.2) B14032-03 |
| Library | Product | Contents | Index

Previous | Next |

# 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 (frmweb.exe on Windows or frmweb.sh on Solaris) for each new Forms Services session.

For more information about how Forms Services run, see Section 3.1, "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 10g Application Server Control Console so that Oracle Application Server Forms Services can access your application module.

   Table 3-1 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 FORMS_PATH environment variable. For example, if your .fmx file is located in `d:\my_files\applications`, in the `FORMS_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.

4. 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, as shown in Table 3-2:

   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.

5. Enter the name of your application into the following URL:

   `http://mycomputer.com:7777/forms/frmservlet?`

   where "mycomputer" is the name of your computer and "7777" is the port used by your HTTP Listener.

   Once you've created 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://mycomputer.com:7777/forms/frmservlet?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 Console.

  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 Section 3.3.3, "Creating Configuration Sections in Enterprise Manager"). 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 Name | Parameter Value
  --- | ---
  baseHTML | mybase.htm
  baseHTMLjinitiator | mybasejini.htm
  baseHTMLjpi | mybasejpi.htm
  form | myapp.fmx
  userid |

Note: Parameters specified in the named configuration section of a Forms Web configuration will override the system parameter settings.

- 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 Section 3.3.1, "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 Chapter 4, "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://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".

Note: Parameters specified in the URL will override 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.

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 t o 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 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:

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