Skip Headers

Oracle9iAS Reports Services Publishing Reports to the Web
Release 2 (9.0.2)

Part Number A92102-01
Go To Table Of Contents
Contents
Go To Index
Index

Go to previous page Go to next page

8
Running Report Requests

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

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:

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

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:

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.

URL syntax can be presented in the following forms:

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:

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="/index.html"
+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
<div>
<table> <tr><td> <hr>
Note:
If the URL has special characters, they must be encoded as per the x-www-form-urlencoded format. <hr> </td> </tr> </table> </div>

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:

8.8.1 Usage Notes

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:

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.

8.9.1 Enabling Key Mapping

Key mapping is enabled when any of these conditions are met:

Usage Notes

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
                              

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