6
Configuring Oracle Reports Server Clusters

This chapter will show you how to configure Oracle Reports Servers in a cluster to improve performance and loading balancing. This becomes important as the need to deliver information to a rapidly growing user base becomes more demanding.

Oracle Reports Servers clustering addresses this demand by leveraging your organization's existing hardware investment by plugging in additional application servers as they are needed. This enables the processing capabilities of your Oracle Reports Servers to grow as your organization grows.

Before you begin to configure your Oracle Reports Servers for clustering, you should be familiar with the basic Oracle Reports Services architecture. See Chapter 1, "Publishing Architecture and Concepts" for more information. You must also have already set up your Oracle Reports Services using a basic configuration. See Chapter 3, "Configuring the Oracle Reports Server on Windows NT and UNIX" for more information.

6.1 Clustering Overview

Suppose that you have three machines configured as Oracle Reports Servers that you want to cluster. These machines are described below:

Table 6-1 Example Server Machines Descriptions

Machine/Server TNS name	Description	Master/Slave
NT-1	4 CPU NT server	Master
NT-2	2 CPU NT server	Slave
SUN-1	2 CPU Sun Solaris workstation	Slave

Note:
The decision to make the NT-1 machine the master server was arbitrary. The number of CPUs was not a determining factor.

For step-by-step instructions on configuring Oracle Reports Servers in a cluster as described in this overview, see Section 6.2, "Configuring Oracle Reports Servers in a Cluster Example".

You will designate NT-1 as the master, then set the CLUSTERCONFIG parameter to enable this server to recognize NT-2 and SUN-1 as slaves. To simplify this example, the MAXENGINE parameter and MINENGINE parameter for the master and each slave server are set to the number of CPUs available on each machine.

Once the machines are configured, you will send report requests to the master server (that is, SERVER=NT-1) which redirects the reports to the slaves. When the master server is started, it checks the configuration file. The master contacts each of the slave servers in the order that they are listed in the configuration file and notifies them to start up the defined number of engines (for example, two engines each). When the slave engines are started, they are under the control of the master, which allocates jobs to them using a round-robin algorithm.

Suppose that the master server (that is, NT-1) receives seven report requests. The master uses its four engines to run the first four reports. For the fifth and sixth reports, the master redirects the requests to the two NT-2 engines to run them. When the master receives the seventh report, it redirects the request to the first SUN-1 engine to run it. All output is written to a central cache (that is, one that is shared by all servers). The master sends the output back to the requestor (for example, a Web browser).

It is possible for slave servers to remain fully functional Oracle Reports Servers in their own right if they can start engines independently of the master server. Suppose that the MAXENGINE and MINENGINE parameters of the NT-2 Oracle Reports Services configuration are set to three. This means that three engines are dedicated to the NT-2 Oracle Reports Servers and can receive requests without the master's knowledge. When configured as a slave server (that is, the MAXENGINE and MINENGINE parameters in the master configuration for NT-2 are set to two), the NT-2 Oracle Reports Services has a total of five engines started: three engines that are dedicated to the NT-2 server and two engines are dedicated slaves to the master.

6.2 Configuring Oracle Reports Servers in a Cluster Example

This section provides step-by step instructions for configuring Oracle Reports Server clusters. This example describes the following:

Enabling communication between the master and slaves
Configuring the master server
Running report requests to clustered servers
Resubmitting jobs when an engine goes down
Adding a server to an existing configuration

In this example, you will configure the server machines for clustering as described in Table 6-1, " Example Server Machines Descriptions".

The following assumptions have also been made for each machine:

The Oracle Reports Services component has been installed.
Oracle Reports Services has been configured using the machine name as the TNS service entry name (for example, NT-1) in the tnsames.ora file.
A central file server is running and set up with two directories: a Source directory (where report definition files are stored) and a Cache directory (where all cached report output is sent).

All engines must write their output to a central cache and all engines read report definition files from a central source directory. A central source directory guarantees that all engines are running the same reports. This also eliminates copying updated report definition files to various locations. A central cache enables the master server to serve duplicate jobs and jobs run within the specified tolerance without going to each slave server's local disk.
All engines see the same aliases for printers (unless the output is always being sent to the default printer).

6.2.1 Enabling Communication Between Master and Slaves

On the NT-1 machine (master) you open the tnsnames.ora located in the ORACLE_HOME\NET80 directory in a text editor, and add the following. The nt-2.world and sun-1.world are the names of the server instances and .world is the domain specified in the NAMES.DEFAULT_DOMAIN setting in the sqlnet.ora file. If the NAMES.DEFAULT_DOMAIN setting is not defined in the sqlnet.ora, then omit .world from the name of the server instance:

nt-2.world=(ADDRESS=(PROTOCOL=tcp)(HOST=nt-2)(PORT=1949))
sun-1.world=(ADDRESS=(PROTOCOL=tcp)(HOST=sun-1)(PORT=1949))

On the NT-2 machine (slave) you do the following:

Open the tnsnames.ora located in the ORACLE_HOME\NET80 directory in a text editor, and add the following, where nt-1.world is the name of the server instance and .world is the domain specified in the NAMES.DEFAULT_DOMAIN setting in the sqlnet.ora file. If the NAMES.DEFAULT_DOMAIN setting is not defined in the sqlnet.ora, then omit .world from the name of the server instance:
```
nt-1.world=(ADDRESS=(PROTOCOL=tcp)(HOST=nt-1)(PORT=1949))
```
Open the nt-2.ora (the Oracle Reports Services configuration file) located in the ORACLE_HOME\REPORT60\SERVER directory, and set the INITEGINE parameter to 0. This ensures that the only engines created at startup are the ones started by the master.
Repeat steps 1 and 2 on the SUN-1 server machine. In step 2, edit the sun-1.ora configuration file.

6.2.2 Configuring the Master Server

In this section your will configure the master using the following settings:

Edit the master server configuration file to identify the slave servers to the master and to control the number of engines associated with master server.
Set the parameters in the master server configuration file that defines the following:
- Engine settings are defined that identify the cache and source directories.
- Since there are four CPUs on this machine, you will use four local engines to start at the same time as the server.
- These four engines will shut down if they are idle for 60 minutes, and will restart after running 50 jobs.
- The number of processes that can communicate with the server at one time is set to the maximum number of 4096.
Set the CLUSTERCONFIG parameter to identify the slave servers to the master. In this example, you will start two engines on each slave server when the master is started.

The ENGLIFE and MAXIDLE parameters for the master server's engines are implied for all slave engines. The unit of measure for the MAXIDLE parameter is minutes and the ENGLIFE parameter is the number of engines.

On the NT-1 server machine (master) you do the following:

Open nt-1.ora (the Oracle Reports Services configuration file) located on ORACLE_HOME\REPORT60\SERVER directory.

Edit the configuration file according to settings below:

maxconnect=4096
sourcedir="X:\Source"
cachedir="X:\Cache"
cachesize=50
minengine=0
maxengine=4
initengine=4
maxidle=60
englife=50

The NT-1 machine is mapped to the central server on the X: drive.

Edit the configuration file according to the settings below:

clusterconfig="(server=nt-2
minengine=0
maxengine=2
initengine=2
cachedir="W:\Cache")
(server=sun-1
minengine=0
maxengine=2
initengine=2
cachedir="/share/Cache")"

where:

server

is the TNS service entry name of the slave server.

minengine

is the minimum number of runtime engines this master server should have available to run reports.

maxengine

is the maximum number of runtime engines this master server has available to run reports.

initengine

is the initial number of runtime engines started by this master server.

cachedir

is the central cache directory for this master server.

Usage Notes

When configuring the master server, you should consider the following:

Each slave definition must be surrounded by parenthesis.
The cache directory setting for the NT and the UNIX machines are different. Not all servers need to see the shared file system by the same definition (that is, the master is mapped to the X: drive, while the slave is mapped to W: drive).
The slave servers must have their REPORTS60_PATH environment variable set to /share/Source (for the SUN-1 server machine) and set to W:\Source (for the NT-2 machine).
Shut down and restart the master server so that the master server can recognize the new configuration.

This completes the configuration. Eight engines will start when the master server is started.

6.2.3 Running Reports in a Clustered Configuration

To run report requests to Oracle Reports Servers that have been configured for clustering, you specify the master server in the SERVER command line argument (that is, SERVER=NT-1)along with any other relevant arguments for the thin client executable. The master server assigns incoming jobs to the engines on the slave servers.

If you set the REPORTS60_REPORTS_SERVER environment variable to the master server, then you can omit the SERVER command line argument. See Appendix C, "Environment Variables" for more information.

See Chapter 4, "Running Report Requests" for more information on the various report request methods you can use.

See Section 6.2.4, "Resubmitting Jobs When an Engine Goes Down" if you have problems submitting report requests to the server cluster.

The master server's jobs can be monitored by using the Queue Viewer in the Queue Manager. Refer to the Queue Manager online help for more information.

6.2.4 Resubmitting Jobs When an Engine Goes Down

If an engine goes down while a report is running, then the Retry settings defined in the SCHEDULE command line argument dictate whether the job will be re-run. If no Retry settings have been specified, then the job is lost. This job failure, however, will be logged against the server log file, and displayed in the list of jobs in the Queue Manager. If the command line includes retry settings, then the master server will re-run the job with the next available engine.

Suppose that you have submitted a job with the Retry option set to 2 in the SCHEDULE command line argument. The master server starts the report request on the second slave engine on the NT-2 server. However, the NT-2 server runs out of temporary space and the job terminates. The master server will resubmit the job. Assuming that no other jobs have been submitted, this job is assigned to the first engine on the SUN-1 server.

The retry option is useful for giving you fail-over support, but should be used with caution. For example, setting the retry to a large number might not solve the problem. The resubmitted job might always fail if the underlying problem is with the report itself, not the engine.

6.2.5 Adding Another Slave Server to the Master

You want to add another slave server to the existing cluster configuration as defined in the following table:

Table 6-2 Additional Server Machine Description

Machine/Server TNS name	Description	Master/Slave
SUN-2	4 CPU Sun Solaris server	Slave

This example assumes that this machine has already been configured as an Oracle Reports Server. The TNS service entry name for Oracle Reports Server is the machine name.

On the SUN-2 server machine (slave), open the sun-2.ora (the Oracle Reports Services configuration file) located in the ORACLE_HOME\REPORT60\SERVER directory and add the following, where nt-1.world is the name of the server instance and .world is the domain specified in the NAMES.DEFAULT_DOMAIN setting in the sqlnet.ora file. If the NAMES.DEFAULT_DOMAIN setting is not defined in the sqlnet.ora, then omit .world from the name of the server instance:

nt-1.world=(ADDRESS=(PROTOCOL=tcp)(HOST=nt-1)(PORT=1949))

On the NT-1 server machine (master), do the following:

Open the tnsnames.ora file located in the ORACLE_HOME\NET80\ADMIN directory and add the following entry, where sun-2.world is the name of the server instance and .world is the domain specified in the NAMES.DEFAULT_DOMAIN setting in the sqlnet.ora file. If the NAMES.DEFAULT_DOMAIN setting is not defined in the sqlnet.ora, then omit .world from the name of the server instance:
```
sun-2.world=(ADDRESS=(PROTOCOL=tcp)(HOST=sun-1)(PORT=1949))
```

Open the nt-1.ora (the Oracle Reports Services configuration file) and add the following bold text to the already existing CLUSTERCONFIG parameter:

clusterconfig="(server=nt-2
minengine=0
maxengine=2
initengine=2
cachedir="W:\Cache")
(server=sun-1
minengine=0
maxengine=2
initengine=2
cachedir="/share/Cache")
(server=sun-2
minengine=0
maxengine=4
initengine=4
cachedir="/share/Cache")"

Shut down and restart the master server so that the master server can recognize the newly configured slave server.

Suppose that while you were configuring the SUN-2 machine as a slave server, another administrator took down the NT-2 machine (for example, to perform a backup). While the NT-2 machine is still down, you restart the Oracle Reports Server on the NT-1 machine. The NT-1 machine was able to start the slave engines on the two Sun machines, but could not start the slave engines on the NT-2 machine because it was down.

Because the NT-1 server is polling all the slave servers, once the NT-2 machine is brought back up and Oracle Reports Services started, the NT-2 machine will be detected automatically by the NT-1 server. When the four slave engines start, they are available to receive jobs from the master.

`server`	is the TNS service entry name of the slave server.
`minengine`	is the minimum number of runtime engines this master server should have available to run reports.
`maxengine`	is the maximum number of runtime engines this master server has available to run reports.
`initengine`	is the initial number of runtime engines started by this master server.
`cachedir`	is the central cache directory for this master server.

6 Configuring Oracle Reports Server Clusters