8
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

• Publishing a Report Portlet in Oracle9iAS Portal

• Specifying a Report Request from a Web Browser

• Sending a Request to the URL Engine

• Scheduling Reports to Run Automatically

• Reusing Report Output from Cache

• Using a Key Map File

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

8.1.1 Servlet

The syntax for the URL of a report run via the Reports Servlet is:

http://<web_server>.<domain_name>:<port>/<alias>/rwservlet?<parameters>

Table 8-1 lists and describes the components of the servlet URL.

Table 8-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 Oracle9iAS Reports Services servlet.
?	Identifies the beginning of the command line arguments.
<parameters>	All the command line arguments, or the key to the key map file where command line arguments are specified.

The URL that calls the Reports Servlet could look like this:

http://neptune.world.com:80/reports/rwservlet?keyname

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 8.9, "Using a Key Map File".

Using the servlet does not mean that you cannot also use Reports JSP files, if the JSP files contain both Web and paper layouts. When you run the report, specify the servlet in the URL and call the JSP with the command line argument: 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 lines in Appendix A, "Command Line Arguments".

8.1.2 JSP

The syntax for a JSP-based report URL is:

http://<web_server>.<domain_name>:<port>/<alias>/myreport.jsp?<parameters>

Table 8-2 lists and describes the components of the JSP-based report URL.

Table 8-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 you want this URL to execute.
?	Identifies the beginning of the command line arguments.
<parameters>	All the command line arguments, and/or the key to the key map file where command line arguments 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, provided it follows 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.

Using a JSP does not mean that you cannot also use the Reports Servlet. When you run the report, specify the servlet in the URL and call the JSP with the command line argument: 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 Arguments". You'll find more information about the cgicmd.dat file in Section 8.9, "Using a Key Map File". For information on choosing whether to use the Reports Servlet to run JSP reports, refer to Chapter 1, "Oracle9iAS Reports Services Architecture".

8.1.3 CGI

Note: The Reports CGI is included in Oracle9iAS Reports Services for backward compatibility. We strongly recommend that you deploy your reports with either a servlet or JSP implementation.

The syntax for the URL of a report run via 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 8-3 lists and describes the components of a CGI-based report URL.

Table 8-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 Oracle9iAS Reports Services. If Reports Services is installed on a UNIX machine, use ".sh" in lieu of ".exe".
?	Identifies the beginning of the command line arguments.
<parameters>	All the command line arguments, or the key to the key map file where command line arguments 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

If Reports Services is installed on a UNIX machine, use ".sh" in lieu of ".exe". For example:

http://neptune.world.com:80/CGI-BIN/rwcgi/sh?key2

8.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 Oracle9iAS Reports Server. It can use command line arguments similar to those used with the Oracle9iAS 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=html desformat=cache
  

  On UNIX, the same command would look like this:

  rwclient.sh report=<my_report>.rdf userid=<username>/<password>@<my_db>
  server=<server_name> destype=html desformat=cache
  

  See Appendix A, "Command Line Arguments" for more information about command line arguments.

• A URL

  To run a report from a browser, use the URL syntax.The Oracle9iAS Reports Servlet (and CGI, for backward compatibility) converts the URL syntax into an rwclient command line request that is processed by Oracle9iAS 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.

• Via Oracle9iAS Portal

  The Oracle9iAS Portal component enables you to add a link to a report in an Oracle9iAS 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. Oracle9iAS Reports Services system administrators use Oracle9iAS Portal wizards to create the packaged procedure making it more convenient and secure to publish the report via the Web. Authorized users accessing the Oracle9iAS Portal page group simply click the link to run the report. System administrators can run the report directly from the wizard. See the Oracle9iAS Portal online help for more information.

  Refer to Publishing a Report Portlet in Oracle9iAS Portal for more information about how to publish your report as a portlet.

• A packaged procedure

  SRW.RUN_REPORT is a built-in that runs an Oracle9iAS Reports Runtime command. When you specify SRW.RUN_REPORT, set the SERVER argument to the Oracle9iAS Reports Services server name to cause the SRW.RUN_REPORT command to behave as though you executed an rwclient command.

  Refer to the Oracle9i Developer Suite (Oracle9iDS) Reports Builder online help for more information.

8.3 Publishing a Report Portlet in Oracle9iAS Portal

One of the best ways to publish your reports is through the declarative, secure interface of Oracle9iAS Portal. To a expose a report in a portal, you must do the following:

1. Create a provider for your reports. This step defines a provider to contain the reports you wish to make available to users in the portal.

2. Create the report definition file access. This step makes the report available as a portlet to page designers within the portal by defining the reports properties, in particular the provider that contains it.

3. Add the report portlet to a page and optionally customize it. This step makes the report available to users in a portlet on a page and enables the page designer to set the report parameters and schedule it to run automatically.

8.3.1 Creating a Provider for Your Reports

If you do not already have a provider defined to contain your reports, you need to create one. For more information on creating a provider, see the Oracle9iAS Portal online help.

8.3.2 Creating the Report Definition File Access

To make your report available as a portlet, you must do the following:

1. From the Oracle9iAS Portal home page, click the Corporate Documents tab.

2. Click Builder.

3. Click the Administer tab.

4. In the Oracle Reports Security portlet, click Oracle Reports Security Settings.

5. In the Reports Definition File portlet, click Create Reports Definition File Access.

6. Follow the steps in the wizard and click the question mark in the upper right corner for additional information about the available settings. At the end of the wizard, click Finish.

7. Click the Access tab.

8. Click Publish to Portal.

9. Click Apply. Your report has now been added to the Portlet Repository and you can add it to a page.

8.3.3 Adding the Report Portlet to a Page

Once the portlet for your report is in the Portlet Repository, you may add it to any page just as you would any other portlet.

1. From the Oracle9iAS Portal home page, click the Corporate Documents tab.

2. Click Builder.

3. Click the Build tab.

4. In the Page Groups portlet, enter the Page Group Name of the page group in which you want to place your report portlet.

5. Create a new page by clicking Create a Page or edit an existing page by entering the name of an existing page and clicking Edit.

6. If you are creating a new page, follow the steps in the wizard and click the question mark in the upper right corner for additional information about the available settings. Click Finish when you are done. If you are editing an existing page, skip to the next step.

7. In the page region where you wish to add your report portlet, click the Add Portlet tool. (Tip: Hints for each tool will display when you roll your mouse over them.)

8. Drill down through the Portlet Repository to the provider that contains the report portlet. The report portlet is listed in the Portlet Repository under the Portal DB provider to which it belongs. The location of the provider depends on how the Portlet Repository has been organized. If the Portal DB provider is a fairly new provider, it may be under the New page of the Portlet Repository.

9. Click the name of your report portlet to add it to the Selected Portlets list.

10. Click OK.

11. Click Customize in the upper right corner of your report portlet.

12. Enter parameter values in the Parameter tab and, if desired, schedule the job to run automatically in the Schedule tab.

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

Note: Another way to publish reports on a Web site is to create an Oracle9iAS Portal component. For more information, refer to Oracle9iAS Portal online help.

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 arguments, then refer to Appendix A, "Command Line Arguments" for a list of valid rwclient command line arguments.

• Simplified URL request using key mapping, for example:

  http://<your_webserver>.<domain_name>:<port>/<alias>/rwservlet?key1
  

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

1. Set up an HREF tag on the host Web page, for example:

   <A HREF="http://<web_server>.<domain_name>:<port>/<alias>/rwservlet?key1>
   Employee Directory</A>
   

2. Point users to the Web page that hosts the link.

3. Users click the link to run the report.

8.5 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 arguments:

• 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 (e.g., urlEngine) in the server configuration file that is associated with a URL engine.

  Note: For information on activating the URL engine, refer to Chapter 3, "Configuring Oracle9iAS Reports Services".

For example, a request that specifies an external URL for urlParameter might look like the following:

http://localhost.com/servlet/RWServlet?server=ReportsServer
+jobType=urlEngine+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://<localhost>/servlet/RWServlet?server=ReportsServer+jobType=rwurl
+destype=cache+urlParameter="http%3A%2F%2F<localhost>%2Ffoo.jsp%3Fuserid
%3Dscott%2Ftiger@v815%3Fserver%3DreportsServer

8.6 Scheduling Reports to Run Automatically

You can use the server to run reports automatically from the Oracle9iAS Reports Queue Manager, Oracle9iAS Portal, or with the SCHEDULE command line argument. The scheduling feature enables you to specify a time and frequency for the report to run.

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

If you publish a report as a Portal component on an Oracle9iAS Portal page, then you can schedule the report request to run automatically and push the resulting reports to specified pages. Refer to Oracle9iAS Portal online help for more information.

The SCHEDULE keyword is available for use with the rwclient, rwservlet, and rwcgi commands. See Appendix A, Section A.4.83, "SCHEDULE" for more information.

8.7 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 8-4 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 Server is running.
SERVER_PORT	The port number of the server on which the Reports Server 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.

8.8 Reusing Report Output from Cache

When you run a report, a copy of the report output is saved in the Oracle9iAS 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 don't 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", and it doesn't happen, then the Reports Server will try to find a job in the Finished Jobs Queue which was successfully completed within n minutes. If the Reports Server can find such a job, then the new job request "A" will return the output of job "B".

  Note: Refer to Appendix A, "Command Line Arguments" for more information about the TOLERANCE command line argument.

• In a clustered environment, duplicate job checking (i.e., jobs with the same cache key) is executed across cluster members. If a duplicate job is found in another server in the same cluster, the job request will be transferred to that server to retrieve the cached result.

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

8.8.1 Usage Notes

• You can set the cache size through the Oracle9iAS Reports Queue Manager or via the cache element in the server configuration file (<server_name>.conf).The Oracle9iAS Reports Server attempts to keep the total size of cache files below the set limit, deleting the least recently used files from the cache first. In addition, you can empty the cache through the Oracle9iAS Reports Queue Manager.

  For more information on setting the cache, refer to the Oracle9iAS Reports Queue Manager online help, and see Chapter 3, "Configuring Oracle9iAS Reports Services".

• If a report is being processed when an identical job is submitted, then Oracle9iAS Reports Services reuses the output of the currently running job even if TOLERANCE is not specified or is equal to zero. For example, suppose that job_1 is currently being run and someone submits job_2, which has the same cache key as job _1. Oracle9iAS Reports Services uses the output from job_1 for job_2. In this case, processing job_2 is significantly faster since job_2 is fetched from cache rather than run in its own right.

8.9 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 arguments 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: You'll find more information about the cmdkey keyword in Appendix A, "Command Line Arguments".

8.9.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: the 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, "Reports-Related Environment Variables" for more information.

Usage Notes

• In rwcgi URLs, the first argument (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 argument is a name/value pair (i.e., keyword=value), then the whole command line is used in lieu of a cgicmd.dat key entry.

8.9.2 Adding Key Mapping Entries to a Key Map File

To add key mapping entries to a key map file:

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

2. Add a key mapping entry. For example:

   key1: report=<your_report.rdf> USERID=<username>/<password>@<my_db>
   DESFORMAT=html SERVER=<server_name>.<cluster_name (if present)>
   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 arguments follow the syntax rules of rwclient. See Appendix A, "Command Line Arguments" for more information.

3. Add or update the hyperlinks on your Web page.

   For more information, see Section 8.4, "Specifying a Report Request from a Web Browser".

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

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