|
Oracle9i Reports Release Notes (Patch 4)
Release 4 (9.0.2) Part Number B13551-01 |
|
|
|
|
Oracle9i Reports Release Notes (Patch 4)
Release 4 (9.0.2) Part Number B13551-01 |
|
|
|
|
This chapter describes the changes that occurred in Patch Release 4. As Patch Release 4 is a cumulative patch, installing it will enable newly incorporated features and fixes, including those that pertain to Patch Release 3.
This chapter contains the following sections:
This section outlines the newly incorporated enhancements pertaining to Patch Release 4.
Bug Nos: 2968284, 2659642, 3017227
All Platforms
When you create R-T-L PDF reports with font subsetting enabled, you may see some font misalignment if the row contains a large number of characters. This issue occurs because of the variance between the actual value and the width calculated by Oracle Toolkit in the case of variable width fonts.
To fix this issue, you must download and install the patch located at: http://metalink.oracle.com.
The ARU patch number for Windows is 5143372.
The ARU patch number for HP-UX 11 is 4519711.
The ARU patch number for HP-UX 11.0/32 BIT is 4519711.
The ARU patch number for Solaris is 3039666.
The ARU patch number for Sun Solaris (SPARC) is 4650528.
On UNIX platforms, you may see some font alignment issues even after applying the patch. This issue will be fixed in a later release.
To work around this issue, use fixed width fonts instead of variable width fonts. For example, Miriam Fixed True Type font (Hebrew), a fixed width font available on Windows 2000 can be used for font subsetting on UNIX platforms. This should fix any font alignment issues with Hebrew fonts.
This section outlines the newly incorporated enhancements pertaining to Patch Release 1, Patch Release 2, and Patch Release 3.
Bug No: 2775230
In prior releases, Oracle9i Reports formatted the sections of a report in sequential order: Header section, followed by Main section, followed by Trailer section. This release introduces the capability to change the order in which the three sections of a report are formatted.
The format order can be set using the SRW.SET_FORMAT_ORDER built-in procedure.
This feature is useful for formatting any report section first to retrieve information that is known only at the time of formatting, such as page numbers, then using that information in the formatting of a previous section.
For example, to create a table of contents (TOC) for a report, you can format the Main section first and use report triggers to build a table containing the TOC entries. When the first element for the TOC is formatted, a trigger fires and creates a row in the TOC table containing the TOC entry and the page number. After the Main section has completed formatting, the format order setting can define that the Header section is formatted next. The Header section can contain a report block based on the TOC table. After formatting, you can output your report with a TOC (the Header section), followed by the report body (the Main section), followed by the Trailer section.
Use the SRW.SET_FORMAT_ORDER built-in procedure to specify the order in which the three sections of a report (Header, Main, and Trailer) are formatted.
SRW.SET_FORMAT_ORDER (first_section, second_section, third_section);
where:
first_section,second_section,third_section
If SRW.HEADER_SECTION,SRW.MAIN_SECTION,SRW.TRAILER_SECTION specified in the order in which the report should be formatted
SRW.SET_FORMAT_ORDER can be called in either the Before Parameter Form trigger or the After Parameter Form trigger. If called in both triggers, the call from the After Parameter Form trigger takes precedence.
|
Note: Regardless of the order in which the report sections are formatted, the output order (that is, visual order) is unchanged: Header section, followed by Main section, followed by Trailer section. |
In certain circumstances involving the Paper Design view, Reports Builder does not execute the Before Parameter Form or After Parameter Form triggers; therefore, SRW.SET_FORMAT_ORDER is not executed. This occurs in the following cases:
If you switch view from the Paper Design view to, say, the Paper Layout view and then back to the Paper Design view.
If in the Paper Design view, you choose Print Preview, then close the Print Preview window.
If you perform a live refresh on the Paper Design view.
To overcome this limitation, you can close the Paper Design view, then redisplay it.
|
Note: This limitation applies only in Reports Builder; it does not occur in Reports Runtime and Reports Builder. |
If the SRW.SET_FORMAT_ORDER built-in procedure is called from any trigger other than the Before Parameter Form trigger or the After Parameter Form trigger Reports Builder issues an error message:
REP-1426: <trigger name>: Running SRW.SET_FORMAT_ORDER from incorrect context.
function AfterPForm return boolean is
begin
SRW.SET_FORMAT_ORDER(SRW.MAIN_SECTION, SRW.HEADER_SECTION, SRW.TRAILER_SECTION);
return (TRUE);
end;
This example produces the same result as the earlier example.
function AfterPForm return boolean is
begin
SRW.SET_FORMAT_ORDER(1, 0, 2);
return (TRUE);
end;
|
Note: The possible range of values thatSRW.SET_FORMAT_ORDER takes are: 0,1 and 2. If you specify values outside this range, Reports Builder issues an error message:
REP-1417: <trigger name>: Invalid integer argument passed to SRW.SWT_FORMAT_ORDER. |
Bug No: 2833652
Prior to Patch Release 3, turning on the trace option in the server configuration file turned tracing on for both the server and the engine. Performance suffers when you set the tracing option for the engine.
To specify the tracing option only for the server, you must set the new trace attribute, traceModule. The values for traceModule are: all,server,and engine.
For example:
<trace traceOpts="trace_all" traceModule="server"/>
If you do not specify a value for traceModule, both server and engine tracing are turned on.
Bug No: 2192297
The REPORTS_GRAPH_IMAGE_DPI environment variable specifies a dots per inch (DPI) value for graphs being output to a PDF file or a printer. This environment variable enables you to increase the earlier fixed default value of 72 DPI, in turn improving the image resolution of graphs output to a PDF file or a printer.
72 through 300
250
|
Note: With the default value of 250:
|
(Windows only) Use the registry to specify the value. (UNIX only) Set the value as an environment variable (shell script).
When you set a DPI value greater than 250 and your chart is bigger than 5"x5" (approximately), you may also need to change the JVM heap size value using REPORTS_JVM_OPTIONS to avoid the Out Of Memory error for the JVM.
|
See Also: Setting the JVM options in Oracle9i Reports. For more information on setting the JVM options. |
To revert to the old behavior, set the value of this environment variable to 72 DPI.This variable is currently not supported in YES distribution functionality as this is specific to PDF and printer outputs only.
Bug number: 2192297
The REPORTS_JVM_OPTIONS environment variable specifies any JVM options that you want Reports Builder, Reports Runtime, or Oracle9iAS Reports Services to consider when it starts its JVM. For example, you can use this environment variable to specify the starting heap size and maximum heap size for the JVM, additional classpath entries, and so on.
List of JVM options in the JVM command line syntax.
-Xmx256M
(Windows only) Use the registry to specify the value. (UNIX only) Set the value as an environment variable (shell script).
The default value -Xmx256M specifies the JVM heap size of 256 to avoid the Out Of Memory error when running reports with large graphs or running big reports.
In the server mode, you can also specify the jvmoptions in the servername.conf file in the engine attribute. If specified, the jvmoptions set in the server configuration file would take precedence over the REPORTS_JVM_OPTIONS environment variable. In this case any value set in the REPORTS_JVM_OPTIONS will be discarded.
Bug No: 2926463
The REPORTS_BIDI_ALGORITHM environment variable specifies the bidirectional (BiDi) algorithm to be used to resolve NLS-related issues of BiDi languages (for example, Arabic or Hebrew) such as the period (.) for NLS_CURRENCY.
Set the value of this environment variable based on where you will invoke your report. For example, Microsoft's Internet Explorer, Netscape, and Java use the Unicode algorithm (BIDI_ALGORITHM_UNICODE) for Bidi handling. However, Oracle9iAS Forms Services uses the Oracle algorithm (BIDI_ALGORITHM_PASTA200)
ORACLE|UNICODE
where
ORACLE = BIDI_ALGORITHM_PASTA200
UNICODE = BIDI_ALGORITHM_UNICODE
ORACLE
The DELIMITED_LINE_END environment variable specifies whether to print the delimited character at the end of the line for delimited output.
YES|NO
YES
Set this environment variable to NO to ensure that the delimited character is not printed at the end of the line.
Table 1-1 indicates which commands can use the COLLATE keyword.
Table 1-1 Commands that can use the COLLATE keyword
| rwclient | rwrun | rwbuilder | rwconverter | rwservlet | rwcgi | rwserver |
|---|---|---|---|---|---|---|
| yes | yes | no | no | yes | yes | no |
Use COLLATE to control the collating behavior when a report is sent to a printer. This behavior is applicable to both Postcript and PCL on UNIX platforms.
For example, printing three copies of a three page document with COLLATE set to YES would result in an output similar to the following:
1 2 3|1 2 3| 1 2 3
The order specified is the page numbers being printed. This behavior is similar to selecting the Collate check box in the Print dialog box.
Printing three copies of a three page document with COLLATE set to NO would result in an output similar to the following:
1 1 1| 2 2 2| 3 3 3
COLLATE={YES|NO}
YES Collates the pages when sent to a printer.
NO Does not collate the pages when sent to a printer.
YES
Bug No: 2965782
In the past, Reports Server could only serve reports that were compatible with the environment in place when Reports Server was started. For example, reports had to be compatible with the value of the NLS_LANG parameter at the time 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 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.
The environment element defines the characteristics (that is, 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 this Release Note.
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 this Release Note.
The following 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>
You may include as many environment elements as you need (for example, 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.
defaultEnvId is an optional attribute of the engine element in your Reports Server configuration file. It specifies the default environment with which 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 environment Element.
defaultEnvId is optional. If you do not specify defaultEnvId, Reports Server spawns engines with the environment settings in force at startup time.
Reports Server starts an engine with the environment variables specified in the referenced environment element plus whatever environment variables that Reports Server is running under.
The following examples illustrate the usage of the dynamic environment switching feature:
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 variable 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 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 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 Reports Server to exceed its maxEngines setting, then 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 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, 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.
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.
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 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, 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.
The following example illustrates how the environment switching feature could be used in conjunction with a JSP report, that is, 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 placeenvid=uk into a key in the cgicmd.dat file.
|
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.
Reports Server will start one or more engines for each 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.
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 standalone 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)
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 (for example, due to the engine hanging or a long blocking SQL query), 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.
Bug number: 1211760
A new destination format (DESFORMAT) is available in this patch that resolves a bug (1211760) with the earlier delimited formatting functionality.
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 Reports Builder with the new DelimitedData behavior. Next release onwards, 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.
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.
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
Table 1-2 indicates which commands can use the BACKGROUND keyword.
Table 1-2 Commands that can use the BACKGROUND keyword
| rwclient | rwrun | rwbuilder | rwconverter | rwservlet | rwcgi | rwserver |
|---|---|---|---|---|---|---|
| yes | no | no | no | yes | yes | no |
BACKGROUND specifies whether a report on the server should be run synchronously (NO) or asynchronously (YES).
BACKGROUND={YES|NO}
YES Runs the report asynchronously. The client sends the call to the server, then continues with other processes without waiting for the report job to complete. If the client process is killed, the job is canceled.
NO Runs the report synchronously. The client waits for the report to queue, be assigned to a runtime engine, run, and finish.
NO
If BACKGROUND=YESis used with rwbuilder or rwrun, a warning is issued and the keyword is ignored.
This section outlines the important bug fixes and workarounds pertaining to Patch Release 4:
|
See Also: Appendix A, " Fixes and Workarounds for 9.0.2.4"For more information on all the bugs fixed and workarounds required. |
Bug No: 2906401
Solaris only
You may see garbled output when you run a multibyte report that is designed in Windows on a Solaris machine with the we8iso8859-15 character set.
To work around this issue, you must do the following:
Make an entry for the fonts used in your default printer’s .ppd file. This file is located in the following directory:
$ORACLE_HOME/guicommon9/tk90/admin
|
Note: The entries are for the fonts that appears garbled in the report output. |
Set the encoding scheme in the font's AFM file to FontSpecific if it is AdobeStandardEncoding. Thus, the following entry in the AFM file:
EncodingScheme AdobeStandardEncoding
must change to:
EncodingScheme FontSpecific
Bug No: 3056717
All Platforms
The character set of the error message template (rwerror.htm) is now iso-8859-1 to ensure consistency across all platforms. Earlier, it was windows-1252, which is a character set specific to the Windows platform.
|
Note: The error message template and all other templates are located under the following directory:$ORACLE_HOME/reports/templates / |
Bug No: 2855714
All Platforms
When you pass a multibyte character with a URL escape to rwservlet, the NLS characters appear garbled.
After you have downloaded the 9.0.2.4 patch, you can now specify non-ASCII escaped characters in the request URL or in the parameter form input. You must specify the character encoding in the rwservlet.properties file before you can apply it. This is to ensure that rwservlet uses the required encoding when parsing the parameter value.
You can set the value of DEFAULTCHARSET in the rwservlet.properties file to either:
The NLS characterset (for example, JA16EUC)
The IANA charset (for example, EUC-JP)
DEFAULTCHARSET=JA16EUC
Bug No: 3146008
All Platforms
Reports Engine may stop responding after a long running report is executed multiple times. This is because the engine always maintains a connection with the database.
Patch Release 4 onwards, the server configuration file, server_name.conf includes a new engine property, keepConnection, for the default runtime engine implementation. This property tells the default runtime engine whether to retain the existing connection (YES) or discard it and reconnect (NO).
To enable the keepConnection property:
Uncomment the entry in the engine node of the server_name.conf, file.
Specify the appropriate value.
YES Retain the existing database connection information.
NO Discard the existing database connection information and reconnect with the userid specified for the job.
YES
The keepConnection property does not affect reports deployed using either rwbuilder or rwrun.
The keepConnection property will be migrated if a server_name.conf file used in previous versions (for example, 9.0.2.x) runs in the current environment.
