The configuration settings for the Reports Server component of Oracle Reports Services are stored in the XML file rwserver.conf and rwbuilder.conf, located in the directories specified in Table 7-1.
Both files are supported by the rwserver.template file in ORACLE_HOME\reports\conf, which contains default server configuration values on both Windows and UNIX.
The rwserver.conf file is the default server configuration file. The rwbuilder.conf file configures the server instance used in-process by Oracle Reports Builder.
The rwserver.conf and rwbuilder.conf files are nearly identical. The only difference between them is that rwbuilder.conf does not use the persistFile or security configuration elements, described later in this section.
Both of these files are created automatically, under the following circumstances:
The rwserver.conf file is created when a new Reports Server component is created.
The rwbuilder.conf file is created when a new Reports Tools component is created.
This section describes:
The rwserverconf.xsd file provides the following data type definitions for configuring rwserver.conf and rwbuilder.conf elements and attributes:
These elements along with their related attributes and sub-elements are discussed in the following subsections.
Note that these are XML elements, and XML is case-sensitive. Additionally, when you add any of these elements to the rwserver.conf or rwbuilder.conf configuration file, you must follow the order of elements as described in rwserverconf.xsd.
The ORBPorts element is defined in rwserverconf.xsd as follows:
<xs:element name="ORBPorts">
<xs:complexType>
<xs:attribute name="value" use="required" type="xs:string"/>
</xs:complexType>
</xs:element>
In rwserver.conf, the ORBPorts element may be specified as shown in this example:
To specify a port range:
<ORBPorts value="17000-17010"/>
To specify specific ports:
<ORBPorts value="17000,17010,17020,17030,17040"/>
Optional. By default, CORBA objects use any available port for communication. Since Reports Server uses CORBA for communication, it will use any available free port for communication. If you want Reports Server to use predefined ports instead of random ports, you must include the ORBPorts element in the server configuration file.
The ORBPorts element specifies either a range of ports or specific ports for CORBA communication. When ORBPorts is specified, Reports Server will choose one of the ports from the list specified for ORB internal communication. One port is needed for Reports Server and one for each engine.
Note:
TheORBPorts element is used to assign specific ports to Reports Server and engines for running report and other requests. Do not confuse these ports with those you see in Oracle Enterprise Manager through the Ports link, which are ports reserved for Reports Server discovery mechanism and the Oracle Reports Bridge component.You cannot specify port numbers for individual engines. Each engine picks up the next port number in the list. Suppose you have the maxengine attribute of the engine element set to 5 for rwEng, and URLEng is also enabled, then you must specify a minimum of 7 ports in the ORBPorts element (1 for Reports Server + 5 for rwEng + 1 for rwURLEng).
The ORBPorts element attribute is described in Table 7-2.
Table 7-2 Attribute of the ORBPorts Element
| Attribute | Valid Values | Description |
|---|---|---|
|
|
Range of values or Numbers separated by commas |
The port range that can be used for Reports Server and engine communication through CORBA. |
Note:
TheORBPorts element should be defined only if you have enabled TCP port filtering on your server where Reports Server is running. If port filtering is enabled, you can open few ports for Reports Server, then use ORBPorts to specify them in the server configuration file for Reports Server/engine communication. If any of the ports are not available, Reports Server or engines may fail to start and an error displays.The pluginParam element is defined in rwserverconf.xsd as follows:
<xs:element name="pluginParam">
<xs:complexType mixed="true">
<xs:sequence>
<xs:element ref="property" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
<xs:attribute name="name" use="required" type="xs:ID"/>
<xs:attribute name="value" use="required" type="xs:string"/>
<xs:attribute name="type" default="text">
<xs:simpleType>
<xs:restriction base="xs:NMTOKEN">
<xs:enumeration value="text"/>
<xs:enumeration value="file"/>
<xs:enumeration value="url"/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
</xs:complexType>
</xs:element>
In rwserver.conf, the pluginParam element may be specified as shown in this example:
<pluginParam name="mailServer" value="mail.oracle.com"> <property name="enableSSL" value="yes"/> <property name="mailUserName" value="%MAILUSER%"/> <property name="mailPassword" value="%xyz%"/> </pluginParam>
Optional. You can have as many pluginParam elements as you require.
The pluginParam element provides a means of specifying plug-ins that can be used by several built-in destinations such as e-mail, JDBC pluggable data source (PDS), Text PDS, and so on. It is not used by the FTP and WebDAV built-in destinations, and is not available to custom pluggable destinations, such as fax. Now every server has its own textpds.conf, jdbcpds.conf and xmlpds.conf files.
You can specify any plug-in parameter and name it in any way as long as it is supported or required by the built-in destination.
The pluginParam element attributes are described in Table 7-3.
Table 7-3 Attributes of the pluginParam Element
| Attribute | Valid Values | Description |
|---|---|---|
|
Mail Server. |
string |
The name of the plug-in parameter. See Properties below for information about specifying the |
|
string |
The value of the specified plug-in parameter. |
|
|
|
Default: Describes the type of plug-in being specified. For For For Note that when you have a default type ( |
You can also optionally enter multiple property sub-elements for the pluginParam element. The only requirement is that they be name/value pairs recognized by the specified plug-in parameter. For example:
<pluginParam name="mailServer" value="%MAILSERVER%"> <property name="enableSSL" value="yes"/> </pluginParam>
In this example, the property sub-element specifies the enableSSL property, which is only applicable to mailServer. If the specified mailServer is SSL-enabled, it rejects plain connection requests, so it is necessary to use SSL Sockets to establish a connection with the specified mailServer and send emails, by default, the value of enableSSL is no for compatibility with prior releases.
The cache element is defined in rwserverconf.xsd as follows:
<xs:element name="cache">
<xs:complexType>
<xs:sequence>
<xs:element ref="property" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
<xs:attribute name="class" default="oracle.reports.cache.RWCache"
type="xs:string"/>
</xs:complexType>
</xs:element>
In rwserver.conf, the cache element may be specified as shown in this example:
<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 specifies 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 Oracle Reports Services Cache API.
Note:
For more information about thecache API, refer to Oracle Reports Java API Reference on the Oracle Technology Network (OTN) at (http://www.oracle.com/technetwork/middleware/reports/overview/index.html).The cache element attribute is described in Table 7-4.
Table 7-4 Attribute of the cache Element
| Attribute | Valid Values | Description |
|---|---|---|
|
See the Description column |
Default: A fully qualified Java class that implements the |
You can also optionally enter multiple property sub-elements for the cache element. The only requirement is that they be name/value pairs recognized by the implementation class you register under cache. For example, if you use the default cache Java class that is provided with Oracle 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="home/john/HRInstance/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"/>
Maximum Cached Files.
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"/>
The connection element is defined in rwserverconf.xsd as follows:
<xs:element name="connection">
<xs:complexType>
<xs:sequence>
<xs:element ref="orbClient" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
<xs:attribute name="idleTimeOut" default="15">
<xs:simpleType>
<xs:restriction base="xs:integer">
<xs:minInclusive value="1"/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="maxConnect" default="50">
<xs:simpleType>
<xs:restriction base="xs:integer">
<xs:minInclusive value="1"/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
</xs:complexType>
</xs:element>
In rwserver.conf, the connection element may be specified as shown in this example:
<connection idleTimeOut="20" maxConnect="50" > <orbClient id="RWClient" publicKeyFile="clientpub.key"/> </connection>
Optional. If you do not specify a connection element in your server configuration file, default values will be used (see Table 7-5). 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.
The connection element attributes are described in Table 7-5.
Table 7-5 Attributes of the connection Element
| Attribute | Valid Values | Description |
|---|---|---|
|
Connection Idle Timeout (min). |
Number |
Default: Allowable amount of time in minutes the connection can be idle. |
|
Maximum Connections. |
Number |
Default: The maximum number of requests that Reports Server can service simultaneously. Requests in excess of the |
The connection element also includes the orbClient sub-element, described in Section 7.2.1.16, "orbClient".
The destination element is defined in rwserverconf.xsd as follows:
<xs:element name="destination">
<xs:complexType>
<xs:sequence>
<xs:element ref="property" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
<xs:attribute name="class" use="required" type="xs:string"/>
<xs:attribute name="destype" use="required" type="xs:string"/>
</xs:complexType>
</xs:element>
In rwserver.conf, the destination element may be specified as shown in this example:
<destination destype="oraclePortal" class="oracle.reports.server.DesOraclePortal">
<property name="portalUserid"
value="portal_db_username/portal_password@portal_db_connection"
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, e-mail, file, cache, and Oracle 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.
You need not register the following default destinations:
Cache
Printer
File
FTP
WebDAV
You may want to register the following default destination:
Oracle Portal: The entry for this destination is created by default in the server configuration file, but it is commented out. To start using this destination, you must uncomment the destination entry, and also provide appropriate property values (for example, the value for the portalUserid property).
You must register any new destination types you create through the Oracle Reports Services Destinations API.
Note:
For more information about thedestination API, refer to Oracle Reports Java API Reference on the Oracle Technology Network (OTN) at (http://www.oracle.com/technetwork/middleware/reports/overview/index.html).
Configuring destinations is discussed in detail in Chapter 13, "Configuring Destinations for Oracle Reports Services".
The destination element attributes are described in Table 7-6.
Table 7-6 Attributes of the destination Element
| Attribute | Valid Values | Description |
|---|---|---|
|
string |
A fully qualified Java class that is a subclass of Reports Server Destination Java class (
|
|
|
string |
Identifies the destination type; for example:
|
You can also optionally enter multiple property sub-elements for 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="dbuser" value="$$PORTAL_DB_USERNAME$$"/>
<property name="dbpassword" value="csf:$$CSF_ALIAS$$:$$PORTAL_DB_PASSWORD_KEY$$"/>
<property name="dbconn" value="$$PORTAL_DB_TNSNAME$$"/>
</destination>
In this example, the property sub-element provides connect information to enable Reports Server to access Oracle Portal. The encrypted attribute is included to automatically invoke encryption on the portalUserid value the next time Reports Server is started.
Note:
ForportalUserid database connection strings, both the thin (scott/tiger@testhost.mydomain.com:1521:iasdb) and Oracle Call Interface (scott/tiger@ordb) JDBC formats are supported.Should your destination implementation require additional information, specify the information in the pluginParam element.
The environment element is defined in rwserverconf.xsd as follows:
<xs:element name="environment">
<xs:complexType>
<xs:sequence>
<xs:element ref="envVariable" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
<xs:attribute name="id" use="required" type="xs:ID"/>
</xs:complexType>
</xs:element>
In rwserver.conf, the environment element may be specified as shown in this example:
<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 (that is, environment variables) that you want to use to establish a particular runtime environment. You may include as many environment elements as you need (for example, one for each language/territory you must 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:
The 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 Section 7.2.1.8, "engine".
The command line keyword, ENVID, of your report's job request, which makes the environment settings only effective for that particular report job request.
The environment element attribute is described in Table 7-7.
Table 7-7 Attribute of the environment Element
| Attribute | Valid Values | Description |
|---|---|---|
|
Default Env ID. |
string |
The name of the environment. |
The environment element includes one or more envVariable sub-elements, described in Section 7.2.1.7, "envVariable".
The envVariable element is defined in rwserverconf.xsd as follows:
<xs:element name="envVariable">
<xs:complexType>
<xs:attribute name="name" use="required" type="xs:string"/>
<xs:attribute name="value" use="optional" type="xs:string"/>
</xs:complexType>
</xs:element>
In rwserver.conf, the envVariable element may be specified as shown in this example:
<envVariable name="NLS_LANG" value="Japanese_Japan.JA16SJIS"/> <envVariable name="NLS_CURRENCY" value="¥"/> <envVariable name="DISPLAY" value="MyServer.MyCompany.com:0.0"/>
Optional.
Each envVariable is specified as a name–value pair. They can be either standard environment variables or user-defined environment variables.
envVariable is a sub-element of the environment element.
The envVariable element attributes are described in Table 7-8.
Table 7-8 Attributes of the envVariable Element
| Attribute | Valid Values | Description |
|---|---|---|
|
Add. |
string |
The name of the environment you wish to use (for example, |
|
Add. |
string |
The value you want to assign to the environment variable identified with the name attribute (for example, Japanese_Japan.JA16SJIS). |
The engine element is defined in rwserverconf.xsd as follows:
<xs:element name="engine">
<xs:complexType>
<xs:sequence>
<xs:element ref="property" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
<xs:attribute name="id" use="required" type="xs:string"/>
<xs:attribute name="class" use="required" type="xs:string"/>
<xs:attribute name="maxEngine" use="required">
<xs:simpleType>
<xs:restriction base="xs:integer">
<xs:minInclusive value="1"/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="minEngine" use="required">
<xs:simpleType>
<xs:restriction base="xs:integer">
<xs:minInclusive value="0"/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="engLife" use="required">
<xs:simpleType>
<xs:restriction base="xs:integer">
<xs:minInclusive value="1"/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="maxIdle" default="30">
<xs:simpleType>
<xs:restriction base="xs:integer">
<xs:minInclusive value="1"/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="callbackTimeOut" default="90000">
<xs:simpleType>
<xs:restriction base="xs:integer">
<xs:minInclusive value="60000"/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="engineResponseTimeOut">
<xs:simpleType>
<xs:restriction base="xs:integer">
<xs:minInclusive value="1"/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="initEngine" type="xs:integer"/>
<xs:attribute name="jvmOptions" type="xs:string"/>
<xs:attribute name="classPath" type="xs:string"/>
<xs:attribute name="defaultEnvId" type="xs:string"/>
</xs:complexType>
</xs:element>
In rwserver.conf, the engine element may be specified as shown in this example:
<engine id="rwEng" class="oracle.reports.engine.EngineImpl" initEngine="1"
maxEngine="5" minEngine="1" engLife="50" maxIdle="15" callbackTimeOut="90000">
<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.
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 engines provided with Oracle Reports Services or develop your own implementation through the Oracle 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:
For more information about theengine API, refer to Oracle Reports Java API Reference on the Oracle Technology Network (OTN) at (http://www.oracle.com/technetwork/middleware/reports/overview/index.html).The engine element attributes are described in Table 7-9.
Table 7-9 Attributes of the engine Element
| Attribute | Valid Values | Description |
|---|---|---|
|
string |
A keyword, unique within a given configuration XML file that identifies a particular
|
|
|
string |
Default: A fully qualified Java class that implements two interfaces: |
|
|
Maximum Engines. |
number |
Default: The maximum number of this type of engine that can run on the server. |
|
Minimum Engines. |
number |
Default: The minimum number of this type of engine that is maintained by the server. |
|
Maximum Job Before Restart. |
number |
Default: 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. |
|
Maximum Idle Before Shutdown (min). |
number |
Default: The number of minutes of allowable idle time before the engine is shut down However, the current number of engines should be higher than For example, if |
|
number |
Default: 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. |
|
|
Engine Response Timeout (min). |
number |
Default: 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 (for example, due to the engine hanging or a long blocking SQL query), Reports Server terminates the job. |
|
number |
Default: The number of engines you want Reports Server to start at initialization. When running a report using |
|
|
JVM Options. |
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. If this attribute is not specified, the engine running in the server environment uses the JVM options specified by the value of the |
|
string |
The directory path to the Java class specified in the Windows:
UNIX:
|
|
|
Default Env ID. |
string |
(Optional attribute) The default environment within which Reports Server starts an engine. The attribute takes an ID associated with an When If For more information, refer to Section 7.2.2, "Dynamic Environment Switching". |
You can also optionally enter multiple property sub-elements for the engine element. The only requirement is that they be name/value pairs recognized by the Java class that implements the Oracle Reports engine.
Table 7-10 Properties of the engine Element
| Property | Valid Values | Description |
|---|---|---|
|
Reports Source Directory. |
directory path |
The default directory you will use for report definition files. It overrides path information specified in the The directory specified by See the example that follows this table. |
|
Reports Temp Directory. |
directory path |
The name and location of the temporary directory Oracle Reports Services will use for its temporary files. If this value is unspecified for a default engine, Oracle Reports Services uses the temporary directory specified in the See the example that follows this table. |
|
Keep Database Connection. |
|
Default: Used by the default runtime engine implementation (that is,
The This property will be migrated if a |
|
Enable Engine Diagnostics. |
|
Diagnoses whether or not a specific function in a report run completed successfully. The diagnostic log provides information on important checkpoints or tasks in the engine during a report run. This information is useful in cases where the engine stops responding, resulting in "hanging" jobs.
The engine diagnosis option provides more detailed information than report tracing, which is typically used to debug the execution of a report to provide information such as the file currently formatting, or report trigger currently running. See the example that follows this table. |
Example of sourcedir and tempDir properties: If you use the default engine Java class that is provided with Oracle Reports Services, your engine configuration entry might look like this (in a Windows environment):
<engine id="rwEng" class="oracle.reports.engine.EngineImpl" initEngine="1"
maxEngine="5" minEngine="1" engLife="50" maxIdle="15" callbackTimeOut="90000">
<property name="sourceDir" value="D:\orawin\reports\myReport"/>
<property name="tempDir" value="D:\orawin\reports\myTemp"/>
</engine>
The classPath attribute is not specified because this configuration uses the default engine class.
Example of diagnosis property: To enable the engine diagnosis option, your engine configuration element might look like this:
<engine id="rwEng" class="oracle.reports.engine.EngineImpl" initEngine="2"
maxEngine="8" minEngine="1" engLife="1" maxIdle="3" callbackTimeOut="90000">
<property name="diagnosis" value="yes"/>
</engine>
The job element is defined in rwserverconf.xsd as follows:
<xs:element name="job">
<xs:complexType>
<xs:attribute name="engineId" use="required" type="xs:string"/>
<xs:attribute name="jobType" default="report" type="xs:string"/>
<xs:attribute name="securityId" type="xs:string"/>
<xs:attribute name="retry" default="0">
<xs:simpleType>
<xs:restriction base="xs:integer">
<xs:minInclusive value="0"/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
</xs:complexType>
</xs:element>
In rwserver.conf, the job element may be specified as shown in this example:
<job jobType="report" engineId="rwEng" securityId="rwSec" retry="3"/>
Required. You must have at least one job element.
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 Oracle 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.
The job element attributes are described in Table 7-11.
Table 7-11 Attributes of the job Element
| Attribute | Valid Values | Description |
|---|---|---|
|
string |
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 |
|
|
string |
Default: 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. The database authentication functionality provided in Oracle Reports is available only when |
|
|
string |
References the ID entered for the security mechanism that will be applied to this job type. Available IDs are specified under the |
|
|
Job Retries. |
integer |
Default: When This attribute is ignored if the job is explicitly cancelled or when If an invalid value is specified, this attribute is ignored and the default value of If JOBRETRY is specified on the command line, it takes precedence, and the |
The jobRecovery element is defined in rwserverconf.xsd as follows:
<xs:element name="jobRecovery">
<xs:complexType>
<xs:attribute name="auxDatFiles" default="no">
<xs:simpleType>
<xs:restriction base="xs:NMTOKEN">
<xs:enumeration value="yes"/>
<xs:enumeration value="no"/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
</xs:complexType>
</xs:element>
In rwserver.conf, the jobRecovery element may be specified as shown in this example:
<jobRecovery auxDatFiles="yes"/>
Optional. To enable the job recovery mechanism, add the jobRecovery element to the server configuration file. The job recovery mechanism is disabled by default.
The jobRecovery element includes the auxDatFiles attribute. When auxDatFiles=yes, Oracle Reports enables a more resilient job recovery mechanism for maximal retrieval of jobs in case the original.dat file is corrupt due to some reason. When auxDatFiles=yes, Reports Server creates the following two auxiliary files in addition to server_name.dat (the main.dat file):
datfilename_offset.dat contains the auxiliary information of jobs in the main.dat file, which helps in retrieving jobs from the main.dat file.
datfilename_sc.dat contains all scheduled jobs information (in addition to the information stored in main.dat file).
If the job recovery mechanism is enabled, Reports Server on startup reads the main.dat file with the help of the datfilename_offset.dat file using the auxiliary information stored in it. If the main.dat file is corrupt and Reports Server cannot retrieve all the jobs information, it starts reading the datfilename_sc.dat file and recovers the scheduled jobs for this file. Thus, datfilename_sc.dat serves as a backup file, which results in maximum possibility of recovery of scheduled jobs in case of corruption of the main.dat file.
If Reports Server fails to find the datfilename_offset.dat file (for example, when the jobRecovery element is enabled for first time) when the job recovery mechanism is enabled, it reads the jobs from the main.dat file and creates the other two auxiliary files from scratch.
The server_name.dat, datfilename_offset.dat, and datfilename_sc.dat files form a unique triplet, and the auxiliary files are valid only when the job recovery mechanism is enabled. If the auxiliary files are found when the job recovery mechanism is disabled, Reports Server deletes these files from the file system to maintain the integrity between these files. For this reason, you must always handle these three files together (for example, if you are copying a file from one machine to another, you must copy these three files together).
The jobRecovery element attribute is described in Table 7-12.
The jobStatusRepository element is defined in rwserverconf.xsd as follows:
<xs:element name="jobStatusRepository">
<xs:complexType>
<xs:sequence>
<xs:element ref="property" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
<xs:attribute name="class" default="oracle.reports.server.JobRepositoryDB"
type="xs:string"/>
</xs:complexType>
</xs:element>
In rwserver.conf, the jobStatusReposity element may be specified as shown in this example:
<jobStatusRepository> <property name="dbuser" value="<dbuser>"/> <property name="dbpassword" value=csf:reports:"<dbkey>"/> <property name="dbconn" value="<dbconn>"/> </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 element 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.
The jobStatusRepository element attribute is described in Table 7-13.
Table 7-13 Attribute of the jobStatusRepository Element
| Attribute | Valid Values | Description |
|---|---|---|
|
Enable Job Repository DB. |
string |
Default: A fully qualified Java class that implements the Reports Server Job Repository Java class ( |
You can also optionally enter multiple property sub-elements for the jobStatusRepository element for passing options into the repository. The only requirement is that they be name/value pairs recognized by the class you specify in the server configuration file.
The jobStatusRepository element might look like this in your server configuration file:
<jobStatusRepository> <property name="dbuser" value="<dbuser>"/> <property name="dbpassword" value=csf:reports:"<dbkey>"/> <property name="dbconn" value="<dbconn>"/> </jobStatusRepository>
Note:
Oracle Reports uses thedbconn property of the jobstatusrepository element to connect to the database when updating the log information about job queues.The log element is defined in rwserverconf.xsd as follows:
<xs:element name="log">
<xs:complexType>
<xs:attribute name="option" default="noJob">
<xs:simpleType>
<xs:restriction base="xs:NMTOKEN">
<xs:enumeration value="allJobs"/>
<xs:enumeration value="succeededJobs"/>
<xs:enumeration value="failedJobs"/>
<xs:enumeration value="noJob"/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
</xs:complexType>
</xs:element>
In rwserver.conf, the log element may be specified as shown in this example:
<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_INSTANCE /diagnostics/logs/ReportsSeverComponent/<reports_server_name>/rwserver_diagnostic.log
The log element attribute is described in Table 7-14.
Table 7-14 Attribute of the log Element
| Attribute | Valid Values | Description |
|---|---|---|
|
|
Default: Describes the type of jobs that are logged. This is in addition to the default server activities that are logged. Choose from the following options:
|
The jobRepository element is defined in rwserverconf.xsd as follows:
<xs:element name="jobRepository">
<xs:complexType>
<xs:sequence>
<xs:element ref="property" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
</xs:element>
In rwserver.conf, the jobRepository element may be specified as shown in this example:
<jobRepository> <property name="dbuser" value="dbuser"/> <property name="dbpassword" value="csf:reports:dbpasswdKey"/> <property name="dbconn" value="dbconn"/> </jobRepository>
Required in a high availability (HA) environment. Optional in a non-HA environment. You can have a maximum of one jobRepository element in your server configuration file.
The jobRepository element enables you to store all job information in the database instead of the file system (that is, in DAT files). This element is mandatory if you want to use high availability (HA), because Reports Servers in the group share job information, which is possible only if the job information is stored in the database, and not individual DAT files.
The jobRepository element has no attributes.
jobRepository requires only one property sub-element, repositoryconn. and the jobRepository element enables you to store all job information in the database or the file system (that is, in DAT files).
The notification element is defined in rwserverconf.xsd as follows:
<xs:element name="notification">
<xs:complexType>
<xs:sequence>
<xs:element ref="property" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
<xs:attribute name="class" use="required" type="xs:string"/>
<xs:attribute name="id" default="mailNotify" type="xs:string"/>
</xs:complexType>
</xs:element>
In rwserver.conf, the notification element may be specified as shown in this example:
<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 through e-mail, or design your own with the Oracle Reports Notification API.
Note:
For more information about thenotification API, refer to Oracle Reports Java API Reference on the Oracle Technology Network (OTN) at (http://www.oracle.com/technetwork/middleware/reports/overview/index.html).The notification element attributes are described in Table 7-15.
Table 7-15 Attributes of the notification Element
| Attribute | Valid Values | Description |
|---|---|---|
|
string |
Default: 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 the Reports Server Notification Java class |
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 command line keyword notifysuccess and notifyfailure to specify the email address where notification should be sent (see Appendix A, "Command-Line Keywords"). 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/>
The succNoteFile and failNoteFile Email notification file for success and Email notification file for failure.
Some mail servers may validate the sender's domain name. If the notification fails because of this domain name validation, then you must add the following property as part of the notification element:
<property name="sender" value="valid email address"/>
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.
The oidconnection element is defined in rwserverconf.xsd as follows:
<xs:element name="oidconnection">
<xs:complexType>
<xs:attribute name="increment" default="10" type="xs:integer"/>
<xs:attribute name="init" default="10" type="xs:integer"/>
<xs:attribute name="timeout" default="0" type="xs:integer"/>
</xs:complexType>
</xs:element>
In rwserver.conf, the oidconnection element may be specified as shown in this example:
<oidconnection init="10" increment="10" timeout="600"/>
Optional.
The oidconnection element specifies Oracle Internet Directory connection pooling parameters for Reports Server. In a production environment, you can use this parameter to provide granular control over Oracle Internet Directory connection pooling of Reports Server, namely:
The number of connections to keep open in the pool when Reports Server is initialized.
Upon exhausting the available connections, the number of new connections to be added to the pool when a new request arrives.
The timeout for closing idle open Oracle Internet Directory connections to reduce the resource usage.
The oidconnection element attributes are described in Table 7-16.
Table 7-16 Attributes of the oidconnection Element
| Attribute | Valid Values | Description |
|---|---|---|
|
number |
Default: Initial number of Oracle Internet Directory connections to be created when Reports Server is initialized. |
|
|
number |
Default: Number of connections to be incremented when all connections are used up. |
|
|
number |
Default: Time in seconds for which a connection can be idle before it is closed. |
Note:
Setting much lower or higher values than the default values for these attributes can have a performance impact on Oracle Reports Services. In a typical production environment, the default values are recommended.For Oracle Reports Servlet (rwservlet), you can specify Oracle Internet Directory connection pooling parameters using the oidconnection element in the rwservlet.properties file.
The orbClient element is defined in rwserverconf.xsd as follows:
<xs:element name="orbClient">
<xs:complexType>
<xs:attribute name="id" use="required" type="xs:string"/>
<xs:attribute name="publicKeyFile" use="required" type="xs:string"/>
</xs:complexType>
</xs:element>
In rwserver.conf, the orbClient element may be specified as shown in this example:
<orbClient id="RWClient" publicKeyFile="clientpub.key"/>
Optional. If you do not specify the orbClient element in your server configuration file, the default values will be used.(see Table 7-17)
The orbClient element specifies 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 elements in your server configuration file.
orbClient is a sub-element of the connection element
The orbClient element attributes are described in Table 7-17.
Table 7-17 Attributes of the orbClient Element
| Attribute | Valid Values | Description |
|---|---|---|
|
string |
Default: Identifies the Reports Client to be served by the public and private key. |
|
|
|
Default: Identifies 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. The default file is stored in the |
Oracle 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 Oracle 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:
On Windows:
rwgenkey.bat path_and_client_public_key_file_name path_and_client_private_key_file_name
On 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.
The persistFile element is defined in rwserverconf.xsd as follows:
<xs:element name="persistFile">
<xs:complexType>
<xs:attribute name="fileName" type="xs:string"/>
</xs:complexType>
</xs:element>
In rwserver.conf, the persistFile element may be specified as shown in this example:
<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 attribute is described in Table 7-18.
Table 7-18 Attribute of the persistFile Element
| Attribute | Valid Values | Description |
|---|---|---|
|
string |
Default: The name and, optionally, the path of the server persistent file. You can leave the path off if the file is kept in its default directory:
The path is the same for Windows or UNIX. |
The identifier element is defined in rwserverconf.xsd as follows:
<xs:element name="identifier">
<xs:complexType mixed="true">
<xs:attribute name="encrypted" default="no">
<xs:simpleType>
<xs:restriction base="xs:NMTOKEN">
<xs:enumeration value="yes"/>
<xs:enumeration value="no"/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
</xs:complexType>
</xs:element>
In rwserver.conf, the identifier element may be specified as shown in this example:
<identifier 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 by the Reports Configuration Assistant when you first install Oracle Reports. The Reports Configuration Assistant sets the values in the form SERVERACCESSKEY/12312312313, where SERVERACESSKEY is the user name and the random generated number (12312312313) is the password. This user name and password is then encrypted and written to rwserver.template and targets.xml during the time of configuring Oracle Reports Services. Any Reports Server started after the installation will have this identifier information stored in its configuration file.
For a non-secured Reports Server, the values of the identifier element is used when:
Connecting to a Reports Server through the Reports Queue Manager.
Shutting down a Reports Server through the command line.
In either of these cases, you must provide the authid in the command line that matches the values specified in the identifier element. To provide a specific password (as the password is a pseudo random number), you must do the following:
Edit the server configuration file, rwserver.conf.
Replace the encrypted username/password values generated with custom values.
Set encrypted=no.
For example:
<identifier encrypted="no">username/password</identifier>
Restart Reports Server. Reports Server sets encrypted=yes when it restarts.
Edit the targets.xml file and specify the same username and password values that were included in the rwserver.conf file.
You should restart Reports Server, immediately, after making this change. Reports Server automatically encrypts the user name and password and resets encrypted to yes. The values should now read as follows:
<identifier encrypted="yes">fpoiVNFvnlkjRPortn+sneU88=NnN</identifier>
For a secure Reports Server, the authentication is done by the security infrastructure; that is, by using the Oracle Internet Directory repository. Thus, you cannot pass the values in the identifier element to shut down a Reports Server or launch Reports Queue Manager through the console window.
Note:
This user name and password is also used for accessing Web commands, such asgetjobid, getserverinfo, showjobs, and showenv when DIAGNOSTIC=NO in the rwservlet.properties file. When DIAGNOSTIC=NO, Web commands are disabled for everyone except those administrators who have this user name and password.For more information on Reports Queue Manager, see the Reports Queue Manager online Help. For more information on rwservlet.properties, refer to Section 7.3, "Oracle Reports Servlet Configuration File".
The property element is defined in rwserverconf.xsd as follows:
<xs:element name="property">
<xs:complexType>
<xs:attribute name="name" use="required" type="xs:string"/>
<xs:attribute name="value" use="required" type="xs:string"/>
<xs:attribute name="encrypted" type="xs:string"/>
</xs:complexType>
</xs:element>
See the following element descriptions for information about specifying the property element in rwserver.conf:
The queue element is defined in rwserverconf.xsd as follows:
<xs:element name="queue">
<xs:complexType>
<xs:attribute name="maxQueueSize" default="1000">
<xs:simpleType>
<xs:restriction base="xs:integer">
<xs:minInclusive value="100"/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
</xs:complexType>
</xs:element>
In rwserver.conf, the queue element may be specified as shown in this example:
<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 maxQueueSize, 1000, will remain in effect.
Use the queue element to specify the maximum number of jobs that can be held in a completed job queue. Oracle Reports Services has three queue components:
a queue of scheduled jobs
a queue of jobs in progress
a queue of completed jobs
The queue element provides the allowable value for each of these components.
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.By default reports server queue size is 1000 jobs.
If you increase the queue size to more than 3000, and use Reports Queue Manager (rwrqm.exe) to monitor the queue, Queue Manager may fail. When a queue size of 3000 or greater is required, use Oracle Reports Servlet (rwservlet) to manage and monitor the Reports Server jobs queue.
The queue element attribute is described in Table 7-19.
The folderAccess element is defined in rwserverconf.xsd as follows:
<xs:element name="folderAccess">
<xs:complexType>
<xs:sequence>
<xs:element name="read" type="xs:string"/>
<xs:element name="write" type="xs:string"/>
</xs:sequence>
</xs:complexType>
</xs:element>
In rwserver.conf, the folderAccess element may be specified as shown in following two examples:
<folderAccess> <read>c:\myreports\*;C:\Samples\*</read> <write>c:\myoutputs\*</write> </folderAccess>
Note:
In the above example, the Samples should be downloaded from OTN locationhttp://www.oracle.com/technetwork/middleware/reports/downloads/index.html and then be placed at local location C:\Samples.The next example specifies access to only the mentioned level folder and sub-folders:
<folderAccess> <read>c:\myreports;C:\Samples\Subsamples</read> <write>c:\myoutputs</write></folderAccess>
Optional.
The folderAccess element defines read and write access to file system folders for both secured and non-secured Reports Server, Reports Application (in-process Reports Server), or Oracle Reports Runtime.
The folderAccess element has no attributes. It includes two sub-elements:
read: specifies the folder(s) to which the Reports Server, Reports Application (in-process Reports Server), or Oracle Reports Runtime has read access only. Enable File System Access Control > Read Directories.
write: specifies the folder(s) to which the Reports Server can write. Enable File System Access Control > Write Directories.
In the example above, the report definition files located in c:\myreports and C:\Samples are allowed to run only. Similarly, when destype=file, the output file can be created only in c:\myoutputs (desname=c:\myoutput\test.pdf).
Note: Blank or * in the read or write sub-element are not allowed. A folder needs to be defined for the <read> or <write> sub-elements and when using it in combination of "*" then any sub-directory under /folder/ can be used. Separate the directory names with a semicolon (;).
The security element is defined in rwserverconf.xsd as follows:
<xs:element name="security">
<xs:complexType>
<xs:sequence>
<xs:element ref="property" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
<xs:attribute name="class" use="required" type="xs:string"/>
<xs:attribute name="id" use="required" type="xs:string"/>
</xs:complexType>
</xs:element>
In rwserver.conf, the security element may be specified as shown in this example for 11g:
<security id="rwJaznSec" class="oracle.reports.server.RWJAZNSecurity"/>
For backward compatibility, the security element may be specified as:
<security id="rwSec" class="oracle.reports.server.RWSecurity"> <property name="oidAppEntity" value="$$Self.oidAppEntity$$"/> <property name="oidUrl" value="$$Self.oidUrl$$"/> <property name="oidPasswdKey" value="$$Self.oidPasswdKey$$"/> <property name="portalUserName" value="$$Self.portalUserName$$"/> <property name="portalConnection" value="$$Self.portalConnection$$"/> <property name="portalPasswdKey" value="$$Self.portalPasswdKey$$"/> </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 Oracle Reports Services, or develop your own implementation through the Reports Server Security API.
Note:
For more information about thesecurity API, refer to Oracle Reports Java API Reference on the Oracle Technology Network (OTN) at (http://www.oracle.com/technetwork/middleware/reports/overview/index.html).The security element attributes are described in Table 7-20.
Table 7-20 Attributes of the security Element
| Attribute | Valid Values | Description |
|---|---|---|
|
string |
A keyword, unique within a given configuration XML file that identifies a particular
For backward compatibility,
|
|
|
See the Description column |
Default for 11g: Default for backward compatibility: A fully qualified Java class that implements Reports Server Security Java interface ( |
You can associate multiple properties with the security element. The only requirement is that they be name/value pairs recognized by the Java class that implements Reports Server security.
The value of all the properties is set by the Installer upon installation. Reports Server uses this entity to connect to Oracle Internet Directory and Portal. Components of the Oracle Fusion Middleware can all connect to Oracle Internet Directory and Oracle Portal, but each component may have different privileges in the directory. Hence, each component needs to identify itself through its own entity name to Oracle Internet Directory when it connects. The Oracle Reports Services entity is of the following format:
reportsApp_hostname_GUID
For example:
reportsApp_testhost.mydomain.com_BBEFDCDAC2343600E0340800020C7BBCC
The proxyServer element is defined in rwserverconf.xsd as follows:
<xs:element name="proxyServer">
<xs:complexType>
<xs:attribute name="name" type="xs:string" use="required"/>
<xs:attribute name="port" type="xs:string" use="required"/>
<xs:attribute name="protocol" default="all">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:enumeration value="http"/>
<xs:enumeration value="https"/>
<xs:enumeration value="ftp"/>
<xs:enumeration value="file"/>
<xs:enumeration value="all"/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
</xs:complexType>
</xs:element>
In rwserver.conf, the proxyServer element may be specified as shown in this example:
<proxyServer name="www-proxy.example.com" port="80" protocol="all"/>
Optional.
Element that specifies the name, port and protocol of proxy server to be used in order to connect to external network.
The proxyServer element attributes are described in Table 7-20.
The domain element is defined in rwserverconf.xsd as follows:
<xs:element name="domain"> <xs:complexType mixed="true"> </xs:complexType> </xs:element>
In rwserver.conf, the domain element may be specified as shown in this example:
<bypassProxy> <domain><localhost</domain> <domain>127.0.0.1</domain> </bypassProxy>
Optional.
Element that specifies the name of the proxy server for which proxy setting should not be used. The domain element has no attributes.
The bypassProxy element is defined in rwserverconf.xsd as follows:
<xs:element name="bypassProxy"> <xs:complexType> <xs:sequence> <xs:element ref="domain" minOccurs="0" maxOccurs="unbounded"/> </xs:sequence> </xs:complexType> </xs:element>
In rwserver.conf, the bypassProxy element may be specified as shown in this example:
<bypassProxy>
<domain>localhost</domain>
<domain>127.0.0.1</domain>
</bypassProxy>
Optional.
The element that provides a list of domains which specifies name of the proxy server for which proxy setting should not be used
The bypassProxy element has no attributes. It includes the domain sub-element (see Section 7.2.1.24, "domain").
The proxyServers element is defined in rwserverconf.xsd as follows:
<xs:element name="proxyServers"> <xs:complexType> <xs:sequence> <xs:element ref="proxyServer" minOccurs="0" maxOccurs="unbounded"/> </xs:sequence> </xs:complexType> </xs:element>
In rwserver.conf, the proxyServers element may be specified as shown in this example:
<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>
Optional.
Element that specifies a list of proxy servers used by reports server.
The proxyServers element has no attributes. It includes the proxyServer sub-element (see Section 7.2.1.23, "proxyServer").
The proxyInfo element is defined in rwserverconf.xsd as follows:
<xs:element name="proxyInfo"> <xs:complexType> <xs:sequence> <xs:element ref="proxyServers"/> <xs:element ref="bypassProxy"/> </xs:sequence> </xs:complexType> </xs:element>
In rwserver.conf, the proxyInfo element may be specified as shown in this example:
<proxyInfo>
<proxyServers>
<proxyServer name="www-proxy.example.com" port="80" protocol="all"/>
</proxyServers>
<bypassProxy>
<domain>localhost</domain>
<domain>127.0.0.1</domain>
</bypassProxy>
</proxyInfo>
Optional.
Element specifying proxy servers used by reports and the bypass hosts for which proxy should not be used.
The proxyInfo element has no attributes. It includes two sub-elements:
proxyServers: see Section 7.2.1.26, "proxyServers"
bypassProxy: see Section 7.2.1.25, "bypassProxy"
The webLayout element is defined in rwserverconf.xsd as follows:
<xs:element name="webLayout">
<xs:complexType>
<xs:attribute name="port" type="xs:string"/>
<xs:attribute name="docroot" type="xs:string"/>
</xs:complexType>
</xs:element>
In rwserver.conf, the webLayout element may be specified as shown in this example:
<webLayout port="8888" docroot="$DOMAIN_HOME/servers/WLS_REPORTS/tmp/_WL_user/reports_<version>/<random_string>/war"/>
Optional.
webLayout element is required to run a report to weblayout using Reports Builder.
The webLayout element attributes are described in Table 7-22.
The dbProxyKey element is defined in rwserverconf.xsd as follows:
<xs:element name="dbProxyKey"> <xs:complexType> <xs:attribute name="name" type="xs:string" use="required"/> <xs:attribute name="database" type="xs:string" use="required"/> </xs:complexType> </xs:element>
In rwserver.conf, the dbProxyKey element may be specified as shown in this example:
<dbProxyConnKeys> <dbProxyKey name=key1 database=db1/> <dbProxyKey name=key2 database=db2/> </dbroxyConnKeys>
Optional.
The dbProxyKey consists of the name and database parameters. It is obtained from the server configuration file based on the database mentioned in the userid commandline parameter.
The dbProxyKey element attributes are described in Table 7-23.
The dbProxyConnKeys element is defined in rwserverconf.xsd as follows:
<xs:element name="dbProxyConnKeys"> <xs:complexType> <xs:sequence> <xs:element ref="dbProxyKey" minOccurs="0" maxOccurs="unbounded"/> </xs:sequence> </xs:complexType> </xs:element>
In rwserver.conf, the dbProxyConnKeys element may be specified as shown in this example:
<dbProxyConnKeys> <dbProxyKey name=key1 database=db1/> <dbProxyKey name=key2 database=db2/> </dbProxyConnKeys>
Optional.
The dbProxyConnKeys element has no attributes. It includes the dbProxyKey sub-element (see Section 7.2.1.29, "dbProxyKey").
The urlEngineAccess element is defined in rwserverconf.xsd as follows:
<xs:element name="urlEngineAccess">
<xs:complexType>
<xs:sequence>
<xs:element ref="urlPatterns" minOccurs="0" maxOccurs="1"/>
</xs:sequence>
</xs:complexType>
<xs:element name="urlPatterns">
<xs:complexType>
<xs:sequence>
<xs:element ref="urlPattern" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<urlEngineAccess>
<urlPatterns>
<urlPattern>http://host:port/myservlet/*</urlPattern>
<urlPattern>http://host:port/servlet2/myreportsOnly/*</urlPattern>
</urlPatterns>
</urlEngineAccess>
Optional
This element specifies patterns of allowed URLs which can be accessed by reports URL engine. By default, the list of URL patterns is empty, that is, no URL is allowed. Note that only HTTP and HTTPS protocols are allowed.
The jobThresholds element is defined in rwserverconf.xsd as follows:
<xs:element name="jobThresholds">
<xs:complexType>
<xs:attribute name="longRunning" default="180">
<xs:simpleType>
<xs:restriction base="xs:integer">
<xs:minInclusive value="1"/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="potentialRunAway" default="180">
<xs:simpleType>
<xs:restriction base="xs:integer">
<xs:minInclusive value="1"/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
</xs:complexType>
</xs:element>
In rwserver.conf, the jobThresholds element may be specified as shown in this example:
<jobThresholds longRunning="180" potentialRunAway="180"/>
Optional.
jobThreshold consists of two attributes, longRunning and PotentialRunAway. See Table 7-24.
Table 7-24 Attributes of the jobThresholds Element
| Attribute | Valid Values | Description |
|---|---|---|
|
seconds |
the cut-off time for a job after which it is considered a long run job. a job that takes relatively longer time. |
|
|
seconds |
the cut-off time for a currently running job after which it is considered as a potential runaway job. a job which has relatively lesser chance of successful completion. |
The server element is defined in rwserverconf.xsd as follows:
<xs:element name="server">
<xs:complexType>
<xs:sequence>
<xs:element ref="cache" minOccurs="0" maxOccurs="1"/>
<xs:element ref="engine" minOccurs="1" maxOccurs="unbounded"/>
<xs:element ref="environment" minOccurs="0" maxOccurs="unbounded"/>
<xs:element ref="security" minOccurs="0" maxOccurs="unbounded"/>
<xs:element ref="oidconnection" minOccurs="0" maxOccurs="1"/>
<xs:element ref="destination" minOccurs="0" maxOccurs="unbounded"/>
<xs:element ref="job" minOccurs="1" maxOccurs="unbounded"/>
<xs:element ref="notification" minOccurs="0" maxOccurs="unbounded"/>
<xs:element ref="log" minOccurs="0" maxOccurs="1"/>
<xs:element ref="jobStatusRepository" minOccurs="0" maxOccurs="1"/>
<xs:element ref="jobRepository" minOccurs="0" maxOccurs="1"/>
<xs:element ref="trace" minOccurs="0" maxOccurs="1"/-->
<xs:element ref="connection" minOccurs="0" maxOccurs="1"/>
<xs:element ref="ORBPorts" minOccurs="0" maxOccurs="1"/>
<xs:element ref="queue" minOccurs="0" maxOccurs="1"/>
<xs:element ref="folderAccess" minOccurs="0" maxOccurs="1"/>
<xs:element ref="persistFile" minOccurs="0" maxOccurs="1"/>
<xs:element ref="jobRecovery" minOccurs="0" maxOccurs="1"/-->
<xs:element ref="identifier" minOccurs="0" maxOccurs="1"/>
<xs:element ref="proxyInfo" minOccurs="0" maxOccurs="1"/>
<xs:element ref="pluginParam" minOccurs="0" maxOccurs="unbounded"/>
<xs:element ref="webLayout" minOccurs="0" maxOccurs="1"/>
<xs:element ref="dbProxyConnKeys" minOccurs="0" maxOccurs="1"/>
<xs:element ref="jobThresholds" minOccurs="0" maxOccurs="1"/>
<xs:element ref="urlEngineAccess" minOccurs="0" maxOccurs="1"/>
</xs:sequence>
<xs:attribute name="version" type="xs:string"/>
</xs:complexType>
</xs:element>
In rwserver.conf, the server element may be specified as shown in this example:
<server>
one or more element specifications
</server>
Required. You can have a maximum of one 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.
The server element attribute is described in Table 7-25.
Dynamic environment switching enables you to dynamically change the environment after Reports Server is started, or for a specific job request. This means that one instance of Reports Server can serve reports with any arbitrary environment settings, such as language, currency, and display settings.
To enable dynamic environment switching, you must 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 of the following ways:
Set the value of the defaultEnvId attribute of the engine element in the Reports Server configuration file to the id of the environment element, to apply the environment settings to that engine when it starts up. For more information, refer to Section 7.2.1.8, "engine".
Set the value of the ENVID command line keyword to the id of the environment element, to make the environment settings effective for the current report job request. For more information, refer to Section A.6.5, "ENVID".
The following examples illustrate the use of dynamic environment switching.
Suppose that you want to run reports in Japanese from your Reports Server. An environment conducive to running reports in Japanese would include:
NLS_LANG = Japanese_Japan.JA16SJIS
The currency unit (NLS_CURRENCY) would be set to Yen (¥), the currency of Japan.
If Reports Server is running on UNIX, then DISPLAY must 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 in either of the following ways:
Use the defaultEnvId attribute of the engine element in the Reports Server configuration file as follows:
<engine id="rwEng" initEngine="1" minEngine="0" maxEngine="10" engLife="50" maxIdle="30" defaultEnvId="JP"/>
The value JP identifies the environment element in the Reports Server configuration file. The initial engines will be spawned with the environment settings specified in this environment element.
Set the ENVID command line keyword, as follows:
http://machine_name:port/reports/rwservlet?SERVER=server_name &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 keyword and matches the specified id (in this case, JP) to the corresponding id of the environment element 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 maxEngine 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.
If you do not pass ENVID 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.
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://machine_name:port/reports/rwservlet?SERVER=server_name &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; that is, without Oracle Reports Servlet (rwservlet).
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 key map file. See Section 18.14, "Using a Key Map File".
Although this feature is ideal for handling reports of various languages, its application can be much broader. You could use it in any situation where a report requires a particular environment to execute correctly.
Reports Server will start one or more engines per environment id as and when it gets requests for specific environments. The total number of engines, however, cannot exceed the 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.
For engines used by the in-process Reports Server, the order of precedence for environment variables from highest to lowest is as follows:
reports.sh (UNIX only)
Note:
If you have modified your currentreports.sh file, you should save it and, after installing Oracle Reports, merge your modifications into the version of reports.sh installed with the latest version. The latest reports.sh contains some required changes.environment element in the Reports Server configuration file
Go to the WebLogic Administration Console, navigate to the Server Start tab and specify the oracle.home and oracle.instance parameters.
The system settings and registry (Windows only)
For engines used by the standalone server, the order of precedence for environment variables from highest to lowest is as follows:
reports.sh (UNIX only)
Note:
If you have modified your currentreports.sh file, you should save it and, after installing Oracle Reports, merge your modifications into the version of reports.sh installed with the latest version. The latest reports.sh contains some required changes.environment element in the Reports Server configuration file
The environment set in the console where you start rwserver.sh
The system settings and registry (Windows only)
If the same environment variable that is set in ENVID is also set in reports.sh (ORACLE_INSTANCE/config/reports/bin/reports.sh), 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 switching 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:
Open reports.sh and comment the environment variable value. For example, comment the REPORTS_PATH value set in the reports.sh file.
Open the rwserver.conf file.
Copy the environment variable value in the reports.sh file to the rwserver.conf file. For example:
<environment id="default"> <envVariable name=REPORTS_PATH value="$ORACLE_ HOME/reports/templates:$ORACLE_ C:/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_ C:/Samples/demo:$ORACLE_HOME/reports/integ:$ORACLE_HOME/ reports/printers"/> </environment>
Note:
In the above example, the Samples should be downloaded from OTN locationhttp://www.oracle.com/technetwork/middleware/reports/downloads/index.html and then be copied at local location C:\Samples.Add the defaultEnvId value to the appropriate tag in the rwserver.conf file.For example, add the defaultEnvId attribute to the engine element 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="90000" defaultEnvId="default">
Now run the report.