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