Configuring Oracle9 i AS Reports Services
REQUIRED/OPTIONAL
3.3 Configuring the Reports Servlet
Configure the Reports Servlet with a file named rwservlet.properties, located in the following path (Windows and UNIX use the same path):
ORACLE_HOME\reports\conf\rwservlet.properties
You may notice that the servlet uses components you may have become familiar with if you used to employ a CGI implementation.
Use the Reports Servlet configuration file for:
type text
file url
Default:text
Describes the type of plugin being specified.
For text, put in the string that is required to identify the named plugin, for example, the name of a mail server. Text means the content of the pluginParam element is text, so the
getPluginParam() method will return the exact content specified in the element.
For file, put in the directory path and filename of the plugin file. Use the standards for specifying directory paths appropriate to the Reports Server's host machine (either Windows or UNIX).
File means that the content of the pluginParam element is a filename, and the getPluginParam() method will return the content read from the file specified.
For url, put in the full, absolute URL required by the plugin, for example, the full URL to an FTP site. URL means the content of the pluginParam element is a URL, and the getPluginParam(() method will return the content read from that URL. The URL you use must reside on the same side of the firewall as Oracle9iAS Reports Services.
Note that when you have a default type (text), it is not necessary to specify it in the pluginParam string. The example that heads this section doesn't specify a type because the plugin, a mail server name, is the default type, text.
Table 3–17 Attributes of the pluginParam element Attribute Valid values Description
Specifying the location of the key map file
Reloading the Key Map File
Hiding Verbose Error Messages
Selecting Login Dialog Boxes
Setting up Trace Options for the Reports Servlet and JSPs
Customizing the Appearance of Server Error Messages
Specifying an In-Process Server
Identifying the Default Reports Server
Pointing to Dynamically Generated Images
Setting Expiration for DB Authentication and SYSAUTH Cookies
Setting an Encryption Key for the DB Authentication Cookie
Adding Formatting to Diagnostic/Debugging Output
Specifying an SSL Port Number
Defining the rwservlet Help File
Specifying the Use of Single Sign-On
The entries in this configuration file are not case sensitive.
For Windows, note that the servlet configuration file uses double backslashes (\\) in lieu 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 Reports Servlet file, the path:
d:\orawin\reports\conf\filename.ext
Becomes:
d:\\orawin\\reports\\conf\\filename.ext
For UNIX, use that platform's standard for specifying directory paths, for example:
orawin/reports/conf/filename.ext
3.3.1 Specifying the location of the key map file
Your report runtime command line may include information you do not want to expose to your users. Additionally, it may be comprised of a long string of options that is difficult to remember or makes for an ungainly URL.
You have the option of entering a report's command line arguments in a key map file (cgicmd.dat), then limiting the exposed runtime command to the name of the particular key section in this file that holds the required arguments.
The key map file is discussed inChapter 8, "Running Report Requests". Use the Reports Servlet configuration file to list the location of this file.
For example:
KeyMapFile=d:\\orawin\\reports\\conf\\cgicmd.dat
This example uses the default filename and location. An entry for the location and filename of the key map file doesn't appear by default in the servlet configuration file because the servlet already knows what to look for and where to look for it. If you use a file with a different name and/or different location, you must include a KeyMapFileparameter in your servlet configuration file that includes the directory path and filename.
3.3.2 Reloading the Key Map File
Use the RELOAD_KEYMAP parameter to specify whether the key map file (cgicmd.dat) should be reloaded each time the servlet receives a request.
For example:
RELOAD_KEYMAP=yes
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 parameter is set to no in a production environment and yes in a testing environment.
3.3.3 Hiding Verbose Error Messages
Should a runtime error occur, the body of the resulting error message can include the details of the runtime command line. If your runtime command line contains sensitive information, such as a userid and password, you may not wish to have it display along with the text of the error message.
Use the DIAGNOSTIC parameter in the servlet configuration file to specify whether command line information should be included along with the rest of the error message.
Enter NO for the DIAGNOSTIC parameter if you don't want command line details to display. NO is the default value. For example:
DIAGNOSTIC=NO
Enter YES if you prefer that all error messages include the detailed runtime command line.
3.3.4 Selecting Login Dialog Boxes
The servlet configuration file offers a number of parameters dealing with templates for userid/password dialog boxes that should open when a user logs in to a database or runs a secure report. Generally, these parameters point to various templates to be used for setting up your login screens. You can customize these templates with your company logo, linked buttons, and/or any other HTML you care to use.
The DBAUTH and SYSAUTH parameters are for specifying the location and filename of the HTML templates to be used for individual login screens.
For example, the following entry points to the template for the database login screen:
DBAUTH=dbauth.htm
SYSAUTH points to a login screen for a secure report. For example:
SYSAUTH=SYSAUTH.HTM
It isn't necessary to enter the path to a template when it is stored in the default template directory:
ORACLE_HOME\reports\templates
The DB_SYS_DIFFAUTH and DB_SYS_SAMEAUTH templates are for combining these login screens into one screen. Use DB_SYS_DIFFAUTH when your users must enter different login information for database and report access.
For example:
DB_SYS_DIFFAUTH=dbsysdif.htm
Use DB_SYS_SAMEAUTH template when your users enter the same login information for both types of access.
For example:
DB_SYS_SAMEAUTH=dbsyssam.htm
In this case, the user is prompted to enter the login information only once, and the servlet will take care of passing the values to both the database and the Reports Server.
3.3.5 Setting up Trace Options for the Reports Servlet and JSPs
Trace has been added to the Reports Services environment to allow the logging of many different types of runtime information on various Reports Services
components.
If you wish to track and log runtime information on the Reports Servlet and JSPs, use the TRACEOPTS parameter in the servlet configuration file. You can enter from zero to multiple trace options. Separate each option with a vertical bar.
For example:
TRACEOPTS=trace_prf|trace_pls|trace_dbg
All available trace options are listed and described inTable 3–12.
Additionally, you can use the TRACEFILE and TRACEMODE parameters.
Use TRACEFILE to specify the filename of the trace file. For example:
TRACEFILE=<server_name>.trc
If no path is specified, the trace file will be in the following directory on both Windows and UNIX:
ORACLE_HOME\reports\logs
Note: Tracing for the Reports Server is configured in the server configuration file, <server_name>.conf, discussed inSection 3.2.1.11.
Tracing for an individual report can be built into the reports runtime command line, discussed inAppendix A, "Command Line Arguments".
Use TRACEMODE to define whether new trace information will either overwrite the existing trace file (trace_replace), or be added to the end of the trace, leaving existing trace information intact (trace_append). For example:
TRACEMODE=trace_append
The default for TRACEMODE is trace_replace.
3.3.6 Customizing the Appearance of Server Error Messages
Reports Services provides a template for server error messages. These messages are generated automatically, according to cause. The 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 providing your own HTML framework for automatically generated error messages.
The entry in the servlet configuration file is for pointing to the name and location of your error message template.
By default, the entry is:
ERRORTEMPLATE=rwerror.htm
It isn't necessary to enter the path to the error message template when it is stored in the default template directory:
ORACLE_HOME\reports\templates
3.3.7 Specifying an In-Process Server
If you choose to run the Reports Server within the same process as the Reports Servlet, you indicate that with the SERVER_IN_PROCESS parameter. To run the Reports Server as an in-process server, specify the following in the servlet configuration file:
SERVER_IN_PROCESS=yes
Enter no if you do not want the Reports Server to run within the same process as the Reports Servlet.
3.3.8 Identifying the Default Reports Server
The Reports Servlet uses the SERVER parameter to identify the default Reports Server. If a server name is not specified, for example, in the runtime URL, the default server specified here is used. Enter the name of your default Reports Server in the servlet configuration file.
For example:
SERVER=<server_name>
If the default Reports Server is a member of a server cluster, use the cluster name:
SERVER=<cluster_name>
If you use a combination of the server name and cluster name, requests sent to the default server will go to this specific machine. If this machine is down, an error message will be returned and the report will not be run. By specifying just the cluster name, requests will be sent to a random cluster member, and fowarded to another if the target machine doesn't have an idle engine.
If you don’t specify a SERVER parameter inrwservlet.properties, the default server name isrep_<machine_name>.
3.3.9 Pointing to Dynamically Generated Images
Use the IMAGE_URL parameter to specify where the Reports dynamically generated images can be accessed.
For example:
IMAGE_URL=http://<server_or_web_server_name>.<domain_
name>:<port>/reports/rwservlet
This parameter is in place for JSPs that do not run via the Reports Servlet. 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 the Reports Servlet have this protection automatically.
Note: The pros and cons of running an in-process server are explored inChapter 1, "Oracle9iAS Reports Services Architecture".
3.3.10 Setting Expiration for DB Authentication and SYSAUTH Cookies
Use the COOKIEEXPIRE parameter to set the lifetime (in minutes) of the database and system authentication cookie. For example:
COOKIEEXPIRE=20
The default is 30.
Cookies 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 is longer than the number of minutes defined in COOKIEEXPIRE, the server rejects the cookie and returns to the client the database authentication form along with an error message. Users must re-authenticate to run the report.
3.3.11 Setting an Encryption Key for the DB Authentication Cookie
Use ENCRYPTIONKEY to specify the encryption key to be used to encrypt the user name and password of the DB authentication cookie. The encryption key can be any character string. For example:
ENCRYPTIONKEY=egbdf
3.3.12 Adding Formatting to Diagnostic/Debugging Output
The DIAGBODYTAGS and DIAGHEADTAGS parameters are available for
including additional HTML encoding in the <body> and <head> tags in the output files associated with diagnostic and debugging output.
DIAGBODYTAGS defines the entire <body> tag; while DIAGHEADTAGS defines tags to appear between the open and close <head>/</head> tags.
You can use these to include formatting arguments to make diagnostic and debugging output easier to read. For example:
DIAGBODYTAGS=<BODY [additional HTML encoding]>
DIAGHEADTAGS=<HEAD>[additional HTML encoding]</HEAD>
3.3.13 Specifying an SSL Port Number
Use SSLPORT if you’re using Secure Sockets Layer (SSL) and you want to use a port other than the default (443). For example:
SSLPORT=<port number>
3.3.14 Defining the rwservlet Help File
AHELPkeyword is available with the rwservlet command for bringing up a servlet-related help topic. The help file is invoked when you specify the following URL:
http://yourwebserver/yourservletpath/rwservlet/help
We provide a default help file for the servlet, which will be displayed if you leave this parameter undefined. (The default information is pulled from code and is not a file as such.) You may want to supply a help file of your own. To do this, specify the name and location URL of your servlet help file with the HELPURL parameter in the servlet configuration file. For example:
HELPURL=http://your_web_server/your_help_file_path/helpfile.htm
3.3.15 Specifying the Use of Single Sign-On
If you plan to take advantage of Oracle9iAS Reports Services single sign-on capability, you must specify this in the servlet configuration file with the
SINGLESIGNON parameter. Enter YES to indicate that you will use single sign-on to authenticate users; enter NO if you will not use single sign-on. If you choose NO, the Reports Server will use its own authentication mechanism to authenticate users (i.e., as was used in Reports6i).
To specify that you will use single sign-on to authenticate users, enter:
SINGLESIGNON=yes