Oracle® Application Server Reports Services Publishing Reports to the Web
10g (9.0.4) Part Number B13673-01 |
|
![]() |
![]() |
This chapter discusses various ways to send report requests to the Reports Server. It includes the following sections:
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.
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: You can also supply these parameters within the JSP file itself. |
Note: If you shutdown or disable Web Cache and you run a report throughrwservlet to a browser with pagestreaming , the resulting report output will not display correctly. This is expected behavior as the port and listener property in httpd.conf (Oracle HTTP Server configuration file) are not referring to the same port.
If WebCache is to be bypassed / shutdown / disabled for requests to Oracle Reports, then the value for |
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.
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
There are a number of request methods available to you for running your report requests. These include:
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.
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.
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.
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).
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. |
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 . |
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.
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.
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.
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).
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.
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.
|
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, calledreports_tld.jar . In Oracle Developer Suite, you can find the tag library here:
ORACLE_HOME\reports\j2ee\reports_ids\web\WEB-INF\lib where In Oracle Application Server, you can find the tag library here:
|
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.
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.
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, theweb.xml file is located here:
On Oracle Application Server, the
|
If you are deploying a JSP report that only contains a Web layout, continue to Step 7.
Add the following code to the web.xml
file.
<servlet> <servlet-name>rwservlet</servlet-name> <servlet-class>oracle.reports.rwclient.RWClient</servlet-class> <load-on-startup>yes</load-on-startup> </servlet> <servlet-mapping> <servlet-name>rwservlet</servlet-name> <url-pattern>/rwservlet*</url-pattern> </servlet-mapping>
This new definition will redirect all URLs ending with /rwservlet
to the servlet you’ve defined.
Note: You can change the servlet name and URL. |
Save the web.xml
file.
Create an EAR file from the WAR file. Once these files are compiled, note where they are saved.
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 10g using either an existing OC4J instance or a new OC4J instance.
This section contains the two methods of deploying the J2EE application:
Make sure you’ve created the J2EE application as described in Creating a New J2EE Application.
In Oracle Enterprise Manager 10g, display the detail page for your middle tier.
Under System Components, click OC4J_BI_Forms.
Under Deployed Applications, click Deploy EAR file to deploy the EAR file you created in Creating a New J2EE Application.
On the first page of the Deploy Application wizard, click Next (located at the bottom of the screen).
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.
Under Specify a unique application name for this application, type the name of your application, such as MyReportApp
, then click Next.
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.
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
Click Finish.
On the next page, click Deploy.
On the OC4J_BI_Forms detail page that displays, you should now see your application (MyReportApp
) listed under Deployed Applications.
Click your application name (MyReportApp
).
On the Application page, under Properties, click General.
Under Library Paths, click Add Another Row, then add the following path to the rwrun.jar
library:
ORACLE_HOME\reports\jlib\rwrun.jar
Add another row with the following path to the zrclient.jar
library:
ORACLE_HOME\jlib\zrclient.jar
Click Apply, then click OK.
Click Stop, then Start to restart your application so that the new library paths take effect.
Make sure you’ve created the J2EE application as described in Creating a New J2EE Application.
In Oracle Enterprise Manager, display the detail page for your middle tier.
Click Create OC4J Instance.
Type the name of your OC4J instance.
Click Create.
On the confirmation page, click OK.
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.
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
In the opmn.xml
file in your ORACLE_HOME
, add the PATH
and DISPLAY
properties to your new OC4J instance:
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>
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>
Restart the OC4J instance
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.
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.
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.rg
b 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 withREPORTS_DEFAULT_DISPLAY=NO . Reports Server / Reports Runtime uses REPORTS_DEFAULT_DISPLAY to determine the fonts needed.
|
Tk2Motif*fontMapCs: ISO8859-1=WE8MSWIN1252
(if there are ISO8859-1 fonts installed on the system.)
One of the best ways to publish your report is through the declarative, secure interface of OracleAS Portal.
See Also: 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 initialNLS_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:
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.
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.
Add the report as an item linkFoot 1 or as a portletFoot 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.
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. |
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. |
If you are not already on the Builder page, click Builder at the top of the page.
Click the Administer tab.
In the Oracle Reports Security portlet, click Oracle Reports Security Settings.
In the Reports Definition File Access portlet, click Create Reports Definition File Access.
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.
Click the Access tab.
Click Publish to Portal.
Click Apply. Your report has now been added to the Portlet Repository and you can add it 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.
If you are not already on the Builder page, click Builder at the top of the page.
Click the Build tab.
In the Page Groups portlet, choose the name of the page group in which you want to place your report portlet.
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.
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. |
If you are editing an existing page, skip to the next step.
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. |
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.
Click the name of your report portlet to add it to the Selected Portlets list.
Click OK.
Click Customize in the upper right corner of your report portlet.
Enter parameter values in the Parameter tab and, if desired, schedule the job to run automatically in the Schedule tab.
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.
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:
Click Customize at the bottom of the Manage Component page for the report.
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:
|
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. |
If you are not already on the Builder page, click Builder at the top of the page.
Click the Build tab.
In the Page Groups portlet, choose the name of the page group in which you want to place your report item link.
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.
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.
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.
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.
Click OK.
Select the Oracle Reports item type in the Content Item Types menu and click Next. The Add Oracle Reports page displays.
Enter a Display Name that users of your portal will view when clicking your report.
Select from the available default Oracle Reports components.
Select Display Parameter Form if you have require any user inputs before your report is displayed.
Select Link That Displays Item In New Browser Window to ensure that the report is viewed in a separate page.
Click Finish. The Oracle Reports item now displays as a link in your page.
Click the link to run the report and provide any parameters required, if Display Parameter Form is selected.
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
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.
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+urlParameter="http://www.oracle.com"+destype=mail+desname=foo@bar.com+desformat=htmlcss
Alternatively, a request that specifies a JSP report for urlParameter
would look like the following:
http://your_webserver:portnum/reports/rwservlet?server=ReportsServer+jobType=rwurl+destype=cache+urlParameter="http%3A%2F%2Flocalhost%2Ffoo.jsp%3Fuserid%3Dscott%2Ftiger@oraDB%3Fserver%3DreportsServer"
Note: If the URL has special characters, they must be encoded as per the x-www-form-urlencoded format. |
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 ServiceFor more information on the Oracle Reports Web service and installing and using the sample proxy and Java client. |
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.
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. |
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".
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.
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.
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.
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.
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.
To add key mapping entries to a key map file:
Navigate to the cgicmd.dat
file on the machine that hosts your Reports Server, and open it with a text editor.
You'll find this file in the following directory on both Windows and UNIX:
ORACLE_HOME\reports\server\conf\cgicmd.dat
Add a key mapping entry. For example:
key1: report=your_report.rdf userid=username/password@my_db desformat=html SERVER=server_name.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.
Add or update the hyperlinks on your Web page.
For more information, see Specifying a Report Request from a Web Browser.
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
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.
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 usecmdkey 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
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.