3
Configuring Oracle9iAS Reports Services

When you install Oracle9i Application Server (Oracle9iAS), Reports Services is configured automatically for you. There will likely be adjustments you wish to make to customize your environment, but you will not be required to set up the entire environment, or even most of it.

This chapter is included largely for reference, should you wish to introduce customizations or have a better understanding of the default configuration. It lists services-related configuration files and describes in detail the content of most of them. It includes the following main sections:

• Oracle9iAS Reports Services Configuration Files

• Configuring the Oracle9iAS Reports Server

• Configuring the Reports Servlet

• Configuring the URL Engine

  Note: The examples in this chapter use ORACLE_HOME to denote where the Oracle9i Application Server (Oracle9iAS) is installed. Oracle9iAS includes Oracle9iAS Reports Services.

Another aspect of configuration is the setting of environment variables. These are set for you automatically during installation. For reference, environment variables are discussed in Appendix B, "Reports-Related Environment Variables".

3.1 Oracle9iAS Reports Services Configuration Files

This section identifies the various configuration files associated with Oracle9iAS Reports Services. In most cases, you can leave these files untouched. Because they control many aspects of your server environment, you could put that environment at risk if you change a file in some unsupported way. Always keep a back-up of the current version of any configuration file you plan to change.

The configuration files associated with Oracle9iAS Reports Services relate to the Reports Server and the Reports Servlet. They are listed and described in Table 3-1:

Table 3-1 Oracle9iAS Reports Services Configuration Files

3.2 Configuring the Oracle9iAS Reports Server

The Reports Server component of Oracle9iAS Reports Services is configurable via the XML files <server_name>.conf and rwbuilder.conf, located in the following directory (on both Windows and UNIX):

ORACLE_HOME\reports\conf\<server_name or rwbuilder>.conf

Both files are supported by the rwserver.template file, which contains default server configuration values (ORACLE_HOME\reports\conf\rwserver.template on both Windows and UNIX).

The <server_name>.conf file is the default server configuration file. The rwbuilder.conf file configures the server instance used in-process by the Reports Builder. All run requests must go through the Reports Server, meaning that the Reports Builder requires a server to run reports. When you run a report from the Builder, the rwbuilder.conf file provides the configuration for the server instance that is invoked (an in-process server) when it runs in the same process as the Reports Builder. The <server_name>.conf and rwbuilder.conf files are nearly identical. The only difference between them is that rwbuilder.conf does not use the compatible, persistFile, or security configuration elements, described later in this section, and <server_name>.conf does.

Both of these files are created automatically, under the following circumstances:

• The <server_name>.conf file is created the first time you start the server. It is based on the rwserver.template file.

• The rwbuilder.conf file is created the first time you run a report through the Reports Builder. It also is based on the rwserver.template file.

• After you rename the server, a new <server_name>.conf file is created the next time you start the server. The new configuration file is based on the default values present in the rwserver.template file. If you wish to retain the configuration associated with the old server name, you must rename your <server_name>.conf file to the new server name (<new_server_name>.conf), before starting the renamed server.

• If you delete one of these files, the deleted file is recreated the next time you start the server. The new file is based on the default values present in the rwserver.template file.

To explain the syntax and values allowed in these files we'll look at the rwserverconf.dtd file, located in the following directory (on both Windows and UNIX):

ORACLE_HOME\reports\dtd\rwserverconf.dtd

3.2.1 Reports Server Configuration Elements (rwserverconf.dtd)

The rwserverconf.dtd file provides the following elements for configuring the Reports Server:

• server

• compatible

• cache

• engine

• security

• destination

• job

• notification

• log

• jobStatusRepository

• trace

• connection

• queue

• persistFile

• identifier

• pluginParam

Note that these are XML elements, and XML is case sensitive.

Additionally, when you add any of these elements to the server configuration file (<server_name>.conf), you'll save yourself potential error messages from any XML editor you may use if you follow the order in which they are listed in the rwserverconf.dtd file located in ORACLE_HOME\reports\dtd\ on both Windows and UNIX. The configuration file will work even if you do not follow this order, but it will not work if you fail to follow the case specified in rwserverconf.dtd.

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

3.2.1.1 server

EXAMPLE

<server>

[One or more configuration specifications]

</server>

REQUIRED/OPTIONAL

Required. You can have a maximum of one open and close server element in a given configuration file.

DESCRIPTION

The server element opens and closes the content area of the server configuration file. In terms of the file's hierarchy, all the other elements are subordinate to the server element.

3.2.1.2 compatible

EXAMPLE

<compatible version="6i"/>

REQUIRED/OPTIONAL

Optional. You can have a maximum of one compatible element in your server configuration file.

DESCRIPTION

The compatible element is available for backward compatibility with Reports 6i clients (RWCLI60, RWCGI60, RWQMU60.EXE, RWQM60.EXE, RWQV60.EXE). When compatible is set to 6i, the Reports Server will make use of an executable file, named rwproxy, that listens for requests from a 6i client and forwards them to a 9i server.

Compatible has one attribute: version, described in Table 3-2.

Table 3-2 Attributes of the compatible element

If you use the compatible element, you must also have an entry for the Reports Server in your tnsnames.ora file, as you would have had for the 6i version of the Reports Server. For example:

testsvr.world = (ADDRESS=

(PROTOCOL=tcp)
(HOST=testhost.us.oracle.com)
(PORT=1949)
)

You can bypass this requirement by turning compatibility off. To turn compatibility off, remove the compatibile element from the server configuration file.

myserver.world (standalone server with default domain)

myserver.cluster1 (server part of cluster1)

myserver.cluster1.world (invalid entry)

3.2.1.3 cache

EXAMPLE

<cache class="oracle.reports.cache.RWCache">

<property name="cacheSize" value="50"/>
<property name="cacheDir" value="D:\orawin\reports\server\cache"/>

</cache>

REQUIRED/OPTIONAL

Optional. You can have a maximum of one cache element in your server configuration file. If no cache element is specified, the default is used (oracle.reports.cache.RWCache).

DESCRIPTION

The cache element is available for specifying the Java class that defines the server's cache implementation. You can use the default cache Java class or develop your own implementation through the Oracle9iAS Reports Services Cache API.

The cache element has one attribute: class, described in Table 3-3.

Table 3-3 Attributes of the cache element

You can also enter from zero to multiple properties under the cache element. Properties are name/value pairs recognized and understood by the implementation class you register under cache. For example, if you use the default cache Java class that is provided with Reports Services, your configuration entry might look like this:

<cache class="oracle.reports.cache.RWCache">

<property name="cacheSize" value="50"/>
<property name="cacheDir" value="D:\orawin\reports\server\cache"/>

</cache>

In the preceding example, cacheSize is measured in megabytes, and cacheDir, which points to the location of the cache, is specified for a Windows platform. On UNIX, use UNIX standards, for example:

<property name="cacheDir" value="/ORACLE_HOME/reports/server/cache"/>

Should your cache implementation require access to additional information specify the information in the pluginParam element.

3.2.1.4 engine

EXAMPLE

<engine id="rwEng" class="oracle.reports.engine.EngineImpl" initEngine="1"
maxEngine="5" minEngine="1" engLife="50" maxIdle="15" callbackTimeOut="60000">

<property name="sourceDir" value="D:\orawin\reports\myReport"/>
<property name="tempDir" value="D:\orawin\reports\myTemp"/>

</engine>

REQUIRED/OPTIONAL

Required. You must have at least one engine element in your configuration file, and you can have more than one.

DESCRIPTION

The engine element identifies the fully qualified Java class that starts an engine and provides a number of attributes that set operational controls on the engine. You can use the default engine provided with Reports Services (oracle.reports.engine.EngineImpl) or develop your own implementation through the Oracle9iAS Reports Services Engine API. As an example of a custom engine, you may have developed an engine to execute an operating system command should an event occur in your database.

The engine element has several attributes, described in Table 3-4.

Table 3-4 Attributes of the engine element

You can also enter from zero to multiple properties under the engine element. The only requirement is that they be name/value pairs recognized by the Java class that implements the Reports engine. For example, if you use the default engine Java class that is provided with Reports Services, your engine configuration entry might look like this:

<engine id="rwEng" class="oracle.reports.engine.EngineImpl" initEngine="1"
maxEngine="5" minEngine="1" engLife="50" maxIdle="15" callbackTimeOut="60000">

<property name="sourceDir" value="D:\orawin\reports\myReport"/>
<property name="tempDir" value="D:\orawin\reports\myTemp"/>

</engine>

In this example, sourceDir and tempDir are set up for a Windows environment (UNIX would be sourceDir="ORACLE_HOME/reports/myReport" and tempDir="ORACLE_HOME/reports/myTemp"). The sourceDir property identifies the default directory you will use for report definition files. It overrides path information specified in the REPORTS_PATH environment variable.

The tempDir property identifies the name and location of the temporary directory Reports Services will use for its temporary files. If this value is unspecified for a default engine, Reports Services will use the temporary directory specified in the REPORTS_TMP environment variable. If REPORTS_TMP is also not specified, Reports Services will use your operating system's default temporary directory.

The classPath attribute is not specified because this configuration uses the default engine class.

Should your engine require access to additional information, such as an outgoing mail server, specify the additional information in the pluginParam element.

3.2.1.5 security

EXAMPLE

<security id="rwSec" class="oracle.reports.server.RWSecurity">

<property name="securityUserid" value="portal_id/portal_password@portal_
schema" confidential="yes" encrypted="no"/>

</security>

REQUIRED/OPTIONAL

Optional. If you do not enter a security element in the configuration file, the Reports Server is not secure. You can have from zero to multiple security elements in your configuration file.

DESCRIPTION

The security element identifies the fully qualified Java class that controls server access. You can use the default security class provided with Reports Services, which relies on security features available through Oracle9iAS Portal (included with Oracle9iAS), or develop your own implementation through the Reports Server Security API.

Security attributes are described in Table 3-5.

Table 3-5 Attributes of the security element

You also have the option of entering multiple properties under the security element. The only requirement is that they be name/value pairs recognized by the Java class that implements Reports Server security. For example, if you use the default security Java class that is provided with Reports Services, your security configuration entry might look like this:

<security id="rwSec" class="oracle.reports.server.RWSecurity">

<property name="securityUserid" value="portal_id/portal_password@portal_
schema" confidential="yes" encrypted="no"/>

</security>

In this example, connect information is provided to enable the Reports Server to access to Oracle9iAS Portal security features. The property attributes confidential and encrypted are available for encrypting the information within the property. Once the confidential="yes" and encrypted="no" attributes are entered, the property value will be encrypted automatically by the Reports Server after you restart the server. When you next open the configuration file, the password information will be scrambled, and encrypted will be set to yes. If you forget the password you entered in the configuration file, you can delete the property and reenter it with new values, making sure to set encrypted to no.

Should your security implementation require access to additional information specify the information in the pluginParam element.

When setting up Security in a clustered environment, each cluster member should use the same security policy to prevent users experiencing unexpected behavior.

3.2.1.6 destination

EXAMPLE

<destination destype="oraclePortal"
class="oracle.reports.server.DesOraclePortal">

<property name="portalUserid" value="portal_id/portal_password@portal_
schema" confidential="yes" encrypted="no"/>

</destination>

REQUIRED/OPTIONAL

Optional. If you do not enter a destination element in the server configuration file, the provided destination classes will be used (printer, mail, file, cache, and Oracle9iAS Portal--which is an exception in that it requires an entry in the server configuration file so that you may specify the userid and password the server will use to log in to the portal). You can have from zero to multiple destination elements in your server configuration file.

DESCRIPTION

Use the destination element to register destination types with the server. There is no need, with the exception of Oracle9iAS Portal, to register provided (default) destinations, such as printers, e-mail, files, or cache. You must register the destination types you create through the Oracle9iAS Reports Services Destinations API.

Destination attributes are listed and described in Table 3-6.

Table 3-6 Attributes of the destination element

destype="printer"

You also have the option of entering multiple properties under the destination element. The only requirement is that they be name/value pairs recognized by the Java class that is a subclass of the Reports Server Destination Java class. For example:

<destination destype="oraclePortal"
class="oracle.reports.server.DesOraclePortal">

<property name="portalUserid" value="portal_id/portal_password@portal_
schema" confidential="yes" encrypted="no"/>

</destination>

In this example, the property provides connect information to enable the Reports Server to access Oracle9iAS Portal. The confidential and encrypted attributes are included to automatically invoke encryption on the portalUserid value the next time the Reports Server is started.

Should your destination implementation require additional information, specify the information in the pluginParam element.

3.2.1.7 job

EXAMPLE

<job jobType="report" engineId="rwEng" securityId="rwSec"/>

REQUIRED/OPTIONAL

Required. You must have at least one job element and can have more than one.

DESCRIPTION

The job element works in collaboration with the engine and security elements. Use job to identify a job type and specify which engine and which security implementation should be used with that type of job. For example, you may have developed an engine to execute an operating system command should an event occur in your database. Using Oracle9iAS Report Service's event-driven publishing API, you identify the event as a specific job type. When the event occurs, the job type information is sent to the Reports Server, which looks up the job type under the job element in its configuration file, and follows the direction provided in the element's attributes to the engine (and, if applicable, security implementation) specified for that type of job.

Attributes of the job element are listed and described in Table 3-7.

Table 3-7 Attributes of the job element

3.2.1.8 notification

EXAMPLE

<notification id="tellMe02" class="oracle.reports.server.MailNotify"/>

REQUIRED/OPTIONAL

Optional. If you do not enter a notification element in the configuration file, the notification function is disabled. You can have from zero to multiple notification elements in your configuration file.

DESCRIPTION

Use the notification element to specify a Java class that defines the type of notification that should be sent when a job succeeds or fails. You can use the default notification class, which provides for notification via e-mail, or design your own with the Reports Notification API.

Attributes of the notification element are listed and described in Table 3-8.

Table 3-8 Attributes of the job element

If you use the default e-mail notification implementation, use the pluginParam element to specify the outgoing SMTP mail server to be used to send the mail. Use the runtime commands notifysuccess and notifyfailure to specify the e-mail address where notification should be sent (for more information, see Appendix A, "Command Line Arguments"). For example, you can include these commands in your runtime URL:

notifysuccess=<recipient's e-mail address>&notifyfailure=<recipient's e-mail
address>

With the default e-mail implementation, you can specify only one address for each type of notification. You can specify one or both types of notification. You can send notification each to the same address or each to a different addresses.

A notification element in the server configuration file might look like this:

<notification id="mailNotify" class="oracle.reports.server.MailNotify"/>
   <property name="succNoteFile" value="succnote.txt"/>
   <property name=failNoteFile value="failnote.txt"/>

With the default notification implementation, it's not necessary to specify a path to the success or failure text files, provided they're in the default location: ORACLE_HOME\reports\templates. Otherwise, enter the directory path along with the filenames according to the requirements of the platform that hosts the server.

3.2.1.9 log

EXAMPLE

<log option="allJobs"/>

REQUIRED/OPTIONAL

Optional. You can have a maximum of one log element in your server configuration file.

DESCRIPTION

The log element is available for backward compatibility. It invokes the generation and population of a Reports log file. The log file is automatically generated and stored in the following path (the path is the same for Windows and UNIX):

ORACLE_HOME\reports\logs\*.log

The log element has one attribute: option, described in Table 3-9.

Table 3-9 Attributes of the log element

3.2.1.10 jobStatusRepository

EXAMPLE

<jobStatusRepository class="oracle.reports.server.JobRepositoryDB">

<property name="repositoryConn" value="scott/tiger@ORCL" confidential="yes"
encrypted="no"/>

</jobStatusRepository>

REQUIRED/OPTIONAL

Optional. You can have a maximum of one jobStatusRepository elements in your server configuration file.

DESCRIPTION

The jobStatusRepository element specifies the Java class that implements a job status repository. It provides an additional means (over the persistFile element) of storing job status information.

The persistFile is a binary file and, therefore, cannot be used to publish job status information within your application. The jobStatusRepository provides a means of including status information in your application by providing additional ways of storing it.

The default class, oracle.reports.server.JobRepositoryDB, stores information in a database. Use the Reports APIs to create your own implementation of the Reports Server Job Repository interface (oracle.reports.server.JobRepository) that stores information wherever you wish.

The jobStatusRepository element has one attribute: class, described in Table 3-10.

Table 3-10 Attributes of the jobStatusRepository element

The jobStatusRepository element allows for zero or multiple properties for passing arguments into the repository. The only requirement is that the class you specify in the server configuration file must recognize the name/value pairs you introduce.

The jobStatusRepository element might look like this in your server configuration file:

<jobStatusRepository class="oracle.reports.server.JobRepositoryDB">

<property name="repositoryConn" value="scott/tiger@ORCL" confidential="yes"
encrypted="no"/>

</jobStatusRepository>

In this example, the value for the repositoryConn property is the login for access to the database that stores the repository. The confidential and encrypted attributes are used to invoke encryption on the login information once the Reports Server is restarted.

Should your job status repository require additional information, specify the information in the pluginParam element.

3.2.1.11 trace

EXAMPLE

<trace traceFile="neptune.trc" traceOpts="trace_prf|trace_dbg|trace_wrn"
traceMode="trace_append"/>

REQUIRED/OPTIONAL

Optional. You can have a maximum of one trace element in your server configuration file.

DESCRIPTION

Use the trace element to create a file for tracing your report's execution and to specify the objects and activities you want to trace. The trace element controls tracing only for the server and the engine.

Trace attributes are listed and described in Table 3-11.

Table 3-11 Attributes of the trace element

Table 3-12 Valid values for the traceOpts attribute

When you specify multiple trace elements, separate them with vertical bars. For example:

traceOpts="trace_prf|trace_dbg|trace_wrn"

3.2.1.12 connection

EXAMPLE

<connection maxConnect="50" idleTimeOut="20">

<orbClient id="RWClient" publicKeyFile="clientpub.key"/>
<cluster publicKeyFile="ORACLE_HOME\reports\server\serverpub.key"
privateKeyFile="ORACLE_HOME\reports\server\serverpri.key"/>

</connection>

REQUIRED/OPTIONAL

Optional. If you do not specify a connection element in your server configuration file, default values will be used (see Table 3-13). You can have a maximum of one connection element in your server configuration file.

DESCRIPTION

The connection element defines the rules of engagement between the server and the clients connected to it.

Connection attributes are listed and described in Table 3-13.

Table 3-13 Attributes of the connection element

In addition to its attributes, connection has two sub-elements: orbClient and cluster.

Use orbClient to provide the name of the public key file that the client will use to connect to the Reports Server. You can have from zero to multiple orbClient sub-elements in your server configuration file.

The orbClient element attributes are listed and described in Table 3-14.

Table 3-14 Attributes of the orbClient element

We provide default client public and private key files, clientpub.key and clientpri.key. These key files are in place for all components of Oracle9iAS Reports Services. You can regenerate public and private key files to replace the default key pair. To do this, at the command prompt use the following command:

java oracle.report.utility.KeyManager <path_and_client_public_key_file_name>
<path_and_client_private_key_file_name>

If you regenerate these keys, you can specify the public key file locations with the publicKeyFile attribute, and replace the private key file in the rwrun.jar file (ORACLE_HOME\reports\jlib\rwrun.jar). To do this, you must unjar the file, place the regenerated private key into it, and rejar the file.

Use the cluster sub-element to specify the public and private key files to be used for all cluster members. You can have zero or one cluster element in your server configuration file.

For servers to be members of the same cluster, they must share the same extended cluster name and public and private keys. This means that their extended cluster names (e.g., serverA.clus, serverB.clus--in this case, .clus is the extended cluster name) should be the same, and the same public and private key files should be specified in each cluster member's server configuration file (<server_name>.conf).

The default server public and private keys are stored in the rwrun.jar file, in the path ORACLE_HOME\reports\jlib\rwrun.jar on both Windows and UNIX. However, there is no need to jar the newly-generated public and private keys that will be used for the cluster. Put them anywhere, and specify the absolute path and filename for them in the server configuration file.

3.2.1.13 queue

EXAMPLE

<queue maxQueueSize="1000"/>

REQUIRED/OPTIONAL

Optional. You can have a maximum of one queue element in your server configuration file. If you have no queue element, the default, 1000, will remain in effect.

DESCRIPTION

Use the queue element to specify the maximum number of jobs that can be held in each of the Reports queues. Reports Services has three queue components:

• a queue of scheduled jobs

• a queue of jobs in progress

• a queue of completed jobs

The queue element provides the allowable value for each of these components. If the number of jobs exceeds the specified maximum of a given queue, that queue will automatically purge its expired, then its oldest jobs. You can also use the Reports Queue Manager to manually reduce the number of jobs held in the queue.

The queue element has one attribute: maxQueueSize, described in Table 3-15.

Table 3-15 Attributes of the queue element

3.2.1.14 persistFile

EXAMPLE

<persistFile filename="neptune.dat"/>

REQUIRED/OPTIONAL

Optional. If you do not specify a file, the server will create one of its own with the default name <server_name>.dat. You can have a maximum of one persistFile element.

DESCRIPTION

The persistFile element identifies the file that records all job status. It is used by the Reports Server to restore the server to the status it held before shutdown.

It is named persistFile because the file remains intact, or persists, even when the server is brought down and restarted.

The server persistent file is created automatically the first time you start the server or the first time you start the server after the current server persistent file has been deleted or renamed. If you want to rename this file but continue using it, enter the new name in the server configuration file before you actually rename the file, then restart the server.

The persistFile element has one attribute, fileName, described in Table 3-16.

Table 3-16 Attributes of the persistFile element

3.2.1.15 identifier

EXAMPLE

<identifier confidential="yes"
encrypted="yes">fpoiVNFvnlkjRPortn+sneU88=NnN</identifier>

REQUIRED/OPTIONAL

Optional. You can have a maximum of one identifier element in your server configuration file.

DESCRIPTION

The identifier element is automatically written to the configuration file when you first log in to the Reports Queue Manager as an administrator. The first login sets the Queue Manager's administrator user ID and password. That information is encrypted and written to the server configuration file, then used for authentication for all future Queue Manager logins.

If you forget the Queue Manager login, delete it from the server configuration file, and reenter the information in the Reports Server configuration file in the following format:

<identifier confidential="yes" encrypted="no">username/password</identifier>

The next time you run the Queue Manager, the Reports Server will automatically encrypt the identifier and reset encrypted to yes. It will look something like this:

<identifier confidential="yes"
encrypted="yes">fpoiVNFvnlkjRPortn+sneU88=NnN</identifier>

For more information on the Reports Queue Manager, see the Reports Queue Manager online help.

3.2.1.16 pluginParam

EXAMPLE

<pluginParam name="mailServer">smtp01.mycorp.com</pluginParam>

REQUIRED/OPTIONAL

Optional. You can have as many pluginParam elements as you require.

DESCRIPTION

The pluginParam element works in cooperation with all pluggable components of Oracle9iAS Reports Services. This includes the engine, security, cache, destination, and jobstatusRepository components. Any one of these may need access to a mail server, an FTP URL, or some other type of plugin. The pluginParam element provides a means of specifying plugins that can be used by all pluggable components. This spares you the task of including this information in the class definition of the pluggable component and allows you to rapidly and easily change the source of the plugin.

For example, your custom pluggable engine and destination Java classes may both need access to a proxy server. Instead of hard-coding access to the server in both of these classes, you can merely call the type of plugin you need, for example proxy, and point to its location under pluginParam in the server configuration file.

You can put in any plugin and name it in any way as long as it is a plugin supported or required by the pluggable component, and the pluggable component knows its name.

The pluginParam attributes are listed and described in Table 3-17.

Table 3-17 Attributes of the pluginParam element

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:

• 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 in Chapter 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 KeyMapFile parameter 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 in Table 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

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 in rwservlet.properties, the default server name is rep_<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.

3.3.10 Setting Expiration for DB Authentication and SYSAUTH Cookies

Use the COOKIEEXPIRE parameter to set the lifetime (in minutes) of the database 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

A HELP keyword 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

3.4 Configuring the URL Engine

The Reports Server includes a URL engine that can take the contents of any URL and distribute them. The URL engine allows you to leverage the powerful scheduling and distribution capabilities of the Reports Server to distribute content from any publicly available URL to various destinations such as e-mail, Oracle9iAS Portal, and WebDav. Since the Reports Server's destinations are pluggable, you can also add your own custom destinations for the URL content.

Furthermore, if you use the URL engine in conjunction with the Reports Server's event-based APIs, database events can trigger the content distribution. For example, suppose you have created a JSP report for high fidelity Web publishing of data stored in a table containing employee expense data. You could then use the URL engine and the event-based API to e-mail that JSP whenever the expense application stores new or updated employee expense data in the table.

By default, the URL engine is not activated when you install Oracle9iAS Reports Services. You can activate the URL engine by doing the following:

1. Add an engine element for the URL engine to the server configuration file. For example, your engine element might be as follows:

   <engine id="rwURLEng"
               class="oracle.reports.engine.URLEngineImpl"
               initEngine="1"
               maxEngine="1"
               minEngine="0"
               engLife="50"
               maxIdle="30"
               callbackTimeOut="60000"
   />
   

2. Add a job element that associates the appropriate job types with the URL engine to the server configuration file. For example, your job element might be as follows:

   <job jobType="urlEngine"
        engineId="rwURLEng"
   />
   

3. Stop and restart the Reports Server.

   Note: When you restart your Reports Server with these new elements, you should see the number of engines increase accordingly in the Reports Server status message box. In the above example, the number of engines would increase by one (the value of initEngine) when you restart the Reports Server.

To learn about sending requests to the URL engine, refer to Chapter 8, "Running Report Requests".

3.5 Entering Proxy Information

Some features of Oracle9iAS Reports Services support retrieving or sending information through a firewall. For example, the URL engine, the XML data source, the Text data source, and the mail destination features all retrieve or send information through the firewall. For these features to function properly, the Reports Server requires certain proxy information. In the interests of simplicity, you store the necessary proxy information in a single location and point to it from the Reports Server configuration file. To configure your Reports Server with proxy information, you do the following:

1. Add the pluginParam element to the server configuration file and have it point to the proxy information file (e.g., proxyinfo.xml). For example, your pluginParam element might be as follows:

   <pluginParam name="proxy" type="file">proxyinfo.xml</pluginParam>
   

   Note: You can optionally specify a path for the proxy information file. By default, this file is located in this file is located in <ORACLE_HOME>/reports/conf.

2. Update the proxy information file with the necessary proxy values for your configuration. For example, proxyinfo.xml might contain the following:

   <proxyInfo>
      <proxyServers>
        <proxyServer name="xyz.abc.com" port="80" protocol="http"/>
        <proxyServer name="www-proxy1.xyz.abc.com" port="80" protocol="ftp"/>
        <proxyServer name="www-prox21.xyz.abc.com" port="80" protocol="https"/>
      </proxyServers>
      <bypassProxy>
        <domain>*.abc.com</domain>
      </bypassProxy>
   </proxyInfo>
   

   Note: Refer to the default proxy information file, <ORACLE_HOME>/reports/conf/proxyinfo.xml, for additional information.

3.6 Configuring the Reports Server for Oracle Enterprise Manager

Oracle Enterprise Manager (OEM), included with Oracle9iAS, provides managing and monitoring services to Oracle9iAS Reports Services. To take advantage of these services, OEM must be configured to work with the Reports Server. The default Reports Server instance that is configured and started as part of the Oracle9iAS installation is automatically configured with OEM. If you add another Reports Server instance, you must configure it with OEM by running the following command line:

On Unix:

<ORACLE_HOME>/bin/addNewServerTarget.sh <reports_server_name>

On Windows:

<ORACLE_HOME>\bin\addNewServerTarget.bat <reports_server_name>

For more information about using OEM for the Reports Server, refer to Chapter 13, "Managing and Monitoring Oracle9iAS Reports Services".