Oracle® Application Server Reports Services Publishing Reports to the Web
10g Release 2 (10.1.2) B14048-02 |
|
Previous |
Next |
This chapter discusses various ways to send report requests to the Reports Server. It includes the following sections:
This section provides quick reference information on formulating a URL for publishing a report. It covers three deployment types:
The information is largely the same for both Windows and UNIX environments. Differences are noted.
The syntax for the URL of a report run through the Reports Servlet is:
http://web_server.domain_name:port/alias/rwservlet?parameters
Table 13-1 lists and describes the components of the servlet URL.
Table 13-1 Components of a URL That Calls the Reports Servlet
Component | Description |
---|---|
|
The name you gave the Oracle HTTP Server when you installed it. |
|
Your organization's domain name. |
|
The port number on which the Oracle HTTP Server listens for requests. When no port is specified, the default is used (80). |
|
The virtual path that stands in for the absolute path to the files a URL will access. |
|
Invokes the Reports Servlet. |
|
Identifies the beginning of the command line options. |
|
All the command line options, or the key to the key map file where command line options are specified. |
The URL that calls the Reports Servlet could look like this:
http://neptune.world.com:80/reports/rwservlet?keyname
where keyname
refers to a command line listed under a unique header (the key name) in the cgicmd.dat
file. Note that this works differently for JSP files, which use the keyword/value pair cmdkey=
value
to specify key names for command lines that are stored in the cgicmd.dat
file. You'll find more information about using key mapping in Section 13.12, "Using a Key Map File".
When you use the Reports Servlet, you can also execute JSP report files if the JSP files contain paper layouts. When you run the report, specify the Reports Servlet in the URL and call the JSP with the command line option: report=
myreport
.jsp
.
For example:
http://neptune.world.com:80/reports/rwservlet?report=myreport.jsp&destype=cache&desformat=html
You'll find more information about command line keywords and values in Appendix A, "Command Line Keywords".
The syntax for a JSP-based report URL is:
http://web_server.domain_name:port/alias/myreport.jsp?parameters
Table 13-2 lists and describes the components of the JSP-based report URL.
Table 13-2 Components of a JSP-based Report URL
Component | Description |
---|---|
|
The name you gave the Oracle HTTP Server when you installed it. |
|
Your organization's domain name. |
|
The port number on which the Oracle HTTP Server listens for requests. When no port is specified, the default is used (80). |
|
The virtual path that stands in for the absolute path to the files a URL will access. |
|
The report |
|
Identifies the beginning of the command line options. |
|
All the command line options, or the key to the key map file where command line options are specified. |
The URL used to invoke a JSP-based report could look like this:
http://neptune.world.com:80/jsp/myreport.jsp?
You can specify a key in the URL that refers to a command line in the cgicmd.dat
file that contains additional command line parameters. In this case, you must use the name value pair: cmdkey=
keyname
. This can appear anywhere in your URL after the start of the query string (marked by a question mark). For example:
http://neptune.world.com:80/jsp/myreport.jsp?userid=scott/tiger@hrdb&cmdkey=key1
In your URL, use an ampersand (&
) with no spaces to string parameters together.
When you use a JSP, you can also use the Reports Servlet. When you run the report, specify the Reports Servlet in the URL and call the JSP with the command line option: report=
myreport
.jsp
.
For example:
http://neptune.world.com:80/reports/rwservlet?report=myreport.jsp&destype=cache&desformat=html
You'll find more information about command line keywords in Appendix A, "Command Line Keywords". You'll find more information about the cgicmd.dat
file in Section 13.12, "Using a Key Map File".
Note: With Oracle Reports 10g, the Reports CGI (rwcgi ) is deprecated (maintained only for backward compatibility); instead, use JSPs, rwservlet (Reports Servlet), or Web Services.
|
The syntax for the URL of a report run through the Reports CGI on Windows is:
http://web_server.domain_name:port/alias/rwcgi.exe?parameters
And on UNIX is:
http://web_server.domain_name:port/alias/rwcgi.sh?parameters
Table 13-3 lists and describes the components of a CGI-based report URL.
Table 13-3 Components of a URL That Calls the Reports CGI
Component | Description |
---|---|
|
The name you gave the Oracle HTTP Server when you installed it. |
|
Your organization's domain name. |
|
The port number on which the Oracle HTTP Server listens for requests. When no port is specified, the default is used (80). |
|
The virtual path that stands in for the absolute path to the files a URL will access. |
|
The executable file that invokes the CGI component of OracleAS Reports Services. If OracleAS Reports Services is installed on a UNIX machine, use " |
|
Identifies the beginning of the command line options. |
|
All the command line options, or the key to the key map file where command line options are specified. |
The URL used to invoke a CGI implementation could look like this on Windows:
http://neptune.world.com:80/cgi-bin/rwcgi.exe?key2
And like this on UNIX:
http://neptune.world.com:80/cgi-bin/rwcgi.sh?key2
There are a number of request methods available to you for running your report requests. These include:
The rwclient
command line (rwclient.sh
on UNIX) is available for running report requests from a command line in a non-Web architecture. It references an executable file that parses and transfers the command line to the specified Reports Server. It can use command line options similar to those used with the Reports Runtime executable file, rwrun
(rwrun.sh
on UNIX).
On Windows, a typical rwclient
command line request looks like this:
rwclient report=my_report.rdf userid=username/password@my_db server=server_name destype=cache desformat=html
On UNIX, the same command would look like this:
rwclient.sh report=my_report.rdf userid=username/password@my_db server=server_name destype=cache desformat=html
See Appendix A, "Command Line Keywords" for more information about command line options.
To run a report from a browser, use the URL syntax. The Reports Servlet (and CGI, for backward compatibility) converts the URL syntax into an rwclient
command line request that is processed by OracleAS Reports Services. You can give your users the URL syntax needed to make the report request from their browser, or you can add the URL syntax to a Web site as a hyperlink. The remainder of this chapter discusses this method in more detail.
The OracleAS Portal component enables you to add a link to a report in an OracleAS Portal page or portlet, or to output report results directly into a portlet. Each report link points to a packaged procedure that contains information about the report request. OracleAS Reports Services system administrators use OracleAS Portal wizards to create the packaged procedure making it more convenient and secure to publish the report through the Web. Authorized users accessing the OracleAS Portal page group simply click the link to run the report. System administrators can run the report directly from the wizard. See the OracleAS Portal online Help for more information.
Refer to Section 13.4, "Publishing a Report in OracleAS Portal" for more information about how to publish your report as a portlet.
SRW.RUN_REPORT
is a built-in procedure that runs a Reports Runtime command. When you specify SRW.RUN_REPORT
, set the SERVER
option to the Reports Server name to cause the SRW.RUN_REPORT
command to behave as though you executed a rwclient
command.
For more information, see Chapter 17, "Using Event-Driven Publishing". For a description of SRW.RUN_REPORT
, refer to the Oracle Reports online Help.
A Web service
You can expose OracleAS Reports Services as a Web service and then call it from any Web service aware environment (for example, a Java application).
For more information, see Chapter 14, "Using the Oracle Reports Web Service".
Once you've created your report, you can deploy it so that end users can view it. This section describes how to deploy a report with a paper layout (that is, REP, RDF, XML, or JSP report) and how to deploy a report with a Web layout (that is, a JSP report).
Note: For an example on building and testing a JSP-based Web report, refer to the Oracle Reports Tutorial and the "Building a JSP-Parameter Form for a Web Report" chapter in the Oracle Reports Building Reports manual. |
The following table describes which method you can use to deploy your report, depending on the type of report.
Table 13-4 Methods for Deploying a Report
Type of Report | Method | Reason for Using |
---|---|---|
Report with paper layout (REP, RDF, XML) |
Deploying a Report with a Paper Layout |
Method for deploying a report with only a paper layout. |
JSP report with a paper layout |
Deploying a Report with a Paper Layout |
Simplest method for deploying a paper report of any type. However, if the JSP report has both a paper and Web layout, we recommend you refer to Section 13.3.3, "Deploying a JSP Report to the Web and to Paper". |
JSP report with a paper and Web layout |
Deploying a JSP Report to the Web and to Paper |
Strongly recommended for those who want to publish a report to both the Web and to paper. |
Once you've created your paper report, you can deploy it to the Reports Server so that users can run the report. The steps in this section show you how to deploy a report of type RDF, REP, XML or JSP.
Note: JSP reports can be deployed either to the Web or to paper, depending on the layout the report designer used for the JSP report. This section discusses how to deploy a JSP report with a paper layout. If you want to deploy a JSP report with a paper and Web layout, follow the steps in Section 13.3.3, "Deploying a JSP Report to the Web and to Paper". |
If your report depends on Java classes (for example, Barcode classes, a Web Service stub, and so on), you must configure the process to access these classes. That is, if your JSP report with a paper layout contains a Java class, you must set the classPath
property of the engine element in the server configuration file (ORACLE_HOME
\reports\conf\
server_name
.conf
).
To deploy your paper report:
Transfer the report file ( RDF, REP, XML, or JSP) and its associated files (for example, PLL, PLX or referenced images) to the deployment directory on your application server.
Note: To transfer the file, you can use any method available, such as FTP or WebDAV. |
Ensure the directory on the application server where you've transferred the file is listed in the Reports Server access path. If it is not, use the REPORTS_PATH environment variable, or set the sourceDir
property of the Reports engine element in the server configuration file.
Now that you have deployed your paper report, you can run it from a Web browser.
In a browser, for example, you can type the following URL in the Location field:
http://your_web_server:port_num/reports/rwservlet?server=server_name&report= &userid=&desformat=pdf&destype=cacheusername/password@my_dbmyreport.rdf
Your report displays as a PDF (since in this case desformat=PDF
) in the browser.
For more information on running a report from the browser, refer to Section 13.5, "Specifying a Report Request from a Web Browser".
There are two ways you can deploy your JSP reports: through the existing Oracle Reports application, or through a J2EE application you create yourself. Using an existing application is useful when you are developing and testing your JSP-based Web reports. When you are ready to deploy your reports, however, we recommend you use an application you've created yourself.
About JSP reports with both paper and Web layouts
With Reports Builder, you can create a JSP report with a paper layout, a Web layout, or both. You execute these reports using different processes:
JSP reports with paper layouts are executed through the Oracle Reports engine.
JSP reports with Web layouts are executed through the J2EE container.
If your report depends on Java classes (for example, Barcode classes, a Web Service stub, and so on), you must configure the process to access these classes. That is, if your JSP report with a paper layout contains a Java class, you must set the classPath
property of the engine element in the server configuration file (ORACLE_HOME
\reports\conf\
server_name
.conf
).
If your JSP report with a Web layout contains a Java class, you can either add the classes or JAR to the WAR file, or change the J2EE container classpath
. For more information, refer to the Oracle Application Server Containers for J2EE documentation.
Note: For an example on building a report with a paper and Web layout, refer to the "Building a Report with a Barcode" chapter in the Oracle Reports Building Reports manual. For a simple JSP-based Web report example, refer to the Oracle Reports Tutorial. |
The steps in this section show you how to deploy a JSP report with a paper and Web layout using a J2EE application. To deploy your JSP report with a paper and Web layout, you can create a new Oracle Reports J2EE application in your Oracle Application Server. You can create this application in a an existing instance or a new instance of Oracle Application Server Containers for J2EE (OC4J).
In this section, you will create a new J2EE application for Oracle Reports. You will create a Web application archive (WAR file) that will contain the application information, then deploy it as an Enterprise archive (EAR file). To create a new J2EE application, you can use Oracle JDeveloper, another Java development tool, or you can create it manually. If you do not use Oracle JDeveloper to create the application, you will need to make a few modifications to the application, as well as to your JSP report.
To create a J2EE application:
Note: If you are not familiar with creating a J2EE application, refer to Sun Microsystem's Web site (http://java.sun.com/j2ee ). For more information on using Oracle JDeveloper, refer to the Oracle JDeveloper online Help.
|
Before you create your EAR file, ensure that your application contains all the necessary directories, such as WEB-INF
and the web.xml
file.
Note: TheWEB-INF directory must contain the JSP tag library for Oracle Reports, called reports_tld.jar . In Oracle Developer Suite, you can find the tag library here:
where In Oracle Application Server, you can find the tag library here:
|
Ensure that your JSP-based Web report points to the location of the JSP tag library for Oracle Reports. Otherwise, the report will not run.
To point to the location of the JSP tag library, include the taglib
directive in the JSP file:
<%@ taglib uri="/WEB-INF/lib/reports_tld.jar" prefix="rw" %>
Create a new EAR file, either manually or using a tool such as Oracle JDeveloper. Ensure you create the WAR file according to the appropriate J2EE format.
If your JSP report contains a paper layout and you want to deploy your report to paper, open the web.xml
file.
Note: In Oracle Developer Suite, theweb.xml file is located here:
On Oracle Application Server, the
|
If you are deploying a JSP report that only contains a Web layout, continue to Step 7.
Add the following code to the web.xml
file.
<servlet> <servlet-name>rwservlet</servlet-name> <servlet-class>oracle.reports.rwclient.RWClient</servlet-class> <load-on-startup>yes</load-on-startup> </servlet> <servlet-mapping> <servlet-name>rwservlet</servlet-name> <url-pattern>/rwservlet*</url-pattern> </servlet-mapping>
This new definition will redirect all URLs starting with /rwservlet
to the servlet you've defined.
Note: You can change the servlet name and URL. |
Save the web.xml
file.
Create an EAR file from the WAR file. Once these files are compiled, note where they are saved.
After you have created the WAR and EAR files, you can deploy them to the Oracle Application Server, which will serve the application to the Web. You can deploy these files using Oracle Enterprise Manager 10g using either an existing OC4J instance or a new OC4J instance.
This section contains the two methods of deploying the J2EE application:
Ensure that you have created the J2EE application as described in Section 13.3.3.1, "Creating a New J2EE Application".
In Oracle Enterprise Manager 10g, display the detail page for your middle tier.
Under System Components, click the OC4J instance on which you want to deploy the J2EE application.
In the OC4J instance page, click Applications.
Under Deployed Applications, click Deploy EAR file to deploy the EAR file you created in Section 13.3.3.1, "Creating a New J2EE Application".
On the first page of the Deploy Application wizard, click Browse to select the J2EE application (EAR file) to be deployed or enter the location of the EAR file that you created.
Under Application Name, specify a unique application name for this application. For example, MyReportApp
.
From the Parent Application list, select the parent application and click Continue.
On the URL Mapping page, note that the text in the URL Mapping field is the name your users will enter to access the new application.
In the URL Mapping field, add a forward slash (/) to the beginning of the application name, since it is part of a URL address. For example:
/MyReportApp
Click Finish.
On the next page, click Deploy.
On the detail page that displays, you should now see your application (MyReportApp
) listed under Deployed Applications.
Click your application name (for example, MyReportApp
).
On the Application page, under Properties, click General.
Under Library Paths, check if rwrun.jar
and zrclient.jar
are included. If not, click Add Another Row, then add the missing path(s):
On Windows:
%ORACLE_HOME%\reports\jlib\rwrun.jar
%ORACLE_HOME%\jlib\zrclient.jar
On Unix:
$ORACLE_HOME/reports/jlib/rwrun.jar
$ORACLE_HOME/jlib/zrclient.jar
Click Apply, then click OK.
Click Stop, then Start to restart your OC4J instance so that the new library paths take effect.
To deploy a J2EE application in a new OC4J instance, you must first create the OC4J instance, then you can deploy the J2EE application.
Creating a New OC4J Instance
Ensure that you have created the J2EE application as described in Section 13.3.3.1, "Creating a New J2EE Application".
In Oracle Enterprise Manager 10g, display the detail page for your middle-tier.
Click Create OC4J Instance.
Type the name of your OC4J instance.
Click Create.
Once the OC4J instance is created, click OK.
Deploying the J2EE Application
On the Application Server page, under System Components, you should now see the new OC4J instance.
Now, you must manually configure the OC4J instance to support connection to a Reports Server and the security integration.
Copy the following properties and their definitions in the oc4j.properties
file from an existing OC4J instance, for example the OC4J_BI_FORMS instance (ORACLE_HOME/j2ee/OC4J_BI_FORM/config/oc4j.properties
), into the oc4j.properties
file of your new OC4J instance (ORACLE_HOME/j2ee/your application/config/oc4j.properties
):
oracle.home
oracle.path
In the opmn.xml
file in your ORACLE_HOME/opmn/conf
directory, add the PATH
(Windows) or LD_LIBRARY_PATH
(UNIX) to your new OC4J instance:
In ORACLE_HOME/opmn/conf/opmn.xml
, find the XML element that describes your new OC4J instance:
<process-type id="New OC4J Instance Name" module-id="OC4J">
Add the PATH
(Windows) or LD_LIBRARY_PATH
(UNIX) module data properties by copying them from the existing OC4J instance in the same opmn.xml
file. For example, on UNIX:
<environment> <variable id="LD_LIBRARY_PATH" value="$ORACLE_HOME/lib:$ORACLE_HOME/network/lib: $ORACLE_HOME/jdk/jre/lib/sparc"/> </environment> <category id="start-parameters"> <data id="java-options" value="-server -Djava.security.policy= $ORACLE_HOME/j2ee/OC4J_BI_Forms/config/java2.policy -Djava.awt.headless=true -Xmx512M"/> <data id="oc4j-options" value="-properties -userThreads "/> </category> <category id="urlping-parameters"> <data id="/MyReportsApp*/rwservlet/pingserver?start=auto" value="200"/> </category> <dependencies> <database infrastructure-key="portal"/> <managed-process process-type="HTTP_Server" process-set="HTTP_Server" ias-component="HTTP_Server" autostart="true"/> </dependencies>
*where MyReportApp
is your newly created Web application name for Oracle Reports.
Restart the OC4J instance.
Follow the steps in Section 13.3.3.2.1, "Deploying the J2EE Application Using an Existing OC4J Instance".
If your JSP report is a Web report, you can now run your JSP-based Web report from a Web browser. In a browser, type the following URL in the Location field:
http://your_computer_name:port/MyReportApp/JSPreportname.jsp?userid=user ID/password@database_name
Note: In the above URL,MyReportApp is the name of the application you created.
|
If you wish you modify your JSP-based Web report at this point, you can either:
Replace the report in this location.
Re-create the WAR file with the modified JSP-based Web report, then redeploy the application. For more information, refer to Section 13.3.3.1, "Creating a New J2EE Application".
For more information on running a report from a browser, refer to Section 13.5, "Specifying a Report Request from a Web Browser".
If your JSP report has a paper layout, you can now run your JSP report from a browser using the following URL:
http://your_web_server:portnum/MyReportApp/rwservlet?report=myreport.jsp&userid= username/password@my_db&server=server_name&desformat=pdf&destype=cache
Your report displays as a PDF (since in this case desformat=PDF
) in the browser.
For more information on running a report from a browser, refer to Section 13.5, "Specifying a Report Request from a Web Browser".
There are no UNIX fonts built into the WE8MSWIN1252
character set. This may cause Oracle Reports to fail when NLS_LANG=AMERICAN_AMERICA.WE8MSWIN1252
. Therefore, you must map the code page of the installed fonts (defined in the Tk2Motif.rgb
file) to the WE8MSWIN1252
character set. TK2Motif.rgb
is located in the ORACLE_HOME
/guicommon/tk/admin/
directory.
Note: This mapping is required for Reports Builder, Reports Converter in non-batch mode (BATCH=NO ), Reports Server and Reports Runtime with REPORTS_DEFAULT_DISPLAY=NO . Reports Server and Reports Runtime uses REPORTS_DEFAULT_DISPLAY to determine the fonts needed.
|
Example1
Tk2Motif*fontMapCs: ISO8859-1=WE8MSWIN1252
(if there are ISO8859-1
fonts installed).
One of the best ways to publish your report is through the declarative, secure interface of OracleAS Portal. To publish a report in OracleAS Portal, refer to Chapter 12, "Deploying Reports in OracleAS Portal". Specifically, you must first register your Oracle Reports components in OracleAS Portal (see Section 12.2, "Registering Oracle Reports Components"), then expose your report in a portal (see Section 12.3, "Publishing Your Report as a Portlet").
Note: When you use features like OracleAS Portal Security, Portal Destination, and Job Status Repository, the JDBC database connections made by OracleAS Reports Services may override the initialNLS_LANG setting. This change may in turn affect the behavior of the running report, such as bidirectional output in PDF. On UNIX platforms, you can work around this issue using the environment switching functionality to dynamically set the environment for reports. Refer to Section 3.2.2, "Dynamic Environment Switching" for more information.
|
You can provide the user with the URL syntax needed to make a report request, or you can add the URL syntax to a Web page as a hyperlink.
URL syntax can be presented in the following forms:
Full URL request, for example:
http://your_webserver.domain_name:port/alias/rwservlet?report=myreport.rdf&userid= username/password@my_db&server=server_name&desformat=html&destype=cache
If you require additional command line keywords, then refer to Appendix A, "Command Line Keywords" for a list of valid rwclient
command line keywords.
Simplified URL request using key mapping, for example:
http://your_webserver.domain_name:port/alias/rwservlet?key1
If you have activated the Reports Server's URL engine, you can send job requests to the URL engine by using the following command line options:
urlParameter
identifies the URL to be placed in the cache. For example, http://www.oracle.com
or a JSP report.
jobType
is the name of a job type (for example, rwurl
) in the server configuration file that is associated with a URL engine.
Note: For information on activating the URL engine, refer to Section 3.5, "Configuring the URL Engine". |
For example, a request that specifies an external URL for urlParameter
might look like the following:
http://your_webserver:portnum/reports/rwservlet?server=ReportsServer+jobType=rwurl+urlParameter= "http://www.oracle.com"+destype=mail+desname=foo@bar.com+desformat=htmlcss
Alternatively, a request that specifies a JSP report for urlParameter
would look like the following:
http://your_webserver:portnum/reports/rwservlet?server= ReportsServer+jobType=rwurl+destype=cache+urlParameter= "http%3A%2F%2Flocalhost%2Ffoo.jsp%3Fuserid%3Dscott%2Ftiger@oraDB%3Fserver%3DreportsServer"
Note: If the URL has special characters, they must be encoded as per thex-www-form-urlencoded format.
|
In many cases, reports are integrated components of some larger application rather than a standalone application themselves. Hence, it can be useful to generate report requests from within an application. We accomplish this goal by exposing OracleAS Reports Services as a Web service. This Web service may then be called from within any Web service-aware environment (for example, a Java application). For example, suppose that you have a Java-based expense reporting form and you want to allow users to generate a PDF version of their expense reports from it each time that they complete an expense form in your system. By creating a Java proxy Oracle Reports Web Service, you could then easily reference it from your Java development environment (for example, Oracle JDeveloper) and add a button that invokes OracleAS Reports Services to generate the PDF file.
See Also: Chapter 14, "Using the Oracle Reports Web Service" for more information on the Oracle Reports Web service and installing and using the sample proxy and Java client. |
For information about running reports from Oracle Workflow, refer to Section 3.8, "Configuring Oracle Reports to Communicate with Oracle Workflow", which points to the Integrating Oracle Workflow with Oracle Reports white paper on OTN (http://www.oracle.com/technology/products/reports/features/workflow
) for complete information.
You can use the server to run reports automatically from Reports Queue Manager (rwrqm
on Windows, or rwrqv.sh
on Solaris), OracleAS Portal, or with the SCHEDULE
command line keword. The scheduling feature enables you to specify a time and frequency for the report to run.
Refer to the Reports Queue Manager online Help for more information about scheduling your reports.
If you publish a report as a portal component on an OracleAS Portal page, then you can schedule the report request to run automatically and push the resulting report ouput to specified pages. Refer to the OracleAS Portal online Help for more information.
The SCHEDULE
command line keyword is available for use with the rwclient
, rwservlet
, and rwcgi
commands. See Section A.3.94, "SCHEDULE" for more information.
When you send a request to the Reports Server, the following additional parameters, the values of which you cannot change, are implicitly passed along with your request:
Table 13-5 Additional Parameters Passed With a Report Request
Name | Description |
---|---|
|
The comma separated list of languages accepted by the browser/user. |
|
The remote IP address from which the user is making the request. |
|
The remote host name from which the user is making the request. |
|
The virtual path of the script being executed. |
|
The host name or IP address of the server on which the Reports Servlet is running. |
|
The port number of the server on which the Reports Servlet is running. |
|
The name and revision of the information protocol with which the request was sent. |
|
The description of the remote client's browser. |
When you run a report, a copy of the report output is saved in the OracleAS Reports Services cache. Subsequently, if an identical report is run (that is, with the same cache key), then the current request is recognized as a duplicate job.
There are several scenarios where reports caching takes effect:
When a new job request "A" comes to the Reports Server, and there is another job "B" that has the same cache key in the Current Jobs Queue (where it is waiting for an available engine or is in the middle of execution), then job "A" will use the output from job "B".
The job cache key excludes the destype
, desname
, server
, and tolerance
parameters, and includes almost all other parameters.
This level of cache happens automatically. You do not need to specify any other parameters in the command line for it to work.
If the user specifies TOLERANCE=
n
(where n
is a number in units of minutes) in the new job request "A", then Reports Server will try to find a job in the Finished Jobs Queue than was successfully completed within n
minutes. If Reports Server finds such a job, then the new job request "A" will return the output of job "B".
OracleAS Reports Services cache results are persistent. If the Reports Server is shut down, once it is up again all the previous cache results are recovered and ready to use again.
You can set the cache size through Reports Queue Manager (rwrqm
on Windows, or rwrqv.sh
on Solaris) or through the cache
element in the server configuration file (server_name
.conf
). Reports Server attempts to keep the total size of cache files below the set limit, deleting the oldest cache files. In addition, you can empty the cache through Reports Queue Manager.
For more information on setting the cache, refer to the Reports Queue Manager online Help, and see Chapter 3, "Configuring OracleAS Reports Services".
If you choose to provide users with a URL or add a hyperlink to a Web site, then you can use a key map file to simplify or hide parameters in your URL requests.
The key map file contains command strings for running reports, each headed by a unique key identifier. Except when you run a report as a JSP, you reference only this key in the runtime URL. The server or servlet sends the key value to the map file (cgicmd.dat
), which in turn returns the command associated with the specified key to the server or servlet for processing. By using key mapping, the command line options are all hidden from the user.
Shortening the URL, making it more convenient to use.
Remapping the runtime commands without having to change the original URL.
Standardizing several typical run configurations for your company.
Hiding certain parameters from users (for example, the database connect string).
Restricting the parameters users can use to run a report.
When you specify a key name from the key map file (cgicmd.dat
), it must always be at the beginning of the query string (after the question mark) in a report request URL. An exception to this is if you use the cmdkey command line keyword, and express the key name as its value: CMDKEY=
keyname
. In this case, you can place the key name anywhere in the query string within the report request URL. The CMDKEY
keyword can be used with jobs run as JSPs and with the rwservlet
command.
Key mapping is enabled when any of these conditions are met:
A valid file with the standard file name, cgicmd.dat
, is present in the default location: ORACLE_HOME
\reports\conf
directory on the Web server machine (on either Windows or UNIX).
A valid key map file is entered in the Reports Servlet configuration file (rwservlet.properties
) under the KEYMAPFILE
parameter.
When rwcgi
is used, when the REPORTS_CGIMAP
environment variable on the Web server machine specifies the name of a valid key map file. See Appendix B, "Environment Variables" for more information.
To add key mapping entries to a key map file:
Navigate to the cgicmd.dat
file on the machine that hosts your Reports Server, and open it with a text editor.
You'll find this file in the following directory on both Windows and UNIX:
ORACLE_HOME\reports\server\conf\cgicmd.dat
Add a key mapping entry. For example:
key1: report=your_report.rdf userid=username/password@my_db desformat=html SERVER=server_name destype=cache
In this example, key1
is the name of the key.
Except for the special parameters that are described in the file itself, the command line options follow the syntax rules of rwclient
. See Appendix A, "Command Line Keywords" for more information.
Add or update the hyperlinks on your Web page.
For more information, see Section 13.5, "Specifying a Report Request from a Web Browser".
When you place a key name in a report request URL, it must always be the first value within the query string (immediately after the question mark). For example:
http://…/rwservlet?keyname
Below is an example of a key mapping for a restricted run with a parameter form.
The URL might be:
http://web_server.domain_name:port/cgi-bin/rwcgi.exe?key&par1&par2&parN
The key mapping file might contain:
KEY: REPORT=myreport DEPTNO=%1 MYPARAM=%2 %*
This would generate the equivalent of the following command line request:
rwclient REPORT=myreport DEPTNO=par1 MYPARAM=par2 parN
Usage Note
In rwcgi
URLs, the first option (that is the first information after the question mark) is treated as a key if it is not otherwise a part of a name/value pair. If the first option is not a name/value pair (that is, keyword=
value
), then the whole command line is used in lieu of a cgicmd.dat
key entry.
When you run a report as a JSP and want to call a command key in the cgicmd.dat
file, you must use the cmdkey
keyword in your URL. For example, your JSP URL might look like this:
http://…/myreport.jsp?cmdkey=key
Note: You can also usecmdkey with the rwservlet command.
|
When you use cmdkey
with a JSP or rwservlet
, you can place it anywhere within the query string. For example:
http://…/example.jsp?parameter1=value1&cmdkey=keyname http://…/rwservlet?parameter1=value1&cmdkey=keyname
Usage Note
When using key mapping, the order in which the parameters are substituted from the URL into the key is determined by the placement of cmdkey
in the URL. For example, suppose you have a key such as the following in the cgicmd.dat
file:
mykeys: DEPTNO=%1 MYPARAM=%2
Now, you execute a JSP report that references this key as follows:
http://neptune.world.com:80/jsp/myreport.jsp?userid=scott/tiger@hrdb &cmdkey=mykeys&10&test
Because of the placement of cmdkey
in this URL, the 10
corresponds to %1
and test
corresponds to %2
. Even though they are not the first and second parameters in the URL, 10
and test
are the first and second parameters to follow cmdkey
in the URL. Inthis example, the URL becomes:
http://neptune.world.com:80/jsp/myreport.jsp?userid=scott/tiger@hrdb &DEPTNO=10&MYPARAM=test