...

Approach To The CRN SDK Proven Practice Product(s): IBM Cognos ReportNet 1.1

by user

on
Category: Documents
4

views

Report

Comments

Transcript

Approach To The CRN SDK Proven Practice Product(s): IBM Cognos ReportNet 1.1
Proven Practice
Approach To The CRN SDK
Product(s): IBM Cognos ReportNet 1.1
Area of Interest: SDK
Approach To The CRN 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 Proprietary Information
Approach To The CRN SDK
3
Contents
1
INTRODUCTION ............................................................................................ 4
1.1 PURPOSE ............................................................................................................4
1.2 APPLICABILITY .....................................................................................................5
1.3 EXCLUSIONS AND EXCEPTIONS ..................................................................................5
2
GET THE RIGHT TOOLS FOR THE JOB ........................................................... 5
3
ABOUT CRN WEB SERVICES.......................................................................... 6
4
DEPLOY A STANDALONE CRN INSTALLATION.............................................. 6
5
GO SALES AND RETAILERS ........................................................................... 7
6
CONTENT STORE LAYOUT AND SEARCH PATHS ........................................... 8
7
ENUMERATION SETS..................................................................................... 9
8
ALL THOSE CLASSES ................................................................................... 10
8.1 CLASSES THAT REPRESENT CONTENT STORE OBJECTS ..................................................... 10
8.2 CLASSES THAT IMPLEMENT PROPERTIES OF CONTENT STORE OBJECTS ................................. 11
9
THE COGNOSREPORTNETPORTTYPE OBJECT ............................................. 11
10 LOGGING ON AND LOGGING OFF ............................................................... 12
11 QUERY THE CONTENT STORE ..................................................................... 13
11.1 .......................................................................................... THE QUERY () METHODS. 13
11.2 ............................................................ HOW A CONTENT STORE OBJECTS ARE RETURNED. 14
11.3 ......................................................................................... FOR MORE INFORMATION. 15
12 RUNNING A REPORT ................................................................................... 15
12.1 ......................................................................................... THE EXECUTE() METHODS. 15
12.2 ..................................................................................... THE REPORT CONVERSATION. 17
12.3 .......................................................... HOW THE CONTENTS OF A REPORT ARE RETURNED. 18
12.4 ......................................................................................... FOR MORE INFORMATION. 19
IBM Cognos Proprietary Information
Approach To The CRN SDK
4
1 Introduction
1.1
Purpose
The IBM Cognos ReportNet SDK (CRN SDK) can be used to create anything
from simple utility applications through to full-scale, highly complex
applications. Indeed, most of the functionality provided through IBM Cognos
8 Connection, can be re-created using the CRN SDK.
The CRN SDK documentation contains over 1300 pages in PDF form. In
addition to the documentation, there are code samples that are installed with
the SDK and more than 100 Knowledge Base and SupportLink articles related
to the CRN SDK. For someone just starting out with the CRN SDK, all of this
information can be overwhelming and finding a place to get started can be
difficult.
The purpose of this document is to provide focus on the knowledge elements
that are essential for almost every CRN SDK application. Once comfortable
with these knowledge elements, it will be much easier to navigate and
pinpoint information in the CRN SDK documentation and to quickly make
sense of the many sample code fragments that are available.
This document will make numerous references to the CRN SDK
documentation but and will not repeat what is in the product documentation
unless the information is required for the purpose of illustration.
The reader of this document is expected to have the following background
•
•
•
•
•
Some experience programming in Java, C# or VB.NET
Completed and configured a single-machine install of CRN
Installed the SDK on the same machine as CRN
Deployed the GO Sales and Retailers samples
An understanding on the functionality available through IBM Cognos 8
Connection.
The topics that will be highlighted in this document are
•
•
•
•
•
•
Content Store Layout and Search Paths
Enumeration Sets
Classes and Properties
The CognosReportNetPortType Object
Logging On And Logging Off
Querying the Content Store
IBM Cognos Proprietary Information
Approach To The CRN SDK
•
5
Running a Report
Topics that will not be covered in this document but will be mentioned here
to alert the reader about what is possible with the CRN SDK are
•
•
•
Adding, deleting, modifying objects in the Content Store
Running complex reports that require prompting or the use of the
report conversation
Scheduling reports
In the CRN SDK documentation set, there are separate manuals for
developing Framework Manager metadata models and developing Custom
Authentication Providers. These are topics that require advanced knowledge
and are outside the scope of this document.
To create applications with the CRN SDK, it is not necessary to be an expert
in creating reports or data modeling. However, it is useful to know the basics
of both reporting and modeling. These basics can be obtained from the
product documentation provide with CRN or from courses offered by Cognos
Software Services
(http://support.cognos.com/en/training/index.html?lid=//Services//Training).
Finally, the IBM Cognos 8 SDK will not be covered in this document. While
much of the material in this document does apply, there are enough
differences between the CRN SDK and the IBM Cognos 8 SDK that a
standalone document for the IBM Cognos 8 SDK is warranted.
1.2
Applicability
This document applies to the IBM Cognos ReportNet 1.1 SDK
1.3
Exclusions and Exceptions
None at this time
2 Get the Right Tools for the Job
Before beginning, it is strongly recommended that an IDE (Integrated
Development Environment) be obtained for the preferred programming
language. An IDE offers many things but such features as context sensitive
help, build and debugging facilities, real-time syntax checking and code
coloring are amongst the most useful.
IBM Cognos Proprietary Information
Approach To The CRN SDK
6
If the intent is to write CRN SDK applications in Java, the Eclipse or NetBeans
IDEs are the most widely used and both of them are free. However, there are
other Java IDEs available and Cognos does not endorse one IDE over
another.
The .NET Languages (C# and VB.NET) use Microsoft’s Visual Studio (VS) as
the IDE. As of January 2006, VS 2005 was the latest release and either the
“Standard” or “Professional” editions can be used.
If the intent is to use Visual Basic 6 as the development language, it is
strongly recommended that this be reconsidered and VB.NET be used
instead. The languages are not significantly different and the learning curve is
not steep. VB 6 is nearing the end of its product lifecycle and will soon be
considered unsupported by Microsoft.
Once the preferred programming language is chosen, it is important to read
the relevant information contained in the section IBM Cognos ReportNet
Toolkits in Chapter 1 of the CRN SDK Getting Started Guide.
3 About CRN Web Services
IBM Cognos ReportNet is built using an architecture based on Web Services
and the CRN SDK is implemented on top of these Web Services. In practice,
there is no need to be concerned with the nuts and bolts of the IBM Cognos
ReportNet Web Services. It is safe to say that they work as advertised. If
there is interest in what the web services actually look like, there are
numerous tools available that allow SOAP messages to be viewed.
4 Deploy a Standalone CRN Installation
When starting out with the CRN SDK, it is recommended that a standalone,
single machine installation of IBM Cognos ReportNet be used. This will
protect other installations of IBM Cognos ReportNet from potential errors that
are a result of the initial learning curve.
In the standalone IBM Cognos ReportNet installation, it is recommended to
allow unrestricted access to all objects in the Content Store. This is to
eliminate the need to consider access permissions while learning the core
topics. This is not to say that access permissions are not important but their
user and implications can be applied incrementally.
IBM Cognos Proprietary Information
Approach To The CRN SDK
7
Setting up unrestricted access to the Content Store is done by specifying
individual Account or Group objects as members in the built-in System
Administrators role in the Cognos namespace. As will be discussed later, a
CRN SDK application gains access by logging on as a user in the same
manner as an interactive user. If that user that is a member of the built-in
System Administrators role, the CRN SDK application will have full access to
all objects in the Content Store.
A default single machine installation will allow Anonymous access and will
give the Everyone group in the Cognos namespace the permissions of the
built in System Administrators role. The CRN SDK application will not need to
logon as it will be treated as the Anonymous user.
If Anonymous access is not possible or desired then add a user from a
security namespace, which was setup during the installation process, to the
members of the System Administrators role. The CRN SDK application will
need to use this user account to authenticate and logon to CRN.
5 GO Sales and Retailers
It is strongly recommended that the GO Sales and Retailers samples be
installed before using the CRN SDK. The GO Sales and Retailers samples
create a standalone reporting environment and provide the following benefits
for CRN SDK application development
•
•
•
•
•
Populates the Content Store with sample reports with various styles and
complexities
Referred to in the CRN SDK documentation
Used by most code samples
Is a “well-known” reporting environment with which many people are
already familiar
Allows for easier replication of the reporting environment within Cognos
Support should assistance be required.
It is also recommended that some of the GO Sales and Retailers sample
reports be executed through IBM Cognos 8 Connection in order to get some
understanding on what is possible when running and managing reports. As
stated earlier, all of the functionality related to running and managing reports
through IBM Cognos 8 Connection is available through the CRN SDK.
IBM Cognos Proprietary Information
Approach To The CRN SDK
8
6 Content Store Layout and Search Paths
The objects that the CRN SDK works with are contained in the Content Store
under a hierarchical structure similar to nested folders and files. In order to
access these objects, one needs to be familiar with the layout of the Content
Store. You can find the layout of the Content Store is Chapter 2 of the CRN
SDK Developer’s Guide under the section titled Classes and Initial Objects In
The Hierarchy.
The layout of the Content Store identifies the search path. The search path is
a key component in developing CRN SDK applications as it is used to identify
which Content Store object(s) to retrieve. The section titled Querying the
Content Store in Chapter 2 of the CRN SDK Developer’s guide provides a
background on search paths and how to obtain a search path to an individual
object using Cognos Connection. In this section there is also a short table
that contains various search path samples. From this table, pay particular
attention to the meaning of “~”, “/” (single slash), “//” (double slash)
and”//*” (double slash and asterisk).
•
•
•
•
A “~” (single tilde) is a specific search path used to represent the Account
object of the user that the CRN SDK application is logged in as. More
information on logging in a CRN SDK application is covered later in this
document.
A “/” (single slash) in the search path means “return direct children” of
the specified type from the current location.
A “//” (double slash) in the search means “return everything of the
specified type” from the current location
A “//*” (double slash and asterisk) in the search path means “return
everything of any type” from the current location
A search path is similar to an XPath statement and the details can be found in
Appendix G of the CRN SDK Developer’s Guide. If you are not familiar with
XPath, it is useful to know the basics and you can find an introductory tutorial
at http://www.w3schools.com/xpath. There is no need to be an expert in
XPath to use the CRN SDK but it is worth pointing out that using XPath to
parse and process an XML document can eliminate the need for substantial
chunks of code.
In addition to their role in developing CRN SDK applications, search paths are
also used for other non-SDK purposes such as
•
•
Running a report via URL, independent of IBM Cognos 8 Connection
Referencing user accounts and directory listings when bursting reports
There are 6 top level folders in the Content Store hierarchy. They are
•
•
capability
configuration
IBM Cognos Proprietary Information
Approach To The CRN SDK
•
•
•
•
9
content
directory
exportDeploymentFolder
importDeploymentFolder.
The most widely used top level folders of a CRN SDK application will be
content and directory. In particular, the following sub-folders
•
•
/content/package will contain all of the reports and report views created
against a particular package.
/directory/namespace will contain the external security information such
as users, groups and roles for a particular namespace. It is important to
note that with the exception of the built-in Cognos namespace, the
information contained here not the actual data stored in the external
security provider. It is a representation of the data that is specific to the
Content Store.
In the documentation for the Content Store layout, there are sections for
each top level folder that contain useful search paths. The section for the top
level folder directory contains search paths for the built-in objects of the
Cognos namespace.
Content Store objects under /directory/namespace (including namespace)
have a search path that is different that the rest of the Content Store
hierarchy. These objects will all have a search path that begins with the word
“CAMID”, which stands for Cognos Access Manager ID. A CAMID is a
complete search path in the same manner as “~”. A CAMID is an internal
representation and a CRN SDK application should not be dependent on the
individual components that make up a CAMID. There is no guarantee that the
format or content of CAMID will remain the same across product releases.
7 Enumeration Sets
In the context of the CRN SDK, an enumeration set can be considered as a
list of read-only constants. As standalone entities, enumeration sets don’t
have much value. Their sole purpose is to act as an identifier without having
to know the actual contents. The values in an enumeration set are typically
used to provide input to a method although there are situations where they
are useful to determine an output type.
An entry in an enumeration set is specified in the form
enumSetName.enumMemberName
For example
•
To specify the defaultName member in the propEnum enumeration set,
use propEnum.defaultName.
IBM Cognos Proprietary Information
Approach To The CRN SDK
•
10
To specify the account member in the classEnum enumeration set, use
classEnum.account.
There are over 40 enumeration sets in the CRN SDK but familiarity with only
6 of then are required at this point. They are,
•
General Use
o classEnum
•
Query The Content Store
o propEnum
•
Running Reports
o runOptionEnum
o outputEncapsulationEnum
o outputFormatEnum
o asynchStatusEnum
In the next section, it will be seen that classEnum and propEnum are also useful
as a reference in identifying the purpose of the many classes that make up the
CRN SDK.
8 All Those Classes
All of the classes that make up the CRN SDK are contained in Appendix B –
Classes of the CRN SDK Developers Guide. There are over 200 classes listed
in this appendix. The ReportNet class list can be categorized into two distinct
groups
•
•
8.1
Classes that represent Content Store objects
Classes that implement properties of Content Store objects
Classes that represent Content Store objects
The classes that represent Content Store objects are the ones that a CRN
SDK application will be concerned with the most. These are the same classes
that are seen in the Content Store layout. They are also defined in the
classEnum enumeration set.
In addition to the classes listed in classEnum, there are several other classes
whose sole purpose is to define common properties for other classes. These
classes are known as abstract classes. There are several abstract classes in
the CRN SDK but at this point the most relevant ones are
•
baseClass – defines properties that apply to every class in classEnum and
the classes listed below.
IBM Cognos Proprietary Information
Approach To The CRN SDK
11
•
uiClass –defines properties that can be manipulated through IBM Cognos
8 Connection. This class is inherited by most of the classes listed in
classEnum but not all of them
•
baseReport – inherits from uiClass. Contains properties common to
running and managing reports
•
authoredReport. – inherits from baseReport. Contains properties that are
specific to a particular report. The report specification is a property of this
class.
The terms object and class are often used interchangeably. In this document,
the term class will be used as a definition and the term object will be used to
represent a physical instance of this definition. For example, the term report
object will refer to an actual Content Store object of class report. An object
can be accessed with a search path.
8.2
Classes that implement properties of Content Store objects
The rest of the classes in Appendix B are classes that implement properties of
Content Store objects. In fact, all CRN SDK properties are implemented as
classes. With the CRN SDK, there is no such thing as a “simple” or “native”
data type such as int, string, or boolean. Instead, these data types are
implemented through the use of classes. For example
•
•
•
the class booleanProp represents a native boolean data type
the class intProp represents a native int data type
the class stringProp represents a native string data type.
The classes the represent properties can be found in the propEnum
enumeration set. There are over 170 classes that represent properties
9 The CognosReportNetPortType Object
The CognosReportNetPortType object is what represents ReportNet in an SDK
application. There needs to be at least one of these objects in order to have
CRN SDK application. See “Example – Connect to ReportNet“ in Chapter 2 of
the CRN SDK Getting Started Guide to see the procedure of creating a
CognosReportNetPortType object.
NOTE : The SDK Getting Started guide states that the SDK application can
connect to a ReportNet gateway or ReportNet dispatcher. If the CRN SDK
application will need to be upgraded to IBM Cognos 8 at some point in the
future, it should be pointed that IBM Cognos 8 SDK applications can only
connect through a dispatcher.
IBM Cognos Proprietary Information
Approach To The CRN SDK
12
Appendix A – Methods of the CRN SDK Developer’s Guide contains the list of
methods that make up the CognosReportNetPortType object. There are over
70 methods available but this document will provide focus on the following 4
methods,
•
•
•
•
logon(credentials, roles)
o used to create an authenticated session with ReportNet
logoff()
o used to delete an authenticated session with ReportNet
query(search, properties, sortBy, options)
o used to extract objects from the Content Store
execute(obj, parameters, options)
o used to run a report that is stored in the Content Store
Note that there are multiple occurrences of some methods. For example,
there are four query() methods and two execute() methods. Methods of the
same name are permitted by the programming languages supported by the
CRN SDK as long as they have a different “signature”. A method’s signature is
defined by both the number of parameters and the data type of each
parameter.
When a CognosReportNetPortType object is created, an anonymous session
is established with ReportNet. If ReportNet has anonymous access is enabled
then further setup is not required. Otherwise the CognosReportNetPortType
object needs to login as a user. Logging on and logging off is discussed in the
next section.
In most circumstances, a CRN SDK application will only utilize one
CognosReportNetPortType object. However, it should be pointed out that
more than one CognosReportNetPortType object can be used. This gives a
CRN SDK application the ability to communicate with more than one
ReportNet installation or have multiple connections to a single ReportNet
installation.
For examples on establishing a CognosReportNetPortType object, refer to any
of the articles linked to in the document Categorized KB Documents Related
to Accessing the Content Store on the Cognos Proven Practices website.
10 Logging On and Logging Off
CRN SDK applications have no implied rights or access permissions. The CRN
SDK application needs to login just as an interactive user would login. For
example, if anonymous access is not allowed and a CRN SDK application does
not login, an error (exception) will occur. Likewise, if anonymous access is
allowed, the CRN SDK application will get the same permissions as the
Anonymous user.
IBM Cognos Proprietary Information
Approach To The CRN SDK
13
Logging on is straightforward using the logon(credentials, roles) method. The
credentials parameter is string of XML whose format is described in Chapter 1
of the CRN SDK Developer’s Guide.
Logging off is performed with the logoff() method. Logging off does not
invalidate the CognosReportNetPortType object.
If an SDK application does not explicitly logoff, the session will remain active
until it is timed out. SDK applications should log out when processing is done.
For examples related to anonymous access, logging on and logging off, refer
to any of the articles linked to in the Cognos Proven Practices document titled
KB Docs - Accessing And Manipulating The Content Store With The SDK.
11 Query the Content Store
A typical CRN SDK application will need to look for a particular Content Store
object or get a list of Content Store objects that are the same type. As
mentioned earlier, the Content Store objects are listed in classEnum and are
retrieved using a search path.
11.1 The query () Methods
To retrieve a ContentStore object, the following method of the
CognosReportNetPortType object is used,
query(search, properties, sortBy, options)
The parameters in the query() method are as follows,
•
search is a string that contains the search path to the Content Store
object.
•
properties is a propEnum array that contains the properties to be returned
with the Content Store object.
•
sortBy is an array of sort objects that determines how the returned array
is sorted. This document will not discuss this parameter but even if it is
not used, an empty sort object must be provided.
•
options is a queryOptions object that provides various options on how the
data is processed. This document will not discuss this parameter but even
if it is not used, an empty queryOptions object must be provided.
In many sample code fragments, you will see the query() method called as
follows,.
IBM Cognos Proprietary Information
Approach To The CRN SDK
14
query(search, properties, new Sort[] {}, new QueryOptions())
Note that the sortBy and options parameters are not null. They are empty
instances of an object. If null values are supplied, an error (exception) will
occur.
11.2 How a Content Store Objects are Returned
The query(search, properties, sortBy, options) method will return an array of
baseClass objects but this does not mean that the array actually holds
baseClass objects. The array will actually hold the Content Store objects in
the class you are expecting. The reason for the returned array is that
programming language (Java, C#, VB.NET) requires that all members of the
array be the same class and the only class that applies to all Content Store
objects is baseClass. To access the Content Store object that is stored in the
array as the class expected to be returned, the object must be cast to its
proper class. In most instances, the actual class of the Content Store object
returned will be known so it can be cast directly.
In cases where the returned class is not known, it may be necessary need to
determine the class of the object in order to cast it properly. For example, a
query that returns all Content Store objects under a specific Folder object
could return a combination of Report, ReportView, Folder and URL objects.
To determine the class of object returned, there are two techniques that can
be used
The first technique is to use a language specific operator that will perform
actual an object level comparison. In Java, the “instanceof” operator is used,
for C# use the “is” operator and for VB.NET use “TypeOf” and “Is”.
The second technique is to compare the value of the “objectClass” property
of a baseClass object against a member in ClassEnum. For example,
if (baseClassObj.getObjectClass().getValue() = = ClassEnum.Report)…
if (baseClassObj.getObjectClass().getValue() = = ClassEnum.ReportView)…
if (baseClassObj.getObjectClass().getValue() = = ClassEnum.Account)…
This is essentially all there is to retrieving an object from the Content Store.
Most of the code in the CRN SDK application will involve processing the
properties of the retrieved Content Store object(s).
IBM Cognos Proprietary Information
Approach To The CRN SDK
15
11.3 For More Information
For numerous examples related to retrieving objects from the content store,
see the Cognos Proven Practices document titled KB Docs - Accessing And
Manipulating The Content Store With The SDK.
12 Running a Report
This section will focus on reports that are created and saved using Report
Studio. However, it is important to realize that the same concepts apply
equally to reports created and saved with Query Studio. There are a few
minor differences between the two as outlined here,
•
•
•
Report Studio saves report objects in the content store.
Query Studio saves query objects in the content store.
report and query objects have the same set of properties
When discussing CRN and reports, the term report specification (often shortened to report spec) will be
used often. A report specification is simply an XML document that can be interpreted by CRN to generate a
report. The XML document has no meaning outside of CRN. A report specification contains a large amount
of information and can be very complex. The details of report specifications are beyond the scope of this
document but can be found in Chapter 5 and Appendix E of the CRN SDK Developer’s Guide.
The terms report and a report specification are sometimes used interchangeably in conversations outside
the context of a CRN SDK application. However, in terms of the CRN SDK this usage is not correct. A
report is a Content Store object and is a member of classEnum. A report specification is a property and is a
member of propEnum. As one might expect, the report specification is a property of the report class.
Chapter 4 of the CRN SDK Developer’s Guide contains information related to running reports.
12.1 The execute() Methods
To run a report using the CRN SDK, one of the execute() methods of the
CognosReportNetPortType object are used to run reports. There are two
execute() methods.
The execute(obj, parameters, options) method will execute an XML report
specification that has been previously saved to the Content Store as a report
or reportView object. The obj parameter is a search path to a report or
reportView object. This is the method that gets invoked when you click on a
report or reportView object in IBM Cognos 8 Connection,
The execute(spec, parameters, options) method will run an XML report
specification which is passed via the spec parameter. It is best used when
report specs are created “on the fly”. This is the method that is invoked by
Report Studio and Query Studio to run a report.
IBM Cognos Proprietary Information
Approach To The CRN SDK
16
The parameters and options parameters are the same for the two execute()
methods. Both of these parameters must be actual objects regardless of
whether they are being used. A value of null (or nothing) will generate an
error (exception).
•
parameters is an array of ParameterValue objects. Each item in the array
maps to a prompt that is contained within the report. The intricacies of
prompt/parameter processing are a topic in and of itself and outside the
scope of this document.
•
options is an array of runOption objects. It should be noted that the
runOption object itself is an abstract object and is only used to define
properties for other objects to inherit. The list of actual names for run
options are contained in runOptionEnum and can be found in Appendix D
of the CRN SDK Developer’s Guide.
Some of the most common run options are,
•
•
•
•
•
•
outputFormat – specifies the type(s) of output to generate. The valid
output types are specified in outputFormatEnum.
outputEncapsulation – specified where the output is stored. The valid
output encapsulations are specified in outputEncapsulationEnum.
prompt – specifies whether or not to prompt.
primaryWaitThreshold – initial time, in seconds, to wait for the report to
finish before a report conversion begins. The report conversation will be
discussed in the next section.
secondaryWaitThreshold – when a report conversation is in progress, the
amount of time, in seconds, to wait between status checks.
saveOutput – specifies if the report output should be saved in the Content
Store
As one might expect, the execute() method will wait for the report to finish
running but it is important to point out it will not wait forever. The run option
primaryWaitThreshold specifies the maximum amount of time spent waiting
in the execute() method. The default value is 7 seconds. If the report output
is not ready after this amount time, the execute() method will complete and
the CRN SDK application will continue on with processing. Additional blocks of
code after the execute() method may be required to handle long running
reports. This will be discussed in the next section on the report conversation.
For the sake of completeness, there is also the executeAt() method. This
method behaves the same as the execute(obj, parameters, options) method
except a time to run the report is specified and the output is stored in the
Content Store. The executeAt() method will not be covered in this document.
IBM Cognos Proprietary Information
Approach To The CRN SDK
17
12.2 The Report Conversation
Reports can be very dynamic in nature and there are often many external
factors that determine the performance and presentation of the report. The
factors include such things as the amount of data being retrieved, the
amount of formatting that needs to be done on the report and keeping
communications sockets active. Each of these factors is also subject to the
number of users accessing the environment and the hardware being used in
the environment. With so many variables it is impossible to know how long it
will take to run any given report. In addition to this, there are also product
features such as interactive reporting and prompting that add to the
complexity of generating a report. In order for a CRN SDK application and
ReportNet to run a report in a complex environment, the report conversation
is used.
The most notable application making extensive use of the report conversation
is Report Viewer. Some of the most visible aspects are the rotating hourglass
that is used while waiting for output, the presentation of prompt pages, the
submitting of prompt values and paging up and down in an HTML report.
The details on the report conversation are contained in Chapter 4, Running
Reports in the CRN SDK Developer’s Guide under the section The Report
Execution Conversation. When first starting out with the CRN SDK, the report
conversation may be more confusing than anything but a thorough
understanding of the report conversation will likely be required for production
quality applications.
Even simple reports that have no prompts may take a long time to run. This
is often the case when large amounts of data are present in the report. As
mentioned above, the primaryWaitThreshold is used to determine the amount
of time the execute() method will wait for report output. If this time expires
and the report output is still not ready, then the CRN SDK application must
wait and remain synchronized with ReportNet until the output is ready. This is
accomplished using the wait() method of the CognosReportNetPortType
object. The CRN SDK application will remain in the wait() method until the
report output is ready or the amount of time specified by the run option
secondaryWaitThreshold has passed. The default value for the
secondaryWaitThreshold is 30 seconds. A CRN SDK application will generally
just loop around the wait() method until the report output is ready. There is
only one call to the execute() method for any given report.
Although this document will not address issues related to prompting, it should
be pointed out that if the report has a prompt, both the execute() and wait()
methods will be considered compete if a prompt page is received. The
getStatus() method of the reportServiceResponse object returns a status flag
that is used to determine, amongst other things, if the output is a prompt
page, the completed report output or if processing is still in progress. When
the values that satisfy the prompt have been submitted, the process of
looping around the wait() method begins again.
IBM Cognos Proprietary Information
Approach To The CRN SDK
18
The CRN SDK Developer’s Guide states that it is possible to set either of the
wait thresholds to 0. This means that there will be no report conversation and
the CRN SDK application will wait until report data is returned or an error
occurred. Waiting an indeterminate time is generally considered to be a bad
technique for production quality applications. This is a passive approach and
is difficult, if not impossible, to react to errors and it usually requires
additional code to manage other time-sensitive resources such as
communications sockets. It is far better to learn about and use the report
conversation to actively manage the processing of the report.
Setting a wait threshold to zero or a high value is acceptable for
learning purposes but is strongly discouraged for CRN SDK
applications operating in a production environment. All wait
thresholds are specified in seconds.
12.3 How the Contents of a Report Are Returned
Both execute() methods return a reportServiceResponse object. A
reportServiceResponse object serves several purposes depending on the state
of the report conversation. At this point, focus will be on whether or not the
report has finished running.
•
If the report is not complete, the reportServiceResponse object is used
primarily as a status tracker in the report conversation. The
reportServiceResponse object will be updated by the wait() method of the
CognosReportNetPortType object.
•
If the report is complete, the reportServiceResponse object will contain
the actual report output or a search path to where the output has been
saved in the Content Store. This is accomplished by calling the
getOutput() method of the CognosReportNetPortType object.
The run options saveOutput, outputFormat and outputEncapsulation are the
main drivers of where report output is stored and how the CRN SDK
application goes about accessing it.
If the run option saveOutput is true,
•
•
•
•
•
The run option outputEncapuslation is ignored.
One or more output formats can be specified.
The report output will be stored in the Content Store as part of a
reportVersion object.
The reportVersion object will be named by a timestamp and will be a child
object of the report object that was run.
This reportVersion object will contain one or more child output objects,
each one corresponding to a specified output format.
IBM Cognos Proprietary Information
Approach To The CRN SDK
•
•
19
The list of output objects is obtained with the getOutputObjects() method
of reportServiceResponse.
The execute() method that uses a report specification as a parameter
cannot have saved output since there is no corresponding report object in
the Content Store that can contain the reportVersion object created to
hold the saved output.
If the run option saveOutput is false,
•
•
If multiple output formats are specified, an error (exception) will be
generated and the report will not be run.
The report output may be stored depending on the value of the run
option outputEncapsulation.
o OutputEncapsulationEnum.none - the output will be returned in
the reportServiceResponse and can be accessed with the
getOutputPages() method.
o OutputEncapsulationEnum.URL - The getOutputPages() method of
a reportServiceResponse will contain a URL that points to the
report output. In addition, the getOutputObjects() method of a
reportServiceResponse will contain a complete search path to a
temporary Content Store object that holds the report output.
o OutputEncapsulationEnum.URLQueryString – The
getOutputPages() method of a reportServiceResponse will contain
only the query portion of a URL. In addition, the
getOutputObjects() method of a reportServiceResponse will
contain a complete search path to a temporary Content Store
object that holds the report output.
o OutputEncapsulationEnum.HTML - the output will be returned in
the reportServiceResponse and can be accessed with the
getOutputPages() method. If the output format was HTML, then
the actual report output will be returned. If the output format was
not HTML, then an HTML page that references the report output
will be returned.
As can be seen from this list, specifying any of the outputEncapsulation
values except “none” will cause the report output to be stored in a temporary
Content Store object. If the report being run is large, not having the report
output stored could cause the CRN SDK application to run out of memory. If
the report output is placed in the Content Store, it is possible to query the
Content Store object and retrieve the output in smaller chunks.
12.4 For More Information
This document should provide a basic foundation for running reports and
retrieving output.
For numerous examples related to running reports, see the Cognos Proven
Practices document titled KB Docs - Reporting Using The SDK.
IBM Cognos Proprietary Information
Fly UP