Oracle® Application Server Reports Services Publishing Reports to the Web
10g Release 2 (10.1.2) B14048-02 |
|
Previous |
Next |
When you install Oracle Application Server, OracleAS Reports Services is configured automatically for you. There will likely be adjustments you wish to make to customize your environment, but you will not be required to set up the entire environment, or even most of it.
This chapter is included largely for reference, should you wish to introduce customizations or have a better understanding of the default configuration. It lists services-related configuration files and describes in detail the content of most of them. It includes the following main sections:
Note: The examples in this chapter useORACLE_HOME to denote where Oracle Application Server is installed. Oracle Application Server includes OracleAS Reports Services.
|
Another aspect of configuration is the setting of environment variables. These are set for you automatically during installation. For reference, environment variables are discussed in Appendix B, "Environment Variables".
This section identifies the configuration files associated with OracleAS Reports Services. In most cases, you can leave these files untouched. Because they control many aspects of your server environment, you could put that environment at risk if you change a file in some unsupported way. Always keep a back-up of the current version of any configuration file you plan to change.
The configuration files associated with OracleAS Reports Services relate to Reports Server (rwserver
) and Reports Servlet (rwservlet
). They are listed and described in Table 3-1:
Note: The paths specified in Table 3-1 are the same for both Windows and UNIX environments, though they are expressed here using the Windows backslash convention (\). |
Table 3-1 OracleAS Reports Services Configuration Files
Component | Configuration File |
---|---|
ORACLE_HOME\reports\dtd\rwserverconf.dtd ORACLE_HOME\reports\conf\server_name.conf The Use the For more information, see Section 3.2, "Configuring Reports Server". |
|
Reports Server (network configuration) |
ORACLE_HOME\reports\dtd\rwnetworkconf.dtd ORACLE_HOME\reports\conf\rwnetwork.conf The |
Reports Server (Oracle Reports bridge configuration) |
ORACLE_HOME\reports\dtd\bridgeconf.dtd ORACLE_HOME\reports\conf\repbrg_bridgename.conf The |
Reports BuilderReports Runtime |
ORACLE_HOME\reports\dtd\rwserverconf.dtd ORACLE_HOME\reports\conf\rwbuilder.conf The Use Because this file shares most configuration elements found in |
ORACLE_HOME\reports\conf\rwservlet.properties
The |
The Reports Server component of OracleAS Reports Services can be configured using the XML files server_name
.conf
and rwbuilder.conf
, located in the following directory (Windows and UNIX):
ORACLE_HOME\reports\conf
Both files are supported by the rwserver.template
file in the same directory, which contains default server configuration values on both Windows and UNIX.
The server_name
.conf
file is the default server configuration file. The rwbuilder.conf
file configures the server instance used in-process by Reports Builder.
The server_name
.conf
and rwbuilder.conf
files are nearly identical. The only difference between them is that rwbuilder.conf
does not use the compatible, persistFile, or security configuration elements, described later in this section.
Both of these files are created automatically, under the following circumstances:
The server_name
.conf
file is created the first time you start Reports Server. It is based on the rwserver.template
file.
The rwbuilder.conf
file is created the first time you run a report through Reports Builder. It also is based on the rwserver.template
file.
After you rename the server, a new server_name
.conf
file is created the next time you start the server. The new configuration file is based on the default values present in the rwserver.template
file. If you wish to retain the configuration associated with the old server name, you must rename your server_name
.conf
file to the new server name (new_server_name
.conf
), before starting the renamed server.
If you delete one of these files, the deleted file is re-created the next time you start the server. The new file is based on the default values present in the rwserver.template
file.
To explain the syntax and values allowed in these files we'll look at the rwserverconf.dtd
file, located in the following directory (on both Windows and UNIX):
ORACLE_HOME\reports\dtd\rwserverconf.dtd
This section describes:
The following example of rwserverconf.dtd
illustrates how it is used to configure various aspects of the Reports Server.
<!-- Copyright 2000, 2005 Oracle Corporation. 500 Oracle Parkway, Redwood Shores, CA 94065, U.S.A. All rights reserved. This is the DTD defining the Reports Server Configuration file (XML) format/syntax. --> <!ELEMENT server (compatible?, cache?, engine+, security*, oidconnection?, destination*, networkConfig?, job+, notification*, log?, jobStatusRepository?, trace?, connection?, ORBPorts?, queue?, persistFile?, jobRecovery?, identifier?, environment*, pluginParam*)> <!ATTLIST server version CDATA #IMPLIED> <!ELEMENT cache (property*)> <!-- class specifies full qualified java class name which implements oracle.reports.cache.Cache interface --> <!ATTLIST cache class CDATA "oracle.reports.cache.RWCache"> <!ELEMENT engine (property*)> <!-- class specifies full qualified java class name which starts engine --> <!ATTLIST engine id ID #REQUIRED class CDATA #REQUIRED classPath CDATA #IMPLIED initEngine CDATA "1" maxEngine CDATA "1" minEngine CDATA "0" engLife CDATA "50" maxIdle CDATA "30" callbackTimeOut CDATA "60000" jvmOptions CDATA #IMPLIED engineResponseTimeOut CDATA "0" defaultEnvId CDATA #IMPLIED> <!ELEMENT security (property*)> <!-- class specifies full qualified java class name which implements oracle.reports.server.Security interface --> <!ATTLIST security id ID #REQUIRED class CDATA #REQUIRED> <!ELEMENT oidconnection EMPTY> <!ATTLIST oidconnection init CDATA "10" increment CDATA "10" timeout CDATA "0"> <!ELEMENT destination (property*)> <!-- class specifies full qualified java class name which subclass oracle.reports.server.Destination abstract class --> <!ATTLIST destination destype ID #REQUIRED class CDATA #REQUIRED> <!ELEMENT networkConfig EMPTY> <!ATTLIST networkConfig file CDATA #REQUIRED> <!ELEMENT job EMPTY> <!ATTLIST job jobType CDATA "report" engineId IDREF #REQUIRED securityId IDREF #IMPLIED> <!ELEMENT notification (property*)> <!ATTLIST notification id CDATA "mailNotify" class CDATA #REQUIRED> <!ELEMENT log EMPTY> <!ATTLIST log option (allJobs|succeededJobs|failedJobs|noJob) "noJob"> <!ELEMENT jobStatusRepository (property*)> <!-- class specifies full qualified java class name which implements oracle.reports.server.JobRepository interface --> <!ATTLIST jobStatusRepository class CDATA "oracle.reports.server.JobRepositoryDB"> <!ELEMENT queue EMPTY> <!ATTLIST queue maxQueueSize CDATA "1000"> <!ELEMENT connection (orbClient*, cluster?)> <!ATTLIST connection maxConnect CDATA "20" idleTimeOut CDATA "15"> <!ELEMENT ORBPorts EMPTY> <!ATTLIST ORBPorts value CDATA #REQUIRED> <!ELEMENT orbClient EMPTY> <!ATTLIST orbClient id ID #REQUIRED publicKeyFile CDATA #REQUIRED> <!ELEMENT cluster EMPTY> <!ATTLIST cluster publicKeyFile CDATA #REQUIRED privateKeyFile CDATA #REQUIRED> <!ELEMENT persistFile EMPTY> <!ATTLIST persistFile fileName CDATA #IMPLIED> <!ELEMENT trace EMPTY> <!ATTLIST trace traceFile CDATA #IMPLIED traceOpts (trace_prf|trace_brk|trace_app|trace_pls|trace_sql| trace_tms|trace_dst|trace_log|trace_err|trace_inf| trace_dbg|trace_wrn|trace_sta|trace_exc|trace_all|none) "trace_all" traceMode (trace_replace|trace_append) "trace_replace" traceModule (all|server|engine) "all"> <!ELEMENT compatible EMPTY> <!ATTLIST compatible version (6i) "6i"> <!ELEMENT jobRecovery EMPTY> <!ATTLIST jobRecovery auxDatFiles (yes|no) "no"> <!ELEMENT identifier (#PCDATA)> <!ATTLIST identifier confidential (yes|no) "yes" encrypted (yes|no) "no"> <!ELEMENT environment (envVariable*)> <!ATTLIST environment id ID #REQUIRED> <!ELEMENT envVariable EMPTY> <!ATTLIST envVariable name CDATA #REQUIRED value CDATA #IMPLIED> <!ELEMENT pluginParam (#PCDATA)> <!ATTLIST pluginParam name ID #REQUIRED type (text|file|url) "text"> <!ELEMENT property EMPTY> <!ATTLIST property name CDATA #REQUIRED value CDATA #REQUIRED confidential (yes|no) "no" encrypted (yes|no) "no">
The rwserverconf.dtd
file provides the following elements for configuring the Reports Server:
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 server_name
.conf
or rwbuilder.conf
configuration file, you will save yourself potential error messages from any XML editor if you use the order of the elements shown in the rwserverconf.dtd
. The configuration file will work regardless of the order, but it will not work if you fail to follow the case specified in rwserverconf.dtd
.
Example
<server>
One or more configuration specifications
</server>
Required/Optional
Required. You can have a maximum of one open and close tags in the 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.
Note: Thecompatible element is deprecated in Oracle Reports 10g Release 2 (10.1.2). When the compatible element is set, Oracle Reports 6i client requests will still be forwarded to the Reports Server in 10g Release 2 (10.1.2). However, this is not a supported configuration, and Oracle will not fix bugs that result from this configuration.
By default, Oracle Reports 10g Release 2 (10.1.2) enables compatibility with Oracle Reports 10g Release 1 (9.0.4) clients, and vice versa. See the Oracle Application Server Forms and Reports Services Installation Guide for a matrix showing compatibility between prior release clients and Oracle Reports 10g Release 2 (10.1.2). |
Example
<compatible version="6i"/>
Required/Optional
Optional. You can have a maximum of one compatible
element in your server configuration file.
Description
The compatible
element is available for backward compatibility with Oracle Reports 6i clients (RWCLI60.EXE
, RWCGI60.EXE
, RWQMU60.EXE
, RWRQM60.EXE
, RWRQV60.EXE
, 6i Forms). When compatible
is set to 6i
, Reports Server will make use of an executable file named rwproxy
that listens for requests from a 6i client and forwards them to a 10g server.
The compatible
element attribute is described in Table 3-2.
Table 3-2 Attributes of the compatible
Element
Attribute | Valid Values | Description |
---|---|---|
|
Setting |
If you use the compatible
element, you must also have an entry for Reports Server in the tnsnames.ora
file as you would have had for the 6i version of Reports Server. The installer configures the tnsnames.ora
file for the default Reports Server; that is, rep_
machine_name
.
Note: Thetnsnames.ora file is located in the following directory:
|
For example:
testsvr.world = (ADDRESS=
(PROTOCOL=tcp) (HOST=testhost.mydomain.com) (PORT=1950) )
You can bypass this requirement by turning compatibility off. To turn compatibility off, remove the compatible
element from the Reports Server configuration file.
Example
<cache class="oracle.reports.cache.RWCache">
<property name="cacheSize" value="50"/> <property name="cacheDir" value="D:\orawin\reports\server\cache"/>
</cache>
Required/Optional
Optional. You can have a maximum of one cache
element in your server configuration file. If no cache element is specified, the default is used (oracle.reports.cache.RWCache
).
Description
The cache
element is available for specifying the Java class that defines the server's cache implementation. You can use the default cache Java class or develop your own implementation through the OracleAS 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 10g page (http://www.oracle.com/technology/products/reports/index.html ), click SDK.
|
The cache
element attribute is described in Table 3-3.
Table 3-3 Attributes of the cache
Element
Attribute | Valid Values | Description |
---|---|---|
See the Description column |
Default: A fully qualified Java class that implements the |
You can also enter from zero to multiple properties under the cache
element. Properties are name/value pairs recognized and understood by the implementation class you register under cache
. For example, if you use the default cache Java class that is provided with OracleAS Reports Services, your configuration entry might look like this:
<cache class="oracle.reports.cache.RWCache"> <property name="cacheSize" value="50"/> <property name="cacheDir" value="D:\orawin\reports\server\cache"/> </cache>
In the preceding example, cacheSize
is measured in megabytes, and cacheDir
, which points to the location of the cache, is specified for a Windows platform. On UNIX, use UNIX standards, for example:
<property name="cacheDir" value="$ORACLE_HOME/reports/server/cache"/>
The default cache Java class also provides the following properties:
maxCacheFileNumber
is the maximum number of files allowed in the cache. For example:
<property name="maxCacheFileNumber" value="250"/>
ignoreParameters
lists any report parameters you want to be ignored when Reports Server constructs the cache key. (The cache key is used by Reports Server to determine if an incoming job request matches existing output in the cache.)
<property name="ignoreParameters" value="param1,param2"/>
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, and you can have more than one.
Description
The engine
element identifies the fully qualified Java class that starts an engine and provides a number of attributes that set operational controls on the engine. You can use the default engines provided with OracleAS Reports Services or develop your own implementation through the OracleAS Reports Services Engine API. As an example of a custom engine, you may have developed an engine to execute an operating system command should an event occur in your database.
Note: For more information on theengine API, refer to the Reports Software Development Kit (RSDK) on the Oracle Technology Network (OTN): on the Oracle Reports 10g page (http://www.oracle.com/technology/products/reports/index.html ), click SDK.
|
The engine
element attributes are described in Table 3-4.
Table 3-4 Attributes of the engine
Element
Attribute | Valid Values | Description |
---|---|---|
string |
A keyword, unique within a given configuration XML file that identifies a particular
|
|
See the Description column |
Default: A fully qualified Java class that implements two interfaces: |
|
string |
The directory path to the Java class specified in the Windows:
UNIX:
|
|
number |
Default: The number of engines you want Reports Server to start at initialization. |
|
number |
Default: The maximum number of this type of engine that can run on the server. |
|
number |
Default: The minimum number of this type of engine that is maintained by the server. |
|
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. |
|
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. |
|
|
string |
(Optional attribute) The default environment within which Reports Server starts an engine. The attribute takes an id associated with an environment element in the server configuration file. If you specify If you do not specify For more information, refer to Section 3.2.2, "Dynamic Environment Switching". |
|
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. |
|
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 |
|
|
Default: The keepConnection property is used by the default runtime engine implementation; that is,
The This property will be migrated if a |
Properties
You can also optionally enter multiple properties under the engine
element. The only requirement is that they be name/value pairs recognized by the Java class that implements the Oracle Reports engine.
sourcedir
and tempDir
properties: If you use the default engine Java class that is provided with OracleAS Reports Services, your engine
configuration entry might look like this:
<engine id="rwEng" class="oracle.reports.engine.EngineImpl" initEngine="1" maxEngine="5" minEngine="1" engLife="50" maxIdle="15" callbackTimeOut="90000"> <property name="sourceDir" value="D:\orawin\reports\myReport"/> <property name="tempDir" value="D:\orawin\reports\myTemp"/> </engine>
In this example, sourceDir
and tempDir
are set up for a Windows environment (UNIX would be sourceDir="
ORACLE_HOME
/reports/myReport"
and tempDir="
ORACLE_HOME
/reports/myTemp"
):
The sourceDir
property identifies the default directory you will use for report definition files. It overrides path information specified in the REPORTS_PATH
environment variable.
The tempDir
property identifies the name and location of the temporary directory OracleAS Reports Services will use for its temporary files. If this value is unspecified for a default engine, OracleAS Reports Services will use the temporary directory specified in the REPORTS_TMP
environment variable. If REPORTS_TMP
is also not specified, OracleAS Reports Services will use your operating system's default temporary directory.
The classPath
attribute is not specified because this configuration uses the default engine
class.
diagnosis
property: Oracle Reports 10g Release 2 (10.1.2) introduces the diagnosis
property for engine logging. Including this property in your engine
configuration element enables you to diagnose 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.
To turn on 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>
When the diagnosis
property is set to yes
, the engine creates separate diagnostic files from the Reports Server and engine trace files. Diagnostic files are in the same location as the trace files (see Section 20.1.2, "Report Trace"). Every rwEng
engine creates two diagnostic files per instance (that is, per engine lifetime). For example:
rwEng-0-c-2004-08-31_05-24-54.dig rwEng-0-j-2004-08-31_05-24-54.dig
Each diagnostic log is a new file, with the timestamp included in the file name. Diagnostic files are not appended to or replaced for different instances of the same engine.
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.
Example
<security id="rwSec" class="oracle.reports.server.RWSecurity"> <!--property name="securityUserid" value="portal_db_username/portal_password@portal_db_connection" confidential="yes" encrypted="no"/--> <property name="oidEntity" value="oidentity_name"/> </security>
Note: In releases prior to Oracle Reports 10g Release 1 (9.0.4), thesecurity element was specified differently. In Oracle Reports 10g Release 1 (9.0.4) and 10g Release 2 (10.1.2), the old property specification, securityUserid , is still provided but commented out. You only need to use securityUserid if you want to connect to an OracleAS Portal instance other than the default instance, which is installed with the Oracle Application Server infrastructure.
|
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 OracleAS Reports Services, which relies on security features available through OracleAS Portal (included with Oracle Application Server), or develop your own implementation through the Reports Server Security API.
Note: For more information on thesecurity API, refer to the Reports Software Development Kit (RSDK) on the Oracle Technology Network (OTN): on the Oracle Reports 10g page (http://www.oracle.com/technology/products/reports/index.html ), click SDK.
|
The security
element attributes are described in Table 3-5.
Table 3-5 Attributes of the security
Element
Attribute | Valid Values | Description |
---|---|---|
string |
A keyword, unique within a given configuration XML file that identifies a particular
|
|
See the Description column |
Default: A fully qualified Java class that implements 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. For example, if you use the default security Java class that is provided with OracleAS Reports Services, your security
configuration entry might look like the example provided.
The value of oidEntity
is set by the Installer upon installation. Reports Server uses this entity to connect to Oracle Internet Directory. Components of the Oracle Application Server can all connect to Oracle Internet Directory, 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 OracleAS Reports Services entity is of the following format:
reportsApp_hostname_GUID
For example:
reportsApp_testhost.mydomain.com_BBEFDCDAC2343600E0340800020C7BBCC
The commented out property, securityUserid
, illustrates the old method of specifying security. securityUserid
provides the connection information to enable the Reports Server access to OracleAS Portal security features. The property attributes confidential
and encrypted
are available for encrypting the information within the property. Once the confidential="yes"
and encrypted="no"
attributes are entered, the property value will be encrypted automatically by Reports Server after you restart the server. When you next open the configuration file, the password information will be scrambled, and encrypted
will be set to yes
. If you forget the password you entered in the configuration file, you can delete the property and reenter it with new values, making sure to set encrypted
to no
.
Note: ForsecurityUserid database connection strings, both the thin (testhost.mydomain.com:1521:iasdb ) and Oracle Call Interface (scott/tiger@ordb ) JDBC formats are supported.
|
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 3-6.
Table 3-6 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 OracleAS Reports Services. In a typical production environment, the default values are recommended. |
For Reports Servlet, you can specify Oracle Internet Directory connection pooling parameters using the OID_INIT
, OID_INCREMENT
, and OID_TIMEOUT
properties in the rwservlet.properties
file, as described in Section 3.4.12, "Specifying Oracle Internet Directory Connection Pooling Parameters".
Example
<destination destype="oraclePortal" class="oracle.reports.server.DesOraclePortal"> <property name="portalUserid" value="portal_db_username/portal_password@portal_db_connection" confidential="yes" encrypted="no"/> </destination>
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 OracleAS Portal—which is an exception in that it requires an entry in the server configuration file so that you may specify the userid and password the server will use to log in to the portal). You can have from zero to multiple destination
elements in your server configuration file.
Description
Use the destination
element to register destination types with the server. There is no need to register default destinations. You may need to configure the OracleAS Portal, FTP, or WebDAV destinations, as follows:
OracleAS 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).
FTP and WebDAV: The entries for these destinations are created by default in the server configuration file, and are not commented out. Thus, they are configured and available by default. If you need to send the output to an FTP or WebDAV server that requires a proxy, you will need to edit the proxyinfo.xml
file available in the default location (ORACLE_HOME
\reports\conf
), then uncomment the proxy
property in the destination
element and specify the complete path to the proxyinfo.xml
file as the value. For example:
<destination destype="ftp" class="oracle.reports.plugin.destination.ftp.DesFTP">
<
property name="proxy" value="D:\\oracle\\reports\\conf\\proxyinfo.xml"
/>
</destination>
You must register any new destination types you create through the OracleAS 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 10g page (http://www.oracle.com/technology/products/reports/index.html ), click SDK.
Configuring destinations is discussed in detail in Chapter 8, "Configuring Destinations for OracleAS Reports Services". |
The destination
element attributes are described in Table 3-7.
Table 3-7 Attributes of the destination
Element
Attribute | Valid Values | Description |
---|---|---|
string |
Identifies the destination type; for example:
|
|
See the Description column |
A fully qualified Java class that is a subclass of Reports Server Destination Java class (
|
You also have the option of entering multiple properties under the destination
element. The only requirement is that they be name/value pairs recognized by the Java class that is a subclass of the Reports Server Destination Java class. For example:
<destination destype="oraclePortal" class="oracle.reports.server.DesOraclePortal"> <property name="portalUserid" value="portal_db_username/portal_password@portal_db_connection" confidential="yes" encrypted="no"/> </destination>
In this example, the property provides connect information to enable Reports Server to access OracleAS Portal. The confidential
and encrypted
attributes are included to automatically invoke encryption on the portalUserid
value the next time Reports Server is started.
Note: ForportalUserid database connection strings, both the thin (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.
Example
<networkConfig file="net3.conf"></networkConfig>
where:
net3.conf
is a custom Reports network configuration file that is located in the ORACLE_HOME
/reports/conf
directory. Oracle Reports will use the Reports Server discovery mechanism specified in this file.
Required/Optional
Optional. By default, Oracle Reports uses the rwnetwork.conf
file in the ORACLE_HOME
\reports\conf
directory to decide the Reports Server discovery mechanism. Uncomment this element to specify a custom network configuration file.
Note: If you change the network configuration file for Reports Server, then any client that connects to that server must use the same configuration settings. |
Description
This element specifies the network configuration file that will be used for Reports Server discovery. For more information, refer to Section 3.3, "Configuring the Reports Server Discovery Mechanism".
If namingservice
is enabled, then the Reports Server will register itself to the COS naming service. Oracle Reports clients will then contact the naming service to get the Reports Server reference. The namingService
element attribute is described in Section 3.3.1.3, "namingService".
Example
<job jobType="report" engineId="rwEng" securityId="rwSec"/>
Required/Optional
Required. You must have at least one job
element and can have more than one.
Description
The job
element works in collaboration with the engine and security elements. Use job
to identify a job type and specify which engine and which security implementation should be used with that type of job. For example, you may have developed an engine to execute an operating system command should an event occur in your database. Using OracleAS Reports Services's event-driven publishing API, you identify the event as a specific job type. When the event occurs, the job type information is sent to Reports Server, which looks up the job type under the job
element in its configuration file, and follows the direction provided in the element's attributes to the engine (and, if applicable, security implementation) specified for that type of job.
The job
element attributes are described in Table 3-9.
Table 3-9 Attributes of the job
Element
Attribute | Valid Values | Description |
---|---|---|
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 |
|
ID reference |
References the ID entered for the engine that will process this job type. Available IDs are specified under the engine element in the server configuration file using the |
|
ID reference |
References the ID entered for the security mechanism that will be applied to this job type. Available IDs are specified under the |
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 10g page (http://www.oracle.com/technology/products/reports/index.html ), click SDK.
|
The notification
element attributes are described in Table 3-10.
Table 3-10 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 runtime commands 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/>
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.
Example
<log option="allJobs"/>
Required/Optional
Optional. You can have a maximum of one log
element in your server configuration file.
Description
The log
element is available for backward compatibility. It invokes the generation and population of a reports log file. The log file is automatically generated and stored in the following path (the path is the same for Windows and UNIX):
ORACLE_HOME\reports\server_name\rwserver.log
The log
element attribute is described in Table 3-11.
Table 3-11 Attributes 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:
|
Example
<jobStatusRepository class="oracle.reports.server.JobRepositoryDB"> <property name="repositoryConn" value="scott/tiger@orcl" confidential="yes" encrypted="no"/> </jobStatusRepository>
Required/Optional
Optional. You can have a maximum of one jobStatusRepository
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
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 3-12.
Table 3-12 Attributes of the jobStatusRepository
Element
Attribute | Valid Values | Description |
---|---|---|
See the Description column |
Default: A fully qualified Java class that implements the Reports Server Job Repository Java class ( |
The jobStatusRepository
element allows for zero or multiple properties for passing options into the repository. The only requirement is that the class you specify in the server configuration file must recognize the name/value pairs you introduce.
The jobStatusRepository
element might look like this in your server configuration file:
<jobStatusRepository class="oracle.reports.server.JobRepositoryDB"> <property name="repositoryConn" value="scott/tiger@ORCL" confidential="yes" encrypted="no"/> </jobStatusRepository>
In this example, the value for the repositoryConn
property is the login for access to the database that stores the repository. The confidential
and encrypted
attributes are used to invoke encryption on the login information once Reports Server is restarted.
Note: ForrepositoryConn database connection strings, both the thin (testhost.mydomain.com:1521:iasdb ) and Oracle Call Interface (scott/tiger@ordb ) JDBC formats are supported.
|
Example
<trace traceFile="neptune.trc" traceOpts="trace_prf|trace_dbg|trace_wrn" traceMode="trace_append" traceModule="server"/>
Required/Optional
Optional. You can have a maximum of one trace
element in your server configuration file.
Description
Use the trace
element to create a file for tracing your report's execution and to specify the objects and activities you want to trace. The trace
element controls tracing only for the server and the engine.
Note: For information about the various ways to trace report execution, see Section 20.1.2, "Report Trace". |
Reports Server uses the rwlpr
executable for submitting a print job. For rwlpr
logging for Windows, when you enable tracing for Reports Server using either traceModule=all
or traceModule=server
, a printing diagnostic log (server_name
-rwlpr-
jobid
.log
) is created in the log directory (ORACLE_HOME
\reports\logs\
server_name
\
) for destype=printer
. This log file will contain information regarding the messages that can be used to diagnose any printing issues, such as spooler problems.
By default, trace files are generated in ORACLE_HOME
\reports\logs
. If job tracing is specified, trace files are generated in ORACLE_HOME
\reports\logs
\
server_name
\
job_id
.
The trace
element attributes are described in Table 3-13.
Table 3-13 Attributes of the trace
Element
Attribute | Valid Values | Description |
---|---|---|
|
Default: The filename of the trace file. If no path is specified, the trace file will be in the following directory on both Windows and UNIX:
If job tracing is specified, the trace file will be in:
|
|
See Table 3-14 |
Default: Defines the activities that will be traced. You can have one or more
Separate values with a vertical bar (|). |
|
|
Default: Defines whether new trace information will either overwrite the existing trace file ( |
|
|
|
By default, tracing tracks both server and engine events. Tracing engine events can cause performance problems in some cases. Use < If (Windows only) When you enable tracing for Reports Server, a printing diagnostic log ( |
The traceOpts
element attributes are described in Table 3-14.
Table 3-14 Valid Values for the traceOpts
Attribute
Value | Description |
---|---|
Logs server and engine profile. |
|
Lists debug breakpoints. |
|
Logs information on all report objects. |
|
Logs information on all PL/SQL objects. |
|
Logs information on all SQL. |
|
Enters a timestamp for each entry in the trace file. |
|
Lists distribution lists. Use this value to determine which report section was sent to which destination. |
|
Duplicates log information in your trace file. If you have specified a |
|
Lists server error messages. |
|
A catch-all option that dumps any information not covered by the other options into the trace file. |
|
Logs debug information. |
|
Lists server warning messages. |
|
Provides server and engine state information, such as initialize, ready, run, and shut-down. |
|
Logs all possible server and engine information in the trace file. |
|
Lists all exceptions. |
|
|
Disables tracing, and generates only log files (not trace files) in the directory specified by |
Example
<connection maxConnect="50" idleTimeOut="20"> <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 3-15). 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 3-15.
Table 3-15 Attributes of the connection
Element
Attribute | Valid Values | Description |
---|---|---|
Number |
Default: The maximum number of requests that the server can service simultaneously. Requests in excess of the |
|
Number |
Default: Allowable amount of time in minutes the connection can be idle. |
In addition to its attributes, connection
has a sub-element: orbClient
.
Note: In Oracle Reports 10g Release 2 (10.1.2), Reports Server clustering is deprecated (see A Guide to Functional Changes Between Oracle Reports 6i and 10g for more details), and thecluster sub-element is not valid. See also Section 3.4.20, "Migrating OracleAS Forms Services Applications that Include a Reports Server Cluster Name".
For information about Application Server-level techniques for high availability, refer to Section 1.5.4, "Choosing a High Availability Environment". |
Use orbClient
to provide the name of the public key file that the client will use to connect to Reports Server. Reports Server uses the public key to verify the signature sent by the client when it tries to connect to Reports Server. Reports Server only accepts clients whose signature can be verified through this public key. You can have from zero to multiple orbClient
sub-elements in your server configuration file.
The orbClient
sub-element attributes are described in Table 3-16.
Table 3-16 Attributes of the orbClient
Sub-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 |
OracleAS Reports Services provides default client public and private key files, clientpub.key
and clientpri.key
. These key files are in place for all components of OracleAS Reports Services You can regenerate public and private key files to replace the default key pair. To do this, at the command prompt use the following command:
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.
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 10g through the Ports link, which are ports reserved for Reports Server discovery mechanism and the Oracle Reports bridge component, as set in rwnetwork.conf and rwbridge_ bridgename .conf , respectively (see Section 3.3.1, "Network Configuration Elements (rwnetworkconf.dtd)" and Section 3.3.2, "Bridge Configuration Elements (bridgeconf.dtd)").
|
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 attributes are described in Table 3-17.
Table 3-17 Attributes 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.
|
Example
<queue maxQueueSize="1000"/>
Required/Optional
Optional. You can have a maximum of one queue
element in your server configuration file. If you have no queue
element, the default, 1000
, will remain in effect.
Description
Use the queue
element to specify the maximum number of jobs that can be held in each of the reports queues. OracleAS 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 10g or 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 3-18.
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 3-19.
Table 3-19 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. |
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 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 3-20.
Example
<identifier confidential="yes" encrypted="yes">fpoiVNFvnlkjRPortn+sneU88=NnN</identifier>
Required/Optional
Optional. You can have a maximum of one identifier
element in your server configuration file.
Description
The identifier
element is automatically written to the configuration file 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 OracleAS 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, server_name
.conf
.
Replace the encrypted username/password
values generated with custom values.
Set encrypted=no
.
Note: Setconfidential=no only if you do not want the username/password to be encrypted.
|
For example:
<identifier confidential="yes" 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 server_name
.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 confidential="yes" 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 accessingrwservlet Web commands, such as getjobid , 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 3.4, "Configuring Reports Servlet".
Example
<pluginParam name="mailServer">smtp01.mycorp.com</pluginParam>
Required/Optional
Optional. You can have as many pluginParam
elements as you require.
Description
The pluginParam
element 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.
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 3-21.
Table 3-21 Attributes of the pluginParam
Element
Attribute | Valid Values | Description |
---|---|---|
string |
The name of the plug-in parameter. |
|
|
Default: Describes the type of plug-in being specified. For For For Note that when you have a default type ( |
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 3.2.1.4, "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 3-22.
Table 3-22 Attribute of the environment
Element
Attribute | Valid Values | Description |
---|---|---|
string |
The name of the environment. |
The environment element has one sub-element, envVariable
. Each envVariable
is specified as a name–value pair. They can be either standard environment variables or user-defined environment variables.
The envVariable
element attributes are described in Table 3-23.
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 3.2.1.4, "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.3.34, "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://yourWebServer:port/reports/rwservlet?SERVER=yourreportsserver &REPORT=Japanese.rdf&USERID=username/passwd@db&DESFORMAT=htmlcss &DESTYPE=cache&ENVID=JP
When the URL is submitted to Reports Server, it detects the optional ENVID
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 maxEngines
setting, Reports Server shuts down an engine before starting a new one. An engine may be shut down even though it has not exceeded its engLife
setting. Once Reports Server has an engine with the correct environment running, the job is processed by that engine and the output is routed to the specified DESTYPE
.
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://yourWebServer:port/reports/rwservlet?SERVER=yourreportsserver &REPORT=arabic.rdf&USERID=username/passwd@db&DESFORMAT=htmlcss &DESTYPE=cache&ENVID=AR
Since the job is submitted with ENVID=AR
, Reports Server finds or starts an engine with the environment specified by element AR
in the Reports Server configuration file. The job is processed by the new engine and the output is distributed to the specified destination.
Example 3
The following example illustrates how the environment switching feature could be used in conjunction with a JSP report; that is, without 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
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
In the ORACLE_HOME
/j2ee/OC4J_BI_Forms/config/oc4j.properties
file: the oracle.home
property defines the ORACLE_HOME
setting and oracle.path
defines the PATH
setting.
In ORACLE_HOME
/opmn/conf/opmn.xml
, the <environment>
element under <oc4j instanceName="OC4J_BI_Forms" gid="OC4J_BI_Forms">
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_HOME
/bin/
), Reports Server obtains the environment variable value from reports.sh
and not from ENVID
.
For example, say you want to set the REPORTS_PATH
environment variable to a different engine by using the environment 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 server_name
.conf
file.
Copy the environment variable value in the reports.sh
file to the server_name
.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 server_name
.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.
By default, Reports Server can only use portal users to connect to OracleAS Portal. It cannot use an ordinary userid, such as scott/tiger
, unless you first assign appropriate privileges to its schema.
To assign the appropriate privileges to a schema other than the portal schema, you need to run the following script from SQL*Plus as an OracleAS Portal user:
ORACLE_HOME/portal/admin/plsql/wor/rwgrant.sql
Once the script is loaded, it prompts you to enter the connection string for the new schema (for example, repapp/repapp@orcl
). The script then assigns the appropriate privileges to this new schema. You will then be able to specify this connection string in the Reports Server configuration file to connect to OracleAS Portal.
Oracle Reports 10g Release 2 (10.1.2) replaces the use of Borland's VisiBroker with Sun Microsystems' industry-standard Java Developer's Kit Object Request Broker (JDK ORB), providing support for Reports Server requests from clients across subnets, and using the broadcast mechanism for dynamic Reports Server discovery both within a subnet and across subnets.
Note: Oracle Reports 10g Release 2 (10.1.2) also introduces therwdiag executable to provide diagnosis for the JDK ORB implementation. Using rwdiag , you can replace the functionality of osfind available in the prior VisiBroker implementation, providing information about which ORB applications are running and options for logging ORB-related network traffic. For more information on rwdiag , see Appendix E, "Reports Server and Bridge Diagnostic Utility".
|
The JDK ORB implementation enables you to select either of the following methods to discover a Reports Server in the network:
The Oracle Reports built-in broadcast mechanism (see Section 1.4.1, "Server Discovery Using the Broadcast Mechanism").
The Common Object Service (COS) naming service (see Section 1.4.2, "Server Discovery Using the COS Naming Service").
This section describes the configuration elements required for discovering a Reports Server:
Network Configuration Elements (rwnetworkconf.dtd) (for either method)
Bridge Configuration Elements (bridgeconf.dtd) (for broadcast mechanism across subnets)
Note: The Oracle Reports built-in broadcast mechanism requires the host machine to be inside a network. Thus, following are two scenarios in which the broadcast mechanism may not work, including the solutions for each scenario:
|
The rwnetworkconf.dtd
is a DTD file that contains the data type definitions for the various network configuration file (rwnetwork.conf
) elements and attributes when using either the built-in broadcast mechanism or the COS naming service method for Reports Server discovery. This file is located in the following directory:
ORACLE_HOME\reports\dtd
Data type definitions list all the elements allowed in an associated XML file, the attributes associated with those elements, and the default values for those attributes.
<!-- Copyright 2005 Oracle Corp. 500 Oracle Parkway, Redwood Shores, CA 94065, U.S.A. All rights reserved. This is the DTD defining the Reports network configuration file (XML) format/syntax. --> <!ELEMENT discoveryService ( multicast | namingService )> <!ATTLIST discoveryService version CDATA "10.1.2"> <!ELEMENT multicast EMPTY > <!ATTLIST multicast channel CDATA #REQUIRED port CDATA #REQUIRED timeout CDATA "1000" retry CDATA "3"> <!ELEMENT namingService EMPTY > <!ATTLIST namingService name CDATA #REQUIRED host CDATA #REQUIRED port CDATA #REQUIRED>
The rwnetworkconf.dtd
file provides the following elements for configuring the discovery mechanism for Reports Server:
Required/Optional
Required. You can have a maximum of one open tag and one close tag in the discoveryService
element in a given configuration file.
Description
The discoveryService
element opens and closes the content area of the network configuration file. In terms of the file's hierarchy, all the other elements are subordinate to the discoveryService
element.
Example
<multicast channel="228.5.6.7" port="one of the port in alotted AS ports" timeout="1000" retry="3"/>
Required/Optional
Conditional. The namingService
and multicast
elements are mutually exclusive; that is, only one of these elements can be configured at a time.
Description
The multicast
element contains the necessary information to identify where Reports Server is running the built-in broadcast mechanism. By default, multicast
is specified in rwnetwork.conf
. Alternatively, you can specify the namingservice
element if you need to use the Common Object Service (COS) naming service for Reports Server discovery when built-in broadcast mechanism is not suitable for your environment, as in the following scenarios:
Oracle Reports is installed on a machine that is connected to a network using VPN.
You want to avoid broadcast traffic on your network.
The multicast
element attributes are described in Table 3-24.
Table 3-24 Attributes of the multicast
Element
Attributes | Valid Values | Description |
---|---|---|
|
Broadcast channel |
The broadcast channel used by the Reports Server. |
|
Broadcast port |
The broadcast port used by the Reports Server. |
|
Time (in milliseconds) it should wait for response. The optimum value for this setting is |
The Reports Client will wait for the specified timeout period for a response from the Reports Server. |
|
Retry count |
The Reports Client will retry for the specified number of times, if there is no response from the Reports Server after the timeout period. |
Note: It is strongly recommended that you do not change the default channel and port unless it is absolutely necessary. The default port value forrwnetwork.conf is assigned when you install Oracle Application Server.
If you need to customize |
Example
<namingService name="Cos" host="mymachine.mydomain.com" port="14021"/>
Required/Optional
Conditional. The namingService
and multicast
elements are mutually exclusive; that is, only one of these elements can be configured at a time.
Description
The namingService
element contains the necessary information required to be able to identify the host name and the port where the COS naming service is running. Specify this element only when the built-in broadcast mechanism is not suitable for your environment, as in the following scenarios:
Oracle Reports is installed on a machine that is connected to a network using VPN.
You want to avoid broadcast traffic on your network.
For more information, see Section 1.4.2, "Server Discovery Using the COS Naming Service".
To control the COS naming service through OPMN, refer to Section 3.7.1.5, "COS Naming Service Specification".
Note: Before you configure the COS naming service using thenamingService element, you must start the naming service as described in Section 2.3, "Starting and Stopping the COS Naming Service".
|
The namingService
element attributes are described in Table 3-25.
Table 3-25 Attributes of the namingService
Element
Attributes | Valid Values | Description |
---|---|---|
|
|
The descriptive name of the naming service. |
|
Host name/IP |
The host name of the machine where the naming service is running. |
|
Port number |
The port number of the machine where the naming service is running. |
The bridgeconf.dtd
is a DTD file that contains the data type definitions for the various bridge configuration file (repbrg_
bridgename
.conf
) elements and attributes when using the built-in broadcast mechanism for Reports Server discovery across subnets.
The Oracle Reports bridge acts as a gateway for packets that are broadcast by Reports Server and Reports Client across subnets. For example, in a sample setup, Oracle Reports components are installed on different subnets: Reports Servlet is in subnet A and Reports Server is in subnet B. To achieve this configuration, the Oracle Reports bridge has to be started on each subnet. Bridge configuration will include the host and port settings. The Oracle Reports bridge in subnet A will contact the Oracle Reports bridge in subnet B through reliable TCP to retrieve the server information on subnet B, and vice versa. For more information, see Section 1.4.1.2, "Server Discovery Across Subnets".
To invoke the Oracle Reports bridge, refer to Section 2.2, "Starting and Stopping the Oracle Reports Bridge".
For troubleshooting scenarios and diagnosis, see Section D.8, "Diagnosing Oracle Reports Bridge Problems".
<!-- Copyright 2005 Oracle Corp. 500 Oracle Parkway, Redwood Shores, CA 94065, U.S.A. All rights reserved. This is the DTD defining the Reports Bridge Version 10g Configuration file (XML) format/syntax. --> <!ELEMENT bridge (networkConfig?, identifier?, trace?, remoteBridges? ) > <!ATTLIST bridge version CDATA #REQUIRED port CDATA #REQUIRED timeout CDATA #REQUIRED> <!ELEMENT networkConfig EMPTY> <!ATTLIST networkConfig file CDATA #REQUIRED> <!ELEMENT identifier (#PCDATA)> <!ATTLIST identifier confidential (yes|no) "yes" encrypted (yes|no) "no" > <!ELEMENT remoteBridges (remoteBridge*)> <!ELEMENT remoteBridge EMPTY> <!ATTLIST remoteBridge host CDATA #REQUIRED port CDATA #REQUIRED> <!ELEMENT trace EMPTY> <!ATTLIST trace traceFile CDATA #IMPLIED traceOpts (trace_err|trace_inf| trace_dbg| trace_all) "trace_all" traceMode (trace_replace|trace_append) "trace_replace">
The bridgeconf.dtd
file provides the following elements for configuring the bridge, used to discover the server across subnets:
Example
<bridge version="10.1.2" port="14011" timeout="12000"> <!--networkConfig file="rwnetwork.conf" ></networkConfig--> <!--identifier encrypted="no" confidential="yes">%USERNAME%/%PASSWORD%</identifier--> <!--trace traceOpts="trace_all"></trace--> <!-- Specify one or more remote bridges inside remoteBridges element --> <!--remoteBridges> <remoteBridge host="%HOST%" port="%PORT%"></remoteBridge> </remoteBridges--> </bridge
Required/Optional
Required. You can have a maximum of one open tag and one close tag in the bridge
element in a given configuration file.
Description
The bridge
element opens and closes the content area of the bridge configuration file. In terms of the file's hierarchy, all the other elements are subordinate to the bridge
element.
The bridge
element attributes are described in Table 3-26.
Table 3-26 Attributes of the bridge
Element
Attributes | Valid Values | Description |
---|---|---|
|
|
The bridge version. |
|
The allotted range for Oracle Reports bridge component; that is, |
The port on which the bridge will listen. |
|
|
Value in milliseconds (ms). The bridge will wait for this period for a response from a remote bridge. |
Note: The default port value for the bridge configuration file is assigned when you install Oracle Application Server. Therwbridge template file contains this default port, which is used to generate the configuration file for the bridge. The configuration file name for the bridge named mybridge is repbrg_mybridge.conf .
If you need to customize the port number for the bridge, you must specify a valid port range reserved for the Oracle Reports bridge ( |
For information on the networkConfig
element, refer to Section 3.2.1.8, "networkConfig".
Example
<identifier confidential="yes" encrypted="yes">fpoiVNFvnlkjRPortn+sneU88=NnN</identifier>
Required / Optional
Optional. If this element is commented, then the Oracle Reports bridge will not perform a security check when the bridge shutdown command is issued.
Description
The identifier
element ensures that the Oracle Reports bridge performs a security check before shutting down.
To set the value of the identifier
element:
Uncomment the identifier
element in the bridge configuration file.
Set the value to the adminstrator username/password, set the attribute encrypted=no
, and set confidential=yes
so that the username/password will be encrypted when the Oracle Reports bridge is restarted.
For example:
<identifier encrypted="no" confidential="yes">scott/tiger</identifier>
Start the bridge.
Once this element is set, only the administrator will be able to shut down the bridge by specifying the username/password
in the command line.
Example
<remoteBridges>
value...
</remoteBridges>
Required/Optional
Optional. If this entry is not specified, then this bridge will not contact any remote bridge to get a Reports Server reference. However, remote bridges can contact this bridge to get the references of Reports Servers running in this subnet.
Description
The remoteBridges
element can contain zero or more remoteBridge elements.
Example
<remoteBridge host="myhost.mydomain.com" port="14022"></remoteBridge>
Required/Optional
Optional. You can have one or more remoteBridge
elements in your bridge configuration file.
Description
The remoteBridge
element specifies the host and port on which remote bridges are running.
Figure 3-1 Oracle Reports Bridge Configuration (Two-Way)
If you specify the optional remoteBridge
element(s) in the repbrg_
bridgename
.conf
, then the bridge will act as a two-way bridge. That is, the bridge can get server references from remote bridges.
Figure 3-2 Oracle Reports Bridge Configuration (One-Way)
If you do not specify the optional remoteBridge
element(s) in the repbrg_
bridgename
.conf
, then the bridge will act as a one-way bridge. That is, the bridge can only serve remote bridges. It cannot connect to remote bridges to get the server reference.
The remoteBridge
element attributes are described in Table 3-27.
Table 3-27 Attributes of the remoteBridge
Element
Attributes | Valid Values | Description |
---|---|---|
|
Host name/IP address of the remote bridge. |
The host name or the IP address of the machine where the remote bridge is running. |
|
Port number of the remote bridge. |
The port number of the remote bridge element. |
Oracle Reports bridge tracing supports a subset of options available in Reports Server tracing (described in Section 3.2.1.13, "trace").
Example
<trace traceFile="mybridge.trc" traceOpts="trace_err|trace_inf" traceMode="trace_append"/>
Required/Optional
Optional. You can have a maximum of one trace
element in your bridge configuration file.
Description
Use the trace
element to create a file for tracing your Oracle Reports bridge execution and to specify the activities you want to trace.
Note: For information about the various ways to trace report execution, see Section 20.1.2, "Report Trace". |
The trace
element attributes are described in Table 3-28.
Table 3-28 Attributes of the Oracle Reports Bridge trace
Element
Attribute | Valid Values | Description |
---|---|---|
|
Default: The filename of the trace file. If no path is specified, the trace file will be in the following directory on both Windows and UNIX:
|
|
see Table 3-29 |
Default: Defines the activities that will be traced. You can have one or more
Separate values with a vertical bar (|). |
|
|
Default: Defines whether new trace information will either overwrite the existing trace file ( |
Table 3-29 Valid Values for the Oracle Reports Bridge traceOpts
Attribute
Value | Description |
---|---|
Lists bridge error messages. |
|
This is a catch-all option that dumps any information not covered by the other options into the trace file. |
|
Logs debug information. |
|
Logs all possible bridge information in the trace file. |
You can configure Reports Servlet (rwservlet
) in the servlet configuration file, rwservlet.properties
, located in the following path on both Windows and UNIX:
ORACLE_HOME\reports\conf\rwservlet.properties
Use rwservlet.properties
for:
Specifying the rwservlet Character Encoding to Decode Reports Parameters
Disallowing HTML Code Specified in the URL from Being Executed in a Browser
Specifying the Pool Size for Concurrent Connections to rwservlet
Specifying Oracle Internet Directory Connection Pooling Parameters
Setting Expiration for Database and System Authentication Cookies
Setting an Encryption Key for the Database and System Authentication Cookies
Migrating OracleAS Forms Services Applications that Include a Reports Server Cluster Name
You can also use an alternate configuration file to configure Reports Servlet if you specify the alternate file name as described in:
The entries in the configuration file are not case-sensitive.
For Windows, note that rwservlet.properties
uses double backslashes (\\) instead of single backslashes to specify a directory path. The first slash "escapes" the second, which would otherwise have another meaning in this file. For example, in a Windows-based rwservlet.properties
file, the path:
d:\orawin\reports\conf\filename.ext
becomes:
d:\\orawin\\reports\\conf\\filename.ext
For UNIX, use that platform's standard for specifying directory paths, for example:
orawin/reports/conf/filename.ext
Table 3-30 provides an alphabetic list of the parameters you can define in the Reports Servlet configuration file, along with a reference to the section in which each parameter is described.
Table 3-30 Reports Servlet Configuration Parameters
Your report runtime command line may include information you do not want to expose to your users. Additionally, it may be comprised of a long string of options that is difficult to remember or makes for an ungainly URL.
You have the option of entering a report's command line options in a key map file (cgicmd.dat
), then limiting the exposed runtime command to the name of the particular key section in this file that holds the required options.
The key map file is discussed in Chapter 13, "Running Report Requests". Use rwservlet.properties
to list the location of this file.
For example:
KEYMAPFILE=d:\\orawin\\reports\\conf\\cgicmd.dat
This example uses the default filename and location. An entry for the location and filename of the key map file doesn't appear, by default, in rwservlet.properties
because the servlet already knows what to look for and where to look for it. If you use a file with a different name or different location, you must include a KEYMAPFILE
parameter in rwservlet.properties
that includes the directory path and filename.
Use the RELOAD_KEYMAP
parameter to specify whether the key map file (cgicmd.dat
) should be reloaded each time rwservlet
receives a request.
For example:
RELOAD_KEYMAP=YES
This is useful if you frequently make changes to the map file and want the process of loading your changes to be automatic. Runtime performance will be affected according to how long it takes to reload the file.
Typically, this parameter is set to NO
in a production environment and YES
in a testing environment.
You may want to provide an authentication mechanism for an unsecured Reports Server so that only an administrator (based on the authid
) can run a Web command, like showenv
, showjobs
, and so on. By setting DIAGNOSTIC=NO
in the rwservlet.properties
file, you can provide just such an authentication mechanism. This authentication information is also used for administrative tasks, for example, stopping the Reports Server from the command line.
Note: SettingDIAGNOSTIC=NO only works for non-secured Reports Server. For secure Reports Server users, Reports Server verifies the user's privileges based on the entries in Oracle Internet Directory.
|
To disable Web command display for an unsecured Reports Server
Start a Reports Server.
Set DIAGNOSTIC=NO
in the rwservlet.properties
file.
Access the Reports Server from rwservlet
by using any of the Web commands; for example, getserverinfo.
You must pass an authid
here.
For example:
http://yourwebserver:portnum/reports/rwservlet/getserverinfo?server=aks+authid=scott/tiger
Note: The Reports Server will save thisauthid in the following directory: ORACLE_HOME /reports/conf/ server_name .conf file under the identifier element. The <identifier> element is set in the Reports Server configuration file by the first Web command call if it is not defined in the server configuration file and the values are automatically encrypted when the Reports Server is started. The format to preset the <identifier> element in the Reports Server configuration file is:
The clear text of username and password will be encrypted by Reports Server once it starts up, and the encrypted attribute is changed to yes to indicate the content is encrypted. For more information on the |
Now, any access to the Reports Server for using the Web commands will have to pass the same authid
. If the authid
is not passed, then you will get the following error:
REP-52262: Diagnostic output is disabled.
To modify the administrator user name or password:
Open the Reports Server configuration file (server_name
.conf)
.
Modify the identifier
element:
<identifier encrypted="no"confidential="yes"> admin_name/admin_password</identifier>
Tip: You can specify the administratorusername/password in the identifier element in the rwserver.template file. This ensures that you can pass the same authid for any Reports Server that you start up.
|
The servlet configuration file offers a number of parameters dealing with templates for userid/password dialog boxes that should open when a user logs in to a database or runs a secure report. Generally, these parameters point to various templates to be used for setting up your login screens. You can customize these templates with your company logo, linked buttons, or any other HTML you care to use.
The DBAUTH
and SYSAUTH
parameters are for specifying the location and filename of the HTML templates to be used for individual login screens. By default, the file names are rwdbauth.htm
and rwsysauth.htm
, respectively.
For example, the following entry points to the template for the database login screen:
DBAUTH=rwdbauth.htm
SYSAUTH
points to a login screen for a secure report. For example:
SYSAUTH=rwsysauth.htm
It isn't necessary to enter the path to a template when it is stored in the default template directory:
ORACLE_HOME\reports\templates
Tracing in OracleAS Reports Services provides for logging of many different types of runtime information on various OracleAS Reports Services components, as described in Section 20.1.2, "Report Trace".
To track and log runtime information on Reports Servlet (rwservlet
) and JSPs, use the TRACEOPTS
parameter in rwservlet.properties
. You can enter from zero to multiple trace options. Separate each option with a vertical bar.
For example:
TRACEOPTS=trace_prf|trace_pls|trace_dbg
All available trace options are listed and described in Table 3-14.
Additionally, you can use the TRACEFILE
and TRACEMODE
parameters. Use TRACEFILE
to specify the filename of the trace file. For example:
TRACEFILE=myrwservlet.trc
The default name is rwservlet.trc
. If no path is specified, the trace file will be in the following directory on both Windows and UNIX:
ORACLE_HOME\reports\logs\machine_name
In the rwservlet.properties
configuration file, use a separate line for each option. For example:
TRACEOPTS=TRACE_ALL TRACEFILE=rwservlet.trc TRACEMODE=TRACE_REPLACE
Use TRACEMODE
to define whether new trace information will either overwrite the existing trace file (trace_replace
), or be added to the end of the trace, leaving existing trace information intact (trace_append
). TRACEMODE
replaces or appends to the tracing information that has accumulated since the startup of the Oracle Application Server Containers for J2EE container that contains rwservlet
. For example:
TRACEMODE=trace_append
The default for TRACEMODE
is trace_replace
.
You can specify non-ASCII escaped characters in the request URL or non-ASCII characters in the Parameter Form input. You must specify the character encoding in the rwservlet.properties
file before you can apply it. This is to ensure that rwservlet
uses the required encoding when decoding the parameter name and value.
You can set the value of DEFAULTCHARSET
in the rwservlet.properties
file to either:
The database's NLS_CHARACTERSET
(for example, JA16EUC
).
The IANA-defined character set (for example, EUC-JP
).
Example
DEFAULTCHARSET=JA16EUC
Note: To use non-ASCII characters in user parameter names and values when using the Event-Driven Publishing API, you must ensure that theDEFAULTCHARSET specified in the rwservlet.properties file matches the value of the DEFAULTCHARSET parameter in your parameter list. For more information, see Section 17.1.3, "Including non-ASCII Characters in Parameter Names and Values".
|
Any HTML code included as part of the report request URL might lead to a security compromise as it causes certain browsers to execute any script or code in the URL. Thus, HTML code is not allowed as part of the URL command.
To disallow HTML code as part of the URL command, use the ALLOWHTMLTAGS
property in rwservlet.properties
. This property is set to NO
by default, disallowing any HTML code to be entered in the URL when running a report.
Valid Values
YES
Allows HTML code in the URL.
Note: SettingALLOWHTMLTAGS=YES allows malicious HTML code to be executed by certain browsers.
|
NO
Disallows any HTML code in the URL.
Default
NO
You may want to define the number of users who can connect and submit job requests simultaneously to rwservlet
. To do so, you must set the value of the CONNECTION_POOLSIZE
property in the rwservlet.properties
file.
Default Value
500
Minimum Value
0 (not recommended)
Set the value of CONNECTION_POOLSIZE
keeping in mind the number of active users expected to make concurrent job requests. For example, set this value to 250 if you expect around 100 concurrent active users.
Note: The value set (for example, 100) is the number of active users simultaneously making job requests and not the number of users connected to the system without submitting requests. |
OracleAS Reports Services provides a template for server error messages. These messages are generated automatically, according to cause. The template provides the visual setting within which the error message is displayed.
You may wish to customize the appearance of error messages, for example with your company logo, or with an icon you plan to associate with errors. You may wish to add buttons that link your users to a help system, your company home page, or back to the last browser window. You can do this by providing your own HTML framework for automatically generated error messages.
The ERRORTEMPLATE
property in rwservlet.properties
specifies the name and location of your error message template.
By default, the entry is:
ERRORTEMPLATE=rwerror.htm
It is not necessary to enter the path to the error message template when it is stored in the default template directory:
ORACLE_HOME\reports\templates
The character set of the error message template (rwerror.htm
) is iso-8859-1
to ensure consistency across all platforms. In earlier releases, it was windows-1252
, which is a character set specific to the Windows platform.
If you choose to run Reports Server within the same process as Reports Servlet (rwservlet
), you specify the following in rwservlet.properties
:
SERVER_IN_PROCESS=YES
Specify SERVER_IN_PROCESS=NO
if you do not want Reports Server to run within the same process as Reports Servlet.
Note: The pros and cons of running an in-process server are explored in Chapter 1, "Understanding the OracleAS Reports Services Architecture". |
For the in-process server specification when configuring Reports Server through OPMN, see Section 3.7.1.3, "In-process Reports Server Specification".
For troubleshooting printing and font issues when using the in-process server, see Section D.1.11, "Printing and Font Errors When Using In-process Server".
Reports Servlet (rwservlet
) uses the SERVER
parameter value as the name of the in-process server. If a Reports Server name is not specified, for example, in the runtime URL, rwservlet
starts the in-process server (if not started already) with the name specified by the SERVER
parameter, and submits the job to it.
In AS installations, the Oracle Reports configuration tool sets the value the SERVER
parameter in the rwservlet.properties
file as follows:
SERVER=rep_
hostname_oraclehomename
You can change the in-process server name by setting the SERVER
parameter to a different name in the rwservlet.properties
file:
SERVER=server_name
If the SERVER
parameter in rwservlet.properties
is not set, the default in-process server name in both AS and DS installations is: rep_
hostname
.
When SERVER_IN_PROCESS=NO
, rwservlet
will try to bind to an external server with the name specified by the SERVER
parameter.
To specify Oracle Internet Directory connections for Reports Servlet, specify Oracle Internet Directory connection pooling parameters in the rwservlet.properties
file, as follows:
OIDCON_INIT=Initial number of Oracle Internet Directory connections to be created when Reports Servlet is initialized OIDCON_INCREMENT=Number of connections to be incremented when all connections are used up OIDCON_TIMEOUT=Time in seconds for which a connection can be idle
If you do not specify these parameters, default values are:
OIDCON_INCREMENT=10 OIDCON_INIT=10 OIDCON_TIMEOUT=0 (which specifies no timeout)
For Reports Server, you can specify Oracle Internet Directory connection pooling parameters using the oidconnection
element in the server configuration file, as described in Section 3.2.1.6, "oidconnection".
Optionally, you can use the IMAGE_URL
parameter to specify where the reports' dynamically generated images can be accessed.
For example:
IMAGE_URL=http://server_or_web_server_name.domain_name:port/reports/rwservlet
This parameter is in place for JSPs that do not run through Reports Servlet (rwservlet
). It ensures that dynamically generated images, such as charts, will be viewable only by the person who runs the report. JSPs, and other report types, that run through Reports Servlet have this protection automatically.
Use the COOKIEEXPIRE
parameter to set the lifetime (in minutes) of the database and system authentication cookie. For example:
COOKIEEXPIRE=20
The default is 30
.
Cookies save encrypted user names and passwords on the client-side when users first authenticate themselves. When the server receives a cookie from the client, the server compares the time saved in the cookie with the current system time. If the time is longer than the number of minutes defined in COOKIEEXPIRE
, the server rejects the cookie and returns to the client the authentication form along with an error message. Users must re-authenticate to run the report.
Use ENCRYPTIONKEY
to specify the encryption key to be used to encrypt the user name and password of the database and system authentication cookies. The encryption key can be any character string. For example:
ENCRYPTIONKEY=egbdf
The DIAGBODYTAGS
and DIAGHEADTAGS
parameters are available for including additional HTML encoding in the <body>
and <head>
tags in the output files associated with diagnostic and debugging output.
DIAGBODYTAGS
defines the entire <body>
tag; while DIAGHEADTAGS
defines tags to appear between the open and close <head>
and </head>
tags.
You can use these to include formatting options to make diagnostic and debugging output easier to read. For example:
DIAGBODYTAGS=<BODY>additional HTML encoding</BODY> DIAGHEADTAGS=<HEAD>additional HTML encoding</HEAD>
A HELP
keyword is available with the rwservlet
command for bringing up a servlet-related help topic. The help file is invoked when you specify the following URL:
http://your_web_server/your_servlet_path/rwservlet/help
We provide a default help file for the servlet, ORACLE_HOME
\reports\templates\help.htm
, which will be displayed if you leave this parameter undefined. You may want to supply a help file of your own. To do this, specify the name and location URL of your servlet help file with the HELPURL
parameter in rwservlet.properties
. For example:
HELPURL=http://your_web_server/your_help_file_path/helpfile.htm
If you plan to take advantage of OracleAS Reports Services' Single Sign-On capability, you must ensure the SINGLESIGNON
parameter is set to YES
in rwservlet.properties
. SINGLESIGNON=Y
ES
by default upon installation.
For more information, refer to Section 11.3.1, "Enabling and Disabling OracleAS Single Sign-On".
By default, Reports Servlet uses the rwnetwork.conf
file to decide on the discovery mechanism it will use. If you want to use a custom network configuration file, set the REPORTS_NETWORK_CONFIG
property in rwservlet.properties
to a valid network configuration file name in the ORACLE_HOME
/reports/conf
directory. For example:
REPORTS_NETWORK_CONFIG=net3.conf
In Oracle Reports 10g Release 2 (10.1.2), Reports Server clustering is deprecated. An OracleAS Forms Services application from prior releases that includes a Reports Server cluster name will fail to bind to the Reports Server cluster it references.
To resolve this issue, Oracle Reports 10g Release 2 (10.1.2) introduces REPORTS_SERVERMAP
, which enables you to map a cluster name to a Reports Server name. This avoids the necessity to change the cluster name in all OracleAS Forms Services applications.
An OracleAS Forms Services application can call Oracle Reports in the following ways:
Using RUN_REPORT_OBJECT
. If the call specifies a Reports Server cluster name instead of a Reports Server name, the REPORTS_SERVERMAP
environment variable must be set in the OracleAS Forms Services default.env
file. For more information, see the Oracle Application Server Forms Services Deployment Guide.
Using WEB.SHOW_DOCUMENT
. In this case, the request is submitted to rwservlet
. If the call specifies a Reports Server cluster name instead of a Reports Server name, the REPORTS_SERVERMAP
parameter must be set in the rwservlet.properties
file. For example:
REPORTS_SERVERMAP=cluster:repserver
where
cluster
is the Reports Server cluster name that was present in prior releases (Oracle Reports 9i and 10g Release 1 (9.0.4)).
repserver
is the Reports Server name in the Oracle Reports 10g Release 2 (10.1.2).
When REPORTS_SERVERMAP
is set in rwservlet.properties
, any request to cluster
in the OracleAS Forms Services application is redirected to repserver
.
By default, Reports Servlet uses the rwservlet.properties
file as the configuration file. If you are running multiple OC4J instances with reports installed on the same Oracle Application Server and wish to use different configuration files, you can do so by adding the following start parameter to opmn.xml
:
-DServletPropFile =your_servlet_properties_file
For example:
<process-type id="OC4J_BI_Forms" module-id="OC4J"> ... <category id="start-parameters"> <data id="java-options" value="-server -Djava.security.policy =/private/oracle/FRHome_1/j2ee/OC4J_BI_Forms/config/java2.policy -Djava.awt.headless=true -Xmx512M" -DServletPropFile=servlet.prop/> <data id="oc4j-options" value="-properties -userThreads "/> </category>
Alternatively, you can edit the web.xml
file for Oracle Reports and add the initparam
to pass the servlet.properties
file name.
For example:
<servlet> <servlet-name>Reports servlet - /reports/rwservlet</servlet-name> <servlet-class>oracle.reports.rwclient.RWClient</servlet-class> <load-on-startup>1</load-on-startup> <init-param> <param-name>ServletPropFile</param-name> <param-value>myservlet.prop</param-value> </init-param> </servlet>
Reports Server includes a URL engine that can take the contents of any URL and distribute them. The URL engine enables you to leverage the powerful scheduling and distribution capabilities of Reports Server to distribute content from any publicly available URL to various destinations such as e-mail, OracleAS Portal, and WebDAV. Since Reports Server's destinations are pluggable, you can also add your own custom destinations for the URL content.
Furthermore, if you use the URL engine in conjunction with Reports Server's event-based APIs, database events can trigger the content distribution. For example, suppose you have created a JSP report for high fidelity Web publishing of data stored in a table containing employee expense data. You could then use the URL engine and the event-based API to e-mail that JSP whenever the expense application stores new or updated employee expense data in the table.
If the URL engine is not activated, you can activate it by doing the following:
Add an engine element for the URL engine to the server configuration file. For example, your engine element might be as follows:
<engine id="rwURLEng" class="oracle.reports.engine.URLEngineImpl" initEngine="1" maxEngine="1" minEngine="0" engLife="50" maxIdle="30" callbackTimeOut="60000" />
Add a job element that associates the appropriate job types with the URL engine to the server configuration file. For example, your job
element might be as follows:
<job jobType="rwurl" engineId="rwURLEng"/>
Stop and restart Reports Server.
Note: When you restart your Reports Server with these new elements, you should see the number of engines increase accordingly in the Reports Server status message box. In the preceding example, the number of engines would increase by one (the value ofinitEngine ) when you restart Reports Server.
|
To learn about sending requests to the URL engine, refer to Chapter 13, "Running Report Requests".
Some features of OracleAS Reports Services support retrieving or sending information through a firewall. For example, the URL engine, the XML data source, the Text data source, and the mail destination features all retrieve or send information through the firewall. For these features to function properly, Reports Server requires certain proxy information. In the interests of simplicity, you store the necessary proxy information in a single location and point to it from the Reports Server configuration file. To configure your Reports Server with proxy information, you do the following:
Add the pluginParam element to the server configuration file and have it point to the proxy information file (for example, proxyinfo.xml
). For example, your pluginParam
element might be as follows:
<pluginParam name="proxy" type="file">proxyinfo.xml</pluginParam>
Note: You can optionally specify a path for the proxy information file. By default, this file is located inORACLE_HOME /reports/conf .
|
Update the proxy information file with the necessary proxy values for your configuration. For example, proxyinfo.xml
might contain the following:
<proxyInfo> <proxyServers> <proxyServer name="xyz.abc.com" port="80" protocol="http"/> <proxyServer name="www-proxy1.xyz.abc.com" port="80" protocol="ftp"/> <proxyServer name="www-prox21.xyz.abc.com" port="80" protocol="https"/> </proxyServers> <bypassProxy> <domain>*.abc.com</domain> </bypassProxy> </proxyInfo>
Note: Refer to the default proxy information file,ORACLE_HOME /reports/conf/proxyinfo.xml , for additional information.
|
The best way to start, shut down, monitor, and manage Reports Server is through the Oracle Process Manager and Notification Server (OPMN) and Oracle Enterprise Manager 10g. OPMN provides a centralized mechanism for initializing, maintaining, and shutting down your Oracle Application Server components, including Reports Server. Oracle Enterprise Manager 10g, included with Oracle Application Server, provides managing and monitoring services to OracleAS Reports Services. You can conveniently monitor your Reports Servers through Oracle Enterprise Manager 10g and, if the process fails for any reason, OPMN restarts Reports Server for you automatically.
During installation of Oracle Application Server, Reports Servers are automatically configured in OPMN and registered with Oracle Enterprise Manager 10g. If you add any Reports Servers after installing Oracle Application Server, you should register the new server(s) in two places:
The Oracle Process Manager and Notification Server's opmn.xml
file.
The Oracle Enterprise Manager 10g's targets.xml
file.
To register a new Reports Server in both opmn.xml
and targets.xml
, run the following command line:
On UNIX:
ORACLE_HOME/bin/addNewServerTarget.sh reports_server_name
On Windows:
ORACLE_HOME\bin\addNewServerTarget.bat reports_server_name
Note: After running this command line, reload the OPMN configuration file for the change to take effect (for example,opmnctl reload ).
|
Components are configured with OPMN in the opmn.xml
file located in ORACLE_HOME
/opmn/conf
. This section describes how to configure the following components through OPMN:
COS Naming Service Specification (optional)
See Also: For a detailed description of OPMN configuration and the contents ofopmn.xml :
|
The module
tag is included by default in opmn.xml
and tells OPMN to load a particular module. In the case of Reports Server, the OracleAS Reports Services module must be loaded. This module is loaded with the following information, by default, in opmn.xml
:
<module path="/private/oraclehome/opmn/lib/libopmnreports"> <module-id id="ReportsServices"/> </module>
In the case of the standalone Reports Server, the Reports Server is running in its own component. Therefore, you must specify a separate component for Reports Server to control the server through OPMN. For example:
<ias-component id="<RSName>" status="enabled" id-matching="false"> <process-type id="ReportsServer" module-id="ReportsServices"> <process-set id="<RSName>" restart-on-death="true" numprocs="1"> <environment> <variable id="PATH" value="your_shell_path"/> </environment> <module-data> <category id="general-parameters"> <data id="batch" value="yes"/> </category> <category id="restart-parameters"> <data id="reverseping-timeout" value="120"/> </category> </module-data> <dependencies> <OID infrastructure="true"/> <database infrastructure-key="portal"/> <managed-process ias-component="OC4J" process-type="OC4J_BI_Forms" process-set="default_island" autostart="true"/> <managed-process ias-component="HTTP_Server" process-type="HTTP_Server" process-set="HTTP_Server" autostart="true"/> <managed-process ias-component="WebCache" process type="WebCache" process_set="WebCache" autostart="true"/> </dependencies> <start timeout="600" retry="2"/> <stop timeout="120"/> <restart timeout="600"/> <ping timeout="30" interval="30"/> </process-set> </process-type> </ias-component>
Note: Thetimeout values in the preceding example are all in number of seconds.
|
The key segments of this specification for Oracle Reports are described below.
<ias-component id="<RSName>" ...>
This tag specifies the name of Reports Server. It must match the Reports Server internal name from targets.xml
.
See Also: Chapter 19, "Managing and Monitoring OracleAS Reports Services" for more information ontargets.xml .
|
<process-type id="ReportsServer" module-id="ReportsServices">
This tag defines the process for the named Reports Server and associates it with the OracleAS Reports Services process module.
<process-set id="<RSName>" restart-on-death="true" numprocs="1">
This tag defines the process characteristics for the named Reports Server. It indicates whether Reports Server should be restarted when it fails. It also specifies the number of Reports Servers started for this process set, which has to be 1 because the process-set id identifies a single Reports Server name.
<variable id="PATH" value="your_shell_path"/>
The first tag specifies the value for the PATH
environment variable for the process. This variable must be set for the start script to find uname
. This environment
element is not needed on the Microsoft Windows platform.
<category id="general-parameters"> <data id="batch" value="yes"/> </category>
This group of tags gathers together all of the data (parameters) common to the process. In this particular example, it provides a way to specify that the BATCH
parameter be sent to Reports Server. batch=yes|no
is an option to the start and stop commands of Reports Server. If it is not configured, this option is not passed in to Reports Server.
<category id="restart-parameters"> <data id="reverseping-timeout" value="120"/> </category>
This group of tags indicates the restart parameters category, which defines parameters to be used in detecting whether the process has failed and needs to be restarted. If a notification is not received within the specified reverseping-timeout
period, then the process is considered failed and will be restarted.
<dependencies>
This tag delimits the list of components upon which Reports Server depends. For example, Reports Server typically depends upon, among other things, the Oracle HTTP Server and Oracle Application Server Containers for J2EE.
OPMN uses dependencies to determine whether to start a process. Like module-data
and environment
blocks, dependencies
blocks can be defined for multiple elements within opmn.xml
. OPMN creates an aggregate dependency list at the process set level that contains all of the dependencies defined at or above it. If duplicate dependencies are defined at different levels, then duplicate checks on that dependency are made before starting a process.
OPMN has two primary types of dependencies: external and internal. External dependencies are resources not managed by OPMN (the database, Oracle Internet Directory, and OracleAS Single Sign-On). For external resources, an external program performs the check on the resource. Internal dependencies are OPMN-managed processes, which may include processes managed by a remote OPMN instance. Internal dependencies are indicated in the list by the managed-process
tag.
OPMN maintains a cache of dependency states that contains the last known state of each dependency and the time it was last checked. A single cache entry exists for each dependency with identical attributes, even if that dependency is specified in multiple locations (that is, for different process sets). A cache timeout parameter for each dependency allows users to specify how long to use its state in the cache. Likewise, a general timeout parameter for each dependency determines how long OPMN should wait for a status update before aborting the dependency check and the process start.
Dependencies are checked in the order in which you declare them. The traversal of this list of dependencies concludes either when the full sequence of checks completes successfully (the resource is available) or when one of the checks fails (the resource is not available or the check timed out).
The following example tags illustrate a typical list of dependencies for Reports Server:
<OID infrastructure="true"/> <database infrastructure-key="portal"/> <managed-process ias-component="OC4J" process-type="OC4J_BI_Forms" process-set="default_island" autostart="true"/> <managed-process ias-component="HTTP_Server" process-type="HTTP_Server" process-set="HTTP_Server" autostart="true"/> <managed-process ias-component="WebCache" process-type="WebCache" process-set="WebCache" autostart="true"/>
The OID
tag indicates that Reports Server uses the default Oracle Internet Directory instance for this Oracle Application Server installation.
The database
tag points to the OracleAS Portal instance used by Reports Server.
The first managed-process
tag specifies the Oracle Application Server Containers for J2EE instance used by Reports Server. The second managed-process
tag indicates the Oracle HTTP Server instance.
See Also: For more information onopmn.xml and its contents:
|
In the case of the in-process server, Reports Server is running inside the OC4J component. If you are using the in-process server, then within the OC4J component you must specify the Reports Server data. For example:
<ias-component id="OC4J"> <process-type id="OC4J_BI_Forms"> <module-data><category id="urlping-parameters">
<data id="/reports/rwservlet/pingserver?start=auto" value="200"/>
</category>
</module-data> <process-set .../> </process-type> </ias-component>
The key segments of this specification are:
category
specification:
<category id="urlping-parameters">
where
urlping-parameters
is a category that identifies all of the URLs to be pinged by the OC4J module. The protocol used for pinging is AJPv1.3.
data
specification:
<data id="/reports/rwservlet/pingserver?start=auto" value="200"/>
where
/reports/rwservlet/pingserver?start=auto
is the URL to be pinged by the OC4J module. In the context of the in-process server, pinging this URL allows OPMN to determine whether the Reports Server application is responsive. If it is unresponsive, OPMN restarts the corresponding OC4J process.
Note: Thepingserver command to Reports Servlet attempts to start the in-process server. If Reports Server setup is not correct, it fails to start the engine. This causes Reports Server to go into deadlock and not send success status back to OPMN. OPMN interprets this as a failure of the OC4J_BI_FORMS instance and attempts to restart this instance. To recover from this condition, verify the Reports Server setup to make sure it is able to spawn engines properly. For additional information, see Section 3.9, "Optimizing the Deployment of Reports".
|
value="200"
specifies a valid HTTP code (200
) that is expected in response to the ping request. If the response HTTP code matches the value configured here, OPMN considers the application healthy and responsive. Otherwise, OPMN restarts the OC4J process.
The Oracle Reports bridge runs within its own component. Therefore, you must specify a separate ias-component
tag for the Oracle Reports bridge to control the bridge through OPMN.
For troubleshooting scenarios and diagnosis, see Section D.8, "Diagnosing Oracle Reports Bridge Problems".
The following are examples for a minimum bridge configuration as well as a full bridge configuration.
Example 3-1 Minimum Configuration for Oracle Reports Bridge
<ias-component id="your_bridge_name" status="enabled" id-matching="false" xmlns="http://www.oracle.com/ias-instance"> <process-type id="ReportsBridge" module-id="ReportsBridgeServices"> <process-set id="your_bridge_name" restart-on-death="true" numprocs="1"> <environment> <variable id="PATH" value="your_oracle_home_directory/jdk/jre/bin" append="true"/> <variable id="PATH" value="your_shell_path" append="true"/> <variable id="CLASSPATH" value="your_oracle_home_directory /jlib/zrclient.jar" append="true"/> <variable id="CLASSPATH" value="your_oracle_home_directory /reports/jlib/rwrun.jar" append="true"/> </environment> </process-set> </process-type> </ias-component>
Example 3-2 Full Configuration for Oracle Reports Bridge
<ias-component id="your_bridge_name" status="enabled" id-matching="false"> <process-type id="ReportsBridge"module-id="ReportsBridgeServices"> <process-set id="your_bridge_name" restart-on-death="true" numprocs="1"> <environment> <variable id="PATH" value="your_shell_path" append="true"/> <variable id="CLASSPATH" value="your_oracle_home_directory /jlib/zrclient.jar" append="true"/> <variable id="CLASSPATH" value="your_oracle_home_directory /reports/jlib/rwrun.jar" append="true"/> </environment> <module-data> <category id="restart-parameters"> <data id="reverseping-timeout" value="120"/> </category> <category id="start-parameters"> <data id="jvm-options" value="="-Xms128mb -Xmx256mb"/> <data id="bridge-options" value="start_options_if_any"/> </category> <category id="stop-parameters"> <data id="jvm-options" value="-Xms128mb -Xmx256mb"/> <data id="bridge-options" value="stop_options_if_any"/> </category> </module-data> <start timeout="120" retry="3"/> <stop timeout="120"/> <restart timeout="120" retry="0"/> </process-set> </process-type> </ias-component>
By default, Oracle Reports uses the built-in broadcast mechanism for Reports Server discovery. Alternatively, Oracle Reports clients can use the Common Object Service (COS) naming service for Reports Server discovery to submit report requests when the built-in broadcast mechanism is not suitable for your environment, as in the following scenarios:
Oracle Reports is installed on a machine that is connected to a network using VPN.
You want to avoid broadcast traffic on your network.
For more information, see Section 1.4.2, "Server Discovery Using the COS Naming Service".
To control the COS naming service through OPMN, the opmn.xml
file must include a custom ias-component
tag, as follows:
<ias-component id="namingservice"> <process-type id="namingservice" module-id="CUSTOM"> <environment> <variable id="PATH" value="ORACLE_HOME\jdk\bin"/> </environment> <process-set id="namingservice" numprocs="1"> <module-data> <category id="start-parameters"> <data id="start-executable" value="ORACLE_HOME\jdk\bin\orbd"/> <data id="start-args" value="-ORBInitialPort port"/> </category> </module-data> </process-set> </process-type> </ias-component>
where
ORACLE_HOME
is your Oracle Home directory.
port
is the port on which you want to start the COS naming service. This port must be specified in your rwnetwork.conf
file, as described in Section 3.3.1.3, "namingService".
Additionally, to make sure that OPMN starts the COS naming service before it attempts to start Reports Server, opmn.xml
must include the following dependency:
<ias-component id="vin" status="enabled" id-matching="false"> <process-type id="ReportsServer" module-id="ReportsServices"> ... <managed-process ias-component="namingservice" process-type="namingservice" process-set="namingservice" autostart="true"/> ... </process-type> </ias-component>
To use OPMN to control the COS naming service, perform the following steps:
Stop Reports Server and OC4J_BI_Forms.
Edit the opmn.xml
file and add an ias-component
tag. For example:
... <ias-component id="namingservice"> <process-type id="namingservice" module-id="CUSTOM"> <environment> <variable id="PATH" value="G:\FRHome_2\jdk\bin"/> </environment> <process-set id="namingservice" numprocs="1"> <module-data> <category id="start-parameters"> <data id="start-executable" value="G:\FRHome_2\jdk\bin\orbd"/> <data id="start-args" value="-ORBInitialPort 8988"/> </category> </module-data> </process-set> </process-type> </ias-component> ...
Add a dependency to the Reports Server ias-component
tag. For example:
... <ias-component id="vin" status="enabled" id-matching="false"> <process-type id="ReportsServer" module-id="ReportsServices"> <process-set id="vin" restart-on-death="true" numprocs="1"> <environment> <variable id="PATH" value="C:/OraHome/bin;C:/WINNT/system32;C:/WINNT"/> </environment> <module-data> <category id="general-parameters"> <data id="batch" value="yes"/> </category> <category id="restart-parameters"> <data id="reverseping-timeout" value="120"/> </category> </module-data> <dependencies> <OID infrastructure="true"/> <database infrastructure-key="portal"/> <managed-process ias-component="namingservice" process-type="namingservice" process-set="namingservice" autostart="true"/> <managed-process ias-component="OC4J" process-type="OC4J_BI_Forms" process-set="default_island" autostart="true"/> <managed-process ias-component="HTTP_Server" process-type="HTTP_Server" process-set="HTTP_Server" autostart="true"/> </dependencies> <stop timeout="120"/> <restart timeout="600"/> <ping timeout="30" interval="30"/> </process-set> </process-type> </ias-component> ...
Navigate to your ORACLE_HOME
/opmn/bin
directory.
Run one of the following commands:
If OPMN is up and running, to reload the changes made to the opmn.xml
file: opmnctl reload
If OPMN is not running: opmnctl start
Start the COS naming service using either of the following commands:
opmnctl startproc ias-component=namingservice
OR
opmnctl startproc process-type=namingservice
Modify the rwnetwork.conf
file to use the COS naming service instead of the default broadcast mechanism, as described in Section 3.3.1.3, "namingService".
Start OC4J_BI_Forms and Reports Servers.
To stop the COS naming service, use the following command:
opmnctl stopproc ias-component=namingservice
To restart the COS naming service, use the following command:
opmnctl restartproc ias-component=namingservice
Troubleshooting: If a COMM_FAILURE
error displays when Reports Server is started, either the naming service is not started properly or the port is not specified properly. To resolve this error, check whether the naming service process orbd
is running. If not, start it. If the orbd
process is running, check the port specified for namingService
in the rwnetwork.conf
file. It should be same as the port on which orbd
is started.
When you execute the command opmnctl stopall
, Reports Server may not stop gracefully, and may be killed by OPMN. This is because OPMN does not check the dependency while stopping the process. If OPMN stops the COS naming service before stopping Reports Server, Reports Server will not shut down gracefully. This is harmless, and can be ignored.
Oracle Workflow delivers a complete business process management system that supports business process definition, business process automation, and business process integration. The Oracle Workflow engine is part of the Oracle database. For more information, refer to the Oracle Workflow 10g page on the Oracle Technology Network (OTN) at http://www.oracle.com/technology/products/ias/workflow/index.html
.
By integrating Oracle Workflow with Oracle Reports, you can include Oracle Reports execution as one of the activities in your business process. For example, as soon as a manager approves an expense report, Oracle Workflow generates a report. Additionally, the report notifies the Oracle Workflow engine when the report execution is complete, triggering the next activity in the business process.
For complete information about integrating Oracle Workflow with Oracle Reports, refer to the Integrating Oracle Workflow with Oracle Reports white paper on OTN (http://www.oracle.com/technology/products/reports/features/workflow
). This white paper explains how to install and configure Oracle Workflow and Oracle Reports to communicate with each other, and also provides the steps to include report-specific functions in your business process. Specifically, it covers installing and configuring Oracle Reports and Oracle Workflow, defining an Oracle Workflow process for running a report, running a report from the Oracle Workflow process, and troubleshooting assistance.
Before you deploy a report on a machine that is either slow or is running on a load, you may want to configure the following:
Ping timeout (OPMN-side): Ping timeout is the measure that OPMN uses to determine the time that it must wait for a callback from an in-process Reports Server (in OC4J_BI_FORMS
) before considering it as a timeout.
The default timeout period is 150
. This period is calculated from: ping timeout
, ping interval
, and number of retries
. The default values for these are:
ping timeout = 30 seconds ping interval = 20 seconds number of retries - 3
Note: Thenumber of retries is applicable only when OPMN successfully connects to OC4J and receives regular ONS notifications from the process.
|
Based on these values, there will be three ping attempts with a timeout of 30 seconds each at 20 second intervals. The first ping is done after the specified ping interval
. Thus, from the time the OC4J is started by OPMN, approximately 150 (20 + 3*30 + 2*20) seconds will elapse before the process is considered unresponsive and restarted. However, if after OPMN connects to OC4J but OC4J is too slow in sending regular ONS notifications, then the 30 second timeout applies.
You can configure the ping timeout by adding a ping entry with sufficient timeout configured to the machine's load in following element in opmn.xml
:
<ias-component id="OC4J"> ... <process-type id="OC4J_BI_Forms" module-id="OC4J"> ... <restart timeout="720" retry="2" /> ... <ping timeout="110" interval="30" /> ...
You can also switch off the URL ping by removing or commenting out the following element in opmn.xml
:
<category id="urlping-parameters"> <data id="/reports/rwservlet/pingserver?start=auto" value="200" /> </category>
Then, restart OC4J_BI_Forms
.
Report Server start or restart timeout (OPMN.xml
): Start or restart timeout is the measure that OPMN uses to determine the time that it must wait for Reports Server process type to start or restart (process-type id="ReportsServer"
in opmn.xml
) before considering it as a timeout.
The default timeout period is 600
. The default values for these are:
<start timeout="600" retry="2"/> <restart timeout="600"/>
When running on a loaded machine, an attempt to start all Reports Servers by OPMN may result in a start timeout for some Reports Servers as some of them were not able to finish the start up activities completely. Note that Reports Server also starts the number of engines specified in the initengine
property of the engine
element in the server_name.
config
file. Starting up these engine processes might take some time in loaded machines. In parallel to finetuning the Reports Server process start or restart property, you must also finetune the callbackTimeout
property in server_name.
config
, as explained in the next bullet item.
Callback timeout (Reports Server-side): Callback timeout is the measure that Reports Server uses to determine the time that it must wait for a response from the engine before timing out. You can specify this value in the server_name.
config
file. This time out period is in milliseconds.
For example:
<engine id="rwEng" class="oracle.reports.engine.EngineImpl" initEngine="1" maxEngine="1" minEngine="0" engLife="50" maxIdle="30" callbackTimeOut="90000">
Note: Increase the callback timeout when the machine is very slow. |
Prior to Oracle Reports 10g Release 1 (9.0.4) on UNIX, you had to set the DISPLAY
environment variable in order for Reports Server to use the windowing system display surface for creating images and getting pixel resolution. This dependency is removed with Oracle Reports 10g.
Additionally, earlier releases required a valid printer on UNIX for fonts. When no valid printer was available, OracleAS Reports Services used the screen fonts, which again required setting the DISPLAY
environment variable. Now, OracleAS Reports Services includes a default screen printer surface, ScreenPrinter, that emulates a screen or printer for fonts in the absence of an available printer. As a result, OracleAS Reports Services no longer requires a printer on UNIX.
By default, the environment variable REPORTS_DEFAULT_DISPLAY
is set to YES
, which specifies that OracleAS Reports Services should:
remove the dependency on the DISPLAY
environment variable (UNIX only)
use ScreenPrinter for surface resolution for images and font information (UNIX only)
enable the Advanced Imaging Support (all platforms)
If you wish to revert to the dependency on the DISPLAY
environment variable as in prior releases, you can set REPORTS_DEFAULT_DISPLAY=NO
.
The PostScript printer driver screenprinter.ppd
provides surface resolution for images and specifies font information. This driver is the first entry in uiscreenprint.txt
. The file locations (UNIX only) are:
uiscreenprint.txt : ORACLE_HOME/guicommon/tk/admin screenprinter.ppd : ORACLE_HOME/guicommon/tk/admin/PPD
ScreenPrinter is used for:
Surface resolution when REPORTS_DEFAULT_DISPLAY=YES.
Removal of the printer dependency.
If, when generating report output, there is no valid printer queue available (not found from TK_PRINTER,ORACLE_PRINTER,PRINTER
, or uiprint.txt
), the surface based on screenprinter.ppd
will be created and used to get font information. You can modify the Fonts
section of screenprinter.ppd
to include new fonts, and modify the DefaultResolution
field to change the resolution (DefaultResolution
is 96).
Note: If you do add new fonts, ensure that the new AFM metrics files are placed in the AFM directory. |
The font look up algorithm on UNIX is:
if a valid printer available then look up font information from the printer else create a screenPrinter surface look up font information from ScreenPrinter if ScreenPrinter creation fails then REP-1800 : Formatter Error if REPORTS_DEFAULT_DISPLAY is set else use Screen Fonts
Note: In certain multibyte languages like Chinese, you may want to use screen fonts. However, this would necessitate setting theDISPLAY variable for running the report.
To revert to
|
The quality of images contributes considerably to the overall appearance of a report, particularly for a Web report. You may prefer different image formats in your report output depending on the needs of your project. For example, an aeronautical firm might prefer the higher quality of JPEG or PNG images in their Web reports instead of GIF images. On the other hand, if you are building a Web portal, you might prefer GIF images because of their smaller size and faster download. Similarly, you may wish to import images of these various formats into your report.
Depending on the format of your output, you may choose from a variety of formats for your images.
Table 3-31 Image Format Options by Output Type
Report Output | Available Image Format Choices |
---|---|
HTML, HTMLCSS |
PNG, JPEG, JPG, GIF |
|
PNG, JPEG, JPG, GIF |
RTF |
PNG, JPEG, JPG, BMP |
Note: As you choose your image format, you should take into account the quality and size considerations. Typically, the higher the quality of the image format, the greater the size. For example, PNG and JPEG are higher quality than GIF, but they may also require more storage space. |
To enable advanced imaging, you must set the REPORTS_DEFAULT_DISPLAY
environment variable to YES. The REPORTS_OUTPUTIMAGEFORMAT
environment variable lets you choose the default image type. Users can override the default choice for images with the OUTPUTIMAGEFORMAT
command line keyword. For example:
rwclient server=my_rep_server report=images.rdf destype=file desformat=html desname=images.html userid=scott/tiger outputimageformat=PNG
Enabling advanced imaging also enables you to import images of these same formats into your report.
Usage Notes
UNIX only: Enabling advanced imaging means that you can no longer use the old Computer Graphics Metafile (CGM) and Oracle Graphics Data (OGD) formats in HTML or HTMLCSS output. If you require these formats for input sources, you should set REPORTS_DEFAULT_DISPLAY
=NO
. This limitation does not apply on the Windows platform.
Running a report with JPEG images (REPORTS_OUTPUTIMAGEFORMAT=JPEG
) to RTF output causes an increase in the RTF file size that is not directly proportionate to the image size. This occurs because the binary image stream is first converted to HEX characters and then written to RTF. This conversion increases the file size. This is consistent with the RTF specification and is expected behavior. However, an RTF file with JPEG images is of a smaller size when compared to an RTF file with BMP images.