13 Running Report Requests

This chapter discusses various ways to send report requests to the Reports Server. It includes the following sections:

The Reports URL Syntax
Report Request Methods
Deploying Your Reports
Publishing a Report in OracleAS Portal
Specifying a Report Request from a Web Browser
Sending a Request to the URL Engine
Running Reports Through a Web Service
Running Reports from Oracle Workflow
Scheduling Reports to Run Automatically
Additional Parameters
Reusing Report Output from Cache
Using a Key Map File

13.1 The Reports URL Syntax

This section provides quick reference information on formulating a URL for publishing a report. It covers three deployment types:

Servlet
JSP
CGI (for backward compatibility only)

The information is largely the same for both Windows and UNIX environments. Differences are noted.

13.1.1 Servlet

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
`web_server`	The name you gave the Oracle HTTP Server when you installed it.
`domain_name`	Your organization's domain name.
`port`	The port number on which the Oracle HTTP Server listens for requests. When no port is specified, the default is used (80).
`alias`	The virtual path that stands in for the absolute path to the files a URL will access.
`rwservlet`	Invokes the Reports Servlet.
`?`	Identifies the beginning of the command line options.
`parameters`	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".

13.1.2 JSP

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
`web_server`	The name you gave the Oracle HTTP Server when you installed it.
`domain_name`	Your organization's domain name.
`port`	The port number on which the Oracle HTTP Server listens for requests. When no port is specified, the default is used (80).
`alias`	The virtual path that stands in for the absolute path to the files a URL will access.
`myreport.jsp`	The report `*.jsp` file that you want this URL to execute.
`?`	Identifies the beginning of the command line options.
`parameters`	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".

13.1.3 CGI

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.

rwservlet is strongly recommended over rwcgi for performance reasons. For each request, rwcgi starts a new process, initializing a JVM and resulting in slow performance when running a large number of report requests. On the other hand, rwservlet is deployed on an OC4J instance and leverages servlet functionality, thereby providing better performance over rwcgi.

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
`web_server`	The name you gave the Oracle HTTP Server when you installed it.
`domain_name`	Your organization's domain name.
`port`	The port number on which the Oracle HTTP Server listens for requests. When no port is specified, the default is used (80).
`alias`	The virtual path that stands in for the absolute path to the files a URL will access.
`rwcgi.exe`	The executable file that invokes the CGI component of OracleAS Reports Services. If OracleAS Reports Services is installed on a UNIX machine, use "`.sh`" in lieu of "`.exe`".
`?`	Identifies the beginning of the command line options.
`parameters`	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

13.2 Report Request Methods

There are a number of request methods available to you for running your report requests. These include:

The rwclient command line

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.
A URL

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.
Through OracleAS Portal

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.
A packaged procedure

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".

13.3 Deploying Your Reports

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.

13.3.1 Deploying a Report with a Paper Layout

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.

13.3.2 Running a Report with a Paper Layout

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".

13.3.3 Deploying a JSP Report to the Web and to Paper

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 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).

13.3.3.1 Creating a New J2EE Application

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:

The WEB-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:

ORACLE_HOME\reports\j2ee\reports_ids\web\WEB-INF\lib

where ORACLE_HOME is the directory where the Oracle Developer Suite is installed.

In Oracle Application Server, you can find the tag library here:

ORACLE_HOME\j2ee\OC4J_BI_Forms\applications\reports\web\WEB_INF\lib.

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, the web.xml file is located here:

ORACLE_HOME/reports/j2ee/reports_ids/web/WEB-INF

On Oracle Application Server, the web.xml file is located here:

ORACLE_HOME/j2ee/OC4J_BI_Forms/applications/reports/web/WEB-INF

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.

13.3.3.2 Deploying the J2EE Application Using OC4J

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:

Deploying the J2EE Application Using an Existing OC4J Instance
Deploying the J2EE Application in a New OC4J Instance

13.3.3.2.1 Deploying the J2EE Application Using an Existing 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.
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.

13.3.3.2.2 Deploying the J2EE Application in a New OC4J Instance

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".

13.3.4 Running a JSP-Based Web Report from a Browser

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".

13.3.5 Running a JSP report with a Paper Layout

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".

13.3.6 Running with the WE8MSWIN1252 Character Set on UNIX

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).

13.4 Publishing a Report in OracleAS Portal

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 initial NLS_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.

13.5 Specifying a Report Request from a Web Browser

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

13.6 Sending a Request to the URL Engine

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 the x-www-form-urlencoded format.

13.7 Running Reports Through a Web Service

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.

13.8 Running Reports from Oracle Workflow

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.

13.9 Scheduling Reports to Run Automatically

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.

13.10 Additional Parameters

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
`ACCEPT_LANGUAGE`	The comma separated list of languages accepted by the browser/user.
`REMOTE_ADDR`	The remote IP address from which the user is making the request.
`REMOTE_HOST`	The remote host name from which the user is making the request.
`SCRIPT_NAME`	The virtual path of the script being executed.
`SERVER_NAME`	The host name or IP address of the server on which the Reports Servlet is running.
`SERVER_PORT`	The port number of the server on which the Reports Servlet is running.
`SERVER_PROTOCOL`	The name and revision of the information protocol with which the request was sent.
`USER_AGENT`	The description of the remote client's browser.

13.11 Reusing Report Output from Cache

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".

Note:
Refer to Section A.3.113, "TOLERANCE" for more information.

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.

13.11.1 Usage Note

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".

13.12 Using a Key Map File

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.

Key mapping is useful for:

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.

Note:

See Section A.3.14, "CMDKEY" for more information.

13.12.1 Enabling Key Mapping

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.

13.12.2 Adding Key Mapping Entries to a Key Map File

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".

13.12.3 Using a Key with Everything but JSPs

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.

13.12.4 Using a Key with a Report Run as a JSP

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 use cmdkey 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