Oracle Discoverer 4i Configuration Guide for Oracle9i Application Server Release 4.1 for Windows NT A87430-01 |
Library | Service | Contents | Index

# 2
Running, Maintaining and Supporting
Oracle Discoverer 4i

This chapter explains how to run, maintain and support Discoverer 4i.

The topics include:

- Running Discoverer 4i

- Using the Discoverer NT Service

- Registering and Unregistering Discoverer Services Components

- Editing the End User Preferences

- Shutting Down

- Adding and Removing Server Machines

- Utilizing the Discoverer 4i Viewer JavaScript Enhanced User Interface

- Frequently Asked Questions

## 2.1 Running Discoverer 4i

Once you have completed the Oracle9i Application Server installation (see the Oracle9i Application Server Installation Guide) you can run Discoverer 4i Plus and Oracle Discoverer 4i Viewer.

Note: Before users can use Discoverer to analyze data, the database must contain a Discoverer Release 4.1 EUL. You must create or update the EUL with Oracle Discoverer Administration Edition Release 4.1 or later.

### 2.1.1 Running Discoverer 4i Plus

To run Discoverer 4i Plus complete the following steps:

1. Start a browser window and type in your own details using the following as a guide:

   http://hostname.domain/discwb4/html/english/welcome.htm

   Where hostname.domain represents the Web server machine that the HTTP server is installed on. When specifying a Web server name, you must use its fully qualified host name (including port number if necessary). For example:

   http://machinename.oracle.com:7777/discwb4/html/english/welcome.htm

1. Specify a language and region and click Next.

   If you are using a Netscape browser and depending on the software already installed on the client machine, you might be prompted to download and install Oracle JInitiator. If you are not prompted to download and install Oracle JInitiator, skip the next step.

   1. If you see the above screen, follow the on-screen instructions to download and install Oracle JInitiator.

      When you have installed Oracle JInitiator (if necessary) or if you did not have to install Oracle JInitiator, the following screen appears.

      1. Click on the large image to start Discoverer 4i Plus.

         When the Discoverer 4i Plus applet has loaded, the Login Screen appears.

         1. Enter your User Name, Password and database connect string.

         2. Click Connect.

         You are now running Oracle Discoverer 4i Plus.

         ### 2.1.2 Running Discoverer 4i Viewer

         To run Discoverer 4i Viewer complete the following steps:

         1. Start a browser window and type in your own details using the following as a guide:

            http://hostname.domain/discoverer4i/viewer

            Where hostname.domain represents the Web server machine that the HTTP server is installed on. You must replace this with its fully qualified host name (including port number if necessary). For example:

            http://machinename.oracle.com:7777/discoverer4i/viewer

            This will start Oracle Discoverer 4i Viewer and you will see the following login screen:

         2. Enter your User Name, Password and database connect string.

         3. (Optional) If you are connecting as an Oracle Applications user (to an Oracle Applications database) select the Oracle Applications User check box
            If the Oracle Applications User check box is not displayed in the connect screen above, refer to Section A.1, "Specifying display of the Applications User Checkbox in the Discoverer 4i Viewer Connect Dialog".

         4. Click Connect

         You are now running Oracle Discoverer 4i Viewer.

         ## 2.2 Using the Discoverer NT Service

         ### 2.2.1 What is an NT Service?

         An NT Service is a special process that NT can start automatically at startup. Typical NT Services start various computer operations, such as networking and remote access procedures, server operations, and telephony processes.

         ### 2.2.2 What is the Discoverer NT Service?

         When you install Discoverer, the Discoverer NT service is created as an automatic NT Service called "OracleDiscoverer4i". The Discoverer NT service automatically starts the Discoverer Services Locator component and the CORBA services whenever the NT machine is started. Using the Discoverer NT service, you can also stop all of these components by simply stopping the service from running.

         A key benefit of having Discoverer Services Locator component and the CORBA services components started as a single NT service is that you do not need to remain logged onto a machine for the service (and therefore the Locator and the CORBA services) to stay running. If you launched each component individually on each machine, you would need to stay logged onto the machine(s) as the administrator. Logging off would automatically stop the components.

         The Discoverer NT service runs the appropriate components based on the type of server you selected when installing Discoverer. The following table shows the components started by the Discoverer NT service for the servers.

         ##### Table 2-1 Discoverer NT service components

         Server | Locator | CORBA services | OAD
         --- | --- | --- | ---
         Master Discoverer Server |  | X | X
         HTTP Server | X | X |
         Additional Discoverer Server |  | X | X
         Single Machine Installation | X | X | X

         ### 2.2.3 How does the Discoverer NT service start?

         When you install Discoverer, the Discoverer NT service's Startup property is set to Automatic. In other words, the service starts automatically whenever the machine is started. However, once the service has started automatically you can subsequently stop it and restart it manually.

         You can also change the Discoverer NT service's Startup property to Manual. In other words, the service does not automatically start when the computer is started. This may be useful if your network requires special services that have to start and stop in a particular sequence. You can start the other services, and then manually start the Discoverer NT service at the appropriate time.

         ### 2.2.4 How to start and stop the Discoverer NT service manually

         1. From the Windows Start menu, choose Settings | Control Panel and double-click on the Services icon to display the Services dialog box.

            The Services dialog box contains OracleDiscoverer4i.

            Status--shows if the service is started and running. If the service has not been started, the status column is blank.

            Startup--shows how the service is started, either manually or automatically. The Discoverer NT service is set to start automatically.

         2. To stop the Discoverer NT service, select it in the dialog box and click the Stop button. Then close the dialog box.

         3. To start the service, select it in the dialog box and click Start. Then close the dialog box.

            Note: If your end users run Discoverer against an Oracle Application, always shut down the Listener before you start the Locator.

         ### 2.2.5 How to change the Discoverer NT service to manual startup

         1. From the Windows Start menu, choose Settings | Control Panel and double-click on the Services icon.

            The Services dialog box appears.

         2. Select OracleDiscoverer4i in the Services dialog box.

         3. Click the Startup button.

            The Service dialog box for the OracleDiscoverer4i appears.

         4. In the Startup Type section of the Service dialog box, select Manual.

         5. Click OK to close the Service dialog box.

         6. Click Close to close the Services dialog box.

         ### 2.2.6 Seeing Service Errors

         The NT Event Log displays any errors that occur during startup of the Discoverer NT service. To see the NT Event Log, choose Start | Programs | Administrative Tools (Common) | Event Viewer.

         Discoverer also keeps an internal log of errors that may occur when running the Locator on an HTTP Server. To see a list of Locator errors, open the Locator.log file in the <iSUITES_HOME>\apache\apache\htdocs\DISCWB4\applet directory in the HTTP Server's root directory (or other directory if you installed the Discoverer client in some other directory).

         ## 2.3 Registering and Unregistering Discoverer Services Components

         The Discoverer Services components must be registered with the Visibroker OAD (Object Activation Daemon). The components are registered during installation. When you shut down or remove a machine you must unregister Discoverer Services components.

         You can register and unregister components using the Windows Start menu or using the command line.

         You can view the registered components for one machine or for the entire network.

         To register and unregister components (and to view registered components), the VisiBroker OAD must be running and responding.

         ### 2.3.1 To make sure the OAD is running and responding:

         If you are not sure whether the OAD is running:

         1. Press Ctrl-Alt-Del and click the Task Manager button to run the Windows Task Manager.

         2. Select the Processes tab.

         3. Select the Processes tab and confirm that oad.exe is running and responding.

         If the OAD is not running:

         1. From the Windows Start menu, choose Settings | Control Panel and double-click on the Services icon to display the Services dialog box.

         2. Select OracleDiscoverer4i and click the Start button.

         3. When the OAD is started, click Close to close the Services dialog box.

         If the OAD is running but not responding

         1. From the Windows Start menu, choose Settings | Control Panel and double-click on the Services icon to display the Services dialog box.

         2. Select OracleDiscoverer4i.

         3. Click the Stop button, then click the Start button again.

         4. When the OAD is started, click Close to close the Services dialog box.

         ### 2.3.2 To see the registered components on one machine:

         1. Make sure the OAD is running.

         2. Open an MS-DOS window (choose Start | Command Prompt).

         3. At the command prompt, type:

            `oadutil list` and press return.

         Note: Running the oadutil command displays only the list of components registered on the machine. It does not display all the components registered on the network of Discoverer machines.

         In this example the components are registered with the Discoverer Instance name of "UKP15601". Two components are registered on the machine--Preferences and Session. A Collector file for logging events is also registered.

         If you used the command on one of the Other Discoverer Servers, only the Session component would be registered.

         ### 2.3.3 To see all the registered components on the network:

         1. Make sure the OAD is running.

         2. Open an MS-DOS window (choose Start | Command Prompt).

         3. At the command prompt, type `osfind` and press Return.

         A list shows all of the components running on the network.

         ### 2.3.4 Registering and Unregistering Components from the Windows Start Menu

         On the machine where you want to register or unregister components:

         1. From the Windows Start menu, choose Programs | Oracle Discoverer Server 4i Setup.

         2. Choose the component that you want to register or unregister.

            A confirmation screen appears.

         ### 2.3.5 Registering and Unregistering from the Command Line

         Use the Run dialog box from the Windows Start menu. You can register components using batch scripts. The batch scripts are located in the <ORACLE_806_HOME>\discwb4\util directory of the machine where the components are installed.

         #### 2.3.5.1 To Register the Preferences and Session components with the OAD

         The Preferences and Session components must be registered with the OAD. The OAD will start a new session per connection of the client. For your convenience, scripts are available to help you with registering the Preference and Session components with the OAD.

         The scripts are named:

         - registerSession.bat

         - registerPreference.bat

         To register the Session from the command line:

         1. Open an MS-DOS window.

         2. Change the directory to <ORACLE_806_HOME>\discwb4\util.

         3. Type`registerSession.ba`t and press Return.

         To register the Preferences from the command line:

         1. Open an MS-DOS window.

         2. Change the directory to <ORACLE_806_HOME>\discwb4\util.

         3. Type`registerPreference.ba`t and press Return.

         #### 2.3.5.2 To Unregister the Preferences and Session components from the OAD

         For your convenience, scripts are available to help you with unregistering the Preference and Session components with the OAD.

         To unregister the Preferences component from the OAD:

         1. Open an MS-DOS window.

         2. Change the directory to <ORACLE_806_HOME>\discwb4\util.

         3. Type`unRegisterPreference.ba`t and press Return.

         To unregister the Session component from the OAD:

         1. Open an MS-DOS window.

         2. Change the directory to <ORACLE_806_HOME>\discwb4\util.

         3. Type`unRegisterSession.ba`t and press Return.

         ## 2.4 Editing the End User Preferences

         ### 2.4.1 What are the End User Preferences?

         The End User Preferences control default Oracle Discoverer behavior.

         The Preferences file (pref.txt) controls default settings that apply to all end users. When a new session starts, the settings in the pref.txt file take effect.

         In some cases, end users can override these settings from the Discoverer 4i Plus Options dialog. Individual preferences are stored for each user as a unique combination of database and userid, and loaded whenever the user starts a new session. Therefore, users can log on from different client machines and still have their individual settings take effect. You can view the individual end user preference settings from within the Windows NT Registry Editor. For more information about the Registry settings in the pref.txt file, refer to Section C, "Discoverer 4i Registry Settings".

         Note: Editing Preferences, such as adding a machine IP address, does not require that you shut down the Preferences component. Thus, users can continue working uninterrupted while you edit.

         ### 2.4.2 To set End User Preferences:

         1. From the Windows Start menu, choose Programs | Oracle Discoverer Server 4i Setup | Edit Preferences.

         2. The Pref.txt file appears in Notepad.

         3. Edit the items in the pref.txt file.

         4. Save the file and quit Notepad.

         5. From the Windows Start menu, choose Programs | Oracle Discoverer Server 4i Setup | Apply Preferences.

            A confirmation window shows that the new preferences have been saved. If you suspect that the file contains errors, check the error.txt file in the current directory.

         6. To continue, press the Enter key.

            The Preferences are updated in the Windows NT Registry. Preferences are now set for the Discoverer Services.

         ## 2.5 Shutting Down

         If you need to perform maintenance, change hardware settings, or perform any other tasks, you should take the server machine off line while working. This prevents users from starting sessions on that server while you work. You can shut down Discoverer in two ways:

         - Shut down individual server machines

         - Shut down the entire Discoverer system

         A reminder: You do not need to shut down to edit Discoverer Preferences.

         If the machine you want to shut down runs the Discoverer Services Locator component or Preferences component, you need to shut down the entire Discoverer system. These components are used to create a session, regardless of which server the Session component is on. Therefore, stopping any of these components affects the entire Discoverer system.

         ### 2.5.1 Shutting Down Individual Servers

         You can shut down a server in two ways:

         - gradually, allowing current users to disconnect when they are ready

         - immediately, forcing current users to end their Discoverer session

         #### 2.5.1.1 To Shut Down Individual Servers Gradually

         Shutting down a server gradually enables you to prevent new sessions from starting but allow current users to complete their sessions.

         1. On the machine you want to shut down, from the Windows Start menu, choose Settings | Control Panel and then double-click the Services icon.

            The Services dialog box appears.

         2. Select OracleDiscoverer4i and click the Stop button.

            Stopping the Oracle Discoverer NT service stops the CORBA services and the Locator component, which prevents any new sessions from being started on this machine. Sessions in progress are not affected by shutting down the Oracle Discoverer NT service. Thus, users will not be interrupted while working.

            After all the current users have disconnected from their sessions, you can perform your maintenance tasks. If you want to register or unregister components, the Oracle Discoverer NT service must first be restarted.

            To check that all users have disconnected, open the Windows Task Manager and be sure no instances of the Session executable (dis4ws.exe) are running.

         #### 2.5.1.2 To Shut Down Individual Servers Immediately

         An immediate shut down stops new user sessions from starting and stops the current sessions. To do this, you stop the Oracle Discoverer NT service on the machine (to prevent new sessions from being started) and then you stop the sessions currently running.

         1. On the machine you want to shut down, from the Windows Start menu, choose Settings | Control Panel and then double-click the Services icon.

            The Services dialog box appears.

         2. Select OracleDiscoverer4i and click the Stop button.

         3. Press Ctrl + Alt + Del and open the Windows Task Manager.

         4. Select the Processes tab.

         5. Choose dis4ws.exe.

         6. Click End Task.

         7. Repeat steps 4 and 5 for each session (dis4ws.exe) running in the Task Manager.

         ### 2.5.2 Shutting Down the Entire Discoverer System

         To shut down the entire Discoverer system, you shut down individual machines in a specific order.

         You can shut down the entire Discoverer system in two ways:

         - gradually, allowing current users to disconnect when they are ready

         - immediately, forcing current users to end their Discoverer session

         #### 2.5.2.1 To Shut Down the Discoverer System Gradually

         Shutting down the Discoverer system gradually enables you to prevent new sessions from starting but allow current users to complete their sessions. To shut down gradually, you stop the Oracle Discoverer NT service on each server and then let users finish their sessions.

         1. On each server, choose Settings | Control Panel from the Windows Start menu and then double-click the Services icon.

         2. Select OracleDiscoverer4i and click the Stop button.

            Stopping the Oracle Discoverer NT service stops the CORBA services and the Locator component, which prevents any new sessions from being started on this machine. Sessions in progress are not affected by shutting down the Oracle Discoverer NT service. Thus, users will not be interrupted while working.

            You now shut down the Preferences component.

            Warning: Do not shut down the Preferences component until all sessions are stopped. Shutting down the Preferences component while sessions are active can cause problems with active sessions.

         3. Press Ctrl + Alt + Delete and open the Windows Task Manager.

         4. Choose dis4pr.exe and click End Task to shut down the Preferences component.

         When all of the current users have completed their sessions, the Discoverer system shuts down.

         #### 2.5.2.2 To Shut Down the Discoverer System Immediately

         An immediate shut down stops new user sessions from starting and stops the current sessions. To perform an immediate shut down, you:

         - stop the Oracle Discoverer NT service on each machine (to prevent new sessions from being started)

         - stop the sessions currently running

         - stop the Preferences component

         1. On each server:

            1. From the Windows Start menu, choose Settings | Control Panel and then double-click the Services icon.

            2. Select OracleDiscoverer4i and click the Stop button.

         2. On each machine running a current session:

            1. Press Ctrl + Alt + Del to open the Windows Task Manager.

            1. Choose dis4ws.exe.

            2. Click End Task.

            3. Repeat steps 4 and 5 for each session (dis4ws.exe) and preferences (dis4pr.exe) running in the Task Manager.

         ## 2.6 Adding and Removing Server Machines

         You can add or remove server machines from your Discoverer system at any time.

         ### 2.6.1 Adding an Additional Discoverer Server Machine

         Follow the instructions in Chapter 3, "Installing Oracle Discoverer 4i on multiple machines" to add a new server machine to the Discoverer system.

         ### 2.6.2 To Permanently Remove an Additional Discoverer Server machine

         Disabling the Discoverer NT service or changing its Startup property to Manual effectively removes an Additional Discoverer Server machine from the Discoverer system. You do not have to uninstall any software. However, you must also edit the pref.txt file on the Master Discoverer Server machine to remove the Additional Discoverer Server machine's IP address from it.

         1. From the Windows Start menu, choose Programs | Oracle Discoverer Server 4i Setup | Edit Preferences.

            The pref.txt file opens in Notepad.

         2. Remove the machine's IP address from the pref.txt file.

         3. Save the pref.txt file and close Notepad.

         4. Choose Start | Programs | Oracle Discoverer Server 4i Setup | Apply Preferences.

         5. From the Windows Start menu, choose Programs | Oracle Discoverer Server 4i Setup again and select a component on that server that you want to unregister.

            The components to select depends on the server you want to remove:

            - to remove the Master Discoverer Server machine, unregister both the Session component and the Preferences component

            - to remove Additional Discoverer Server machines, unregister the Session component

         6. Repeat for each component that you want to unregister.

         7. Now from the Windows Start menu, choose Settings | Control Panel and double-click the Services icon.

            The Services dialog box appears.

         8. Select OracleDiscoverer4i and click the Startup button.

            The Service dialog box appears.

         9. In the Startup Type section of the Service dialog box, select Manual or Disabled and click OK.

         Now, the server machine will not automatically start the Discoverer NT service and therefore will not be part of the Discoverer system.

         Note: To temporarily remove a server, shut down the Discoverer NT service.

         ## 2.7 Utilizing the Discoverer 4i Viewer JavaScript Enhanced User Interface

         Discoverer 4i Viewer is supplied with two alternative user interfaces:

         - a pure HTML user interface

         - an JavaScript enhanced user interface

         The JavaScript enhanced user interface provides:

         - a popup menu for drill items

         - drag-and-drop pivot functionality

         - automatically applied page items

         You can specify whether the JavaScript enhanced user interface is available to users using the use_javascript_enhanced_ui option in the viewer_config.xml file.

         Make changes as follows:

         1. Open the viewer_config.xml file for editing.

            The viewer_config.xml file is located in <iSUITES_HOME>\apache\apache\htdocs.

         2. Change the use_javascript_enhanced_ui option as required.

            Below is an example of the change:

            viewer_config.xml - Before change

                <option id="use_javascript_enhanced_ui" state="true"/>

            viewer_config.xml - After change

                <option id="use_javascript_enhanced_ui" state="false"/>

         Note that for a user to run the JavaScript enhanced user interface, both JavaScript and cookies must be enabled in the user's browser.

         ## 2.8 Frequently Asked Questions

         What environment variables are set?

         During installation, two environment variables are set for the VisiBroker products:

         VBROKER_JAVAVM = <ORACLE_806_HOME>\jre11728o\bin\jre
         VBROKER_TAG = -D

         The CLASSPATH variable is not modified.

         The PATH variable is updated with:

         PATH = <iSUITES_HOME>\bin;<ORACLE_806_HOME>\vbroker\bin;<ORACLE_806_HOME>\bin; <iSUITES_HOME>\Apache\Perl\5.00503\bin\mswin32-x86;%PATH%

         This minimizes any conflict with other products.

         What happens if the Locator or Preferences components stop running?

         If the Locator component goes down, no more users can log in to the system until it comes back up. Existing sessions are not affected.

         The Locator component is designed so that it does not need to be shut down even when you edit the pref.txt file. By default the Locator component will pick up the edited values when the next client is connected.

         Similarly, if the Preferences component goes down, the Locator component will continue to function and sessions already in progress are not affected. When the Preferences component is brought back up, the Locator component will bind to the Preferences component again.

         What should I do if I get a network error?

         If Discoverer 4i receives a network exception during login, check the following:

         - Are there any directories or jar files in the CLASSPATH or PATH that might interfere with Discoverer 4i? Discoverer 4i uses VisiBroker CORBA V3.4 and JDK 1.2.

         - Make sure the Locator component is up and running. Did you see any error messages in the locator.log file? Make sure the locator.ior file is in the discwb4\applet directory.

         - Make sure the VisiBroker SmartAgent and OAD are up and running and that a new session can be started.

         - Make sure the Preferences component is up and running. To confirm that the Preferences component is up and running, use the Windows Task Manager and make sure that Dis4pr.exe is running.

         What do I need to do if I get ORA-12154 TNS: Could not resolve service name?

         This is an Oracle error that appears when the session cannot connect to the database alias specified in the Connect field. Check that the:

         - database alias is in the tnsnames.ora file

         - database alias exists in the tnsnames.ora file on every machine that runs sessions

         Hint: If you have SQL*Plus (or any other Oracle product) running on that machine, try connecting to the database with that product.

         What do I need to do if I get a message that the Locator component cannot bind to the Preferences component?

         If the Locator component cannot bind to the Preferences component, check the following:

         - Is the Preferences component up and running? To see if the Preferences component is running, use the Windows Task Manager. See Section 2.2, "Using the Discoverer NT Service" to restart the Preferences component.

         - Is a SmartAgent running on the subnet? To see a list of agents, OADs, and other registered components running on the subnet, open an MS-DOS window and on the command line, type `osfind`. Note that the agents are listed first. If the SmartAgent is not running, see Section 2.2, "Using the Discoverer NT Service" to restart it.

         - Is the Preferences component installed? To confirm that the Preferences component is up and running, use the Windows Task Manager and make sure that Dis4pr.exe is running.

         - Is the Preferences component registered with its OAD? To confirm that the Preferences component is registered, see Section 2.3.2, "To see the registered components on one machine:". This must be done on the machine on which the Preferences component was installed. If the Preferences component is not registered, see Section 2.3.5.1, "To Register the Preferences and Session components with the OAD".

         - Is the machine running the Preferences component on the same subnet as the machine running the Locator component and the machines running Session components? To see a list of agents, OADs, and other registered components running on the subnet, open an MS-DOS window and on the command line, type `osfind`. Note that the agents are listed first. The Preferences component must be installed on the same subnet.

         - Is the pref.txt file corrupted? You cannot directly determine from the pref.txt file that it is corrupted. To test if the pref.txt file is corrupted:

           1. Save a copy of the pref.txt file.

           2. Delete the original pref.txt file.

           3. From the Windows Start menu, select Run.

           4. In the Run window, type regedit and press [Enter].

           5. Find the registry key at
              HKEY_LOCAL_MACHINE\software\oracle\WebDisco 4i.

           6. Delete that registry key.

           7. Copy the file <ORACLE_806_HOME>\discwb4\util\defaults.txt" to "pref.txt."

           8. Choose Start | Programs | Oracle Discoverer Server 4i Setup | Apply Preferences.

           9. Run a Discoverer session.

              If the session runs correctly, the original pref.txt file was probably corrupted.

           10. Quit the session.

           11. Delete the saved copy of the original pref.txt file because it contains the corrupted elements.

           12. Reset the end user preferences by editing the new pref.txt file as described in Section 2.4, "Editing the End User Preferences".

| Copyright © 2000 Oracle Corporation. All Rights Reserved. |
Library | Service | Contents | Index