Release 9.0
Part Number A92102-01
 Home |
 Solution Area |
 Contents |
 Index |
| Oracle9iAS Reports Services Publishing Reports to the Web Release 9.0 Part Number A92102-01 |
|
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:
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".
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:
|
Note: The paths specified in Table 3-1 are the same for both Windows and UNIX environments, though they are expressed here using the Windows backslash convention (\). |
| Component | Configuration File |
|---|---|
|
Reports Server |
Use this XML file to define initial values for the Reports Cache, the Reports Engine, and security; to register valid destination types; to specify the information to be logged; and to set other server-related values. This file is automatically created when you start up the server. If you want to rename your server and wish to keep custom configuration settings you've entered into this file, you must first rename this file to the new server name, then rename the server. Otherwise, the server will create its own new default configuration file. You'll find more information about this file in the section Configuring the Oracle9iAS Reports Server. |
|
Reports Server |
This file contains data type definitions for <server_name>.conf and rwbuilder.conf elements and attributes. Data type definitions lists all elements allowed in an associated XML file, the attributes associated with those elements, and default values for those attributes. You'll find more information about this file in Reports Server Configuration Elements (rwserverconf.dtd). |
|
Reports Server |
Use this XML file to configure the Reports Server that runs in the same process as the Builder. All run requests must go through the Reports Server, meaning that the Reports Builder requires a server to run reports. The Reports Builder automatically starts a Reports Server to handle its requests. When you run a report from the Builder, this file provides the configuration for the in-process server instance that is invoked. Like the <server_name>.conf file, this file relies on the rwserverconf.dtd file for its data type definitions, though several elements do not apply, including the compatible, persistFile, and security elements. Because this file shares most configuration elements found in <server_name>.conf, you'll find the information you need for configuring this file in Configuring the Oracle9iAS Reports Server. |
|
Reports Servlet |
Among other things, this file is where you specify the location and filename of the Reports key map file (cgicmd.dat) and specify whether you will use the Reports Servlet's in-process server. You'll find more information about this file in Configuring the Reports Servlet. |
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:
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
The rwserverconf.dtd file provides the following elements for configuring the Reports Server:
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.
<server>[One or more configuration specifications]</server>
Required. You can have a maximum of one open and close server element in a given configuration file.
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.
<compatible version="6i"/>
Optional. You can have a maximum of one compatible element in your server configuration file.
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.
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.
<cache class="oracle.reports.cache.RWCache"><property name="cacheSize" value="50"/> <property name="cacheDir" value="D:\orawin\reports\server\cache"/></cache>
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).
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.
|
Note: Look for upcoming information about Reports APIs on the Oracle Technology Network: http://otn.oracle.com. |
The cache element has one attribute: class, described in Table 3-3.
| Attribute | Valid values | Description |
|---|---|---|
|
class |
see the Description column |
Default: oracle.reports.cache.RWCache A fully qualified Java class that implements the oracle.reports.cache.Cache interface. |
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.
<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. You must have at least one engine element in your configuration file, and you can have more than one.
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.
|
Note: Look for upcoming information about Reports APIs on the Oracle Technology Network: http://otn.oracle.com. |
The engine element has several attributes, described in Table 3-4.
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.
<security id="rwSec" class="oracle.reports.server.RWSecurity"><property name="securityUserid" value="portal_id/portal_password@portal_ schema" confidential="yes" encrypted="no"/></security>
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.
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.
|
Note: Look for upcoming information about Reports APIs on the Oracle Technology Network: http://otn.oracle.com. |
Security attributes are described in Table 3-5.
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.
<destination destype="oraclePortal" class="oracle.reports.server.DesOraclePortal"><property name="portalUserid" value="portal_id/portal_password@portal_ schema" confidential="yes" encrypted="no"/></destination>
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.
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.
|
Note: Look for upcoming information about Reports APIs on the Oracle Technology Network: http://otn.oracle.com. Configuring destinations is discussed in detail in Chapter 4, "Configuring Destinations for Oracle9iAS Reports Services". |
Destination attributes are listed and described in Table 3-6.
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.
<job jobType="report" engineId="rwEng" securityId="rwSec"/>
Required. You must have at least one job element and can have more than one.
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.
<notification id="tellMe02" class="oracle.reports.server.MailNotify"/>
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.
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.
|
Note: Look for upcoming information about Reports APIs on the Oracle Technology Network: http://otn.oracle.com. |
Attributes of the notification element are listed and described in Table 3-8.
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>¬ifyfailure=<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.
<log option="allJobs"/>
Optional. You can have a maximum of one log element in your server configuration file.
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.
<jobStatusRepository class="oracle.reports.server.JobRepositoryDB"><property name="repositoryConn" value="scott/tiger@ORCL" confidential="yes" encrypted="no"/></jobStatusRepository>
Optional. You can have a maximum of one jobStatusRepository elements in your server configuration file.
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.
|
Note: Look for upcoming information about Reports APIs on the Oracle Technology Network: http://otn.oracle.com. |
The jobStatusRepository element has one attribute: class, described in Table 3-10.
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.
<trace traceFile="neptune.trc" traceOpts="trace_prf|trace_dbg|trace_wrn" traceMode="trace_append"/>
Optional. You can have a maximum of one trace element in your server configuration file.
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.
|
Note: Tracing for the servlet and JSP are configured in the servlet configuration file, rwservlet.properties, discussed in Section 3.3. Tracing for an individual report can be built into the reports runtime command line, discussed in Appendix A, "Command Line Arguments". |
Trace attributes are listed and described in Table 3-11.
| Attribute | Valid values | Description |
|---|---|---|
|
traceFile |
*.trc |
The filename of the trace file. If no path is specified, the trace file will be in the following directory on both Windows and UNIX: ORACLE_HOME/reports/logs/ |
|
traceOpts |
see Table 3-12 |
This attribute defines the activities that will be traced. You can have one or more traceOpt values. For example: <traceOpts="trace_prf|trace_brk"> Separate values with a vertical bar (|).Valid values are listed and described in Table 3-12. |
|
traceMode |
trace_append |
Defines 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). |
When you specify multiple trace elements, separate them with vertical bars. For example:
traceOpts="trace_prf|trace_dbg|trace_wrn"
<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>
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.
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.
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.
| Attribute | Valid values | Description |
|---|---|---|
|
id |
string |
Identifies the reports client to be served by the public and private key. You can also specify custom-built clients through the pluggable clients API. You'll find more information about Oracle9iAS Reports Services APIs on the Oracle Technology Network, http://otn.oracle.com. |
|
publicKeyFile |
<filename>.key |
Identifies the public key file that the client will use to connect to the Reports Server. The default file is stored in the rwrun.jar file. |
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.
|
Note: For more information on server clusters, see Chapter 6, "Reports Server Clusters". |
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.
<queue maxQueueSize="1000"/>
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.
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:
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.
| Attribute | Valid values | Description |
|---|---|---|
|
maxQueueSize |
Number |
The maximum number of jobs that can be held in a given Reports job queue. |
<persistFile filename="neptune.dat"/>
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.
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.
<identifier confidential="yes" encrypted="yes">fpoiVNFvnlkjRPortn+sneU88=NnN</identifier>
Optional. You can have a maximum of one identifier element in your server configuration file.
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.
<pluginParam name="mailServer">smtp01.mycorp.com</pluginParam>
Optional. You can have as many pluginParam elements as you require.
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.
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:
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
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.
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.
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.
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.
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.
|
Note: Tracing for the Reports Server is configured in the server configuration file, <server_name>.conf, discussed in Section 3.2.1.11. Tracing for an individual report can be built into the reports runtime command line, discussed in Appendix A, "Command Line Arguments". |
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.
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
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.
|
Note: The pros and cons of running an in-process server are explored in Chapter 1, "Oracle9iAS Reports Services Architecture". |
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>.
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.
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.
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
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>
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>
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
|
Note:
For more about the |
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
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
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:
<engine id="rwURLEng" class="oracle.reports.engine.URLEngineImpl" initEngine="1" maxEngine="1" minEngine="0" engLife="50" maxIdle="30" callbackTimeOut="60000" />
<job jobType="urlEngine" engineId="rwURLEng" />
To learn about sending requests to the URL engine, refer to Chapter 8, "Running Report Requests".
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:
<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. |
<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. |
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".
|
 Copyright © 2002 Oracle Corporation. All Rights Reserved. |
|