2
Running, Maintaining and Supporting Discoverer 3i Viewer

This chapter explains how to run and maintain Discoverer 3i Viewer.

The topics include:

• Running Discoverer 3i Viewer

• Maintaining Discoverer 3i Viewer

• Seeing Registered Discoverer Server Objects

• Editing End User Preferences

• Registering and Unregistering Objects

• Shutting Down

• Restarting Discoverer 3i System

• Setting up a secure link using HTTPS

• Frequently Asked Questions

2.1 Running Discoverer 3i Viewer

Once you have completed the Oracle Internet Application Server installation (see the Oracle Internet Application Server Installation Guide) you can run the Discoverer 3i Viewer. The Discoverer components should already be registered (if not see Section 2.5.1.1, "To Register the Preferences and Session with the OAD" for details).

To run Discoverer 3i Viewer complete the following steps:

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

http://mywebserver.company.com/servlets/discoservlet

Where mywebserver.company.com represents the Web server machine that the HTTP server is installed on. You must replace this with its fully qualified host name. For example:

http://machinename.oracle.com/servlets/discoservlet

This will start Oracle Discoverer 3i 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, details on how to display it are detailed in an Oracle Applications mode section in the Table 2-1, "Discoverer Server Preferences".

4. Click Connect

You are now running Oracle Discoverer 3i Viewer.

2.2 Maintaining Discoverer 3i Viewer

To maintain Discoverer 3i, first go to the directory <ORACLE_HOME>/DISCWB33/util

If you are using C Shell (csh) run the command

> source discwb.csh

If you are using Korne shell/Bourne shell (ksh/sh) run the command

> ./discwb.sh

Running this command is very important because this will set the required PATH and other environment variables. These settings are required to run the scripts startoad.sh, startosagent.sh, startlocator.sh, stopoad.sh, stoposagent.sh, stopall.sh, registering and unregistering scripts, plus commands like osfind and oadutil.

2.3 Seeing Registered Discoverer Server Objects

Installed objects are registered with the VisiBroker OAD (Object Activation Daemon). You can see the registered objects for one machine or for the entire network.

To see the registered objects on one machine:

1. Make sure the OAD is running. To do this perform Step 2 below:
   If it is not, run the script startoad.sh.

3. At the command prompt, type:

   oadutil list and press return.

Note: Running the oadutil command displays only the list of objects registered on the machine.

2.4 Editing End User Preferences

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

Some of these settings can be customized by users from the Discoverer 3i Options page. 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.

Also see the "Discoverer Administration Edition User's Guide" for more information.

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.

1. Open pref.txt, under the following directory in a text editor (vi or emacs):
   <ORACLE_HOME>/DISCWB33/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.

3. Save the file and quit.

4. Run the applypreferences.sh script, to apply preferences. This script is available under <ORACLE_HOME>/DISCWB33/util directory.

   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.

5. To continue, press any key.

   The Preferences are updated in the Preferences component. Preferences are now set for the Discoverer Services.

The following table shows the items in the Preferences file

Table 2-1 Discoverer Server Preferences

Affected Feature	Preference Item Key Name	Description	Default/Values
Locator	MachineIPs	IP address or machine name of all Discoverer Server Application server; this is the only required item in the Preferences file
Session Manager	Timeout	Amount of time after which Discoverer 3i disconnects an idle session from the database. Minimum time is 180 seconds.	1800 (seconds)
	RowsPerHTML	Number of rows to display per HTML page.	25 (any whole number)
Application	CacheFlushPercentage	Percentage of cache flushed if the cache is full	25
	MaxVirtualDiskMem	Maximum amount of disk memory allowed for the data cache	1024000000
	MaxVirtualHeapMem	Maximum amount of heap memory allowed for the data cache	1024000000
	QueryBehavior	Action to take after opening a workbook.	0
	ShowDialogBitmaps	End users see the bitmap graphics on Discoverer Plus dialogs.	1
	DataFormat	Applies HTML formatting to data cells in worksheets.	"<fontFormat fontName="Dialog" pitch="10" bold="false" italic="false" underline="false" strikethrough="false" foreground="0,0,0" background="255, 255, 255" halign="right" valign="top"> </fontFormat>"
	HeadingFormat	Applies HTML formatting to heading cells in worksheets.	"<fontFormat fontName="Dialog" pitch="10" bold="false" italic="false" underline="false" strikethrough="false" foreground="0,0,0" background="204, 204, 204" halign="left" valign="top"> </fontFormat>"
	TotalsFormat	Applies HTML formatting to cells that contain totals in worksheets	"<fontFormat fontName="Dialog" pitch="10" bold="false" italic="false" underline="false" strikethrough="false" foreground="0,0,0" background="255, 255, 255" halign="left" valign="top"> </fontFormat>"
	NullValue	Specifies how null values are displayed in worksheets, for example, "NULL", "N/A", "0"	"NULL"
Database	DisableFanTrapDetection	Disables detection for fan trap in user queries	0 (0 = on, 1 = off)
	DisableMultiJoinDetection	Disables multiple join detection	1 (0 = on, 1 = off)
	DisableAutoQuery	If set to 0, queries do not automatically run when a worksheet opens	0 (0 = on, 1 = off)
	ItemClassDelay	Fetch list of values for this amount of time before timing out	15 (seconds)
	PredictionThresholdSeconds	Warn user if the predicted query time will exceed the number of seconds	60 (seconds)
	PredictionThresholdSeconds Enabled	Query prediction threshold disabled (0) or enabled (1)	1
	QueryTimeLimit	Limit on query time in seconds	1800 (seconds)
	QueryTimeLimitEnabled	Query time limit disabled (0) or enabled (1)	1
	RowFetchLimit	The maximum number of rows fetched	10000 (rows)
	RowFetchLimitEnabled	RowFetchLimit parameter is disabled (0) or enabled (1)	1
	RowsPerFetch	The number of rows to fetch at once	100 (rows)
	SummaryThreshold	Use summary table only if it is no older than this number of days	30 (days) 0 do not use summary at all
	SummaryThresholdEnabled	If enabled (1), will use the value specified by SummaryThreshold. Otherwise, Discoverer will always use summary tables if they are available	1
	DefaultEUL	Sets the EUL you want all users to connect to. Each user can override this default from the Discoverer Plus Options dialog	Any EUL you have created.
Oracle Applications Mode	AppsGWYUID	Specifies the public username and password for the AOL security dll	"APPLSYSPUB/PUB"
	AppsFNDNAM	Specified the schema in which certain vital Oracle Applications data is stored	"APPS"
	ShowUserTypeChoice	Activates an end-user checkbox that allows them to specify whether they want to run Discoverer against an Oracle Application	1
	DefaultUserTypeIsApps	Specifies that users run Discoverer by default against an Oracle Application	1
Internal settings	BusinessAreaFastFetchLevel	Controls the amount of pre-caching that occurs for components and items whenever a Business Area is fetched	1
	ObjectsAlwaysAccessible	Verify that Business Area objects and items exist in the database	0 (0=verify; 1=don't verify and assume that the objects and items exist)
	SummaryObjectsUseCachedAccessibility	Controls whether to access the summary-derived objects in the cache	0
	AvoidServerWildcardBug	Set to 1 if running against RDBMS 7.3.2 with NLS_LANG set to Japanese_Japan.JA16SJIS to avoid certain list box appearing empty	0
	RdbFastSQLOff		0
Query Prediction and Performance	QPPEnable	Uses query prediction/performance (QPP) if set to 1	1 (0 = false, 1 = true)
	QPPCreateNewStats	Records new statistics if set to 1	1 (0 = false, 1 = true)
	QPPLoadStatsByObjectUseKey	Records statistics for same objects first if set to 1	1 (0 = false, 1 = true)
	QPPUseCpuTime	Query prediction uses CPU time within its algorithm	1 (0 = false, 1 = true)
	QPPAvgCostTimeAlgorithm		2
	QPPMaxObjectUseKey	Affects the amount of statistics to cache in memory for query prediction	30
	QPPCBOEnforced	Will use cost-based optimizer if set to 1. Will use default optimizer if set to 0	1
	QPPObtainCostMethod		1
	QPPMinCost	Only records or uses statistics with a cost greater than this value	0
	QPPMaxStats	Only loads this many previous statistics	500
	QPPMinActCpuTime	Only records or uses statistics with a CPU time greater than this value	0
	QPPMinActElapsedTime	Only records or uses statistics with an actual elapsed time greater than this value	0
	QPPMinEstElapsedTime	Only records or uses statistics with an estimated elapsed time greater than this value	0
	UseOptimizerHints	Will add optimized hints to SQL if set 1	0
	QuerySQLFastFetchLevel		1
	SQLTrace	False (off)	0
Crosstab Layout	Title	Displays titles that were created in Discoverer 3.1 worksheets	1 (0 = no, 1 = yes)
	Cell XGridline	Show horizontal gridlines	0 (0 = no, 1 = yes)
	Cell YGridline	Show vertical gridlines	0 (0 = no, 1 = yes)
	Axis Style	Crosstab axis position	2 (1 = inline, 2 = outline)
Table Layout	Title	Displays titles that were created in Discoverer 3.1 worksheets	1 (0 = no, 1 = yes)
	Cell XGridline	Show horizontal gridlines	0 (0 = no, 1 = yes)
	Cell YGridline	Show vertical gridlines	0 (0 = no, 1 = yes)
	Row Headings	Display row numbers on table worksheets	0 (0 = no, 1 = yes)

:

2.5 Registering and Unregistering Objects

The VisiBroker OAD must be running to register and unregister components, using the command line.

2.5.1 Registering and Unregistering Individual Component(s)

You can register components using shell scripts. The shell scripts are located in the <ORACLE_HOME>/DISCWB33/util directory of the machine where the components are installed.

2.5.1.1 To Register the Preferences and Session with the OAD

The Preferences and Session must be registered with the OAD. The OAD will spawn 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

• registerpreferences.sh

To register the Session from the command line:

1. Change the directory to <ORACLE_HOME>/DISCWB33/util.

2. Type

   > ./registersession.sh

To register the Preferences from the command line:

1. Change the directory to <ORACLE_HOME>/DISCWB33/util.

2. Type

   > ./registerpreferences.sh

2.5.1.2 To Unregister Objects from OAD

You can unregister the Preferences and Session from the OAD.

2.5.1.2.1 Unregistering the Preferences

A script is available to help you unregister the Preferences from the OAD.

To unregister the Preferences from the OAD:

1. Change the directory to <ORACLE_HOME>/DISCWB33/util.

2. Type

   > ./unregisterpreferences.sh

2.5.1.2.2 Unregistering the Session

A script is available to help you unregister the Session from the OAD.

To unregister the Session from the OAD:

1. Change the directory to <ORACLE_HOME>/DISCWB33/util.

2. Type

   > ./unregistersession.sh

2.6 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 will need to shut down the entire Discoverer 3i system.

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

2.6.1 Shutting down the entire Discoverer 3i system

1. Run the script:

   stoplocator.sh.
   

available under <ORACLE_HOME>/DISCWB33/util directory.

• This stops the locator. Stopping the Locator prevents any new users from logging in.

• Run the script:

  stopoad.sh.
  
  

  available under <ORACLE_HOME>/DISCWB33/util directory. This stops the OAD.
  At Command Prompt, type ps -A|grep dis33ws to get the process ID of all the running dis33ws. For example the output will be

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

  Run the kill command to kill the process dis33ws:

  Example:

  > kill -9 18064. 
  
  

  where 18064 is the ProcessID of dis33ws which is shown in step 4 example's output.

  Run the script:

  stoposagent.sh.
  
  

  available under <ORACLE_HOME>/DISCWB33/util directory. This stops the SmartAgent.

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

  2.7 Restarting Discoverer 3i System

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

  2.7.1 Restarting Discoverer 3i system using shell files

  Use the following process on your Discoverer 3i system.

  • From the <ORACLE_HOME>/DISCWB33/util directory, type:

    > ./startosagent.sh

    > ./startoad.sh

    > ./startlocator.sh

  2.8 Setting up a secure link using HTTPS

  To ensure that your entire discoverer document is secure and to get your browser to acknowledge a "secure" page, it is necessary to make a minor adjustment to your disco3iv.xml file.

  Make changes as follows:

  1. Open your disco3iv.xml file for editing

  2. Change the image_path so to includes https and the full path to the image directory.

  <argument name="image_path" type="href"> images</argument><argument name="image_path" type="href">https://mywebserver.company.com/disco3ivhome/ images</argument>

  Below is an example of the change:

  disco3iv.xml - Before change

  <argument name="help_path" type="href">help</argument><argument name="image_path" type="href"> images</argument><argument name="show_login_method_control">true</argument></document></disco_config>

  disco3iv.xml - After change

  <argument name="help_path" type="href">help</argument><argument name="image_path" type="href">https://mywebserver.company.com/disco3ivfiles/images</argument><argument name="show_login_method_control">true</argument> </document></disco_config>

  2.9 Frequently Asked Questions

  What environment variables are set?

  The Discoverer Server sets four environment variables for the VisiBroker products when installed:

  VBROKER_ADM = <ORACLE_HOME>/vbroker/adm

  VBROKER_JAVAVM = <ORACLE_HOME>/vbroker/bin

  OSAGENT_PORT= 14000

  VBROKER_IMPL_DIR= <ORACLE_HOME>/vbroker/adm/impl_dir

  The Discoverer Server does not modify the CLASSPATH. The PATH variable is updated with:

  PATH = $<ORACLE_HOME>/bin:$<ORACLE_HOME>/vbroker/bin:$PATH

  This minimizes any conflict with other products.

  What happens when the Locator or Preferences objects stop running?

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

  The Locator is designed so it does not need to be shut down even when you edit Preferences. By default the Locator will pick up the edited values when the next client is connected. If the preferences object stops running it will automatically be brought up again when either the Locator or any Session tries to connect to it, since it is registered with OAD. Similarly, if the Preferences goes down, the Locator will continue to function. When the Preferences is brought back up, the Locator will bind to the Preferences again.

  What do I need to do when I get a network error?

  When Discoverer 3i Viewer receives a network exception during login, the server is most likely having the problem. Check the following:

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

  • Make sure the Locator is up and running. Did you see any error messages in the locator.log file? Make sure the locator.ior file is in the:

    [HTTP_DIR]/discwb33/applet directory

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

  • Make sure the Preferences object is up and running. To see that the Preferences object is up and running use the command ps-a and make sure that dis31pr is running.

  What do I need to do when 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 aliases are 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 another Oracle product running on that machine, try connecting to the database with that product or SQL*Plus.

  What do I need to do when 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"?

  Check your startoad.sh script. It should contain the following line.

  unset ORA_NLS33

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

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

  OAD gives cross-device link error:

  • If your VBROKER_ADM directory and /tmp directory are not on the same device. In this case you should set the TMPDIR environment variable to a directory on the same device of VBROKER_ADM, before starting OAD.

  • If you don't have write permission for VBROKER_ADM/impl_dir directory also for files under the directory viz. impl_rep and impl_rep~. In this case make sure that you have enabled the write permission.

  What do I need to do, when I run registerall.sh it gives me "oadutil: unable to bind to OAD"?

  Check the following:

  • See whether oad is properly running (using ps command). If not running see oad.log for any errors.

  • Make sure there's at least one osagent running in the subnet (You can run one in your machine itself from startosagent.sh).

  • If your machine is configured for multiple IP addresses, (to find out run "ifconfig -a" and see if you have more than one network interface configured).

  In last case i.e., for multiple IP machines, follow these steps:

  Get the IP address recognized by OAD.

  $. discwb.sh (or in case of c shell "source discwb.csh") 
  $oad -v 
  

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

  Minor: 0 
  Completion Status: NO 
  ] 
  ^C 
  

  Note down this <IP_ADDR>

  Edit the oadutil file which will be present in ORACLE_HOME/vbroker/bin, change the last line. i.e.

  ${VBJ}-VBJincppjar1-VBJaddJarvbjtools.jarcom.visigenic.vbroker.activ
  ationImpl.OADutil $@ 
           to 
  ${VBJ}-VBJincppjar1-VBJaddJarvbjtools.jarcom.visigenic.vbroker.activ
  ationImpl.OADutil $@ -host <IP_ADDR> 
  

  (Note the addition of -host <ip_addr>)