Oracle Application Server Reports Services Publishing Reports to the Web 10g (9.0.4) Part Number B10314-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.
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".
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.
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.
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.
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:
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.
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.
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).
The following table describes which method you can use to deploy your report, depending on the type of report.
Type of Report | Method | Reason for Using |
---|---|---|
Report with paper layout (REP, RDF, XML) |
Method for deploying a report with only a paper layout. |
|
JSP 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 |
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. |
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:
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.
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,( |
web.xml
file.
web.xml
file.
If you are deploying a JSP report that only contains a Web layout, continue to Step 7.
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.
web.xml
file.
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:
MyReportApp
, then click Next.
/MyReportApp
MyReportApp
) listed under Deployed Applications.
MyReportApp
).
rwrun.jar
library:
ORACLE_HOME\reports\jlib\rwrun.jar
zrclient.jar
library:
ORACLE_HOME\jlib\zrclient.jar
Now, you must manually configure the OC4J to support connection to a Reports Server and the security integration.
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
):
opmn.xml
file in your ORACLE_HOME
, add the PATH
and DISPLAY
properties to your new OC4J instance:
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>
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>
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
If you wish you modify your JSP-based Web report at this point, you can either:
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.rgb
is located in the ORACLE_HOME
/guicommon9/tk90/admin
/ directory.
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 initial |
To a expose a report in a portal, you must do the following:
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.
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. |
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.
Adding the Reports Component as an Item to a Page for information on how to add the Oracle Reports item to a page.
See Also:
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.
To make a report's parameters visible to users:
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.
You can add an Oracle Reports component to a page as an item link using the Oracle Reports item type.
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:
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.
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 information on activating the URL engine, refer to Configuring OracleAS Reports Services.
Note:
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=foo@bar.com+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"
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. |
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:
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:
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.
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".
Refer to Command Line Options for more information about the
Note:
TOLERANCE
command line option.
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.
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.
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.
Note:
You'll find more information about the |
Key mapping is enabled when any of these conditions are met:
cgicmd.dat
, is present in the default location: the ORACLE_HOME
\reports\conf\
directory on the Web server machine (on either Windows or UNIX).
rwservlet.properties
) under the KEYMAPFILE
parameter.
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:
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
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.
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
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
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
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.
1
An individual piece of content (text, hyperlink, image, etc.) that resides on a page in
an item region.
2
A reusable, pluggable Web component that typically displays portions of Web
content.
|
Copyright © 2003 Oracle Corporation. All Rights Reserved. |
|