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

• 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 via 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

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

Using the servlet does not mean that you cannot also use JSP report 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 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 lines in Appendix A, "Command Line Options".

Note: Yo can also supply these parameters within the JSP file itself.

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[s] that you want this URL to execute.
?	Identifies the beginning of the command line options.
parameters	All the command line options, and/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, 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 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 Options". You'll find more information about the cgicmd.dat file in Using a Key Map File.

13.1.3 CGI

Note: The Reports CGI is included in Oracle Application Server 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 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 Command Line Options 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 Oracle Application Server 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 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 via 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 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 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 an rwclient command.

  Refer to the Reports Builder online help for more information.

• A Web service

  You can expose OracleAS Reports Services as a Web service and then call it from any Web service aware environment (e.g., a Java application).

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 (i.e., REP, RDF, XML, or JSP report) and how to deploy a report with a Web layout (i.e., 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 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 Deploying a JSP report to the Web and to Paper.

To deploy your paper report:

1. Transfer the report file ( RDF, REP, XML, or JSP) and its associated files (e.g., 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.

Make sure 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/rwservlet?server=server_
name&report=myreport.rdf&userid=username/password@my_db&desformat=pdf

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 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 via the Reports Engine

• JSP reports with Web layouts are executed via the J2EE container

If your report depends on Java classes (e.g., Barcode classes, a Web Service stub, etc.), 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 Reports engine element in the server configuration file (ORACLE_HOME\reports\conf\server_name.conf).

If your JSP report with a Web layout contains a Java class, you can either add the classes or JAR to the WAR file, or change the J2EE container classpath. For more information, refer to the Oracle Application Server Containers for J2EE documentation.

Note: For an example on building a report with a paper and Web layout, refer to the "Building a Report with a Barcode" chapter in the Oracle Reports Building Reports manual. For a simple JSP-based Web report example, refer to the Oracle Reports Tutorial.

The steps in this section show you how to deploy a JSP report with a paper and Web layout using a J2EE application. To deploy your JSP report with a paper and Web layout, you can create a new Oracle Reports J2EE application in your Oracle Application Server. You can create this application in a an existing instance or a new instance of Oracle Application Server Containers for J2EE (OC4J).

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 (a WAR file) that will contain the application information, then deploy it as an Enterprise archive (an 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's Web site at,(http://java.sun.com/j2ee/). For more information on using Oracle JDeveloper, refer to the Oracle JDeveloper Online Help.

1. Before you create your WAR file, make sure 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.

2. Make sure your JSP-based Web report points to the location of the JSP tag library for Oracle Reports. Otherwise, the report will not run.

3. Create a new WAR file, either manually or using a tool, such as Oracle JDeveloper. Make sure you create the WAR file according to the appropriate J2EE format.

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

5. 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 ending with /rwservlet to the servlet you've defined.

   Note: You can change the servlet name and URL.

6. Save the web.xml file.

7. Create an EAR file from the WAR file. Once these files are compiled, note where they are saved.

13.3.3.2 Deploying the Application Using OC4J

After you've 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 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

1. Make sure you've created the J2EE application as described in Creating a New J2EE Application.

2. In Oracle Enterprise Manager, display the detail page for your middle tier.

3. Under System Components, click OC4J_BI_Forms.

4. Under Deployed Applications, click Deploy EAR file to deploy the EAR file you created in Creating a New J2EE Application.

5. On the first page of the Deploy Application wizard, click Next (located at the bottom of the screen).

6. On the Select Application page, under Select the J2EE application (EAR file) to be deployed, enter the location of the EAR file you created in the previous section.

7. Under Specify a unique application name for this application, type the name of your application, such as MyReportApp, then click Next.

8. On the URL Mapping page, note that the text in the URL Binding field is the name your users will enter to access the new application.

9. In the URL Binding field, add a forward slash (/) to the beginning of the application name, since it is part of a URL address. For example:

    /MyReportApp
   
   

10. Click Finish.

11. On the next page, click Deploy.

12. On the OC4J_BI_Forms detail page that displays, you should now see your application (MyReportApp) listed under Deployed Applications.

13. Click your application name (MyReportApp).

14. On the Application page, under Properties, click General.

15. Under Library Paths, click Add Another Row, then add the following path to the rwrun.jar library:

    ORACLE_HOME\reports\jlib\rwrun.jar
    

16. Add another row with the following path to the zrclient.jar library:

    ORACLE_HOME\jlib\zrclient.jar
    

17. Click Apply, then click OK.

18. Click Stop, then Start to restart your application so that the new library paths take effect.

13.3.3.2.2 Deploying the J2EE Application in a New OC4J Instance

1. Make sure you've created the J2EE application as described in Creating a New J2EE Application.

2. In Oracle Enterprise Manager, display the detail page for your middle tier.

3. Click Create OC4J Instance.

4. Type the name of your OC4J instance.

5. Click Create.

6. On the confirmation page, click OK.

7. On Application Server page, under System Components, you should now see the new OC4J instance.

   Now, you must manually configure the OC4J to support connection to a Reports Server and the security integration.

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

   • java.rmi.server.randomIDs

   • oracle.display

   • oracle.path

   • org.omg.CORBA.ORBClass

   • org.omg.CORBA.ORBSingletonClass

9. In the opmn.xml file in your ORACLE_HOME, add the PATH and DISPLAY properties to your new OC4J instance:
   1. In ORACLE_HOME/opmn/conf/opmn.xml, find the XML element that describes your new OC4J instance:

      <oc4j instanceName="<your application>" gid="<your application>">
            <config-file path="D:\oracle\Ora9iasR2App\j2ee\<your 
      application>\config\server.xml"/>
            <oc4j-option value="-properties"/>
            <port ajp="3001-3100" rmi="3101-3200" jms="3201-3300"/>
          </oc4j>
      
      

   2. Add the PATH and DISPLAY properties by copying them from the OC4J_BI_FORMS instance in the same opmn.xml file, for example:

          <oc4j instanceName="<your application>" gid="<your application>">
            <config-file path="D:\oracle\Ora9iasR2App\j2ee\<your 
      application>\config\server.xml"/>
            <oc4j-option value="-properties"/>
            <port ajp="3001-3100" rmi="3101-3200" jms="3201-3300"/>
            <environment> <!-- entry to copy from the other instan -->
              <prop name="PATH" value="values are dependant of the system"/>
              <prop name="DISPLAY" value="localhost:0"/>
            </environment>
          </oc4j>
      
      

   3. Restart the 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 the above location.

• Recreate the WAR file with the modified JSP-based Web report, then redeploy the application. For more information, refer to Creating a New J2EE Application.

For more information on running a report from a browser, refer to 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 Specifying a Report Request from a Web Browser.

13.3.6 Running with the WE8MSWIN1252 character set on Solaris

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/guicommon9/tk90/admin/ directory.

Note: This mapping is required for Reports Builder, Reports Converter in non-batch mode (batch=no), Reports Server / Reports Runtime with REPORTS_DEFAULT_DISPLAY=NO. Reports Server / Reports Runtime uses REPORTS_DEFAULT_DISPLAY to determine the fonts needed.

Example1:

Tk2Motif*fontMapCs: ISO8859-1=WE8MSWIN1252 (if there are ISO8859-1 fonts installed on the system.)

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.

See Also: Registering a Reports Server Registering a Report Registering a Printer Creating an Availability Calendar For more information on registering required components with OracleAS Portal before proceeding.

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 by setting the NLS_LANG explicitly in report.sh. You can also use the new environment switching functionality to dynamically set the environment for reports. Refer to Dynamic Environment Switching, for more information.

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 as an item link^{Foot 1} or as a portlet^{Foot 2} to a page and optionally customize it. This step makes the report available to users on a page and enables the page designer to set the report parameters and schedule it to run automatically.

13.4.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 OracleAS Portal online help.

Note: The provider that contains your reports must be a database provider and must have the Expose as Provider setting selected on its Access page.

13.4.2 Creating the Report Definition File Access

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

Note: If you need to create report definition file access for a number of reports, it may be more efficient to batch register them. For more information, see Batch Registering Reports in OracleAS Portal.

1. If you are not already on the Builder page, click Builder at the top of the page.

2. Click the Administer tab.

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

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

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

6. Click the Access tab.

7. Click Publish to Portal.

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

13.4.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. If you are not already on the Builder page, click Builder at the top of the page.

2. Click the Build tab.

3. In the Page Groups portlet, choose the name of the page group in which you want to place your report portlet.

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

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

   See Also: Adding the Reports Component as an Item to a Page for information on how to add the Oracle Reports item to a page.

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

13. You can control the size of the portlet by specifying the Portlet Width and Portlet Height parameters on the Customize page for the Reports Definition File object. The value of these parameters may be a percentage (%) or a number of pixels.

    For example, you can enter:

    Portlet Width: 90%

    Portlet Height: 480

    If no value is specified, Oracle Application Server Reports Services uses its default value (640 pixels wide and 320 pixels high).

    If the Portlet Width and Portlet Height fields are visible to users, then they can also adjust each portlet's width and height via Customize. The user's value will override the value set in the Customize page of the Reports Definition File Object component.

14. You can choose whether to make a report's parameters visible to users through the Customization page of a Reports Definition File Access component.

    To make a report's parameters visible to users:

    1. Click Customize at the bottom of the Manage Component page for the report.

    2. Click Visible to user for each parameter you want to expose.

       Note: You can also set the default value of the parameter from this page.

    The value from the Manage Component page will always be used as the default value in the Customize page for the portlet. If the parameter you are exposing has a corresponding OracleAS Portal page parameter, and you leave the parameter value empty in the Customize page, the portlet inherits the page parameter's value. If the user enters a value for the report portlet's parameter, that value will override the page parameter value.

    Note: Running reports from within OracleAS Portal requires the HTML iframe tag, which is not supported in Netscape 4.x. As a result, the following limitations apply when using Netscape 4.x: A report portlet cannot display in place if you are using HTTPS or if it is not a JSP report. You need to click on the portlet title to see the report in a separate browser window. A report portlet cannot be scheduled to run via the Customize link if you are using HTTPS.

13.4.4 Adding the Reports Component as an Item to a Page

You can add an Oracle Reports component to a page as an item link using the Oracle Reports item type.

Note: This item type must be included from the hidden list of item types and can be configured only if you are the page group administrator.

1. If you are not already on the Builder page, click Builder at the top of the page.

2. Click the Build tab.

3. In the Page Groups portlet, choose the name of the page group in which you want to place your report item link.

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

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

6. If you are editing an existing page, skip to the next step.

7. Click the Add Item link. The Oracle Reports item type is available as a hidden item type. To include it as an available item type, click the configure the list of available item types link.

8. Select Oracle Reports in the Hidden Item Types list and click the > link to move it to the Visible Item Types list. Alternatively, you can click the >> link to move the entire Hidden Item Types list to the Visible Item Types list.

9. Click OK.

10. Select the Oracle Reports item type in the Content Item Types menu and click Next. The Add Oracle Reports page displays.

11. Enter a Display Name that users of your portal will view when clicking your report.

12. Select from the available default Oracle Reports components.

13. Select Display Parameter Form if you have require any user inputs before your report is displayed.

14. Select Link That Displays Item In New Browser Window to ensure that the report is viewed in a separate page.

15. Click Finish. The Oracle Reports item now displays as a link in your page.

16. Click the link to run the report and provide any parameters required, if Display Parameter Form is selected.

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 options, then refer to Command Line Options for a list of valid rwclient command line options.

• 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 (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 Configuring OracleAS Reports Services.

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=urlEngine+urlPa
rameter="http://www.oracle.com"+destype=mail+desname=[e-mail]+desformat=htmlc
ss

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=c
ache+urlParameter="http%3A%2F%2Flocalhost%2Ffoo.jsp%3Fuserid%3Dscott%2Ftiger@ora
DB%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 a stand alone 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 (e.g., 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 (e.g., Oracle JDeveloper) and add a button that invokes OracleAS Reports Services to generate the PDF file.

See Also: Using the Oracle Reports Web Service For more information on the Oracle Reports Web service and installing and using the sample proxy and Java client.

13.8 Scheduling Reports to Run Automatically

You can use the server to run reports automatically from Reports Queue Manager, OracleAS Portal, or with the SCHEDULE command line option. 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 reports to specified pages. Refer to OracleAS Portal online help for more information.

The SCHEDULE keyword is available for use with the rwclient, rwservlet, and rwcgi commands. See Command Line Options, SCHEDULE for more information.

13.9 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.10 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 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 Reports Server will try to find a job in the Finished Jobs Queue which was successfully completed within n minutes. If Reports Server can find such a job, then the new job request "A" will return the output of job "B".

  Note: Refer to Command Line Options for more information about the TOLERANCE command line option.

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

  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.10.1 Usage Notes

• You can set the cache size through Reports Queue Manager or via 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 Configuring OracleAS Reports Services.

13.11 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: You'll find more information about the cmdkey keyword in Command Line Options.

13.11.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 Reports-Related Environment Variables for more information.

13.11.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 options follow the syntax rules of rwclient. See Command Line Options for more information.

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

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

13.11.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 Notes

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

13.11.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 Notes

• 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 one 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.

---

¹ An individual piece of content (text, hyperlink, image, etc.) that resides on a page in
an item region.

² A reusable, pluggable Web component that typically displays portions of Web
content.