Oracle® Fusion Middleware Publishing Reports to the Web with Oracle Reports Services 11g Release 1 (11.1.1) B32121-01 |
|
![]() Previous |
![]() Next |
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 pre-configured out-of-the-box.
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>
Example
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"/>
Required/Optional
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.
Description
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>
Example
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>
Required/Optional
Optional. You can have as many pluginParam
elements as you require.
Description
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 |
---|---|---|
Set for an e-mail destination in Oracle Enterprise Manager on the Reports Server Basic Configuration page: 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 ( |
Properties
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>
Example
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>
Required/Optional
Optional. You can have a maximum of one cache
element in your server configuration file. If no cache element is specified, the default is used (oracle.reports.cache.RWCache
).
Description
The cache
element 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 on thecache API, refer to the Reports Software Development Kit (RSDK) on the Oracle Technology Network (OTN): on the Oracle Reports page (http://www.oracle.com/technology/products/reports/index.html ), click SDK. |
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 |
Properties
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:
JOCCacheDir
uses the Java object cache. For example:
<property name="JOCCacheDir" value="\\host\shared"/>
maxCacheFileNumber
is the maximum number of files allowed in the cache. For example:
<property name="maxCacheFileNumber" value="250"/>
Specify this property value in Oracle Enterprise Manager on the Reports Server Advanced Configuration page: 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"/>
To configure the Java Object Cache (JOC) Cache Directory, use the following:
<cache class="oracle.reports.cache.RWCache"> <property name="JOCCacheDir" value="\\host\shared"/> </cache>
Where host
is the machine where the shared folder is available, and shared
is the folder name.
Note: In Oracle Reports 10g Release 2 (10.1.2), Reports Server clustering was deprecated (see A Guide to Functional Changes Between Oracle Reports 6i and 11g for more details), and thecluster element is not valid.
For information about Oracle Fusion Middleware techniques for high availability, refer to Section 2.5, "Setting Up a High Availability Environment". |
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>
Example
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>
Required/Optional
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.
Description
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 |
---|---|---|
Set in Oracle Enterprise Manager on the Reports Server Advanced Configuration page: Connection Idle Timeout (min). |
Number |
Default: Allowable amount of time in minutes the connection can be idle. |
Set in Oracle Enterprise Manager on the Reports Server Advanced Configuration page: 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.17, "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>
Example
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>
Required/Optional
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.
Description
Use the destination
element to register destination types with the server.
You do not need to register the following default destinations:
Cache
Printer
File
FTP
WebDAV
You may need 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 on thedestination API, refer to the Reports Software Development Kit (RSDK) on the Oracle Technology Network (OTN): on the Oracle Reports page (http://www.oracle.com/technology/products/reports/index.html ), click SDK.
Configuring destinations is discussed in detail in Chapter 12, "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:
|
Properties
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>
Example
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>
Required/Optional
Optional. You can have as many environment
elements as you require.
Description
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 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:
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.9, "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 |
---|---|---|
Set in Oracle Enterprise Manager on the Reports Server Basic Configuration page: 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.8, "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>
Example
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"/>
Required/Optional
Optional.
Description
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 |
---|---|---|
Set in Oracle Enterprise Manager on the Reports Server Basic Configuration page: Add. |
string |
The name of the environment you wish to use (for example, |
Set in Oracle Enterprise Manager on the Reports Server Basic Configuration page: 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>
Example
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/Optional
Required. You must have at least one engine
element in your configuration file.
Description
The engine
element identifies the fully qualified Java class that starts an engine and provides a number of attributes that set operational controls on the engine. You can use the default 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 on theengine API, refer to the Reports Software Development Kit (RSDK) on the Oracle Technology Network (OTN): on the Oracle Reports page (http://www.oracle.com/technology/products/reports/index.html ), click SDK. |
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: |
|
Set in Oracle Enterprise Manager on the Reports Server Basic Configuration page: Maximum Engines. |
number |
Default: The maximum number of this type of engine that can run on the server. |
Set in Oracle Enterprise Manager on the Reports Server Basic Configuration page: Minimum Engines. |
number |
Default: The minimum number of this type of engine that is maintained by the server. |
Set in Oracle Enterprise Manager on the Reports Server Basic Configuration page: 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. |
Set in Oracle Enterprise Manager on the Reports Server Basic Configuration page: 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. |
|
Set in Oracle Enterprise Manager on the Reports Server Advanced Configuration page: 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 |
|
Set in Oracle Enterprise Manager on the Reports Server Basic Configuration page: 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:
|
|
Set in Oracle Enterprise Manager on the Reports Server Basic Configuration page: 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". |
Properties
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 |
---|---|---|
Set in Oracle Enterprise Manager on the Reports Server Advanced Configuration page: 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. |
Set in Oracle Enterprise Manager on the Reports Server Advanced Configuration page: 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 will use the temporary directory specified in the See the example that follows this table. |
Set in Oracle Enterprise Manager on the Reports Server Advanced Configuration page: Keep Database Connection. |
|
Default: Used by the default runtime engine implementation (that is,
The This property will be migrated if a |
Set in Oracle Enterprise Manager on the Reports Server Advanced Configuration page: Enable Engine Diagnostics. |
|
Introduced in Oracle Reports 10g Release 2 (10.1.2) for engine logging. 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>
Example
In rwserver.conf
, the job
element may be specified as shown in this example:
<job jobType="report" engineId="rwEng" securityId="rwSec" retry="3"/>
Required/Optional
Required. You must have at least one job
element.
Description
The job
element works in collaboration with the engine and security elements. Use job
to identify a job type and specify which engine and which security implementation should be used with that type of job. For example, you may have developed an engine to execute an operating system command should an event occur in your database. Using 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 |
|
Set in Oracle Enterprise Manager on the Reports Server Advanced Configuration page: 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>
Example
In rwserver.conf
, the jobRecovery
element may be specified as shown in this example:
<jobRecovery auxDatFiles="yes"/>
Required/Optional
Optional. To enable the job recovery mechanism, add the jobRecovery
element to the server configuration file. The job recovery mechanism is disabled by default.
Description
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>
Example
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>
Required/Optional
Optional. You can have a maximum of one jobStatusRepository
element in your server configuration file.
Description
The jobStatusRepository
element specifies the Java class that implements a job status repository. It provides an additional means (over the persistFile element) of storing job status information.
The persistFile
is a binary file and, therefore, cannot be used to publish job status information within your application. The jobStatusRepository
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 |
---|---|---|
Set to the default value in Oracle Enterprise Manager on the Reports Server Advanced Configuration page: Enable Job Repository DB. |
string |
Default: A fully qualified Java class that implements the Reports Server Job Repository Java class ( |
Properties
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>
Example
In rwserver.conf
, the log
element may be specified as shown in this example:
<log option="allJobs"/>
Required/Optional
Optional. You can have a maximum of one log
element in your server configuration file.
Description
The log
element is available for backward compatibility. It invokes the generation and population of a reports log file. The log file is automatically generated and stored in the following path (the path is the same for Windows and UNIX):
$ORACLE_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 need to be 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>
Example
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/Optional
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.
Description
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 need to 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.
Properties
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>
Example
In rwserver.conf
, the notification
element may be specified as shown in this example:
<notification id="tellMe02" class="oracle.reports.server.MailNotify"/>
Required/Optional
Optional. If you do not enter a notification
element in the configuration file, the notification function is disabled. You can have from zero to multiple notification
elements in your configuration file.
Description
Use the notification
element to specify a Java class that defines the type of notification that should be sent when a job succeeds or fails. You can use the default notification class, which provides for notification through e-mail, or design your own with the Oracle Reports Notification API.
Note: For more information on thenotification API, refer to the Reports Software Development Kit (RSDK) on the Oracle Technology Network (OTN): on the Oracle Reports page (http://www.oracle.com/technology/products/reports/index.html ), click SDK. |
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 (for more information, 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
properties are set in Oracle Enterprise Manager on the Reports Server Advanced Configuration page: 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>
Example
In rwserver.conf
, the oidconnection
element may be specified as shown in this example:
<oidconnection init="10" increment="10" timeout="600"/>
Required/Optional
Optional.
Description
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>
Example
In rwserver.conf
, the orbClient
element may be specified as shown in this example:
<orbClient id="RWClient" publicKeyFile="clientpub.key"/>
Required/Optional
Optional. If you do not specify the orbClient element in your server configuration file, the default values will be used.( see Table 7-17)
Description
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>
Example
In rwserver.conf
, the persistFile
element may be specified as shown in this example:
<persistFile fileName="neptune.dat"/>
Required/Optional
Optional. If you do not specify a file, the server will create one of its own with the default name server_name
.dat
. You can have a maximum of one persistFile
element.
Description
The persistFile
element identifies the file that records all job status. It is used by 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>
Example
In rwserver.conf
, the identifier
element may be specified as shown in this example:
<identifier encrypted="yes">fpoiVNFvnlkjRPortn+sneU88=NnN</identifier>
Required/Optional
Optional. You can have a maximum of one identifier
element in your server configuration file.
Description
The identifier
element is automatically written to the configuration file 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>
Example
In rwserver.conf
, the queue
element may be specified as shown in this example:
<queue maxQueueSize="1000"/>
Required/Optional
Optional. You can have a maximum of one queue
element in your server configuration file. If you have no queue
element, the default maxQueueSize
, 1000
, will remain in effect.
Description
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 Enterprise Manager or Oracle Reports Servlet (rwservlet
) to manage and monitor the Reports Server jobs queue.
Note: For more information, see the Reports Queue Manager online Help. |
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>
Example
In rwserver.conf
, the folderAccess
element may be specified as shown in this example:
<folderAccess> <read>c:\myreports;c:\orawin\reports\samples<\read> <write>c:\myoutputs<\write> <\folderAccess>
Required/Optional
Optional.
Description
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. The value of this sub-element is set in Oracle Enterprise Manager on the Advanced Configuration page: Enable File System Access Control > Read Directories.
write
: specifies the folder(s) to which the Reports Server can write. The value of this sub-element is set in Oracle Enterprise Manager on the Advanced Configuration page: Enable File System Access Control > Write Directories.
In the example above, the report definition files located in c:\myreports
and c:\orawin\reports\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 specifies global access. Separate 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>
Example
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
Required/Optional
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.
Description
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 on thesecurity API, refer to the Reports Software Development Kit (RSDK) on the Oracle Technology Network (OTN): on the Oracle Reports page (http://www.oracle.com/technology/products/reports/index.html ), click SDK. |
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>
Example
In rwserver.conf
, the proxyServer
element may be specified as shown in this example:
<proxyServer name="www-proxy.us.oracle.com" port="80" protocol="all"/>
Required/Optional
Optional.
Description
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>
Example
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>
Required/Optional
Optional.
Description
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>
Example
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>
Required/Optional
Optional.
Description
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.25, "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>
Example
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>
Required/Optional
Optional.
Description
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.24, "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>
Example
In rwserver.conf
, the proxyInfo
element may be specified as shown in this example:
<proxyInfo> <proxyServers> <proxyServer name="www-proxy.us.oracle.com" port="80" protocol="all"/> </proxyServers> <bypassProxy> <domain>localhost</domain> <domain>127.0.0.1</domain> </bypassProxy> </proxyInfo>
Required/Optional
Optional.
Description
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.27, "proxyServers"
bypassProxy
: see Section 7.2.1.26, "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>
Example
In rwserver.conf
, the webLayout
element may be specified as shown in this example:
<webLayout port="8888" docroot="DOMAIN_HOME/servers/WLS_REPORTS/stage/reports/reports/web.war"/>
Required/Optional
Optional.
Description
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>
Example
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>
Required/Optional
Optional.
Description
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>
Example
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>
Required/Optional
Optional.
Description
The dbProxyConnKeys
element has no attributes. It includes the dbProxyKey
sub-element (see Section 7.2.1.30, "dbProxyKey").
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>
Example
In rwserver.conf
, the jobThresholds
element may be specified as shown in this example:
<jobThresholds longRunning="180" potentialRunAway="180"/>
Required/Optional
Optional.
Description
jobThreshold consists of two attributes, longRunning
and PotentialRunAway
. For more information, 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:sequence> <xs:attribute name="version" type="xs:string"/> </xs:complexType> </xs:element>
Example
In rwserver.conf
, the server
element may be specified as shown in this example:
<server>
one or more element specifications
</server>
Required/Optional
Required. You can have a maximum of one server
element in a given configuration file.
Description
The server
element opens and closes the content area of the server configuration file. In terms of the file's hierarchy, all the other elements are subordinate to the server
element.
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 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 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.9, "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.
Example 1
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
The currency unit (NLS_CURRENCY
) would be set to Yen (¥), the currency of Japan.
If Reports Server is running on UNIX, then 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 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.
Example 2
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.
Example 3
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 (for more information, see Section 17.13, "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_ 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>
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.