10g (9.0.4)
Part Number B10314-01
 Home |
 Solution Area |
 Contents |
 Index |
| Oracle Application Server Reports Services Publishing Reports to the Web 10g (9.0.4) Part Number B10314-01 |
|
When you install Oracle Application Server, OracleAS 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 OracleAS 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 OracleAS 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 |
ORACLE_HOME\reports\conf\server_name.conf Use this XML file to define initial values for the Reports Server 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 Reports Server. |
|
Reports Server |
ORACLE_HOME\reports\dtd\rwserverconf.dtd
This file contains data type definitions for You'll find more information about this file in Reports Server Configuration Elements (rwserverconf.dtd). |
|
Reports Server Reports Builder |
ORACLE_HOME\reports\conf\rwbuilder.conf
Use this XML file to configure the Reports Server that is embedded in Reports Builder and Reports Runtime. All run requests must go through Reports Server, meaning that Reports Builder requires a server to run reports. 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
Because this file shares most configuration elements found in |
|
Reports Servlet |
ORACLE_HOME\reports\conf\rwservlet.properties
Among other things, this file is where you specify the location and filename of the Reports Servlet key map file ( You'll find more information about this file in Configuring the Reports Servlet. |
The Reports Server component of OracleAS 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 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 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:
server_name.conf file is created the first time you start Reports Server. It is based on the rwserver.template file.
rwbuilder.conf file is created the first time you run a report through Reports Builder. It also is based on the rwserver.template file.
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.
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
The following example of rwserverconf.dtd illustrates how it is used to configure various aspects of the Reports Server.
<!-- Copyright 2003 Oracle Corp. 500 Oracle Parkway, Redwood Shores, CA 94065, U.S.A. All rights reserved. This is the DTD defining the Reports Server Version 9i Configuration file (XML) format/syntax. --> <!ELEMENT server (compatible?, cache?, engine+, security*, destination*, job+, notification*, log?, jobStatusRepository?, trace?, connection?, queue?, persistFile?, identifier?, environment*, pluginParam*)> <!ATTLIST server version CDATA #IMPLIED> <!ELEMENT cache (property*)> <!-- class specifies fully qualified java class name which implements oracle.reports.cache.Cache interface --> <!ATTLIST cache class CDATA "oracle.reports.cache.RWCache"> <!ELEMENT engine (property*)> <!-- class specifies full qualified java class name which starts engine --> <!ATTLIST engine id ID #REQUIRED class CDATA #REQUIRED classPath CDATA #IMPLIED initEngine CDATA "1" maxEngine CDATA "1" minEngine CDATA "0" engLife CDATA "50" maxIdle CDATA "30" callbackTimeOut CDATA "60000" jvmOptions CDATA #IMPLIED engineResponseTimeOut CDATA "0" defaultEnvId CDATA #IMPLIED> <!ELEMENT security (property*)> <!-- class specifies full qualified java class name which implements oracle.reports.server.Security interface --> <!ATTLIST security id ID #REQUIRED class CDATA #REQUIRED> <!ELEMENT destination (property*)> <!-- class specifies full qualified java class name which subclass oracle.reports.server.Destination abstract class --> <!ATTLIST destination destype ID #REQUIRED class CDATA #REQUIRED> <!ELEMENT job EMPTY> <!ATTLIST job jobType CDATA "report" engineId IDREF #REQUIRED securityId IDREF #IMPLIED> <!ELEMENT notification (property*)> <!ATTLIST notification id CDATA "mailNotify" class CDATA #REQUIRED> <!ELEMENT log EMPTY> <!ATTLIST log option (allJobs|succeededJobs|failedJobs|noJob) "noJob"> <!ELEMENT jobStatusRepository (property*)> <!-- class specifies full qualified java class name which implements oracle.reports.server.JobRepository interface --> <!ATTLIST jobStatusRepository class CDATA "oracle.reports.server.JobRepositoryDB"> <!ELEMENT queue EMPTY> <!ATTLIST queue maxQueueSize CDATA "10000"> <!ELEMENT connection (orbClient*, cluster?)> <!ATTLIST connection maxConnect CDATA "20" idleTimeOut CDATA "10"> <!ELEMENT orbClient EMPTY> <!ATTLIST orbClient id ID #REQUIRED publicKeyFile CDATA #REQUIRED> <!ELEMENT cluster EMPTY> <!ATTLIST cluster publicKeyFile CDATA #REQUIRED privateKeyFile CDATA #REQUIRED> <!ELEMENT persistFile EMPTY> <!ATTLIST persistFile fileName CDATA #IMPLIED> <!ELEMENT trace EMPTY> <!ATTLIST trace traceFile CDATA #IMPLIED traceOpts (trace_prf|trace_brk|trace_app|trace_pls|trace_sql| trace_tms|trace_dst|trace_log|trace_err|trace_inf| trace_dbg|trace_wrn|trace_sta|trace_exc|trace_all) "trace_ all" traceMode (trace_replace|trace_append) "trace_replace" traceModule (all|server|engine) "all"> <!ELEMENT compatible EMPTY> <!ATTLIST compatible version (6i) "6i"> <!ELEMENT identifier (#PCDATA)> <!ATTLIST identifier confidential (yes|no) "yes" encrypted (yes|no) "no"> <!ELEMENT environment (envVariable*)> <!ATTLIST environment id ID #REQUIRED> <!ELEMENT envVariable EMPTY> <!ATTLIST envVariable name CDATA #REQUIRED value CDATA #IMPLIED> <!ELEMENT pluginParam (#PCDATA)> <!ATTLIST pluginParam name ID #REQUIRED type (text|file|url) "text"> <!ELEMENT property EMPTY> <!ATTLIST property name CDATA #REQUIRED value CDATA #REQUIRED confidential (yes|no) "no" encrypted (yes|no) "no">
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 will save yourself potential error messages from any XML editor if you use the order of the elements shown in the rwserverconf.dtd (ORACLE_HOME\reports\dtd\). The configuration file will work regardless of the 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, RWRQM60.EXE, RWRQV60.EXE, 6i Forms ). When compatible is set to 6i, 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 Reports Server in the tnsnames.ora file as you would have had for the 6i version of Reports Server. The installer configures the tnsnames.ora file for the default Reports Server, i.e., rep_machine_name.
For example:
testsvr.world = (ADDRESS=(PROTOCOL=tcp) (HOST=testhost.mydomain.com) (PORT=1950) )
You can bypass this requirement by turning compatibility off. To turn compatibility off, remove the compatible element from the Reports 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 OracleAS Reports Services Cache API.
|
Note:
Look for information about the OracleAS Reports Services APIs on the Oracle Technology Network, ( |
The cache element has one attribute: class, described in Table 3-3.
| Attribute | Valid values | Description |
|---|---|---|
|
|
see the Description column |
Default:
A fully qualified Java class that implements the |
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 OracleAS 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"/>
The default cache Java class also provides the following properties:
maxCacheFileNumber is the maximum number of files allowed in the cache. For example:
<property name="maxCacheFileNumber" value="250"/>
ignoreParameters lists any report parameters you want to be ignored when Reports Server constructs the cache key. (The cache key is used by Reports Server to determine if an incoming job request matches existing output in the cache.)
<property name="ignoreParameters" value="param1,param2"/>
<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 OracleAS Reports Services (oracle.reports.engine.EngineImpl) or develop your own implementation through the OracleAS 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 Oracle Reports APIs on the Oracle Technology Network, ( |
The engine element has several attributes, described in Table 3-4.
| Attribute | Valid values | Description |
|---|---|---|
|
|
string |
A keyword, unique within a given configuration XML file, that identifies a particular
|
|
|
see the Description column |
Default:
A fully qualified Java class that implements two interfaces: |
|
|
string |
The directory path to the Java class specified in the
|
|
|
number |
The number of engines you want Reports Server to start at initialization. |
|
|
number |
The maximum number of this type of engine that can run on the server. |
|
|
number |
The minimum number of this type of engine that is maintained by the server. |
|
|
number |
The number of jobs the engine can run before the engine is terminated, and, if necessary, a new engine is started. This feature is available to thwart memory leaks. |
|
|
number |
The number of minutes of allowable idle time before the engine is shut down, provided the current number of engines is higher than
For example, if |
|
|
number |
The number of milliseconds of allowable waiting time between when the server launches an engine and the engine calls the server back. If the machine that hosts the server is very fast, you can reduce this number for faster performance. |
|
|
string |
Is an optional attribute. It specifies the default environment with which Reports Server starts an engine. The attribute takes an id that is associated with an environment element in the server configuration file.
If you specify
If you do not specify For more information refer to Dynamic Environment Switching. |
|
|
number |
The maximum amount of time (in minutes) for an engine to update the status of the job while running a report in your environment. If it takes longer than this amount of time to update the job status for some reason (e.g., due to the engine hanging or a long blocking SQL query), Reports Server terminates the job. |
|
|
string |
The Java Virtual Machine (JVM) options to be used by Reports Server when it starts an engine in the JVM. For example, you can use this attribute to specify the starting heap size and maximum heap size for the JVM, additional classpath entries, and so on.
The Reports Engine running in the server environment ignores the value in the |
|
|
|
The
The
This property will be migrated if a |
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 OracleAS 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 OracleAS Reports Services will use for its temporary files. If this value is unspecified for a default engine, OracleAS Reports Services will use the temporary directory specified in the REPORTS_TMP environment variable. If REPORTS_TMP is also not specified, OracleAS 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.
<security id="rwSec" class="oracle.reports.server.RWSecurity"><!--property name="securityUserid" value="portal_db_username/portal_ password@portal_db_connection" confidential="yes" encrypted="no"/--> <property name="oidEntity" value="oidentity_name"/></security>
Optional. If you do not enter a security element in the configuration file, 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 OracleAS Reports Services, which relies on security features available through OracleAS Portal (included with Oracle Application Server), or develop your own implementation through the Reports Server Security API.
|
Note:
Look for information about Oracle Reports APIs on the Oracle Technology Network, ( |
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 OracleAS Reports Services, your security configuration entry might look like this:
<security id="rwSec" class="oracle.reports.server.RWSecurity"><!--property name="securityUserid" value="portal_db_username/portal_ password@portal_db_connection" confidential="yes" encrypted="no"/--> <property name="oidEntity" value="oidentity_name"/></security>
In this example, the oidEntity property illustrates the configuration for 10g (9.0.4) and later. The value of oidEntity is set by the Installer upon installation. Reports Server uses this entity to connect to the Oracle Internet Directory. Components of the Oracle Application Server can all connect to the Oracle Internet Directory, but each component may have different privileges in the directory. Hence, each component needs to identify itself via its own entity name to the Oracle Internet Directory when it connects. The OracleAS Reports Services entity is of the following format:
reportsApp_hostname_GUID
For example:
reportsApp_testhost.mydomain.com_BBEFDCDAC2343600E0340800020C7BBCC
The commented out property, securityUserid, illustrates the old method of specifying security. securityUserid provides the connection information to enable the Reports Server access to OracleAS 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 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.
When setting up security in a clustered environment, each cluster member should use the same security policy to prevent users from experiencing unexpected behavior.
<destination destype="oraclePortal" class="oracle.reports.server.DesOraclePortal"><property name="portalUserid" value="portal_db_username/portal_ password@portal_db_connection" 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 OracleAS 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 OracleAS Portal, to register provided (default) destinations, such as printers, e-mail, files, or cache. You must register the destination types you create through the OracleAS Reports Services Destinations API.
|
Note:
Look for information about Oracle Reports APIs on the Oracle Technology Network, ( Configuring destinations is discussed in detail in Chapter 7, "Configuring Destinations for OracleAS 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_db_username/portal_ password@portal_db_connection" confidential="yes" encrypted="no"/></destination>
In this example, the property provides connect information to enable Reports Server to access OracleAS Portal. The confidential and encrypted attributes are included to automatically invoke encryption on the portalUserid value the next time 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 OracleAS Reports Services'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 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.
| Attribute | Valid values | Description |
|---|---|---|
|
|
string |
Describes the type of job to be processed by the server. You can enter any type of job, as long as Reports Server has an engine to process it. |
|
|
ID reference |
References the ID entered for the engine that will process this job type. Available IDs are specified under the engine element in the server configuration file using the |
|
|
ID reference |
References the ID entered for the security mechanism that will be applied to this job type. Available IDs are specified under the |
<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 Oracle Reports Notification API.
|
Note:
Look for upcoming information about Oracle Reports APIs on the Oracle Technology Network, ( |
Attributes of the notification element are listed and described in Table 3-8.
If you use the default email 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 email address where notification should be sent (for more information, see Appendix A, "Command Line Options"). 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"/><notification/>
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\server_name\rwserver.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 element 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 Oracle 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 information about OracleAS Reports Services APIs on the Oracle Technology Network, ( |
The jobStatusRepository element has one attribute: class, described in Table 3-10.
The jobStatusRepository element allows for zero or multiple properties for passing options 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 Reports Server is restarted.
<trace traceFile="neptune.trc" traceOpts="trace_prf|trace_dbg|trace_wrn" traceMode="trace_append" traceModule="server"/>
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, |
Trace attributes are listed and described in Table 3-11.
| Attribute | Valid values | Description |
|---|---|---|
|
|
|
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:
|
|
|
see Table 3-12 |
This attribute defines the activities that will be traced. You can have one or more traceOpt values. For example:
Separate values with a vertical bar (|).Valid values are listed and described in Table 3-12. |
|
|
|
Defines whether new trace information will either overwrite the existing trace file ( |
|
|
|
By default, tracing tracks both server and engine events. Tracing engine events can cause performance problems in some cases. Use
<
If |
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 Reports Server. Reports Server uses the public key to verify the signature sent by the client when it tries to connect to Reports Server. Reports Server only accepts clients whose signature can be verified through this public key. 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.
OracleAS Reports Services provides default client public and private key files, clientpub.key and clientpri.key. These key files are in place for all components of OracleAS 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:
Microsoft Windows
rwgenkey.bat path_and_client_public_key_file_name path_and_client_private_key_file_name
UNIX
rwgenkey.sh 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 ORACLE_HOME\jlib\zrclient.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 12, "Clustering Reports Servers". |
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 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. OracleAS Reports Services has three queue components:
The queue element provides the allowable value for each of these components.
This element is applicable only to the completed job queue. Thus, if the number of jobs exceeds the specified maximum value, that completed job queue will automatically purge its oldest jobs. The scheduled job queue and the in-progress job queue remain unaffected.
You can also use 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 |
|---|---|---|
|
|
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 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 Reports Queue Manager as an administrator. The first login sets the Reports 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 or need to change it, delete it and reenter it in Reports Server configuration file in the following format:
<identifier confidential="yes" encrypted="no">username/password</identifier>
You should immediately start Reports Server after making this change. Doing so automatically encrypts the user name and password and resets encrypted to yes. It will look something like this:
<identifier confidential="yes" encrypted="yes">fpoiVNFvnlkjRPortn+sneU88=NnN</identifier>
For more information on Reports Queue Manager, see the Reports Queue Manager online help. For more information on rwservlet.properties, refer to Configuring the Reports Servlet.
<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 OracleAS 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 parameter. 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 parameter you need, for example proxy, and point to its location under pluginParam in the server configuration file.
You can put in any plugin parameter 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.
<environment id="JP"> <envVariable name="NLS_LANG" value="Japanese_Japan.JA16SJIS"/> <envVariable name="NLS_CURRENCY" value="¥"/> <envVariable name="DISPLAY" value="MyServer.MyCompany.com:0.0"/> </environment>
Optional. You can have as many environment elements as you require.
The environment element defines the characteristics (i.e., environment variables) that you want to use to establish a particular runtime environment. You may include as many environment elements as you need (e.g., one for each language/territory you need to support). Inside an environment element, you can add as many envVariable elements as required.
By referencing the environment element's id, you invoke its settings. You can reference an environment element id from:
defaultEnvId attribute of the engine element in the Reports Server configuration file, to apply the corresponding environment settings to that engine when it starts up. For more information, refer to engine.
ENVID, of your report's job request, which makes the environment settings only effective for that particular report job request.
The environment attributes are listed and described in Table 3-18.
| Attribute | Valid values | Description |
|---|---|---|
|
|
string |
The name of the environment. |
The environment element has one sub-element, envVariable. Each envVariable is specified as a name-value pair. They can be either standard environment variables or user-defined environment variables.
The envVariable element attributes are listed and described in Table 3-19.
In the past, Reports Server could only serve reports that were compatible with the environment in place when Reports Server was started. For example, reports had to be compatible with the value of the NLS_LANG parameter at the time Reports Server was started. This restriction meant that you needed to have one Reports Server running for each language you wanted to process. The new environment switching feature eliminates this restriction by enabling one instance of Reports Server to serve reports with any arbitrary environment settings, including language.
To use this feature, you first need to add an environment element to your Reports Server configuration file to establish a particular runtime environment. Once you have an environment element established, you can switch to its settings in either one of the following ways:
defaultEnvId attribute of the engine element in the Reports Server configuration file applies the specified environment element to the engine when it starts up. For more information, refer to engine.
ENVID, of your report's job request, which makes the environment settings only effective for that particular report job request. Refer to Examples.
Below is an example of an environment element:
<environment id="JP"> <envVariable name="NLS_LANG" value="Japanese_Japan.JA16SJIS"/> <envVariable name="NLS_CURRENCY" value="¥"/> <envVariable name="DISPLAY" value="MyServer.MyCompany.com:0.0"/> </environment>
You could invoke this environment element from an engine element as follows:
<engine id="rwEng" initEngine="1" minEngine="0" maxEngine="10" engLife="50" maxIdle="30" defaultEnvId="JP"/>
The value JP identifies the environment element created previously in the Reports Server configuration file. The initial engines will be spawned with the environment settings specified in this environment element. For more information on the environment element, refer to engine.
The following examples illustrate the usage of the dynamic environment switching feature:
Suppose that you need to run reports in Japanese from your Reports Server. An environment conducive to running reports in Japanese would include:
NLS_LANG = Japanese_Japan.JA16SJIS
DISPLAY would also need to be set.
To begin, you would have to add an environment element to your Reports Server configuration file that looks something like the following:
<environment id="JP"> <envVariable name="NLS_LANG" value="Japanese_Japan.JA16SJIS"/> <envVariable name="NLS_CURRENCY" value="¥"/> <envVariable name="DISPLAY" value="MyServer.MyCompany.com:0.0"/> </environment>
Once the environment element is in place, you could request a report with Japanese output using the following URL:
http://yourWebServer:port/reports/rwservlet?server=yourreportsserver &report=Japanese.rdf&userid=username/passwd@db&desformat=htmlcss &destype=cache&envid=jp
When the URL is submitted to Reports Server, it detects the optional ENVID parameter and matches the specified id (in this case, JP) to the corresponding id in its configuration file. If Reports Server already has an engine running with these characteristics, it will reuse the existing engine to process the job. If not, then it spawns an engine using the current environment plus the three environment variables specified in the JP environment element. If spawning a new engine would cause Reports Server to exceed its maxEngines setting, Reports Server shuts down an engine before starting a new one. An engine may be shut down even though it has not exceeded its engLife setting.
Once Reports Server has an engine with the correct environment running, the job is processed by that engine and the output is routed to the specified DESTYPE.
envid is an optional parameter. If you do not pass this parameter with the job, Reports Server processes the request using an engine started with the defaultEnvId environment. If defaultEnvId is not specified for the engine element in your Reports Server configuration file, then the engine will inherit the settings with which the Reports Server instance was started.
Reports Server may forward the request to another server on the cluster in cases where it cannot handle the request at that time. Even though the job may be routed to another server on the cluster, the target server will reuse or spawn an engine with the required environment to process this job.
The following example illustrates how to use this environment switching feature to run an Arabic report on the same Reports Server that was used to run the Japanese report in Example 1.
Add another environment element to the Reports Server configuration file as shown below:
<environment id="AR"> <envVariable name="NLS_LANG" value="Arabic_United Arab Emirates.AR8ISO8859P6"/> <envVariable name="NLS_CALENDAR" value="Arabic Hijrah "/> </environment>
The Arabic report has to be submitted to Reports Server with the following command line:
http://yourWebServer:port/reports/rwservlet?server=yourreportsserver &report=arabic.rdf&userid=username/passwd@db&desformat=htmlcss &destype=cache&envid=ar
Since the job is submitted with envid=AR, Reports Server finds or starts an engine with the environment specified by element AR in the Reports Server configuration file. The job is processed by the new engine and the output is distributed to the specified destination.
The following example illustrates how the environment switching feature could be used in conjunction with a JSP report, i.e., without the Reports Servlet.
Suppose that you have the following environment elements in the Reports Server configuration file:
<environment id="UK"> <envVariable name="NLS_LANG" value="AMERICAN_UNITED KINGDOM.WE8ISO8859P1"/> </environment> <environment id="US"> <envVariable name="NLS_LANG" value="AMERICAN_AMERICA.WE8ISO8859P1"/> </environment>
If your JSP report uses a format mask such as the following, it means the currency, grouping, and decimal symbols can change according to the environment:
<rw:field id="sal" src="sal" formatMask="L999G999D999"/>
To run the report using the UK symbols for currency, grouping, and decimal, you would use the following URL:
http://myserver:port/test/myjsp?userid=scott/tiger@orcl&envid=uk
Note: You could place envid=uk into a key in the cgicmd.dat file.
maxEngine specified for that engine type. It is recommended that you set maxEngine to a value greater or equal to the number of environment elements specified in the Reports Server configuration file.
defaultEnvId can also be applied to pluggable engines other than rwEng. Reports Server will spawn the pluggable engine with the specified environment id.
reports.sh (UNIX only)
Environment element in the Reports Server configuration file
ORACLE_HOME/j2ee/OC4J_BI_Forms/config/oc4j.properties file: the oracle.home property defines the ORACLE_HOME setting and oracle.path defines the PATH setting.
ORACLE_HOME/opmn/conf/opmn.xml, the <environment> element under <oc4j instanceName="OC4J_BI_Forms" gid="OC4J_BI_Forms">
ENVID is also set in reports.sh (ORACLE_HOME/bin/), Reports Server obtains the environment variable value from reports.sh and not from ENVID.
For example, say you want to set the REPORTS_PATH environment variable to a different engine by using the environment switch feature. However, the reports.sh file also has the same REPORTS_PATH environment variable set. Reports Server will now use only REPORTS_PATH set by reports.sh and not the REPORTS_PATH set in ENVID when you pass any request.
To work around this issue, you must:
reports.sh and comment the environment variable value. For example, comment the REPORTS_PATH value set in the reports.sh file.
server_name.conf file.
reports.sh file to the server_name.conf file using the environment id tags. For example:
<environment id="default"> <envVariable name=REPORTS_PATH value="$ORACLE_ HOME/reports/templates:$ORACLE_ HOME/reports/samples/demo:$ORACLE_HOME/reports/integ:$ORACLE_ HOME/reports/printers"/> </environment> <environment id="testenv"> <envVariable name="REPORTS_PATH" value="/private/file_path:$ORACLE_HOME/reports/templates:$ORACLE_ HOME/reports/samples/demo:$ORACLE_HOME/reports/integ:$ORACLE_HOME/ reports/printers"/> </environment>
defaultEnvId value to the appropriate tag in the server_name.conf file.For example, add the defaultEnvId value to the engine tag so that the engine starts with the default REPORTS_PATH.
<engine id="rwEng" class="oracle.reports.engine.EngineImpl" initEngine="1" maxEngine="1" minEngine="0" engLife="50" maxIdle="30"callbackTimeOut="60000" defaultEnvId="default">
reports.sh file:
NLS_LANG=AMERICAN_AMERICA.WE8ISO8859P1; export NLS_LANG
This workaround was introduced because OPMN implicitly sets NLS_LANG to AMERICAN_AMERICA.WE8MSWIN1252, which is passed to the engine if NLS_LANG is not set. This caused a problem in Solaris because the encoding doesn't exist. However, the NLS_LANG setting in reports.sh breaks the environment switching feature and will result in any of the following errors:
REP-3000: Internal error starting Oracle Toolkit
or
REP-56048: Engine rwEng-0 crashed
To work around this issue, you must remove the NLS_LANG entry in reports.sh.
By default, Reports Server can only use portal users to connect to OracleAS Portal. It cannot use an ordinary userid, such as scott/tiger, unless you first assign appropriate privileges to its schema.
To assign the appropriate privileges to a schema other than the portal schema, you need to run the following script from SQL*Plus as an OracleAS Portal user:
ORACLE_HOME/portal/admin/plsql/wor/rwgrant.sql
Once the script is loaded, it prompts you to enter the connection string for the new schema (e.g., repapp/repapp@orcl). The script then assigns the appropriate privileges to this new schema. You will then be able to specify this connection string in the Reports Server configuration file to connect to OracleAS Portal.
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 options 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 options.
The key map file is discussed in Chapter 13, "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.
You may want to provide an authentication mechanism for an unsecured Reports Server so that only an administrator (based on the authid) can run a Web command, like showenv, showjobs, etc. By setting DIAGNOSTIC=NO in the rwserver.properties file, you can provide just such an authentication mechanism. This authentication information is also used for administrative tasks, for example, stopping the Reports Server from the command line.
To disable Web command display for an unsecured Reports Server
DIAGNOSTIC=NO in the rwservlet.properties file.
rwservlet, by using any of the Web commands, for example, getserverinfo. You must pass an authid here.
For example:
http://yourwebserver:portnum/reports/rwservlet/getserverinfo?server=aks+auth id=scott/tiger
|
Note:
The Reports Server will save this
The clear text of username and password will be encrypted by Reports Server once it starts up, and the encrypted atttribute is changed to yes to indicate the content is encrypted.
Refer to identifier, for more information on the |
Now, any access to the reports server for using the Web commands will have to pass the same authid. If the authid is not passed, then you will get the following error:
REP-52262: Diagnostic output is disabled.
To modify the administrator username and / or password:
server_name.conf.
<identifier> element:
<identifier encrypted="no"confidential="yes">admin_name/admin_ password</identifier>
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. By default, the file names are rwdbauth.htm and rwsysauth.htm, respectively.
For example, the following entry points to the template for the database login screen:
DBAUTH=rwdbauth.htm
SYSAUTH points to a login screen for a secure report. For example:
SYSAUTH=rwsysauth.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
Trace has been added to the OracleAS Reports Services environment to allow the logging of many different types of runtime information on various OracleAS Reports Services components.
|
Note:
Tracing for Reports Server is configured in the server configuration file, |
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=myrwservlet.trc
The default name is rwservlet.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). TRACEMODE replaces or appends to the tracing information that has accumulated since the startup of the Oracle Application Server Containers for J2EE container that contains rwservlet. For example:
TRACEMODE=trace_append
The default for TRACEMODE is trace_replace.
From Oracle Reports 10g (9.0.4) onwards, you can specify non-ASCII escaped characters in the request URL or in the Parameter Form input. You must specify the character encoding in the rwservlet.properties file before you can apply it. This is to ensure that rwservlet uses the required encoding when parsing the parameter value.
You can set the value of DEFAULTCHARSET in the rwservlet.properties file to either:
DEFAULTCHARSET=JA16EUC.
Any HTML code included as part of the report request URL might lead to a security compromise as it causes certain browsers to execute any script or code in the URL. From Oracle Reports 10g (9.0.4) onwards, HTML code is not allowed as part of the URL command.
To disallow HTML code as part of the URL command, a new property ALLOWHTMLTAGS is introduced in the rwservlet.properties file. This property is set to NO by default, disallowing any HTML code to be entered in the URL when running a report.
YES Allows HTML code in the URL
NO Disallows any HTML code in the URL
NO
You may want to define the number of users who can connect and submit job requests simultaneously to rwservlet. To do so, you must set the value of the CONNECTION_POOLSIZE property in the rwservlet.properties file.
500
0 (not recommended)
Set the value of CONNECTION_POOLSIZE keeping in mind the number of active users expected to make concurrent job requests. For example, set this value to 250 if you expect around 100 concurrent active users.
OracleAS 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, "Understanding the OracleAS 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=server_name.cluster_name
If you use a combination of the server name and cluster name in your URL, 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 in the URL, 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.
Optionally, you can 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 and system authentication cookie. For example:
COOKIEEXPIRE=20
The default is 30.
Cookies save encrypted user names and passwords on the client-side when users first authenticate themselves. When the server receives a cookie from the client, the server compares the time saved in the cookie with the current system time. If the time is longer than the number of minutes defined in COOKIEEXPIRE, the server rejects the cookie and returns to the client the 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 database and system authentication cookies. 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 options to make diagnostic and debugging output easier to read. For example:
DIAGBODYTAGS=<BODY [additional HTML encoding]> DIAGHEADTAGS=<HEAD>[additional HTML encoding]</HEAD>
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://your_web_server/your_servlet_path/rwservlet/help
|
Note:
For more about the |
We provide a default help file for the servlet, ORACLE_HOME\reports\templates\help.htm, which will be displayed if you leave this parameter undefined. 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 OracleAS Reports Services' Single Sign-On capability, you must ensure the SINGLESIGNON parameter is set to YES in the servlet configuration file. SINGLESIGNON is set to YES by default upon installation.
For more information, refer to Enabling and Disabling OracleAS Single Sign-On.
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 Reports Server to distribute content from any publicly available URL to various destinations such as e-mail, OracleAS Portal, and WebDav. Since 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 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.
If the URL engine is not activated, you can activate it 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 13, "Running Report Requests".
Some features of OracleAS 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, 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:
proxyinfo.xml). For example, your pluginParam element might be as follows:
<pluginParam name="proxy" type="file">proxyinfo.xml</pluginParam>
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>
The best way to start, shutdown, monitor, and manage Reports Server is through the Oracle Process Manager and Notification Server (OPMN) and Oracle Enterprise Manager. OPMN provides a centralized mechanism for initializing, maintaining, and shutting down your Oracle Application Server components, including Reports Server. Oracle Enterprise Manager, included with Oracle Application Server, provides managing and monitoring services to OracleAS Reports Services. You can conveniently monitor your Reports Servers through Oracle Enterprise Manager and, if the process crashes for any reason, OPMN restarts Reports Server for you automatically.
During installation of Oracle Application Server, Reports Servers are automatically configured in OPMN and registered with Oracle Enterprise Manager. If you add any Reports Servers after installing Oracle Application Server, you should register the new server(s) in two places:
opmn.xml file.
targets.xml file.
To register a new Reports Server in both opmn.xml and targets.xml, run the following command line:
On UNIX:
ORACLE_HOME/bin/addNewServerTarget.sh reports_server_name
On Windows:
ORACLE_HOME\bin\addNewServerTarget.bat reports_server_name
You can add a Reports Server to OPMN using addNewServerTarget.sh (UNIX) or addNewServerTarget.bat (Windows). However, to view the Reports Server on the Enterprise Manager page, you must restart OPMN by using the following commands:
opmnctl stopall opmnctl startall
Components are configured with OPMN in the opmn.xml file located in ORACLE_HOME/opmn/conf. To configure Reports Server through OPMN, you need the following in opmn.xml:
The module tag is included by default in opmn.xml and tells OPMN that it needs to load a particular module. In the case of Reports Server, the OracleAS Reports Services module must be loaded. This module is loaded with the following information by default in opmn.xml:
<module path="/private/oraclehome/opmn/lib/libopmnreports"> <module-id id="ReportsServices"/> </module>
In the case of the standalone Reports Server, the Reports Server is running in its own component. Therefore, you must specify a separate component for Reports Server. For example:
<ias-component id="<RSName>" status="enabled" id-matching="false"> <process-type id="ReportsServer" module-id="ReportsServices"> <process-set id="<RSName>" restart-on-death="true" numprocs="1"> <environment> <variable id="PATH" value="your_shell_path"/> </environment> <module-data> <category id="general-parameters"> <data id="batch" value="yes"/> </category> <category id="restart-parameters"> <data id="reverseping-timeout" value="120"/> </category> </module-data> <dependencies> <OID infrastructure="true"/> <database infrastructure-key="portal"/> <managed-process ias-component="OC4J" process-type="OC4J_BI_Forms" process-set="default_island" autostart="true"/> <managed-process ias-component="HTTP_Server" process-type="HTTP_Server" process-set="HTTP_Server" autostart="true"/> <managed-process ias-component="WebCache" process type="WebCache" process_set="WebCache" autostart="true"/> </dependencies> <start timeout="120" retry="3"/> <stop timeout="120"/> <restart timeout="120"/> <ping timeout="30" interval="30"/> </process-set> </process-type> </ias-component>
The key segments of this specification for Oracle Reports are described below.
<ias-component id="<RSName>" ...>
This tag specifies the name of Reports Server. It must match the Reports Server internal name from targets.xml.
|
See Also:
Chapter 19, "Managing and Monitoring OracleAS Reports Services"
For more information about |
<process-type id="ReportsServer" module-id="ReportsServices">
This tag defines the process for the named Reports Server and associates it with the OracleAS Reports Services process module.
<process-set id="<RSName>" restart-on-death="true" numprocs="1">
This tag defines the process characteristics for the named Reports Server. It indicates whether Reports Server should be restarted when it crashes. It also specifies the number of Reports Servers started for this process set, which has to be 1 because the process-set id identifies a single Reports Server name.
<variable id="PATH" value="your_shell_path"/>
The first tag specifies the value for the PATH environment variable for the process. This variable must be set for the start script to find uname. This environment element is not needed on the Microsoft Windows platform.
<category id="general-parameters"> <data id="batch" value="yes"/> </category>
This group of tags gathers together all of the data (parameters) common to the process. In this particular example, it provides a way to specify that the BATCH parameter be sent to Reports Server. batch=yes|no is an option to the start and stop commands of Reports Server. If it is not configured, this option is not passed in to Reports Server.
<category id="restart-parameters"> <data id="reverseping-timeout" value="120"/> </category>
This group of tags indicates the restart parameters category, which defines parameters to be used in detecting whether the process has failed and needs to be restarted. If a notification is not received within the specified reverseping-timeout period, then the process is considered failed and will be restarted.
<dependencies>
This tag delimits the list of components upon which Reports Server depends. For example, Reports Server typically depends upon, among other things, the Oracle HTTP Server and Oracle Application Server Containers for J2EE.
OPMN uses dependencies to determine whether to start a process. Like module-data and environment blocks, dependencies blocks can be defined for multiple elements within opmn.xml. OPMN creates an aggregate dependency list at the process set level that contains all of the dependencies defined at or above it. If duplicate dependencies are defined at different levels, then duplicate checks on that dependency are made before starting a process.
OPMN has two primary types of dependencies: external and internal. External dependencies are resources not managed by OPMN (the database, Oracle Internet Directory, and OracleAS Single Sign-On). For external resources, an external program performs the check on the resource. Internal dependencies are OPMN-managed processes, which may include processes managed by a remote OPMN instance. Internal dependencies are indicated in the list by the managed-process tag.
OPMN maintains a cache of dependency states that contains the last known state of each dependency and the time it was last checked. A single cache entry exists for each dependency with identical attributes, even if that dependency is specified in multiple locations (i.e., for different process sets). A cache timeout parameter for each dependency allows users to specify how long to use its state in the cache. Likewise, a general timeout parameter for each dependency determines how long OPMN should wait for a status update before aborting the dependency check and the process start.
Dependencies are checked in the order in which you declare them. The traversal of this list of dependencies concludes either when the full sequence of checks completes successfully (the resource is available) or when one of the checks fails (the resource is not available or the check timed out).
The following example tags illustrate a typical list of dependencies for Reports Server:
<OID infrastructure="true"/> <database infrastructure-key="portal"/> <managed-process ias-component="OC4J" process-type="OC4J_BI_Forms" process-set="default_island" autostart="true"/> <managed-process ias-component="HTTP_Server" process-type="HTTP_Server" process-set="HTTP_Server" autostart="true"/> <managed-process ias-component="WebCache" process-type="WebCache" process-set="WebCache" autostart="true"/>
The OID tag indicates that Reports Server uses the default Oracle Internet Directory instance for this Oracle Application Server installation.
The database tag points to the OracleAS Portal instance used by Reports Server.
The first managed-process tag specifies the Oracle Application Server Containers for J2EE instance used by Reports Server. The second managed-process tag indicates the Oracle HTTP Server instance.
In the case of the in-process Reports Server, the Reports Server is running inside the OC4J component. If you are using the in-process Reports Server, then, within the OC4J component, you must specify the Reports Server data. For example:
<ias-component id="OC4J"> <process-type id="OC4J_BI_Forms"> <module-data> <category id="urlping-parameters"> <data id="/reports/rwservlet/pingserver?start=auto" value="200"/> </category> </module-data> <process-set .../> </process-type> </ias-component>
The key segments of this specification are described below.
<category id="urlping-parameters">
urlping-parameters is a category that identifies all of the URLs to be pinged by the OC4J module. The protocol used for pinging is AJPv1.3.
<data id="/reports/rwservlet/pingserver?start=auto" value="200"/>
/reports/rwservlet/pingserver?start=auto is the URL to be pinged by the OC4J module. In the context of the in-process Reports Server, pinging this URL allows OPMN to determine whether the Reports Server application is responsive. If it is unresponsive, OPMN restarts the corresponding OC4J process.
value=200 specifies a valid HTTP code (200) that is expected in response to the ping request. If the response HTTP code matches the value configured here, OPMN considers the application healthy and responsive. Otherwise, OPMN restarts the OC4J process.
In previous releases of OracleAS Reports Services on UNIX, you had to set the DISPLAY environment variable for Reports Server. Previous releases required DISPLAY to use the windowing system display surface for creating images and getting pixel resolution. This dependency is removed in OracleAS Reports Services 10g (9.0.4).
Additionally, previous releases required a valid printer on UNIX for fonts. When no valid printer was available, OracleAS Reports Services used the screen fonts, which again required setting the DISPLAY environment variable. In Release 10g (9.0.4), OracleAS Reports Services includes a default screen printer surface, ScreenPrinter, that emulates a screen or printer for fonts in the absence of an available printer. As a result, OracleAS Reports Services does not require a printer on UNIX as of OracleAS Reports Services 10g (9.0.4).
By default, the environment variable REPORTS_DEFAULT_DISPLAY is set to YES, which specifies that OracleAS Reports Services should:
DISPLAY environment variable (UNIX only)
If you wish to revert to the old behavior from previous releases, you can set REPORTS_DEFAULT_DISPLAY=NO.
|
See Also:
Appendix B, "Reports-Related Environment Variables" For more information on Oracle Reports environment variables. |
The PostScript printer driver screenprinter.ppd provides surface resolution for images and specifies font information. This driver is the first entry in uiscreenprint.txt. The file locations (UNIX only) are:
uiscreenprint.txt : ORACLE_HOME/guicommon9/tk90/admin screenprinter.ppd : ORACLE_HOME/guicommon9/tk90/admin/PPD
ScreenPrinter is used for:
If, when generating report output, there is no valid printer queue available (not found from TK_PRINTER,ORACLE_PRINTER,PRINTER, or uiprint.txt), the surface based on screenprinter.ppd will be created and used to get font information. You can modify the Fonts section of screenprinter.ppd to include new fonts, and modify the DefaultResolution field to change the resolution (DefaultResolution is 96).
The font look up algorithm on UNIX is:
if a valid printer available then look up font information from the printer else create a screenPrinter surface look up font information from ScreenPrinter if ScreenPrinter creation fails then REP-1800 : Formatter Error if REPORTS_DEFAULT_DISPLAY is set else use Screen Fonts
The quality of images contributes considerably to the overall appearance of a report, particularly for a Web report. You may prefer different image formats in your report output depending on the needs of your project. For example, an aeronautical firm might prefer the higher quality of JPEG or PNG images in their Web reports instead of GIF images. On the other hand, if you are building a Web portal, you might prefer GIF images because of their smaller size and faster download. Similarly, you may wish to import images of these various formats into your report.
Depending on the format of your output, you may choose from a variety of formats for your images.
| Report Output | Available Image Format Choices |
|---|---|
|
HTML,HTMLCSS |
PNG, JPEG, JPG, GIF |
|
|
PNG, JPEG, JPG, GIF |
|
RTF |
PNG, JPEG, JPG, BMP |
To enable advanced imaging, you must set the REPORTS_DEFAULT_DISPLAY environment variable to YES. The REPORTS_DEFAULT_OUTPUTIMAGEFORMAT environment variable lets you choose the default image type. Users can override the default choice for images with the OUTPUTIMAGEFORMAT command line keyword. For example:
rwclient server=my_rep_server report=images.rdf destype=file desformat=html desname=images.html userid=scott/tiger outputimageformat=PNG
Enabling advanced imaging also allows you to import images of these same formats into your report.
The in-process server does not recognize the default printer of a user currently logged on to Windows. This is because the service that runs the in-process server is logged on as the Local System. Therefore, you might face the following issues:
REP_3002 error. For example, the following command:
http://myrepsrvr.us.oracle.com:7777/reports/rwservlet?report=myrep.rdf&desty pe=printer&desformat=html
will result in the following error:
Error:"REP-3002: Error initializing printer. Please make sure a printer is installed."
To work around the issue:
regedit.exe).
HKEY_CURRENT_USER\Software\Microsoft\Windows NT\CurrentVersion\Windows
Device for this key. For example:
\\MOWGLI\sierra,winspool,Ne02:
HKEY_USERS\.DEFAULT\Software\Microsoft\Windows NT\CurrentVersion\Windows
Device value copied from HKEY_CURRENT_USER (the string value of Device for this key will be empty).
|
 Copyright © 2003 Oracle Corporation. All Rights Reserved. |
|