Oracle9iAS Discoverer Plus and Oracle9iAS Discoverer Viewer
Release 4.1.37 for Microsoft Windows NT/2000 Release Notes

Oracle DiscovererTM
(c) Copyright Oracle Corporation, 2001
May 1st 2001
Release 4.1.37

Perspective for Java licensed from Three D Graphics, Inc.
Copyright 2001 Three D Graphics, Inc.


This document provides various installation and late-breaking product information for both Oracle9iAS Discoverer Plus and Oracle9iAS Discoverer Viewer. This release is shipped in Oracle9i Application Server and includes all prior Discoverer Plus and Viewer 4.1 patch fixes.


1   Installation instructions
2   Required version of Oracle9i Developer Suite for compatibility
3   End User Layer compatibility
4   XSL stylesheet pooling to improve Discoverer Viewer performance
5   Useful information
6   Known issues and workarounds
7   Issues fixed in this release (4.1.37)
8   Issues fixed in previous releases

1.  Installation instructions

This release should only be installed as part of Oracle9i Application Server installation.  We do not support the installation of this release by any other means.

If you have a Beta Release or any other Pre-Production release of Oracle Discoverer Plus or Viewer installed, you must unregister the server components (Session, Preferences and Collector) and completely remove Discoverer using the Oracle Installer BEFORE installing Oracle9i Application Server  Instructions for these tasks are provided in the Configuration Guide.

2. Required version of Oracle9i Developer Suite for compatibility

Oracle Discoverer Administration Edition is used to create End User Layers (EULs) and design Business Areas which are pre-requisites to running Discoverer Plus and Discoverer Viewer. Discoverer Administration Edition is shipped as a component of Oracle9i Developer Suite. The required version of Oracle9i Developer Suite is

3. End User Layer compatibility

This version of Discoverer Plus and Discoverer Viewer (4.1.37) will only connect to an End User Layer either created or upgraded using Discoverer Administration Edition 4.1.36 or 4.1.37. Please see the release notes for Discoverer Administration Edition 4.1.36 or 4.1.37 for more details on the upgrade process for prior versions of the EUL.

4. XSL stylesheet pooling to improve Discoverer Viewer performance

A number of new setttings in disco4iv.xml enable you to improve Discoverer Viewer performance by sharing or 'pooling' XSL stylesheets. Pooling XSL stylesheets enables one or more sessions to share one or more stylesheets, thereby signficantly reducing CPU usage, memory consumption, and transaction time. As a result, there is a significant increase in the number of concurrent Discoverer Viewer users that can be supported by the servlet tier. In addition, stylesheet pooling provides control over exactly how many stylesheets are in memory, and therefore how many requests for HTML pages can be processed at any given time.

The settings in disco4iv.xml relating to stylesheet pooling are shown below:
Setting Use this setting to: Default Recommended
xsl_pool specify that you want to use stylesheet pooling false true
xsl_pool_capacity specify the maximum number of XSL stylesheets to hold in memory at any given time 32000 (effectively unbounded) 4
xsl_pool_minimum specify the minimum number of XSL stylesheets to hold in memory at any given time 0 2
xsl_pool_tolerance specify how much to optimize the pool for concurrent processing of user requests for HTML pages (this must be a floating point number between 0.0 and 1.0):
  • a low number optimizes the number of stylesheets in memory towards the number of concurrent requests (i.e. low memory, low concurrency) 
  • a high number optimizes the number of stylesheets towards the number of concurrent user sessions (i.e. high memory, high concurrency) 
1.0 1.0
xsl_pool_optimize_period specify (in milliseconds) the period over which pool optmization takes place 5000 10000
xsl_pool_log specify that stylesheet pooling statistics be written to a console window 

Only set this option to true when performing scalability and performance diagnositics in a non-production environment because it can significantly degrade performance.

false false

For example, you might add the following to the <document> section of disco4iv.xml:

<!-- Pooling arguments)
<argument name="xsl_pool">true</argument>
<argument name="xsl_pool_capacity">4</argument>
<argument name="xsl_pool_minimum">2</argument>
<argument name="xsl_pool_tolerance">1.0</argument>
<argument name="xsl_pool_optimize_period">10000</argument>
<argument name="xsl_pool_log">false</argument>
<!-- end of pooling arguments -->


If you set xsl_pool_log=true, stylesheet pooling statistics are displayed when one or more of the following events occurs:
Event Description
create object a stylesheet has just been created
remove object a stylesheet has been removed
passivate object a stylesheet has been passivated
activate object a stylesheet has been activated
starvation a request was unable to retrieve a stylesheet from the pool (because all available stylesheets are active) and could not create one because the pool is at capacity (the request therefore has to wait until a stylesheet is passivated)
optimize pool the optimizer has detected an opportunity to add or remove stylesheets

The following stylesheet pooling statistics are displayed when one of the above events occurs:
Stylesheet pooling information Description
active objects activated stylesheets (i.e. the stylesheets in use)
passive objects stylesheets ready for use
total objects all created stylesheets (i.e. the total number of active and passive objects)
peak objects the highest number of objects created in the lifetime of the pool (i.e. since the servlet started)
hits pool hits (i.e. the number of times a stylesheet was activated with a passive object)
misses the number of times no passive object was available, the stylesheet had to be created, or had to wait for passivation
hitrate the number of hits divided by the sum of the number of hits and the number of misses (the higher the number, the better)

= hits / (hits + misses)

optimal objects the optimal number of stylesheets to pool (maintained at the number of sessions + 1)
max capacity the capacity of the pool (i.e. the same as xsl_pool_capacity in disco4iv.xml)
min capacity the minumum number of stylesheets to pool (i.e. the same as xsl_pool_minimum parameter in disco4iv.xml)
starvations the number of times that starvation events occurred in the lifetime of the pool (i.e. since the servlet started)
starving threads the number of threads currently waiting for a passivation (because the pool is at capacity)

For example, you might see the following stylesheet pooling information output to the console log window:

discoverer pool: optimize pool removing 1 objects
discoverer pool: remove object oracle.xml.parser.v2.XSLStylesheet@b9bc9519
discoverer pool: dumpstats=
active objects=0
passive objects=2
total objects=2
peak objects=3
hit rate=100
optimal objects=1
maximum capacity=5
minimum capacity=1
starving threads=0

5. Useful information
This section contains information about product features which have been added or modified after the product documentation was completed.

5.1 Updates to the Configuration Guide

Several updates have been made to the Oracle Discoverer Configuration Guide which is included with Oracle9i Application Server  This is only a brief list of the changes- please refer to the relevant sections of the Configuration Guide for complete details:

  • Added to pref.txt: ExcelVersion
  • Added to viewer_config.xml: base_dir
  • Added new URL arguments: cp_height, cp_show_legend, cp_width, qpd, rd
  • Added new settings to disco4iv.xml: query_progress_delay, redirect_delay
  • [For UNIX platforms] Updated the instructions for using  xhost
  • [For UNIX platforms] Updated references to /DISCWB4 to /discwb4 in pathnames
  • Updated the instructions for setting up HTTPS with Viewer  (Note- there are significant changes from the previous Configuration Guide)
  • 5.2 Discoverer Viewer video store customization example

    Discoverer Viewer ships with an example of how to customize the look and feel of the reporting environment using the video store scenario. This is documented in the 'Oracle Discoverer Configuration Guide for 9i Application Server' (section 5.2). The 9iAS install process automatically uses the name of the machine on which the software is being installed as an instance name. The session name is a concatenation of  the instance name and the text "OracleDiscovererSession4". As an example, if the machine was called DISCOVERER then the session name would be "DISCOVEREROracleDiscovererSession4".

    This session name can be found in the main Viewer XML file :


    When setting up the video store customization example make sure the session name in the above disco4iv.xml file is also entered in the disco4iv.xml file shipped with the customization example which is found in the following location:


    If the session name in the customization example and the main Viewer XML file do not match, manually edit the customization example file to use the correct session name.

    5.3 Migrating Discoverer version 3i  preferences to Discoverer version 4.1

    System preference migration

    It is possible to migrate Discoverer 3i preferences for use with Discoverer 4.1 by copying over the Discoverer 3i pref.txt file and adding the new preferences introduced in Discoverer 4.1. This process is described in section 10.5 of the 4.1.33 release notes (and reproduced below) :

    When copying an existing Discoverer 3i pref.txt file for use in Discoverer 4.1, the following settings, which are new in Discoverer 4.1 need to be added :

    To be added to the [Application] section of the prefs.txt file :

    NonAggregableValue                  = ""

    To be added to the [DATABASE] section of the prefs.txt file :

    DisableAutoOuterJoinsOnFilters      =  0   # Turn off Automatic Outer Joins on filters (0 = on, 1 = off)
    MaterializedViewRedirectionBehavior =  0   # 8.1.6 Materialized View Redirection (0=always when available, 1=always when
                                                 summary data not stale, 2=never)

    In order to simplify this process, the file "Add4iPref.txt" has been shipped with this patch. Append the preferences listed in the file "Add4iPref.txt" to the Discoverer 3i prefs.txt file and then apply preferences:

    <ORACLE_HOME>\DISCWB4\dis4pr -apply -nopause

    User preference migration

    To migrate user level preferences from Discoverer 3i to Discoverer 4.1 please execute the following from the command line:

    <ORACLE_HOME>\DISCWB4\dis4pr -migrate

    5.4 Command line options for "dis4pr"

    The dis4pr executable has the following command line options :

    -preference <preference object name> : Specifies the name for the preference object
    -help -?                             : Lists all available options
    -apply                               : Applies all the preference settings stored in pref.txt
    -apply -file <filename>              : Applies all the preference settings stored in filename
    -migrate                             : Migrates the 3i preferences to 4i
    -migrate -force                      : Doesn't wait for user interference
    -nopause                             : Does not wait for user input after applying preference settings or after migrating
    -clean                               : Removes all user specific preferences from the registry

    5.5 Specifying the version of JInititator if not using default version

    It is possible to specify an alternative version of JInitiator for use with Discoverer Plus by following these steps :

    (1) After Discoverer Plus has been installed, place a copy of the JInitiator self extracting executable file in the 'jinit' directory under the Discoverer installation.

    (2) Edit the following settings in the 'htmlvars.js' file which is found in the 'scripts' directory under the Discoverer installation :

    a. The name of the executable placed in the 'jinit' directory :

    // ORAWEBDISCO_JINITSETUP is the name of the JInitiator executable
    // ex. "jinit11730.exe"
    var ORAWEBDISCO_JINITSETUP = "jinit11730.exe";

    b. The version number separated by a period :

    // ORAWEBDISCO_JINITVERSION is the period separated version of JInitiator
    // ex. ""

    c.  The version number separated by a comma :

    // is comma separated. ex. "1,1,7,30"

    d. The class ID which can be found by installing JInitiator and looking at the text file "jinit-version.txt" under JInitiator's "doc" directory :

    // ORAWEBDISCO_CLASSID is the object id of the specified version of JInitiator.
    // This can be obtained from the doc\jinit-version.txt file in JInitiator's directory.
    // ex. "clsid:9F77A997-F0F3-11d1-9195-00C04FC990DC"
    var ORAWEBDISCO_CLASSID = "clsid:21157916-4d49-11d4-a3e0-00c04fa32518";

    5.6 Netscape Navigator v6

    Please note that at the time of this writing, this version of Discoverer Plus is not certified to run with Netscape Navigator version 6.

    6. Known Issues and Workarounds

    Below is a list of known issues and workarounds where possible.

    6.1 Changing start page in web browser disables access to help

    1485700 - The DiscovererPlus applet is downloaded by clicking on an icon of a magnifying glass in the html page with the title 'Discoverer Start Page'. If this 'start page' is changed to another page then certain functionality will not work until the browser page is returned to the 'start page'. This functionality includes access to help topics and automatically opening up Excel when exporting to an Excel spreadsheet or opening up the web browser when exporting to HTML.

    6.2 Problems finding config XML file if not using default port on HTTP server

    There may be a problem with locating the disco4iv.xml file if not using the default port on the HTTP server. The workaround is to modify the  'Aliased Servlet Init Parameters' section of the configuration file to use the file:/// protocol. See below for an example of where to make the changes in the file (which can be found in the location ...\Apache\Jserv\Servlets\)

    Example of original file entry :


    Change to this :


    6.3 NLS and Netscape - need to manually refresh page if incorrect characters displayed

    If using Netscape in a language other than English, then incorrect characters may be displayed even if the character set is UTF-8. The workaround is to perform a manual refresh of the page.

    6.4 Possible "Out of fetch error" message or "Network error" on query cancellation

    The workaround for this issue is to set the value of the "OutOfFetch" parameter defined in the [session manager] section of the pref.txt file. If the parameter is not present, then add it to the file in the [session manager] section of the file.  The default value is 0. The workaround is to increase the "OutOfFetch" parameter to 1 and apply the preference file.  The affected Plus and Viewer sessions would need to be restarted.  If the issue still occurs after setting this parameter to 1 then increase to 2 and repeat the procedure to apply the preference file.

    6.6 Required Support Files (RSF) Upgrade

    Discoverer installs RSF but in order to solve the following issues upgrade to RSF or later

    6.7 When running Discoverer Plus on a Solaris client, Discoverer freezes after entering an invalid login (bug 1543227)

    The workaround for this is to download and install the JRE/JDK 1.3. The web page for java plugin is  However the plugin is now part of the JRE/JDK itself which can be found at Note that these URLs may change after the time of this writing.

    6.8 An exported chart may appear in black and white (bug 1551483)

    The workaround for this is to change the display settings on the Oracle9iAS server to use a color-depth setting lower than  'True Color'.  If multiple color-depths are available, you may need to try different settings for optimal results.  In general, the problem occurs because the exported GIF is produced on the server which may use a different color pallete than the user's computer.

    6.9 Subtotal percentage column may appear misaligned in Discoverer Viewer  (bug 1694268)

    In Discoverer Viewer, when displaying a Percentage item with both the 'subtotal / subtotal percentage' and 'percentage of grand for each subtotal' options selected, the subtotal percentage column may appear misaligned.  A workaround is to de-select the 'subtotal' option and add one using the Totals feature instead.  Then the page will be displayed correctly in the Viewer.

    6.10 Running Discoverer Viewer in Japanese, Korean, Simplified Chinese, Traditional Chinese or Thai may display currency symbol incorrectly  (bug 1709189)

    When running Discoverer Viewer in any of the following languages :  Japanese, Korean, Simplified Chinese, Traditional Chinese or Thai, the currency symbol may not appear correctly.

    A patch for Korean and Japanese languages will be available on MetaLink shortly after this release is made available.  We are actively working to correct this problem for all of languages listed above.

    7. Issues fixed in this release (4.1.37)

    1731057  Online documentation does not contain information on keyboard accessibility
    1723670  java.lang.illegalstateexception: query state - old & new both 1 error on params
    1703614  NLS: font face order cause yen currency corrupted in html exporting
    1690785  Chart dimensions in the xml should be "sticky"
    1690780  Chart sizing params should maintain aspect ratio if only one dimension is set
    1682674  Worksheet (ws) command missing implied flag
    1682667  Add a 'default' attribute to worksheets.
    1682665  Include excelversion pref.txt entry in config guide
    1678251  Assertion failure in dcwfmt when opening a workbook
    1676784  Web -> windows font mapping needs to be improved
    1650682  SSL: unable to view non-secure items in netscape
    1585752  New attribute <configuration> element "base_dir" added to viewer_config.xml
    1560708  Export: on exporting data in dcs format ,export progress dialog box has no title
    1559214  Percentage grand cannot apply format mask for scientific and currency category
    1528684  Format : cannot increase decimal places for currency , after certain limit
    1312152  Format preview area vertical alignment is reversed for large fonts
    1056649  Should have "fast find" in open dialog
    954748   Enh req: scroll list of values based on letter typed in

    8. Issues fixed in previous releases

    Issues fixed in 4.1.36

    1039038  Options set in Discoverer User Edition impacting on administration tasks
    1089898  Discoverer Plus - printed fonts not same size/style as fonts displayed in report
    1249761  Default aggregate created even when option unchecked in wizard
    1395507  Unable to open workbook against Apps mode EUL after modifying target field in shortcut
    1531329  Issue with workbook that has a grand total at the right and a datapoint with null values
    1586993  Fantrap totals row should be displayed in table with appropriate 'non-aggregable' message
    1587513  ORA-30353 when creating summary tables with default date hierarchy items in Oracle 8.1.7

    Issues fixed in 4.1.33

    875722   NLS: Discoverer server can not handle server message under code conversion**
    1201816  NLS: Number format with comma as a decimal separator
    1371615  Printing page items truncates at edge of page
    1319295  Discoverer doesn't split the page item in more than 1 row when printing
    1354389  Apps model EUL - problems when log in with incorrect responsibility
    1373518  Viewer isn't able to choose on which hierarchy to drill
    1421545  Parameters are re-entered for multiple pages if value in lower and not upper case
    1459731  Unable to retrieve data that includes comma in Discoverer 3i viewer
    1479497  Parameter form appears when you open a scheduled workbook in Discoverer 3i Viewer
    1488342  Discoverer3i Viewer incorrectly displays Greek

    **The Discoverer Server on NT can now run on an OS of any language we support and support clients of any language. Note- This bug never occurred on Solaris or other Unix ports.