4
Running Report Requests

This chapter discusses various ways to specify report requests. The following topics are covered:

Report request methods
Duplicate job detection
Using a mapping file to simplify run requests
Specifying URL run requests
Scheduling reports requests to run automatically

4.1 Report Request Methods

You can run report requests using various request methods, described below:

The RWCLI60 command line enables you to run a report request from the command line prompt. RWCLI60 is an executable file that parses and transfers the command line to the specified Oracle Reports Services server. It uses a command line similar to the Oracle Reports Services Runtime executable file (RWRUN60). An RWCLI60 command line request is made using a non-Web architecture. A typical command line request looks like the following:
```
RWCLI60 REPORT=my_report.rdf USERID=username/password@my_db SERVER=repserver 
DESTYPE=HTML DESFORMAT=cache
```
See Appendix B, "RWCLI60 Command Line Arguments" for a list of valid RWCLI60 command line arguments.
The URL syntax enables you to run a report request from a Web browser. The CGI and servlet converts the URL syntax into an RWCLI60 command line request that is processed by Oracle Reports Services. When the report has finished processing, the output is sent to an HTML or PDF file in a location known to the Web server, which is served back to the requesting Web browser. You can provide 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 Oracle Portal component enables you to add a link as an Oracle Portal component to an Oracle Portal site. This link points to a packaged procedure that contains information about the report request. Oracle Reports Services system administrators use Oracle Portal wizards to create the packaged procedure making it more convenient and secure to publish the report via the Web. Authorized users accessing the Oracle Portal site simply click the link to run the report. System administrators can run the report directly from the wizard. See Chapter 5, "Oracle Reports Services Security with Oracle Portal" for more information.
ActiveX control exposes Oracle Reports Services through industry-standard ActiveX technology enabling you to run reports from any ActiveX container. The Oracle Reports Services Launcher is an example of an ActiveX container. Refer to the ActiveX and Oracle Reports Services Launcher online help for more information.
The SRW.RUN_REPORT is a packaged PL/SQL procedure that runs an Oracle Reports Services Runtime command. When you specify the SRW.RUN_REPORT command line, set the SERVER argument to Oracle Reports Services TNS service entry name to cause the SRW.RUN.REPORT command to behave as though you executed an RWCLI60 command. Refer to the Oracle Reports Services Builder online help for more information.

4.2 Duplicate Job Detection

When you run a report with the DESTYPE set to cache or the TOLERANCE set to any number of minutes (that is, 0 or greater), a copy of the report output is saved in the Oracle Reports Services cache. Subsequently, if an identical report is run (that is, with the exact command line arguments), then the current request is recognized as a duplicate job. Oracle Reports Services reuses the output from the cache instead of executing the report again if it is requested within the specified tolerance (for example, TOLERANCE=10). When the prior job is finished, or if it has already finished, the cached output will be used for the subsequent report, too. If one of the jobs is canceled (for example, canceled from the Oracle Reports Services Queue Manager), then the runtime engine will run the other report normally.

Refer to Appendix B, "RWCLI60 Command Line Arguments" for more information about the DESTYPE and TOLERANCE command line arguments.

4.2.1 Usage Notes

You might find the following usage notes helpful:

The following command line arguments are compared to detect duplicate jobs: REPORT, USERID, DESFORMAT, PARAMFORM, CURRENCY, THOUSANDS, DECIMAL, PAGESIZE, ORIENTATION, MODE, and all user parameters.
To distribute the output of a report to multiple destinations, you can run the report once on a server, and then submit the same command to the same server with a different destination and tolerance. Oracle Reports Services detects the duplicate job and redistribute the cached file to the new destination.
Duplicate job detection operates independently on each instance of a repeated job.
You can set the cache size through the Oracle Reports Services Queue Manager or manually by setting the CACHESIZE parameter in the Oracle Reports Services configuration file. Oracle Reports Services attempts to keep the total size of cache files below this limit, deleting the least recently used files from the cache first. In addition, you can empty the cache through the Oracle Reports Services Queue Manager.

Refer to the Oracle Reports Services Queue Manager online help, or see Appendix C, "Oracle Reports Services Configuration Parameters" for more information on setting the cache.
If a report is being processed when an identical job is submitted, then Oracle Reports Services reuses the output of the currently running job even if TOLERANCE is not specified or is equal to zero. Suppose that job_1 is currently being run by one of the Oracle Reports Services engines and someone else submits job_2, which is identical to job _1. Oracle Reports Services uses the output from job_1 for job_2. In this case, processing job_2 is significantly faster since job_2 is not sent to an engine for execution.

4.3 Using a Key Map File

If you choose to provide users with the URL syntax or add the URL syntax as a hyperlink to any Web site, then you can use a key map file to simplify or hide parameters in your URL requests. Key mapping is useful for:

Shortening the URL, making it more convenient to use.
Remapping the URL run configuration without having to change the original URL.
Standardizing several typical run configurations for the organization.
Hiding certain parameters from users (for example, the database connect string).
Restricting the parameters users can use to run a report.

A more convenient and secure way to publish reports on a Web site is to create an Oracle Portal component. See Chapter 5, "Oracle Reports Services Security with Oracle Portal" for more information.

A map file takes a URL parameter and maps it to the command line arguments that govern the report request. For example, one argument in the URL request syntax could map to all of the command line arguments needed to run the report. By using key mapping, the command line arguments are all hidden from the user.

Below is an example of a key mapping for a restricted run with a Parameter Form.

A submission of:

http://your_webserver/cgi-bin/rwcgi60.exe?key+par1+par2+parN

where the key mapping file contains:

KEY: module=myreport deptno=%1 myparam=%2 %*

generates the equivalent of the following command line request:

RWCLI60 module=myreport deptno=par1 myparam=par2 parN

4.3.1 Enabling Key Mapping

Key mapping is enabled when either of the two following conditions are met:

The REPORTS60_CGIMAP (CGI) environment variable on the Web server machine specifies the name of a valid key map file. See Appendix D, "Environment Variables" for more information.
A valid file with the standard file name, cgicmd.dat, is present in the ORACLE_HOME\REPORT60 directory on the Web server machine.

Usage Notes

The following usage notes might be helpful for key mapping:

When key mapping is enabled, all RWCGI60 URLs are treated as if the first argument is a key. The key map file searches for this key. If the key is found, then its defined value is substituted into the command line for Oracle Reports Services. If it is not found, then an error is generated.
When submitting a URL through an HTML form, the key is coded as an input of type hidden.

4.3.2 Mapping URL Parameters

This section describes how to add key mapping entries to a key map file.

On the Web server machine:

Open the cgicmd.dat (CGI) file, located in the ORACLE_HOME\REPORT60 directory, in a text editor.

Tip: Type: http://your_webserver/cgi-bin/rwcgi60.exe/showmap? in your Web browser to verify the name of the mapping file that is being used.
Add a key mapping entry. A basic key mapping entry looks similar to the following, where key1 is the name of the key:
```
key1: REPORT=your_report.rdf USERID=user_name/password@mydb DESFORMAT=html 
SERVER=repserver DESTYPE=cache
```
Except for the special parameters that are described in the file itself, the command line arguments follow the syntax rules of RWCLI60. See Appendix B, "RWCLI60 Command Line Arguments" for more information about the RWCLI60 command line arguments.

If you set the REPORTS60_REPORTS_SERVER environment variable and are sending the request to the default server, then you can omit the SERVER command line argument. See Appendix D, "Environment Variables" for more information.
Add or update the hyperlinks on your Web page. See Section 4.4.2, "Specifying a Report Request from a Web Browser".

4.4 Specifying Report Requests

You can specify reports by:

Building a report
Specifying a report request from a Web browser
Scheduling reports to run automatically

4.4.1 Building a Report

To build a report, you do the following:

On the machine where your Oracle Reports Services is located, create the reports source directory (for example, C:\WEB_REPORTS) for saving the reports using the path. Ensure that this directory is set in the SOURCEDIR parameter in the Oracle Reports Services configuration file. See Appendix C, "Oracle Reports Services Configuration Parameters".

The reports source path can also be set in the REPORTS60_PATH environment variable. See Appendix D, "Environment Variables" for more information.

Start the Oracle Reports Services Builder and build a report. You can save this report as an RDF or REP file. Be sure to copy this report definition file to the reports source directory on Oracle Reports Services machine (for example, C:\WEB_REPORTS). Refer to the Building Reports manual or Oracle Reports Services Builder online help for more information about building a report. To access Oracle Reports Services Builder only help, click on the Help icon and do the following steps:
1. For online help on this task, choose Help->Report Builder Help Topics.
2. On the Index page, type the following:
```
report, building
```
3. Then click Display to view the following help topic:
```
Building a standard report
```
Make this report available to users. See Section 4.4.2, "Specifying a Report Request from a Web Browser" for more information.

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

A more convenient and secure way to publish reports on a Web site is to create an Oracle Portal component. See Chapter 5, "Oracle Reports Services Security with Oracle Portal" for more information.

URL syntax can be presented in the following forms:

Full URL request that looks similar to the following:
```
http://your_webserver/cgi-bin/rwcgi60.exe?report=your_report.rdf
+userid=user_name/password@mydb+server=repserver+desformat=html
+destype=cache
```
If you require additional command line arguments, then refer to Appendix B, "RWCLI60 Command Line Arguments" for a list of valid RWCLI60 command line arguments.
Simplified URL request using key mapping that looks similar to the following:
```
http://your_webserver/cgi-bin/rwcgi60.exe?report=key1
```

If you set the REPORTS60_REPORTS_SERVER environment variable and are sending the request to the default server, then you can omit the SERVER command line argument. See Appendix D, "Environment Variables" for more information.

To add the URL syntax to a Web page as a hyperlink:

Request as a hyperlink to your Web page your syntax would look similar to the following:
```
<A HREF="http://my_webserver/cgi-bin/rwcgi60.exe?key1>My report> </A>
```
Provide users the Web site URL that publishes the report request. Users click the link to run the report.

If the report does not run or display in Web browser as expected, then refer to Appendix G, "Troubleshooting" for more information.

4.4.3 Scheduling Reports to Run Automatically

You can also use the server to run reports automatically from the Oracle Reports Services Queue Manager or from Oracle Portal. The scheduling feature enables you to specify a time and frequency for the report to run.

Refer to the Oracle Reports Services Queue Manager online help for more information about scheduling your reports.

If you publish your reports on an Oracle Portal site as an Oracle Portal component, then you can schedule these report requests to run automatically and push the resulting reports to specified folders on the site. Refer to Chapter 5, "Oracle Reports Services Security with Oracle Portal" for more information.

4 Running Report Requests