8.3 Oracle Reports Servlet Configuration File

The configuration settings for the Oracle Reports Servlet (rwservlet) component of Oracle Reports Services are stored in the XML file rwservlet.properties, located in the directory specified in Table 8-1.

For Windows, note that rwservlet.properties uses double backslashes (\\) instead of single backslashes to specify a directory path. The first slash "escapes" the second, which would otherwise have another meaning in this file. For example, in a Windows-based rwservlet.properties file, the path:

d:\InstanceHome\config\ReportsServerComponent\ServerName\filename.ext

becomes:

d:\\InstanceHome\\config\\ReportsServerComponent\\ServerName\\filename.ext

For UNIX, use that platform's standard for specifying directory paths, for example:

InstanceHome/config/ReportsServerComponent/ServerName/filename.ext

8.3.1 Oracle Reports Servlet Configuration Elements

The rwservlet.xsd file provides the following data type definitions for configuring rwservlet.properties elements:

These elements along with their related attributes and sub-elements are discussed in the following subsections.

Note that these are XML elements, and XML is case-sensitive. Additionally, when you add any of these elements to the rwservlet.properties configuration file, you must follow the order of elements as described in rwservlet.xsd.

8.3.1.1 rwservlet

The rwservlet element is defined in rwservlet.xsd as follows:

<xs:element name="rwservlet">
  <xs:complexType>
   <xs:sequence>
      <xs:element name="server" type="xs:string" minOccurs="0" maxOccurs="1"/>
      <xs:element name="singlesignon" type="xs:string" minOccurs="0" maxOccurs="1"/>
      <xs:element name="inprocess" type="xs:string" minOccurs="0" maxOccurs="1"/>
      <xs:element name="reports_servermap" type="xs:string" minOccurs="0" maxOccurs="1"/>
      <xs:element ref="cookie" minOccurs="0" maxOccurs="1"/>
      <xs:element name="defaultcharset" type="xs:string" minOccurs="0" maxOccurs="1"/>
      <xs:element ref="webcommandaccess" minOccurs="0" maxOccurs="unbounded"/>
      <xs:element name="allowhtmltags" type="xs:string" minOccurs="0" maxOccurs="1"/>
      <xs:element name="helpurl" type="xs:string" minOccurs="0" maxOccurs="1"/>
      <xs:element name="imageurl" type="xs:string" minOccurs="0" maxOccurs="1"/>
      <xs:element name="reloadkeymap" type="xs:string" minOccurs="0" maxOccurs="1"/>
      <xs:element name="dbauth" type="xs:string" minOccurs="0" maxOccurs="1"/>
      <xs:element name="sysauth" type="xs:string" minOccurs="0" maxOccurs="1"/>
      <xs:element name="errortemplate" type="xs:string" minOccurs="0" maxOccurs="1"/>
      <xs:element ref="diagtags" minOccurs="0" maxOccurs="1"/>
      <xs:element ref="cluster" minOccurs="0" maxOccurs="1"/>
      <xs:element ref="oidconnection" minOccurs="0" maxOccurs="1"/>
      <xs:element name="allowauthid" type="xs:string" minOccurs="0" maxOccurs="1"/>
      <xs:element name="enabledbproxy" type="xs:string" minOccurs="0" maxOccurs="1"/>
    </xs:sequence>
  </xs:complexType>
</xs:element>

Example

In rwservlet.properties, the rwservlet element may be specified as shown in this example:

<rwservlet>
  one or more element specifications
</rwservlet>

Required/Optional

Required. You can have a maximum of one rwservlet element in a given configuration file.

Description

The rwservlet element opens and closes the content area of the Oracle Reports Servlet (rwservlet) configuration file. In terms of the file's hierarchy, all the other elements are subordinate to the rwservlet element.

The rwservlet element includes the following sub-elements in its definition:

8.3.1.1.1 server

The server sub-element of rwservlet is defined in rwservlet.xsd as follows:

<xs:element name="server" type="xs:string" minOccurs="0" maxOccurs="1"/>

Example

In rwservlet.properties, the server element may be specified as shown in this example:

<server>myserver</server>

Description

The server element specifies the name of the in-process server. If a Reports Server name is not specified, for example, in the runtime URL, rwservlet starts the in-process server (if not started already) with the name specified by the server element, and submits the job to it.

If the server element is not specified, the default in-process server name is: rep_hostname.

When the inprocess element specifies no, rwservlet tries to bind to an external server with the name specified by the server element.

8.3.1.1.2 singlesignon

The singlesignon sub-element of rwservlet is defined in rwservlet.xsd as follows:

<xs:element name="singlesignon" type="xs:string" minOccurs="0" maxOccurs="1"/>

Example

In rwservlet.properties, the singlesignon element may be specified as shown in this example:

<singlesignon>yes</singlesignon>

Description

The singlesignon element specifies whether or not OracleAS Single Sign-On is enabled:

  • yes (default): OracleAS Single Sign-On is enabled.

  • no: OracleAS Single Sign-On is not enabled.

For more information about OracleAS Single Sign-On, refer to Chapter 17, "Configuring and Administering OracleAS Single Sign-On".

8.3.1.1.3 inprocess

The inprocess sub-element of rwservlet is defined in rwservlet.xsd as follows:

<xs:element name="inprocess" type="xs:string" minOccurs="0" maxOccurs="1"/>

Example

In rwservlet.properties, the inprocess element may be specified as shown in this example:

<inprocess>yes</inprocess>

Description

The inprocess element specifies whether or not to run Reports Server within the same process as Oracle Reports Servlet (rwservlet):

  • yes (default): Reports Server run within the same process as Oracle Reports Servlet (rwservlet).

  • no: Reports Server does not within the same process as Oracle Reports Servlet (rwservlet).

Note:

The pros and cons of running an in-process server are explored in Chapter 2, "Understanding the Oracle Reports Services Architecture".

For troubleshooting printing and font issues when using the in-process server, see Section D.1.10, "Printing and Font Errors When Using In-process Reports Server".

8.3.1.1.4 reports_servermap

The reports_servermap sub-element of rwservlet is defined in rwservlet.xsd as follows:

<xs:element name="reports_servermap" type="xs:string" minOccurs="0" 
            maxOccurs="1"/>

Example

In rwservlet.properties, the reports_servermap element may be specified as shown in this example:

<reports_servermap>
  dev_cluster:dev_server;prd_cluster:prd_server;qa_cluster:qa_server
</reports_servermap>

Description

In Oracle Reports 10g Release 2 (10.1.2), Reports Server clustering was deprecated. An Oracle Forms Services application from prior releases that includes a Reports Server cluster name will fail to bind to the Reports Server cluster it references.

To resolve this issue, the reports_servermap element maps a cluster name to a Reports Server name. This avoids the necessity to change the cluster name in all Oracle Forms Services applications.

An Oracle Forms Services application can call Oracle Reports in the following ways:

  • Using RUN_REPORT_OBJECT. If the call specifies a Reports Server cluster name instead of a Reports Server name, the REPORTS_SERVERMAP environment variable must be set in the Oracle Forms Services default.env file.

    If your Oracle Forms Services application uses multiple Reports Server cluster names, you can map each of those cluster names to a different Reports Server using REPORTS_SERVERMAP, as follows:

    REPORTS_SERVERMAP=cluster1:repserver1;cluster2:repserver2;cluster3:repserver3
    

    For example, if your Oracle Forms Services application includes 3 clusters with names dev_cluster, prd_cluster, and qa_cluster in 10g Release 1 (9.0.4), you can map these cluster names to respective server names in later releases, as follows:

    REPORTS_SERVERMAP=dev_cluster:dev_server;prd_cluster:prd_server;qa_cluster:qa_server
    

    For more information, see the Oracle Fusion Middleware Forms Services Deployment Guide.

  • Using WEB.SHOW_DOCUMENT. In this case, the request is submitted to rwservlet. If the call specifies a Reports Server cluster name instead of a Reports Server name, the reports_servermap element must be set in the rwservlet.properties file. For example:

    <reports_servermap>
      cluster:repserver
    </reports_servermap>
    

    where

    cluster is the Reports Server cluster name that was present in prior releases (Oracle Reports 9i and 10g Release 1 (9.0.4)).

    repserver is the Reports Server name in later releases.

    When reports_servermap is set in rwservlet.properties, any request to cluster in the Oracle Forms Services application is redirected to repserver.

8.3.1.1.5 cookie

The cookie element is defined in rwservlet.xsd as follows:

<xs:element name="cookie">
  <xs:complexType>
    <xs:attribute name="cookieexpire" use="required" type="xs:integer"/>
    <xs:attribute name="encryptionkey" use="required" type="xs:string"/>
  </xs:complexType>
</xs:element>

Example

In rwservlet.properties, the cookie element may be specified as shown in this example:

<cookie cookieexpire="30" encryptionkey="reports"/>

Required/Optional

Optional.

Description

The cookie element specifies an expiration time and encryption key for cookies, which save encrypted user names and passwords on the client-side when users first authenticate themselves. When the server receives a cookie from the client, the server compares the time saved in the cookie with the current system time. If the time difference is longer than the number of minutes defined in cookieexpire, the server rejects the cookie and returns to the client the authentication form along with an error message. Users must re-authenticate to run the report.

The cookie element attributes are described in Table 8-26.

Table 8-26 Attributes of the cookie Element

Attribute Valid Values Description

cookieexpire

Integer

Default: 30

The lifetime (in minutes) of the database and system authentication cookie.

encryptionkey

any character string

The encryption key to be used to encrypt the user name and password of the database and system authentication cookies.


8.3.1.1.6 defaultcharset

The defaultcharset sub-element of rwservlet is defined in rwservlet.xsd as follows:

<xs:element name="defaultcharset" type="xs:string" minOccurs="0" maxOccurs="1"/>

Example

In rwservlet.properties, the defaultcharset property may be specified as shown in this example:

<defaultcharset>JA16EUC</defaultcharset>

Description

The defaultcharset element specifies the character encoding for decoding non-ASCII escaped characters in the request URL or non-ASCII characters in the Parameter Form input. This ensures that rwservlet uses the required encoding when decoding the parameter name and value.

You can set the defaultcharset element to either:

  • The database's NLS_CHARACTERSET (for example, JA16EUC).

  • The IANA-defined character set (for example, EUC-JP).

Note:

To use non-ASCII characters in user parameter names and values when using the Event-Driven Publishing API, you must ensure that the defaultcharset element in the rwservlet.properties file matches the value of the DEFAULTCHARSET parameter in your parameter list. For more information, see Section 21.1.3, "Including non-ASCII Characters in Parameter Names and Values".

8.3.1.1.7 webcommandaccess

The webcommandaccess element is defined in rwservlet.xsd as follows:

<xs:element name="webcommandaccess">
   <xs:simpleType>
    <xs:restriction base="xs:NMTOKEN">
        <xs:enumeration value="L0"/>
        <xs:enumeration value="L1"/>
        <xs:enumeration value="L2"/>
        <xs:enumeration value="NO"/>
        <xs:enumeration value="YES"/>
     </xs:restriction>
  </xs:simpleType>
</xs:element>

Example

In rwservlet.properties, the webcommandaccess property may be specified as shown in this example:

<webcommandaccess>L1</webcommandaccess>

Description

The webcommandaccess element specifies access permission for rwservlet keywords (Web commands) for a non-secure server.

Note:

For secure Reports Server, Reports Server verifies the user's privileges based on the entries in Oracle Internet Directory.

Valid settings are:

For L2 Web command access, you do not need to pass the authid. The authid parameter is required only for the STOPSERVER command irrespective of the webcommandaccess value.

8.3.1.1.8 allowhtmltags

The allowhtmltags sub-element of rwservlet is defined in rwservlet.xsd as follows:

<xs:element name="allowhtmltags" type="xs:string" minOccurs="0" maxOccurs="1"/>

Example

In rwservlet.properties, the allowhtmltags element may be specified as shown in this example:

<allowhtmltags>yes</allowhtmltags>

Description

The allowhtmltags element specifies whether or not to allow HTML code to be entered in the URL when running a report:

  • no (default): HTML code in the URL is disallowed.

  • yes: HTML code in the URL is allowed.

    Note:

    Any HTML code included as part of a report request URL might lead to a security compromise as it causes certain browsers to execute any script or code in the URL.

8.3.1.1.9 helpurl

The helpurl sub-element of rwservlet is defined in rwservlet.xsd as follows:

<xs:element name="helpurl" type="xs:string" minOccurs="0" maxOccurs="1"/>

Example

In rwservlet.properties, the helpurl element may be specified as shown in this example:

<helpurl>http://myserver/help_file/help_topic.htm</helpurl>

Description

The helpurl element specifies the name of a help file to be used instead of the default (ORACLE_HOME\reports\templates\help.htm).

The rwservlet HELP keyword (Web command) displays either the default help file, or the help file specified by the helpurl element.

Note:

For more about the HELP keyword, see Section A.6.12, "HELP".

8.3.1.1.10 imageurl

The imageurl sub-element of rwservlet is defined in rwservlet.xsd as follows:

<xs:element name="imageurl" type="xs:string" minOccurs="0" maxOccurs="1"/>

Example

In rwservlet.properties, the imageurl property may be specified as shown in this example:

<imageurl>http://machine_name:port/reports/rwservlet</imageurl>

Description

The imageurl element specifies the location of reports' dynamically generated images.

This element applies to JSPs that do not run through Oracle Reports Servlet (rwservlet). It ensures that dynamically generated images, such as charts, will be viewable only by the person who runs the report. JSPs, and other report types, that run through rwservlet automatically have this protection.

8.3.1.1.11 reloadkeymap

The reloadkeymap sub-element of rwservlet is defined in rwservlet.xsd as follows:

<xs:element name="reloadkeymap" type="xs:string" minOccurs="0" maxOccurs="1"/>

Example

In rwservlet.properties, the reloadkeymap element may be specified as shown in this example:

<reloadkeymap>yes</reloadkeymap>

Description

The reloadkeymap element specifies whether the key map file (cgicmd.dat) should be reloaded each time rwservlet receives a request:

  • no (default): Key map file is not reloaded when rwservlet receives a request.

  • yes: Key map file is reloaded when rwservlet receives a request.

This is useful if you frequently make changes to the map file and want the process of loading your changes to be automatic. Runtime performance will be affected according to how long it takes to reload the file.

Typically, this element specifies no in a production environment and yes in a testing environment.

8.3.1.1.12 dbauth

dbauth is the html template used to enter the database information. If the user does not enter the database information while giving reports request, the reports servlet challenges the user to enter the db info in the HTML template.

The dbauth sub-element of rwservlet is defined in rwservlet.xsd as follows:

<xs:element name="dbauth" type="xs:string" minOccurs="0" maxOccurs="1"/>

Example

In rwservlet.properties, the dbauth element may be specified as shown in this example:

<dbauth>rwdbauth.htm</dbauth>

It is not necessary to enter the path to a template when it is stored in the default template directory:

ORACLE_HOME\reports\templates

Description

The dbauth element specifies the location and filename of the HTML templates, if you wish to customize the login dialog boxes with your company logo, linked buttons, or any other HTML you care to use. By default, the file name is rwdbauth.htm.

8.3.1.1.13 sysauth

sysauth is the HTML template used to enter the authentication information.

The sysauth sub-element of rwservlet is defined in rwservlet.xsd as follows:

<xs:element name="sysauth" type="xs:string" minOccurs="0" maxOccurs="1"/>

Example

In rwservlet.properties, the sysauth element may be specified as shown in this example:

<sysauth>rwsysauth.htm</sysauth>

It is not necessary to enter the path to a template when it is stored in the default template directory:

ORACLE_HOME\reports\templates

Description

The sysauth element specifies the location and filename of the HTML templates, if you wish to customize login dialog boxes for a secure report with your company logo, linked buttons, or any other HTML you care to use. By default, the file name is rwsysauth.htm.

8.3.1.1.14 errortemplate

The errortemplate sub-element of rwservlet is defined in rwservlet.xsd as follows:

<xs:element name="errortemplate" type="xs:string" minOccurs="0" maxOccurs="1"/>

Example

In rwservlet.properties, the errortemplate element may be specified as shown in this example:

<errortemplate>rwerror.htm</errortemplate>

It is not necessary to enter the path to the error message template when it is stored in the default template directory:

ORACLE_HOME\reports\templates

Description

The errortemplate element specifies the name and location of your error message template. By default, the file name is rwerror.htm.

The error message template provides the visual setting within which the error message is displayed. You may wish to customize the appearance of error messages, for example with your company logo, or with an icon you plan to associate with errors. You may wish to add buttons that link your users to a help system, your company home page, or back to the last browser window. You can do this by using the errortemplate element to specify your own HTML framework for automatically generated error messages.

The character set of the default error message template (rwerror.htm) is iso-8859-1 to ensure consistency across all platforms.

8.3.1.1.15 diagtags

The diagtags element is defined in rwservlet.xsd as follows:

<xs:element name="diagtags">
  <xs:complexType>
    <xs:attribute name="diagbodytags" use="required" type="xs:string"/>
    <xs:attribute name="diagheadtags" use="required" type="xs:string"/>
  </xs:complexType>
</xs:element>

Required/Optional

Optional.

Description

The diagtags element specifies additional HTML encoding in the <body> and <head> tags in the output files associated with diagnostic and debugging output. You can use these to include formatting options to make diagnostic and debugging output easier to read.

The diagtags element attributes are described in Table 8-27.

Table 8-27 Attributes of the diagtags Element

Attribute Valid Values Description

diagbodytags

HTML code for <body> tag

HTML code to add between the <body> and </body> tags.

diagheadtags

HTML code for <head> tag

HTML code to add between the <head> and </head> tags.


8.3.1.1.16 cluster

Note:

For information about Oracle Fusion Middleware-level techniques for high availability, refer to Section 2.5, "Setting Up a High Availability Environment".

8.3.1.1.17 oidconnection

The oidconnection element is defined in rwservlet.xsd as follows:

<xs:element name="oidconnection">
  <xs:complexType>
    <xs:attribute name="oidcon_appentity" use="required" type="xs:string"/>
    <xs:attribute name="oidcon_passwdkey" use="required" type="xs:string"/>
    <xs:attribute name="oidcon_url" use="required" type="xs:string"/>
    <xs:attribute name="oidcon_init" type="xs:integer"/>
    <xs:attribute name="oidcon_increment" type="xs:integer"/>
    <xs:attribute name="oidcon_timeout">
        <xs:simpleType>
    <xs:restriction base="xs:integer">
        <xs:minInclusive value="1"/>
    </xs:restriction>
        </xs:simpleType>
    </xs:attribute>
  </xs:complexType>
</xs:element>

Example

In rwservlet.properties, the oidconnection element may be specified as shown in this example:

<oidconnection>
  oid_appentity="reportsapp.idc.oracle.com>
  oidcon_init="10" 
  oidcon_increment="10" 
  oidcon_timeout="1">
</oidconnection>

Description

The oidconnection element specifies Oracle Internet Directory for rwservlet.

For Reports Server, you can specify Oracle Internet Directory connection pooling parameters using the oidconnection element in the server configuration file, as described in Section 8.2.1.16, "oidconnection".

The oidconnection element attributes are described in Table 8-28.

Table 8-28 Attributes of the oidconnection Element

Attribute Valid Values Description

oidcon_appentity

N/A

Default: Set at install time

Oracle Internet Directory App entity created at install time for internal use of Reports.

oidcon_passwdkey

N/A

Default: Set at install time

Random password key created to connect to Oracle Internet Directory for internal use of Reports.

oidcon_url

N/A

Default: Set at install time

Oracle Internet Directory Url to connect to oid

oidcon_init

number

Default: 10

Initial number of Oracle Internet Directory connections to be created when rwservlet is initialized.

oidcon_increment

number

Default: 10

Number of connections to be incremented when all connections are used up.

oidcon_timeout

number

Default: 0 (no timeout)

Time in seconds for which a connection can be idle.


8.3.1.1.18 allowauthid

The allowauthid sub-element of rwservlet is defined in rwservlet.xsd as follows:

 <xs:element name="allowauthid" type="xs:string" minOccurs="0" maxOccurs="1"/>

Description

allowauthid is the element to be added in rwservlet.properties either to enable or disable passing of the authid through an URL.

Example

In rwservlet.properties, the allowauthid element may be specified as shown in this example:

  <allowauthid> yes </allowauthid>

Required/Optional

Optional.

Default

By default the allowauthid is set to Yes. If the authid is set to No, authorization through an URL is disabled and Single Sign-On should be used to enter the username and password.

8.3.1.1.19 enabledbproxy

The enabledbproxy sub-element of rwservlet is defined in rwservlet.xsd as follows:

<xs:element name="enabledbproxy" type="xs:string" minOccurs="0" maxOccurs="1"/>

Description

enabledbproxy is the element to be added in the rwservlet.properties file to make the dbproxy feature work through the rwservlet.

Example

In rwservlet.properties, the enabledbproxy element may be specified as shown in this example:

  <enabledbproxy> yes </enabledbproxy>

Required/Optional

Optional.

Default

By default, the enabledbproxy is set to Yes.

8.3.2 Specifying an Alternate Oracle Reports Servlet Configuration File

Perform the following steps to specify an alternate Oracle Reports Servlet Configuration File:

  1. Log in to the WebLogic Server Administration Console.

  2. Under Domain Structure in the left pane, click Environment. The Summary of Environment page is displayed.

  3. In this page, click Servers. The Summary of Servers page is displayed.

  4. From the list of servers, click WLS_REPORTS. The Settings for WLS_ REPORTS page is displayed.

  5. Click the Server Start tab.

  6. Add the following entry in the Arguments field:

    -DServletPropFile=your_servlet_properties_file
    
  7. Click Save.

  8. Restart WLS_REPORTS.

By default, Oracle Reports Servlet (rwservlet) uses the rwservlet.properties file as the configuration file. If you are running multiple Oracle WebLogic Server instances with reports installed on the same Oracle Fusion Middleware and wish to use different configuration files, you can do so by adding the following parameter in the WLS_REPORTS startup parameter section in the WebLogic Server Administration Console:

-DServletPropFile=your_servlet_properties_file