1
Patch Release 1

This chapter describes the changes that occurred in Patch Release 1 of Oracle9i Reports.

1.1 reports.sh (UNIX)

On UNIX, this patch will overwrite reports.sh. If you have modified your current reports.sh file, you should save it and, after the patch is installed, merge your modifications into the version of reports.sh installed with the patch. The version installed with the patch contains some required changes.

1.2 rwlpr.sh on Solaris Version 2.8

On Solaris Version 2.8, quotation marks around the printer name are no longer accepted. As a result, you must alter the shell script, rwlpr.sh, for printing on Solaris. The code segment below illustrates the change:

#either LPR or LP Command was found 
if [ -x $PRNCMDPATH ]
then
  if [ `basename $PRNCMDPATH` = "lpr" ]
  then
    if [ `/usr/bin/uname -r` = "5.8" ]
    then
      $PRNCMDPATH `echo $@ | tr -d "\""`
    else
      $PRNCMDPATH "$@"
    fi
  else
   # parse and Fix the command Line as Required by lp
   if [ `/usr/bin/uname -r` = "5.8" ]
   then 
     getLpCommandLine `echo $@ | tr -d "\""`
   else
     getLpCommandLine "$@"
   fi
   $PRNCMDPATH
  fi  
  # exit with the command's exit code , This will tell the 
  # server Print module if the command completed successfully 
  # or not.
  exit $?
fi
done

1.3 Dynamic Environment Switching

In the past, the Reports Server could only serve reports that were compatible with the environment in place when the Reports Server was started. For example, reports had to be compatible with the value of the NLS_LANG parameter at the time the Reports Server was started. This restriction meant that you needed to have one Reports Server running for each language you wanted to process. The new environment switching feature eliminates this restriction by enabling one instance of the Reports Server to serve reports with any arbitrary environment settings, including language.

To use this new feature, you only need to add some elements to your Reports Server's configuration file.

1.3.1 environment Element

The environment element defines the characteristics (i.e., environment variables) that you want to use to establish a particular runtime environment. By referencing the environment element's id, you invoke its settings. You can reference an environment element id from:

• The defaultEnvId attribute of the engine element in the Reports Server configuration file, to apply the corresponding environment settings to that engine when it starts up. Refer to defaultEnvId Attribute in these release notes.

• The command line argument, ENVID, of your report's job request, which makes the environment settings only effective for that particular report job request. Refer to Examples in these release notes.

Below is an example of an environment that you might want to invoke for the defaultEnvId element.

<environment id="JP">
  <envVariable name="NLS_LANG" value="Japanese_Japan.JA16SJIS"/>
  <envVariable name="NLS_CURRENCY" value="¥"/>
  <envVariable name="DISPLAY" value="MyServer.MyCompany.com:0.0"/>
</environment>

Usage Notes

• You may include as many environment elements as you need (e.g., one for each language/territory you need to support). Inside an environment element, you can add as many envVariable elements as required.

• Each envVariable is specified as name-value pair. They can be either standard environment variables or user-defined environment variables.

1.3.2 defaultEnvId Attribute

defaultEnvId is an optional attribute of the engine element in your Reports Server configuration file. It specifies the default environment with which the Reports Server starts an engine. The attribute takes an id that is associated an environment element in another part of the server configuration file (ORACLE_HOME\reports\conf\<server_name>.conf):

<engine id="rwEng" initEngine="1" minEngine="0" maxEngine="10" engLife="50" 
maxIdle="30" defaultEnvId="JP"/>

The value JP identifies an environment element also specified in the server configuration file. The initial engines will be spawned with the environment settings specified in this environment element. For more information on the environment element, refer to Section 1.3.1, "environment Element".

Usage Notes

• defaultEnvId is optional. If you do not specify defaultEnvId, the Reports Server spawns engines with the environment settings in force at startup time.

• The Reports Server starts an engine with the environment variables specified in the referenced environment element plus whatever environment variables that the Reports Server is running under.

1.3.3 Examples

The following examples illustrate the usage of the dynamic environment switching feature:

Example 1

Suppose that you need to run reports in Japanese from your Reports Server. An environment conducive to running reports in Japanese would include:

• NLS_LANG = Japanese_Japan.JA16SJIS

• The currency unit would be set to Yen (¥), the currency of Japan.

• If the Server is running on UNIX, the DISPLAY would also need to be set.

To begin, you would have to add an environment element to your Reports Server configuration file that looks something like the following:

<environment id="JP">
  <envVariable name="NLS_LANG" value="Japanese_Japan.JA16SJIS"/>
  <envVariable name="NLS_CURRENCY" value="¥"/>
  <envVariable name="DISPLAY" value="MyServer.MyCompany.com:0.0"/>
</environment>

Once the environment element is in place, you could request a report with Japanese output using the following URL:

http://<yourWebServer>:<port>/reports/rwservlet?SERVER=<yourreportsserver> 
&REPORT=Japanese.rdf&USERID=<username>/<passwd>@db&DESFORMAT=htmlcss 
&DESTYPE=cache&ENVID=JP

When the URL is submitted to the Reports Server, it detects the optional ENVID parameter and matches the specified id (in this case, JP) to the corresponding id in its configuration file. If the Reports Server already has an engine running with these characteristics, it will reuse the existing engine to process the job. If not, then it spawns an engine using the current environment plus the three environment variables specified in the JP environment element. If spawning a new engine would cause the Reports Server to exceed its maxEngines setting, the Reports Server shuts down an engine before starting a new one. An engine may be shut down even though it has not exceeded its engLife setting.

Once the Reports Server has an engine with the correct environment running, the job is processed by that engine and the output is routed to the specified DESTYPE.

envid is an optional parameter. If you do not pass this parameter with the job, the Reports Server processes the request using an engine started with the defaultEnvId environment. If defaultEnvId is not specified for the engine element in your Reports Server configuration file, then the engine will inherit the settings with which the Reports Server instance was started.

The Reports Server may forward the request to another server on the cluster in cases where it cannot handle the request at that time. Even though the job may be routed to another server on the cluster, the target server will reuse or spawn an engine with the required environment to process this job.

Example 2

The following example illustrates how to use this environment switching feature to run an Arabic report on the same Reports Server that was used to run the Japanese report in Example 1.

Add another environment element to the Reports Server configuration file as shown below:

<environment id="AR">

 <envVariable name="NLS_LANG" value="Arabic_United Arab Emirates.AR8ISO8859P6"/>

 <envVariable name="NLS_CALENDAR" value="Arabic Hijrah "/>

</environment>

The Arabic report has to be submitted to the Reports Server with the following command line:

http://<yourWebServer>:<port>/reports/rwservlet?SERVER=<yourreportsserver>
&REPORT=Arabic.rdf&USERID=<username>/<passwd>@db&DESFORMAT=htmlcss 
&DESTYPE=cache&ENVID=AR

Since the job is submitted with envid=AR, the Reports Server finds or starts an engine with the environment specified by element AR in the Reports Server configuration file. The job is processed by the new engine and the output is distributed to the specified destination.

Example 3

The following example illustrates how the environment switching feature could be used in conjunction with a JSP report, i.e., without the Reports Servlet.

Suppose that you have the following environment elements in the Reports Server configuration file:

<environment id="UK"> 

 <envVariable name="NLS_LANG"  value="AMERICAN_UNITED KINGDOM.WE8ISO8859P1"/>

</environment>



<environment id="US">

 <envVariable name="NLS_LANG" value="AMERICAN_AMERICA.WE8ISO8859P1"/>

</environment>

If your JSP report uses a format mask such as the following, it means the currency, grouping, and decimal symbols can change according to the environment:

<rw:field id="sal" src="sal" formatMask="L999G999D999"/>

To run the report using the UK symbols for currency, grouping, and decimal, you would use the following URL:

http://myserver:port/test/myjsp?userid=scott/tiger@orcl&envid=uk

Note: You could place envid=uk into a key in the cgicmd.dat file.

Usage Notes

• Although this feature is ideal for handling reports of various languages, its application can be much broader. You could use it in any situation where a report requires a particular environment to execute correctly.

• The Reports Server will start one or more engines per environment id as and when it gets requests requesting specific environments. The total number of engines, however, cannot exceed the maxEngine specified for that engine type. It is recommended that you set maxEngine to a value greater or equal to the number of environment elements specified in Reports Server configuration file.

• defaultEnvId can also be applied to pluggable engines other than rwEng. The Reports Server will spawn the pluggable engine with the specified environment id.

• For engines used by the in-process server, the order of precedence for environment variables from highest to lowest is as follows:
  • reports.sh (UNIX only)

  • environment element in the Reports Server configuration file

  • in the ORACLE_HOME/j2ee/OC4J_BI_Forms/config/oc4j.properties file: the oracle.display property defines the DISPLAY setting, oracle.home property defines the ORACLE_HOME setting, and oracle.path defines the PATH setting.

  • in $ORACLE_HOME/opmn/conf/opmn.xml, the <environment> element under <oc4j instanceName="OC4J_BI_Forms" gid="OC4J_BI_Forms">

  • the system settings and registry (Windows only)

• For engines used by the stand alone server, the order of precedence for environment variables from highest to lowest is as follows:
  • reports.sh (UNIX only)

  • environment element in the Reports Server configuration file

  • the environment set in the console where you start rwserver.sh

  • the system settings and registry (Windows only)

1.4 engineResponseTimeOut Parameter

A new, optional attribute, engineResponseTimeOut, has been added to the engine element in the Reports Server configuration file. This attribute enables you to specify the maximum amount of time (in minutes) for an engine to update the status of the job while running a report in your environment. If it takes longer than this amount of time to update the job status for some reason (e.g., due to the engine hanging or a long blocking SQL query), the Reports Server terminates the job.

engineResponseTimeOut has also been added as a new command line parameter for RWSERVLET, RWCLIENT, and RWCGI. From the command line, it overrides the value specified in the engine attribute for that particular job request only.

1.5 Spaces in HTML Output

Bug number: 2441615

By default, spaces are now replaced with &nbsp in HTML and HTMLCSS report output. This new default behavior eliminates alignment issues for number values that are right aligned. If you do not want spaces replaced with &nbsp in your HTML and HTMLCSS output, then you must set REPORTS_NO_HTML_SPACE_REPLACE to YES. If you want to return to the default behavior of replacing spaces with &nbsp, then REPORTS_NO_HTML_SPACE_REPLACE must not be set at all.

As part of this change, the previous functionality of the DELIMITER command line argument for HTML and HTMLCSS output is removed. DELIMITER is still used with the DELIMITED DESFORMAT as in previous releases.

1.6 DelimitedData DESFORMAT

Bug number: 1211760

A new destination format (DESFORMAT) is available in this patch that resolves a bug (1211760) with the earlier delimited formatting functionality.

1.6.1 Using DelimitedData

Customers who had problems running large volume reports with DESFORMAT=Delimited should now use DESFORMAT=DelimitedData.

To use the DelimitedData DESFORMAT for the Generate to File > XML menu option in Reports Builder, set the following environment variable in the operating system:

REPORTS_OVERRIDE_FILEGENXML = Yes

This setting overrides the XML generation functionality in the Reports Builder with the new DelimitedData behavior. In Oracle9iAS Reports Services Release 9.0.4, both formats will be available natively inside Reports Builder, but, in this patch, you must toggle this environment variable to switch between the two behaviors.

1.6.2 Modifying DelimitedData Output

The new DelimitedData driver runs off of the data model and operates in much the same way as the XML driver, which is already available in the product. Since the driver runs off of the data model, any formatting changes defined in the layout are not reflected in the DelimitedData output. You can set the following column properties (Tools > Property Inspector) to alter column names and exclude columns from the DelimitedData output file:

• XML Tag can be used to enter a column alias.

• Exclude from XML output can be used to exclude the column from the DelimitedData output.

The DelimitedData functionality also honors the DELIMITED, CELLWRAPPER, NUMBERFORMAT, and DATEFORMAT command line arguments just as the original Delimited functionality did. Refer to the command line documentation in the Reports Builder online help for details on these arguments.

1.6.3 Known Issues

This feature has the following known issues:

• 2400121: DELIMITEDDATA: REPORT LEVEL SUMMARY INCLUDED WHILE CREATING COLUMN LEVEL SUMMARY

• 2400115: DELIMITEDDATA: COLUMN DATA REPEATED FOR GROUP LEVEL SUMMARY COLUMN

• 2397366: DELIMITEDDATA: REPORT LEVEL COLUMNS DISPLAYED JUST BELOW THE GROUP LEVEL COLUMNS

1.7 JVM Parameters for the Reports Server and Engine

A new parameter, jvmoptions, has been added to the Reports Server to allow you to set options in the server's Java Virtual Machine (JVM). For example, you could use the following command line to start the Reports Server with a 512Mb heap space:

rwserver server=<servername> jvmoptions=-Xmx512M

Multiple options can be passed, in which case the options must be enclosed in quotes:

rwserver server=<servername> jvmoptions="-Xmx256M -Xms=128M"

Similarly, the jvmoptions parameter can be included in the engine configuration section of the server configuration file, and the engine will pass these options when it invokes a JVM.