...

Handling Report Output Using The SDK Proven Practice

by user

on
Category: Documents
3

views

Report

Comments

Transcript

Handling Report Output Using The SDK Proven Practice
Proven Practice
Handling Report Output Using The
SDK
Product(s): IBM Cognos ReportNet®, IBM Cognos 8
Area of Interest: Development
Handling Report Output Using The SDK
2
Copyright
Copyright © 2008 Cognos ULC (formerly Cognos Incorporated). Cognos ULC
is an IBM Company. While every attempt has been made to ensure that the
information in this document is accurate and complete, some typographical
errors or technical inaccuracies may exist. Cognos does not accept
responsibility for any kind of loss resulting from the use of information
contained in this document. This document shows the publication date. The
information contained in this document is subject to change without notice.
Any improvements or changes to the information contained in this document
will be documented in subsequent editions. This document contains
proprietary information of Cognos. All rights are reserved. No part of this
document may be copied, photocopied, reproduced, stored in a retrieval
system, transmitted in any form or by any means, or translated into another
language without the prior written consent of Cognos. Cognos and the
Cognos logo are trademarks of Cognos ULC (formerly Cognos Incorporated)
in the United States and/or other countries. IBM and the IBM logo are
trademarks of International Business Machines Corporation in the United
States, or other countries, or both. All other names are trademarks or
registered trademarks of their respective companies. Information about
Cognos products can be found at www.cognos.com
This document is maintained by the Best Practices, Product and Technology
team. You can send comments, suggestions, and additions to
[email protected] .
IBM Cognos Confidential Information
Handling Report Output Using The SDK
3
Contents
1
INTRODUCTION ............................................................................................ 4
1.1
1.2
1.3
PURPOSE OF THIS DOCUMENT ..................................................................................... 4
TERMINOLOGY ....................................................................................................... 4
EXCLUSIONS AND EXCEPTIONS .................................................................................... 5
2
COMMON USES OF REPORT OUTPUT ............................................................ 5
2.1
2.2
2.3
2.3.1
2.3.2
2.4
COPY OR MOVE REPORT OUTPUT TO REMOTE SERVERS ....................................................... 5
AS INPUT TO 3RD PARTY TOOLS THAT MERGE OR CONVERT REPORT OUTPUT............................. 5
PROVIDE DATA TO BE CONSUMED BY OTHER APPLICATIONS ................................................. 6
Chart images ......................................................................................................6
XML documents...................................................................................................6
UTILITIES ............................................................................................................. 7
3
CONTENT STORE HIERARCHY FOR SAVED REPORT OUTPUT ....................... 8
3.1
3.2
3.3
3.4
THE REPORTVERSION OBJECT ..................................................................................... 9
THE OUTPUT OBJECT .............................................................................................. 12
THE GRAPHIC OBJECT ............................................................................................. 14
THE PAGE OBJECT ................................................................................................. 16
4
SAVING REPORT OUTPUT ........................................................................... 17
5
THE SESSION OBJECT ................................................................................. 19
6
ACCESSING REPORT OUTPUT ..................................................................... 21
7
MORE ABOUT REPORT OUTPUT FORMATS ................................................. 23
7.1
7.2
7.3
7.4
7.5
HTML ............................................................................................................... 23
PDF.................................................................................................................. 23
EXCEL ................................................................................................................ 23
CSV.................................................................................................................. 24
XML ................................................................................................................. 25
8
SUMMARY ................................................................................................... 25
IBM Cognos Confidential Information
Handling Report Output Using The SDK
4
1 Introduction
1.1
Purpose of this document
This document will focus specifically on areas of the SDK that are related to
report output that is saved into the Content Store. This saved output will be
referred to as stored report output.
This document addresses such topics as :
ƒ identifying the classes, options and properties that are specific to
report output
ƒ showing how an SDK application can get report output to be stored in
the Content Store
ƒ showing how an SDK application accesses stored report output
ƒ discuss some of the intricacies of the various output formats
This document assumes the reader has some familiarity with the IBM Cognos
ReportNet (CRN) or IBM Cognos 8 SDK. At a minimum, the reader should
have reviewed and run the samples installed with the SDK. Ideally, the reader
will have written an application or utility that makes use of the SDK.
This document will be more useful if the reader has also,
ƒ completed and configured a single-server installation of CRN
ƒ installed the SDK on the same server as CRN
ƒ installed the GO Sales and Retailers samples
ƒ an understanding on the functionality available through Cognos
Connection
This document applies to both IBM Cognos ReportNet and IBM Cognos 8 SDK
applications. Differences between the two platforms will be noted as required.
The SDK for IBM Cognos ReportNet and IBM Cognos 8 is large and complex.
There are many methods, classes and properties that make up the SDK. In
fact, the IBM Cognos 8 SDK has over 2000 pages of documentation. The
complexity of the SDK is such that much of the functionality provided in IBM
Cognos 8 Connection could be re-implemented with the SDK if there was a
need to do so.
1.2
Terminology
This document will make references to the “query() method”. For CRN, this
refers to the query method of the CognosReportNetPortType object with the
generic signature of query(search, properties, sortBy, options). For Cognos 8,
this refers to the query method of the ContentManagerService object with the
generic signature of query(searchPath, properties, sortBy, options).
IBM Cognos Confidential Information
Handling Report Output Using The SDK
5
This document will also make references to “running a report”. For CRN, this
refers to the execute method of the CognosReportNetPortType object with
the generic signature of execute(obj, parameters, options). For Cognos 8, this
refers to the run method of the ContentManagerService object with a generic
signature of run(searchPath, parameterValues, options).
1.3
Exclusions and Exceptions
None.
2 Common Uses Of Report Output
2.1
Copy or move report output to remote servers
Copying or moving report output to remote servers is a method of report
distribution or report archiving. The SDK could be utilized by the report
distribution/archiving application to perform such tasks as:
ƒ querying the Content Store to obtain a list of available report output
ƒ extracting the specified report output(s) from the Content Store and
copying it to specific network locations. What actually gets copied may
vary depending on the intention of the application and could include:
ƒ the individual report output files
ƒ a “package” of report output where a “package” might be
ƒ a ZIP file containing several report output files
ƒ a single PDF file created from several merged PDF
output files
ƒ updating report objects to signal that an operation acting on the
output has taken place
ƒ deleting report output from the Content Store after the report output
has been distributed or archived
2.2
As input to 3rd party tools that merge or convert report output
Third party tools can be leveraged to perform many operations that do not
fall within the scope of a single report designed within IBM Cognos 8 or IBM
Cognos ReportNet. Some such operations are:
ƒ Combine several PDFs from several locations into a single PDF. Saved
report output from IBM Cognos 8 or IBM Cognos ReportNet may only
be one of many sources for such a merged document. An example of
such a document would be a consolidated monthly presentation
created using PDF’s from various groups such as Sales, Finance,
Marketing and Engineering.
ƒ Converting PDF output to PostScript to:
ƒ generate PDF output for account statements
ƒ merge all the individual account statements into a single PDF
ƒ convert the single PDF to PostScript
IBM Cognos Confidential Information
Handling Report Output Using The SDK
6
supply PostScript to external company for printing, binding and
delivery
Reformat and incorporate saved output into larger publications such
as adding report output inline to a newspaper or journal publication.
ƒ
ƒ
2.3
Provide data to be consumed by other applications
There may be instances where report output is meant to be consumed by
other applications instead of being viewed and analyzed by people. Two
examples of report output that can be consumed directly by another
application are chart images and XML documents.
2.3.1
Chart images
In this instance, CRN/C8 is used as a chart generator. As will be discussed
later, if a report contains a chart and the report output type is HTML, the
chart image is stored independently of the report output. An example of this
would be a web application that gets invoked via URL, such as an <img> tag
in an HTML page. The web application locates the desired chart image in the
Content Store and sends the chart image as the HTTP response. A real-time
chart could be returned by extending the web app to run the report that
contains the chart before returning the chart data
2.3.2
XML documents
In this scenario, CRN/C8 is used as a sophisticated query engine. The XML
output of a list report is effectively a record set. The XML generated from a
list report might look as follows
<?xml version="1.0" encoding="utf-8" ?>
<dataset xmlns="http://developer.cognos.com/schemas/xmldata/1/"
xmlns:xs="http://www.w3.org/2001/XMLSchema-instance">
<!-<dataset
xmlns="http://developer.cognos.com/schemas/xmldata/1/"
xmlns:xs="http://www.w3.org/2001/XMLSchema-instance"
xs:schemaLocation="http://developer.cognos.com/schemas/xmldata/1/
xmldata.xsd"
>
-->
<metadata>
<item name="Product line" type="xs:string" />
<item name="Product type" type="xs:string" />
<item name="Product name" type="xs:string" />
<item name="Revenue" type="xs:decimal" scale="2"
precision="38"/>
</metadata>
<data>
IBM Cognos Confidential Information
Handling Report Output Using The SDK
7
<row>
<value>Golf Equipment</value>
<value>Woods</value>
<value>Lady Hailstorm Steel Woods Set</value>
<value currency="USD">1250946.84</value>
</row>
<row>
<value>Personal Accessories</value>
<value>Knives</value>
<value>Double Edge</value>
<value currency="USD">603263.98</value>
</row>
<row>
<value>Mountaineering Equipment</value>
<value>Climbing Accessories</value>
<value>Granite Pulley</value>
<value currency="USD">440289.36</value>
</row>
(…)
</data>
</dataset>
The <metadata> section contains several <item> elements and each <item>
element describes the names and the data type of each column. The <data>
section contains a number of <row> elements. Each <row> element
represents a record. The <value> elements contained within a <row>
element are in the same order as the <item> elements contained within the
<metadata> section.
2.4
Utilities
There are also numerous special-purpose utilities making use of report output
that could be written using the SDK. Some examples of utility applications
are:
ƒ Calculate number of bytes used by report output
ƒ all report output
ƒ report output by folder
ƒ report output by package
ƒ Count reports by output type
ƒ provides information on how end users are using CRN/C8
ƒ turn off unused report formats at a global level
IBM Cognos Confidential Information
Handling Report Output Using The SDK
ƒ
8
Remove “dated” report output from the Content Store
ƒ keep Content Store clean
ƒ use the timestamp that is used to name report output
3 Content Store Hierarchy For Saved Report Output
When report output is saved, it is always stored in the Content Store. This
section will identify and discuss the applicable Content Store objects, show
the hierarchy of the Content Store objects and illustrate how the hierarchy is
represented in Cognos Connection.
The following Content Store objects are used in storing report output:
ƒ reportVersion
ƒ output
ƒ graphic
ƒ page
ƒ session
The session object will be treated as a special case. The session object can
be used by an SDK application for handling report output in real-time. Using
the session object will be discussed in detail later in this document.
The Content Store hierarchy for report output is as follows. For the purposes
of this discussion, the Content Store objects report, query and reportView are
only considered to be containers for report output.
IBM Cognos Confidential Information
Handling Report Output Using The SDK
9
Not shown in this hierarchy chart are the Content Store objects that contain
report, query and reportView objects. In IBM Cognos 8 Connection, report,
query and reportView objects are represented in IBM Cognos 8 Connection
under packages or folders. The following screen capture shows each of these
type of objects under the folder named Public Folders>Important
Reports.
The entries List 1, Crosstab 1 and Pie Chart are report objects. The entry
Query 1 is a query object and the entry Report View of List 1 is a reportView
object.
3.1
The reportVersion object
A reportVersion object contains all of the information necessary to generate
the rendered report output that is saved into the Content Store. This includes
information such as prompt values and run options. Each reportVersion object
can and often will contain different values and options than other members in
a collection of reportVersion objects.
A reportVersion object also acts as a container for output objects. An output
object is used to hold rendered report output and will be discussed in the
next section.
IBM Cognos Confidential Information
Handling Report Output Using The SDK
10
The Content Store hierarchy shows that there can be more than one
reportVersion object for a particular report. The number of report versions
can be set on a per report basis. To set or view this limit in Cognos
Connection, click the set properties icon
for a report. In the following
image the number of report versions is three.
Note the number of report versions can also be determined by a time period
instead of an absolute number. If a time period is used, there is no limit to
the actual number of reportVersion objects that can exist. When a
reportVersion object becomes older than the time period specified, it will be
automatically deleted.
IBM Cognos Confidential Information
Handling Report Output Using The SDK
11
To see how reportVersion objects are represented in Cognos Connection, click
on the
icon to view the output versions for a report. If the icon does not
exist then there are no stored output files for the report and, by extension,
there are no reportVersion objects for the report.
A screen similar to the following will appear. Click on the dropdown list to see
the report versions for this report.
Note that there are three different report versions for this report. This
number corresponds to the value seen earlier in the properties of the report.
reportVersion objects are created automatically whenever report output is
saved. When a reportVersion object is created, its name is automatically
derived from a timestamp of the form yyyy-mm-ddThh:mm:ss.xxxZ. The form
of the timestamp is a subset of the ISO 8601 format. The time component is
UTC.
Any SDK application that handles report output will need to determine if a
report has any stored report output. This can be accomplished by testing a
report for the existence of reportVersion objects. A search path similar to
/content/folder[@name='Reports']/report[@name='Crosstab']/reportVersion
would be used for the query() method.
IBM Cognos Confidential Information
Handling Report Output Using The SDK
12
Like any other Content Store object, an SDK application will access a
reportVersion object using the query() method. The query() method in the
following Java code fragment will return an array of reportVersion objects
associated with a report. The following code fragment will extract the
searchPath attribute from each reportVersion object and print the value of
the search path to the console.
The printout to the console will look similar to this:
The searchPath attribute of each reportVersion object can be used in a
separate query to retrieve all the output, graphic and page objects associated
to this reportVersion object. If an SDK application is only concerned about
processing the most recent reportVersion object, a search path similar to
/content/folder[@name='Reports']/report[@name='Crosstab']/reportVersion
[last()] can be used. This search path frees an SDK application from having to
implement code that determines the most recent reportVersion object.
3.2
The output object
An output object contains rendered report output in a specific output format.
IBM Cognos Confidential Information
Handling Report Output Using The SDK
13
As can be seen in the Content Store hierarchy, there can be more than one
output object for a particular report version. If more that one output format
was specified, there will be an output object for each output format.
To see how output objects are represented in IBM Cognos 8 Connection, click
on the
icon to view the output versions for a report. As stated in the
previous section, if the icon does not exist then there are no stored output
files for the report.
A screen similar to the following will appear.
IBM Cognos Confidential Information
Handling Report Output Using The SDK
14
In this case, there are 2 output objects contained within the reportVersion
object named May 8, 2006 11:36:22 AM. There is one output object for each
specified output format.
When seeing output objects represented in IBM Cognos 8 Connection, it may
appear that an output object is named using its output format. However, this
is not the case. The name of an output object is derived in the exact same
manner as the reportVersion object. Since timestamps are not meaningful to
a user when differentiating between output objects, the value that is
displayed in IBM Cognos 8 Connection is the value of the format property of
an output object.
output objects are created automatically along with a reportVersion object
whenever report output is saved.
A search path similar to /content/folder[@name=’Important Reports']/report
[@name='List 1']/reportVersion/output will return all the output objects
stored for a report without regard to report versions or output formats.
If there is more than one report version, specify a search path similar to
/content/folder[@name=’Important Reports']/report[@name='List 1']
/reportVersion[@name='2006-05-08T 15:36:22.752Z']/output to get all the
output objects associated to a particular report version.
If there is more than one report version but only the most recent version
needs to be processed, a search path similar to /content/folder[@name=
’Important Reports']/report[@name='List 1']/reportVersion[last()]/output will
return all the output objects associated with the most recent report version.
3.3
The graphic object
A graphic object contains an image of a generated chart. Each chart in a
report is in a separate graphic object and the image is in PNG format.
IBM Cognos Confidential Information
Handling Report Output Using The SDK
15
As can be seen in the Content Store hierarchy, the graphic object is contained
by an output object only and a graphic object only applies to the HTML
output format. There can be more than one graphic object in a report.
A graphic object cannot be viewed in IBM Cognos 8 Connection as a
standalone entity. It is viewed as part of the complete report output.
The name of a graphic object is defined when it is created. The name takes
the form “imgn” where “n” is the occurrence of the chart in the report as it is
being rendered.
The search path /content/folder[@name=’Important Reports']/report[@name
='List 1']/reportVersion/output/graphic will return all the graphic objects
stored for a report without regard to report versions.
If there is more than one report version, specify a search path similar to
/content/folder[@name=’Important Reports']/report[@name='List
1']/reportVersion[@name='2006-05-08T15:36:22.752Z']/output[@name=
'2006-05-08T15:36:24.752Z']/graphic to get all the graphic objects associated
to a particular report version.
If there is more than one report version but only the most recent report
version is to be processed, specify a search path similar to /content/folder
[@name=Important Reports']/report[@name='List 1']/reportVersion[last()]
/output/graphic to get all the graphic objects associated to a particular report
version.
IBM Cognos Confidential Information
Handling Report Output Using The SDK
16
If more than one of HTML, HTMLFragment and XHTML are specified as
output formats, a particular output object can be specified using the output
format as an attribute in the search path. For example, the search path
/content/folder[@name=’Important Reports']/report[@name='List
1']/reportVersion[last()]/output[@format=’HTML’]/graphic will return from
the most recent report version, the graphic object contained by the output
object whose output format is “HTML”. The search path /content/folder
[@name=’Important Reports']/report[@name='List 1']/reportVersion[last()]
/output[@format=’XHTML’]/graphic will return from the most recent report
version, the graphic object contained by the output object whose output
format is “XHTML”.
3.4
The page object
A page object contains data that represents an Excel 2000 worksheet.
As can be seen in the Content Store hierarchy, the page object is contained
by an output object only but it only applies to the Excel 2000 output format.
There can be more than one page object in a report.
A page object cannot be viewed in IBM Cognos 8 Connection as a standalone
entity. It is part of the complete report output.
The name of a page object is defined when it is created. It takes the form of
“an” where “n” is the Excel worksheet number. The output object that
contains these page objects represents the Excel workbook.
The search path /content/folder[@name=Important Reports']/report[@name
IBM Cognos Confidential Information
Handling Report Output Using The SDK
17
='List 1']/reportVersion/output/page will return all the page objects stored for
a report without regard to report versions. If there is more than one report
version, specify a search path similar to /content/folder[@name=Important
Reports']/report[@name='List 1']/reportVersion[@name='2006-0508T15:36:22.752Z']/output/page to get all the page objects associated to a
particular report output version. Note that the output object in this search
path is not named. This is because page objects only apply to the Excel 2000
output format and there can only be one instance of an output format
specifed for any report version.
If there is more than one report version but only the most recent version
needs to be processed, specify a search path similar to /content/folder
[@name=’Important Reports']/report[@name='List 1']/reportVersion[last()]
/output/page.
4 Saving Report Output
An SDK application can have a report’s output saved in one of two ways,
1. runOption.saveOutput == true
ƒ a reportVersion object will be created automatically
ƒ must be true if multiple output formats are specified
ƒ default value for runOption.saveOutput is false
2. runOption.saveAs is set
ƒ will create a reportView object in the Content Store
ƒ default value for runOption.saveAs is empty
Saved report output is always saved into the Content Store.
When a report is run, the report output can be generated in multiple output
formats. Common output formats are
ƒ HTML
ƒ PDF
ƒ singleXLS (Excel 2000 single-sheet)
ƒ XLWA (Excel 2002)
ƒ XLS (Excel 2000)
ƒ XML
ƒ CSV
An SDK application specifies which output formats get generated when the
report is run through the use of runOption.outputFormat. It is possible to
specify more than one output format in a single request to run the report.
The default value for runOption.outputFormat is HTML.
IBM Cognos 8 Connection can be used to save report output and specify
multiple output formats. Click on the Run with options icon
for a report.
IBM Cognos Confidential Information
Handling Report Output Using The SDK
18
On the Run with options screen, click on the Advanced options link. Note that
on the Run with options screen, a single report output format can be saved
by clicking the Save the report button.
The Run with advanced options screen is where multiple output formats can
be specified. There are also more options to save the report output.
IBM Cognos Confidential Information
Handling Report Output Using The SDK
19
In an SDK application, each one of the selected output formats would be an
entry in the runOption.outputFormat array.
If the Save the report button is selected, this will have the same effect as an
SDK application setting runOption.saveOutput to true.
If the Save the report as a report view button is selected, this will have the
same effect as an SDK application setting a value for runOption.saveAs.
As stated earlier in this document, report output is retained in the Content
Store using until explicitly deleted. Automatic deletion will take place based
on the settings seen when discussing the reportVersion object. An SDK
application can delete report output at any time.
5 The session Object
A session object is automatically created when a user or SDK application logs
in. A session object is accessible by SDK applications and can be queried with
a search path of “~~”.A session object can contain an output object meaning
a session object can be used to save report output in the Content Store. Any
report output stored by a session object should be considered temporary
because the output only exists for the duration of the logged in session or
until another report is run. Accessing temporarily saved output is the same as
accessing permanently saved output
To store report output temporarily, an SDK application must do the following,
ƒ ensure runOption.saveOutput to false
IBM Cognos Confidential Information
Handling Report Output Using The SDK
ƒ
ƒ
ƒ
20
the default is false
set runOption.outputEncapsulation != none
ƒ more on this below
specify only one output format
ƒ multiple output formats require a reportVersion object and a
reportVersion object has no relationship to a session object.
When the report is finished running, the session object will contain an output
object. A derived search path to the output object is returned in the report
response when the report is finished running. The search path will look
similar to this,
CAMID(“LDAPu:cn=doug,ou=cp2")/session[@name='101:738f5613-d9d76fe2-5b54-42c3b192458b:2361238954']/output[@name='2006-0424T15:14:47.358Z']
The search path ~~/output will also return any output object contained by a
session object.
The value of runOption.outputEncapsulation helps determine if a report
output gets saved temporarily. Possible values are:
ƒ none
ƒ HTML
ƒ URL
ƒ URLQueryString
The effect of runOption.outputEncapsulation is described in the SDK
Developer’s Guide. For IBM Cognos ReportNet, refer to the outputObjects
property of a reportServiceResponse object. For Cognos 8, refer to the
outputObjects property of an asychDetailReportOutput object
The default value of runOption.outputEncapsulation is none which means
output does not get saved temporarily and the report output is returned in
the response when the report is finished running. No output objects are
available. However, there is a special case that applies only to the HTML and
Excel 2000 output formats where an empty output object may be returned
which will contain page or graphic objects.
If the value of runOption.outputEncapsulation is HTML, URL, URLQueryString
then output objects will be available when the report is finished running. An
SDK application treats an output object contained by a session object in the
same manner as an output object that is contained by a reportVersion object.
Some of the common scenarios that make use of temporary report output
are:
IBM Cognos Confidential Information
Handling Report Output Using The SDK
21
1. If the report being run contains a large amount of data and memory
constraints could mean that the SDK application will be unable to
process the report output in real-time. This is more prevalent where
the SDK application can service multiple requests for report output. If
the report output is stored in the Content Store, an SDK application
can retrieve the stored report output in optimally sized chunks.
Processing stored report output in chunks will be discussed later in
this document. This scenario often applies to an SDK application that
delivers self-contained report output (PDF, XLWA) back to the caller.
2. To serve a real-time generated chart image without the HTML that
goes with the chart image. Recall the earlier example of the web app
that uses CRN/C8 as a chart generator. An SDK application would run
a report specifying an output format of HTML and have the output
stored in temporary storage. The SDK application can the use the
query() method with a search path of ~~/output/graphic to bypass
the HTML and directly access the generated chart image.
6 Accessing Report Output
As seen in previous sections, accessing an output, page or graphic object is
done using the query() method and is no different than accessing any other
Content Store object.
To extract the actual data from an output, page or graphic object, specify
these propEnum values for the query() method
ƒ propEnum.data
ƒ propEnum.dataSize
ƒ propEnum.dataType
ƒ propEnum.format
The data property will contain the report output.
The dataSize property will contain the number of bytes in the report output
The dataType property contains the type of report output. This is the value
that is used in the “Content-Type” field of an HTTP header. More than one
output format can share the same value.
The format property contains a value specified in runOption.outputFormat.
The format property only applies to an output object and is not available for
graphic and page objects.
It is possible that that report output can get very large, into the hundreds or
even thousands of pages. An SDK application that needs to handle large
report output must take into account any memory–related issues when
retrieving report output from the Content Store into memory.
Instead of trying to read the stored report output into memory, it is possible
to read the stored report output in chunks. This is done be adding
queryOptions when calling the query() method on an output, graphic or page
object. The queryOptions to add are:
IBM Cognos Confidential Information
Handling Report Output Using The SDK
ƒ
ƒ
22
queryOptions.maxDataBytes. This specifies how many bytes to read
for this query(). This value is usually only set once.
queryOptions.skipDataBytes. This specifies where to start reading the
data for the next call to the query() method. This value is usually set
to the cumulative number of bytes read in the previous calls to the
query() method.
As with retrieving all of the report output at once, the chunk of output that is
retrieved will be stored in the data property. An SDK application will keep
calling the query() method with updated value for skipDataBytes until there is
no more data. The following code fragment demonstrates how to read stored
report output in chunks.
IBM Cognos Confidential Information
Handling Report Output Using The SDK
23
7 More About Report Output Formats
7.1
HTML
HTML report output is stored as a single page. Individual pages of HTML
output that can be seen with Report Viewer / Cognos Viewer are generated
real-time and are not stored.
HTML report output is not self-contained. Content can reside outside of the
main HTML document. Examples of external content are stylesheets and
image tags that reference chart images stored in graphic objects. HTML
report output contains relative URLs to external content. The use of relative
URLs in HTML report output is deliberate as it is preferable for the browser to
resolve URLs.
Serving HTML report output “as is” is not recommended if the purpose is to
simply render the HTML. In this case, consider using URLs to call Report
Viewer / Cognos Viewer to display the report output. URL options exist to
display only the report data and hide other user interface elements. If Report
Viewer / Cognos Viewer is not used then relative URLs may need to be
rewritten to render the HTML output properly.
7.2
PDF
PDF output is entirely self contained and is unreadable to anything but a PDF
engine. All content, including images, resides within the document. If PDF
output needs to be manipulated then one of the many 3rd party tools
available for this task must be selected.
An SDK application can serve PDF output “as is”. Consider a web application
that allows non-Cognos Connection users to view selected reports. The web
application would perform the following steps,
1. From a browser, the user clicks on a link to the web application.
2. The web application retrieves PDF output from the Content Store.
3. The web application sends the PDF output back to the browser.
4. The browser opens the PDF using Adobe Reader
7.3
Excel
There
ƒ
ƒ
ƒ
are several report output formats for Excel
Excel 2000
Excel 2000 single sheet
Excel 2002
Both Excel 2002 and Excel 2000 single-sheet output are self contained. Excel
2002 data is stored in XLWA (Excel Web Archive) format and Excel 2000
single-sheet output is stored as HTML. Excel has all the functionality to
differentiate the two. In the same manner as PDF output, Excel 2002 and
Excel 2000 single-sheet output formats can be served “as is”.
IBM Cognos Confidential Information
Handling Report Output Using The SDK
24
Excel 2000 output contains links to other page objects. 1 output object that
represents the workbook, one or more page objects that represent the
worksheets. The output object references the page objects. If the SDK
application needs to serve Excel 2000 report output to an external
application, order to serve this format “as is”, the references to the page
objects must be rewritten.
The dataType property contains the type of report output. This is the value
that is used in the “Content-Type” field of an HTTP header. More than one
output format can share the same value.
As stated earlier, the dataType property contains a value that is used in the
“Content-Type” field of an HTTP header and more than one output format
can share the same value. All Excel output formats have the same dataType
property, application/vnd.ms-excel. Since there are three different types of
Excel output, use the format property of the output object to determine the
actual Excel output format.
ƒ Excel 2000 = “XLS”
ƒ Excel 2000 single-sheet = “singleXLS”
ƒ Excel 2002 = “XLWA”
7.4
CSV
CSV output is often considered to be the lowest common denominator. For
CRN, CSV output can be generated for list reports only but in Cognos 8
crosstab reports can also generate CSV output. CSV output generation is very
fast when compared to HTML, PDF or Excel because no formatting or styles
are applied to the output.
Some aspects of how CSV output is generated are determined by the
following global settings:
ƒ RSVP.CSV.ENCODING
ƒ RSVP.CSV.DELIMITER
ƒ RSVP.CSV.QUALIFIER
ƒ RSVP.CSV.TERMINATOR
ƒ RSVP.CSV.MIMETYPE (Cognos 8)
These global settings are described in the Administration and Security Guide.
When processing CSV output, a byte order mark (BOM) occupies the first
bytes of the CSV data. The actual CSV data begins in the byte following the
BOM. The value and length of the BOM is determined by the setting
RSVP.CSV.ENCODING. For more information on byte order marks, see
http://www.unicode.org/faq/utf_bom.html#BOM.
CSV report output is easily consumed by external applications. However, the
external application may need to derive the data types for the columns of a
list report. Also, the columns in list reports may not be in the same order as
they would be in a formatted report as the column order is defined by the
order of the data items in the query specification.
IBM Cognos Confidential Information
Handling Report Output Using The SDK
25
In the same manner as PDF output, CSV output can be served “as is”.
7.5
XML
For CRN, XML output can be generated for list reports only but in Cognos 8
crosstab reports can also generate XML output. XML output generation is very
fast when compared to HTML, PDF or Excel. This is because no formatting or
styles are applied to the output.
Like CSV, XML report output is easily consumed by external apps. The data
types for columns in list reports are specified in the <metadata> element and
the columns in list reports are ordered as they are in a formatted report.
Sometimes the question arises on whether to use XML or CSV output for
external applications. In general, XML should be considered as the first choice
since the XML data types are known and an XML parser can do most, if not
all, of the work involved in parsing the data.
In the same manner as PDF output, XML output can be served “as is”.
8 Summary
This document identified the following Content Store objects that are directly
related to report output:
ƒ reportVersion
ƒ output
ƒ graphic
ƒ page
In order for report output to be stored into the Content Store, the following
runOptions were highlighted:
ƒ outputFormat
ƒ outputEncapsulation
ƒ saveOutput
ƒ saveAs
This document also introduced the following queryOptions that are helpful in
processing large report output:
ƒ maxDataBytes
ƒ skipDataBytes
IBM Cognos Confidential Information
Fly UP