3 Configuring OracleAS Reports Services

3.2.1.1 server

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.

3.2.1.2 compatible

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.

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.

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.

3.2.1.3 cache

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.

The cache element attribute is described in Table 3-3.

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"/>
  

3.2.1.4 engine

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.

The engine element attributes are described in Table 3-4.

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.

3.2.1.5 security

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> 

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.

The security element attributes are described in Table 3-5.

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.

3.2.1.6 oidconnection

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.

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".

3.2.1.7 destination

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.

The destination element attributes are described in Table 3-7.

You also have the option of entering multiple properties under the destination element. The only requirement is that they be name/value pairs recognized by the Java class that is a subclass of the Reports Server Destination Java class. For example:

<destination destype="oraclePortal" class="oracle.reports.server.DesOraclePortal">
<property name="portalUserid" 
          value="portal_db_username/portal_password@portal_db_connection"
          confidential="yes" encrypted="no"/>
</destination>

In this example, the property provides connect information to enable Reports Server to access OracleAS Portal. The confidential and encrypted attributes are included to automatically invoke encryption on the portalUserid value the next time Reports Server is started.

Should your destination implementation require additional information, specify the information in the pluginParam element.

3.2.1.8 networkConfig

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.

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".

3.2.1.9 job

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.

3.2.1.10 notification

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.

The notification element attributes are described in Table 3-10.

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&notifyfailure=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.

3.2.1.11 log

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.

3.2.1.12 jobStatusRepository

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.

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.

3.2.1.13 trace

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.

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.

The traceOpts element attributes are described in Table 3-14.

3.2.1.14 connection

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.

In addition to its attributes, connection has a sub-element: orbClient.

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.

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.

3.2.1.15 ORBPorts

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.

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.

3.2.1.16 queue

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.

The queue element attribute is described in Table 3-18.

3.2.1.17 persistFile

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.

3.2.1.18 jobRecovery

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.

3.2.1.19 identifier

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:

1. Edit the server configuration file, server_name.conf.

2. Replace the encrypted username/password values generated with custom values.

3. Set encrypted=no.

   
   

   Note: Set confidential=no only if you do not want the username/password to be encrypted.

   
   

   For example:

   <identifier confidential="yes" encrypted="no">username/password</identifier>
   
   

4. Restart Reports Server. Reports Server sets encrypted=yes when it restarts.

5. 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.

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".

3.2.1.20 pluginParam

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.

3.2.1.21 environment

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.

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.

3.2.2.1 Examples

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.

3.2.2.2 Usage Notes

• 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 current reports.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 current reports.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:

  1. Open reports.sh and comment the environment variable value. For example, comment the REPORTS_PATH value set in the reports.sh file.

  2. Open the server_name.conf file.

  3. 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>
     
     

  4. 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">
     
     

  5. Now run the report.

3.3.1.1 discoveryService

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.

3.3.1.2 multicast

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.

3.3.1.3 namingService

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".

The namingService element attributes are described in Table 3-25.

3.3.2.1 bridge

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.

3.3.2.2 networkConfig

For information on the networkConfig element, refer to Section 3.2.1.8, "networkConfig".

3.3.2.3 identifier

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:

1. Uncomment the identifier element in the bridge configuration file.

2. 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>
   
   

3. 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.

3.3.2.4 remoteBridges

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.

3.3.2.5 remoteBridge

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)

Description of "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)

Description of "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.

3.3.2.6 trace

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.

The trace element attributes are described in Table 3-28.

3.7.1.1 Module Specification

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> 

3.7.1.2 Standalone Reports Server Specification

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>

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.

<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.

3.7.1.3 In-process Reports Server Specification

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: The pingserver 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.

3.7.1.4 Oracle Reports Bridge Specification

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.

<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>

<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>

3.7.1.5 COS Naming Service Specification

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:

1. Stop Reports Server and OC4J_BI_Forms.

2. 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>
   ...
   
   

3. 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>
   ...
   
   

4. Navigate to your ORACLE_HOME/opmn/bin directory.

5. 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

6. Start the COS naming service using either of the following commands:

   opmnctl startproc ias-component=namingservice

   OR

   opmnctl startproc process-type=namingservice

7. 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".

8. 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.