2
Running, Maintaining and Supporting
Oracle9iAS Discoverer

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

The topics include:

• Running Oracle9iAS Discoverer

• Maintaining Oracle9iAS Discoverer

• Registering and Unregistering Discoverer Services Components

• Editing the End User Preferences

• Shutting Down

• Restarting the Discoverer system

• Adding and Removing Servers

• Utilizing the Discoverer Viewer JavaScript Enhanced User Interface

• Frequently Asked Questions

2.1 Running Oracle9iAS Discoverer

Once you have completed the Oracle9i Application Server installation (see the Oracle9i Application Server Installation Guide), you can run Discoverer Plus immediately.

Before you can run Discoverer Viewer, an XWindow display must be available to the Viewer servlet for its graphing and charting functions. After installation, you must grant XWindow permissions to the host named in the DISPLAY environment variable in the jserv.properties file in the <iSUITES_HOME>/Apache/JServ/etc directory. By default, the DISPLAY variable is the hostname of the machine running Oracle9i Application Server. In order for Apache JServ to function properly, you must log in to the console of the host named in the DISPLAY environment variable and issue the following command:

> xhost +hostname.domain

where hostname.domain is the name and domain for the machine on which you installed Oracle9i Application Server.

For example, if you installed Oracle9i Application Server on a machine called myserver.oracle.com, you would type the following:

> xhost +myserver.oracle.com

Note that you must issue the xhost command each time the DISPLAY host system is restarted.

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 Plus

To run Discoverer Plus complete the following steps:

1. Start a browser window and type in your Discoverer Plus URL, 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

   
   

2. 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 the Java Plug-in. If you are not prompted to download and install the Java Plug-in, skip the next step.

   Note: The screen below only appears when using a Unix browser.

   
   
   3. If you see the above screen, follow the instructions to download and install the Java Plug-in.

   4. After you install the Java Plug-in, you must configure it to work with Discoverer. Follow the on-screen instructions.

   Note: The screen below only appears when using a Unix browser.

   
   

   When you have configured the Java Plug-in (or if you did not have to install and configure the Java Plug-in) the following screen appears:

   
   
   5. Click on the large image to start Discoverer Plus.

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

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

      7. Click Connect.

      You are now running Discoverer Plus.

      2.1.2 Running Discoverer Viewer

      To run Discoverer 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. 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/discoverer4i/viewer

         This will start Discoverer 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 Appendix A.1, "Specifying display of the Applications User Checkbox in the Discoverer Viewer Connect Dialog".

      4. Click Connect

      You are now running Discoverer Viewer.

      2.2 Maintaining Oracle9iAS Discoverer

      To maintain Oracle9iAS Discoverer, you must first set the PATH and other environment variables. These settings enable you to:

      • run Discoverer shell scripts (e.g. startoad.sh, startosagent.sh, startlocator.sh, stopoad.sh, stoposagent.sh, stopall.sh)

      • register and unregister Discoverer Services components

      • run other commands correctly (e.g. osfind, oadutil)

      1. From the command prompt, navigate to the <ORACLE_806_HOME>/discwb4 directory and run the appropriate script:
         • If you are using the Korn shell or the Bourne shell, type the following at the command prompt:

           > . ./discwb.sh
           

           Note that you must separate the periods with a space.

         • If you are using the C Shell, type the following at the command prompt:

           > source discwb.csh
           

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

      2.3.1 To make sure the OAD is running:

      If you are not sure whether the OAD is running:

      1. Type the following at the command prompt:

         > ps -A| grep oad 
         
         

         If the OAD process is running, it appears in the list of processes. For example:

         8634 pts/3 0:01 oad

      If the OAD is not running:

      1. Navigate to the <ORACLE_806_HOME>/discwb4/util directory and type the following at the command prompt:

         > startoad.sh
         
         

      2.3.2 To see the registered components on one machine:

      1. Make sure the OAD is running.

      2. Type the following at the command prompt:

         > oadutil list
         

      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.

      2.3.3 To see all the registered components on the network:

      1. Make sure the OAD is running.

      2. Type the following at the command prompt

         > osfind
         
         

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

      2.3.4 Registering and Unregistering from the Command Line

      You register and unregister components using shell scripts. The shell scripts are located in the <ORACLE_806_HOME>/discwb4/util directory of the machine where the components are installed.

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

      • registerpreference.sh

      To register the Session from the command line:

      1. Navigate to the <ORACLE_806_HOME>/discwb4/util directory.

      2. Type the following at the command prompt:

         > registersession.sh
         
         

      To register the Preferences from the command line:

      1. Navigate to the <ORACLE_806_HOME>/discwb4/util directory.

      2. Type the following at the command prompt:

         > registerpreference.sh
         
         

      2.3.4.2 To Unregister the Preferences and Session components from the OAD

      You can unregister the Preferences and Session from the OAD.

      To unregister the Preferences component from the OAD:

      1. Navigate to the <ORACLE_806_HOME>/discwb4/util directory.

      2. Type the following at the command prompt:

         > unregisterpreference.sh
         
         

      To unregister the Session component from the OAD:

      1. Navigate to the <ORACLE_806_HOME>/discwb4/util directory.

      2. Type the following at the command prompt:

         > unregistersession.sh
         
         

      2.4 Editing the End User Preferences

      2.4.1 What are the End User Preferences?

      The End User Preferences control default Oracle9iAS 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 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.

      For more information about the settings in the pref.txt file, refer to Appendix C.1, "Preference settings in pref.txt".

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

      2.4.2 To set End User Preferences:

      1. Use a text editor to open the pref.txt file in the following location:

         <ORACLE_806_HOME>/discwb4/util

         The file defaults.txt (located in the above directory) is a copy of the original prefs.txt file and contains the default preference values for subsequent reference.

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

      3. Save the file and close the text editor.

      4. Navigate to the <ORACLE_806_HOME>/discwb4/util directory.

      5. Type the following at the command prompt to apply the preferences:

         > applypreferences.sh
         
         

         A confirmation message 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.

         
         

         The Preferences are updated in the Preferences component. 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 must shut down the entire Discoverer system. This prevents users from starting sessions on that server while you work.

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

      2.5.1 Shutting Down the Entire Discoverer System

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

      1. Navigate to the <ORACLE_806_HOME>/discwb4/util directory and type the following at the command prompt to stop the Locator:

         > stoplocator.sh
         
         

         Stopping the Locator prevents any new users from logging in.

      2. Navigate to the <ORACLE_806_HOME>/discwb4/util directory and type the following at the command prompt to stop the OAD:

         > stopoad.sh
         
         

      3. Navigate to the <ORACLE_806_HOME>/discwb4/util directory and type the following at the command prompt to stop the SmartAgent:

         > stoposagent.sh
         
         

      4. Type the following at the command prompt to list the numeric identifier of every dis4pr Discoverer process that is currently running:

         > ps -A|grep dis4pr 
         
         

         For example, the output might be:

         18064 pts/3   0:01   dis4pr
         18072 pts/4   0:08   dis4pr
         
         

      5. Type the following at the command prompt to stop the first dis4pr process:

         > kill -9 <process id>
         
         

         where <process id> is the numeric identifier of the first dis4pr process.

         For example, you might type the following:

         > kill -9 18064
         
         

      6. Repeat the previous step until you have stopped all the dis4pr processes.

      When all of the current users have completed their sessions, the Discoverer server is shut down.

      To check whether any Discoverer sessions are active, type the following at the command prompt to list the numeric identifier of every dis4ws Discoverer process that is currently running:

      > ps -A|grep dis4ws 
      
      

      To stop any Discoverer dis4ws processes that are still active, type the following at the command prompt:

      > kill -9 <process id>
      
      

      where <process id> is the numeric identifier of the dis4ws process.

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

      • prevent new sessions from being started

      • stop the sessions currently running

      • stop the Preferences component

      1. Type the following at the command prompt:

         > stopall.sh
         
         

      2.6 Restarting the Discoverer system

      You can restart the Discoverer system quickly and easily from the command line because all of the components are already registered with the OAD.

      To restart the Discover system:

      1. Navigate to the <ORACLE_806_HOME>/discwb4/util directory and type the following (in the order shown here) at the command prompt:

         > startosagent.sh
         
         > startoad.sh
         
         > startlocator.sh
         
         

      2.7 Adding and Removing Servers

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

      2.7.1 Adding an Additional Discoverer Server machine

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

      2.7.2 To Permanently Remove an Additional Discoverer Server Machine

      Shutting down the OAD effectively removes an Additional Discoverer Server machine from the Discoverer system. You do not have to uninstall any software. However, you must edit the pref.txt file on the Master Discoverer Server machine to remove the Additional Discoverer Server machine's IP address from it.

      1. Use a text editor to open the pref.txt file in the following location:

         <ORACLE_806_HOME>/discwb4/util

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

      3. Save the pref.txt file and close the text editor.

      4. Type the following at the command prompt to apply the preferences:

         > applypreferences.sh
         
         

      5. Unregister all the Discoverer Services components installed on the Additional Discoverer Server machine by navigating to the <ORACLE_806_HOME>/discwb4/util directory and running the appropriate unregister scripts as follows:
         • Type the following at the command prompt to unregister the Preferences component from the OAD:

           > unregisterpreference.sh
           
           

         • Type the following at the command prompt to unregister the Session component from the OAD:

           > unregistersession.sh
           
           

      6. Navigate to the <ORACLE_806_HOME>/discwb4/util directory and type the following at the command prompt to stop the OAD:

         > stopoad.sh.
         
         

      Note: To temporarily remove a machine, shut down the OAD.

      2.8 Utilizing the Discoverer Viewer JavaScript Enhanced User Interface

      Discoverer 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 the <iSUITES_HOME>/Apache/Apache/htdocs/disco4iv/html directory.

      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.9 Frequently Asked Questions

      What environment variables are set?

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

      OSAGENT_PORT= 14000
      VBROKER_ADM = <ORACLE_806_HOME>/vbroker/adm
      VBROKER_IMPL_DIR= <ORACLE_806_HOME>/vbroker/adm/impl_dir
      VBROKER_JAVAVM = <ORACLE_806_HOME>/jre1162o/bin/jre
      
      

      The CLASSPATH variable is not modified.

      The PATH variable is updated with:

      PATH = $<ORACLE_806_HOME>/vbroker/bin:$<ORACLE_806_HOME>/discwb4/bin:$<ORACLE_
      806_HOME>/bin:$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 Oracle 9iAS Discoverer 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 Oracle9iAS Discoverer? Oracle9iAS Discoverer 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 <iSUITES_HOME>/Apache/Apache/htdocs/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. Use the command ps-A|grep dis4pr to confirm that the dis4pr process 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 the client gives the error: " Unable to connect to Oracle Discoverer Application Server because session failed to find locale en_US. Please contact your system administrator"?

      1. Use a text editor to open the startoad.sh script in the following location:

      2. Make sure that the startoad.sh script contains the following line:

         unset ORA_NLS4

      3. If the script does not contain this line, add it now.

      What do I need to do if oad.log contains "OAD: Fatal Error [Cross-device link] " while registering with OAD?

      The OAD gives a cross-device link error in the following circumstances:

      • if the VBROKER_ADM directory and the /tmp directory are not on the same device

        In this case, set the TMPDIR environment variable to a directory on the same device as the VBROKER_ADM directory before starting OAD.

      • if you do not have write permission for the VBROKER_ADM/impl_dir directory or for the impl_rep and/or impl_rep~ files.

        In this case, enable write permission on the above directory and files.

      What do I need to do if I run registerall.sh and the message"oadutil: unable to bind to OAD" is displayed?

      Check the following:

      • Make sure the OAD is properly running. To find out, use the ps -A|grep oad command. If the OAD is not running, check the oad.log file for any errors.

      • Make sure there is at least one osagent running in the subnet (you can run one in the machine itself using startosagent.sh).

      • Determine whether the machine is configured for multiple IP addresses. To find out, use the ifconfig -a command.

      If the machine is configured for multiple IP addresses, follow these steps to include the machine IP address in the oadutil file:

      1. From the command prompt, navigate to the <ORACLE_806_HOME>/discwb4 directory and run the appropriate script:
         • If you are using the Korne shell or the Bourne shell run the command

           > . ./discwb.sh
           

           Note that you must separate the periods with a space.

         • If you are using the C Shell, type the following at the command prompt

           > source discwb.csh
           
           

      2. Type the following at the command prompt:

         > oad -v 
         
         

         The first line of the output contains the machine IP address, as shown below:

         Caught exception while checking for OAD [<IP_ADDR>, Exception: CORBA::NO_IMPLEMENT

         where <IP_ADDR> is the machine IP address.

      3. Use a text editor to open the oadutil file in the following location:

         <ORACLE_806_HOME>/vbroker/bin

      4. Add the machine IP address (preceded by -host) to the last line of the oadutil file as shown below:

         Before change:	${VBJ} -VBJincppjar 1 -VBJaddJar vbjtools.jarcom.visigenic.vbroker.activationImpl.OADutil $@
         After change:	${VBJ} -VBJincppjar 1 -VBJaddJar vbjtools.jarcom.visigenic.vbroker.activationImpl.OADutil $@ -host <IP_ADDR>
         where:	<IP_ADDR> is the machine IP address identified by running the oad -v command.

      5. Save the oadutil file and close the text editor.