IBM Cognos 8 SDK 入门2

xiaoerp

6 内容库布局和搜索路径

IBM Cognos 8 SDK 使用的所有对象都以类似于嵌套文件夹和文件的分层结构保存在内容库中。要访问这些对象，用户需要熟悉内容库的布局。您可以在《IBM Cognos 8 SDK 开发人员指南》“管理内容”一章的“内容库结构”一节中找到内容库的布局。

内容库的布局定义了搜索路径。搜索路径是开发 IBM Cognos 8 SDK 应用程序过程中的一个关键组件，因为它的作用是识别要检索的内容库对象。《IBM Cognos 8 SDK 开发人员指南》在附录“搜索路径语法”中提供了关于搜索路径的详细信息，包括如何使用 IBM Cognos 8 Connection 获取到各对象的搜索路径。在本节中，我们在一个简短的表格中也提供了一些搜索路径示例。在这个表格中，请格外注意“—”、“/”（单斜杠）、“//”（双斜杠）和“//*”（双斜杠加星号）的含义。

• "—"（单代字号）是搜索路径的快捷方式，它代表 IBM Cognos 8 SDK 应用程序用于进行身份验证的用户的 Account 对象。本文档将在稍后详细信息讨论关于 IBM Cognos 8 SDK 应用程序登录的信息。
• “/”（单斜杠）在搜索路径中表示从当前位置返回指定类型的“直接子类型”。
• “//”（双斜杠）在搜索路径中表示从当前位置“返回全部指定类型”
• “//*”（双斜杠加星号）在搜索路径中表示从当前位置“返回任意类型”
  

搜索路径类似于 XPath 语句，关于此主题的详细信息请参阅《IBM Cognos 8 SDK 开发人员指南》的附录 G。如果不熟悉 XPath，请了解基本概念并阅读入门教程：http://www.w3schools.com/xpath。使用 IBM Cognos 8 SDK 不需要精通 XPath，但值得说明的是，使用 XPath 解析和处理任何 XML 文档都可极大简化开发任务，因为它可以减少应用程序的代码量。

除了在开发 IBM Cognos 8 SDK 应用程序中的作用之外，搜索路径还可以用作其他非 SDK 用途，比如：

• 通过 URL 独立于 IBM Cognos 8 Connection 运行报表
• 在批量分发报表时引用用户帐户和目录清单
  

在 IBM Cognos 8 的内容库层次结构中，7 个顶层文件夹分别是：

• adminFolder
• capability
• configuration
• content
• directory
• portal
• tra nsientStateFol der
  

IBM Cognos 8 SDK 应用程序的 content 和 directory 顶级目录使用最为广泛。特别是以下子文件夹。

• /content/package 包含依照特定包创建的所有报表和报表视图。
• /directory/namespace 包含各种外部安全信息，比如特定名称空间的用户、组和角色。值得重点注意的是，除了内置 Cognos 名称空间之外，包含在其中的信息并不是存储在外部安全提供程序中的实际数据。它是与特定内容库相关联的数据的表示。
  

在内容库布局文档中，一些针对各顶级文件夹的区域中会包含用的搜索路径。顶级文件夹 directory 部分包含 Cognos 名称空间的内置对象的搜索路径。

directory/namespace 下的内容库（包括名称空间）包含不同于其余内容库层次结构的搜索路径。这些对象的搜索路径将使用“CAMID”一词作为开头，它代表 Cognos Access Manager ID。CAMID 是一个完整的搜索路径，这与“~”的方式相同。CAMID 是一种内部表示，并且 IBM Cognos 8 SDK 应用程序不应独立于构成 CAMID 的单独组件。这无法保证 CAMID 的格式或内容在各产品发行版之间保持相同。

7 枚举集

IBM Cognos 8 SDK 的上下文中，可以将枚举集看作一个只读常量列表。作为单独的实体，枚举集中的值并不多。它们的作用是作为标识符，而不需要知道实际内容。枚举集中的值通常用于提供方法的输入，但有时也可用于确定输出类型。

枚举集中的实体采用以下格式指定：

enumSetName.enumMemberName

例如：

• 要在 propEnum 枚举集中指定 defaultName 成员，请使用 propEnum.defaultName。
• 要在 classEnum 枚举集中指定 account 成员，请使用 classEnum.account。
  

IBM Cognos 8 SDK 提供了超过 80 种枚举集，但目前只需要熟悉其中 7 种，它们包括：

• 常规使用
  • classEnum
    
• 查询内容库
  • propEnum
    
• 运行报表
  • runOptionEnum
  • outputEncapsulationEnum
  • outputFormatEnum
  • asynchReplyStatusEnum
  • asynchDetailReportStatusEnum
    
  
  

要获取枚举集的完整列表，请参阅《IBM Cognos 8 SDK 开发人员指南》的“枚举集”一章。

在下一节中，您可以看到 classEnum 和 propEnum 还可用于确定组成 IBM Cognos 8 SDK 的各种类的作用。

8 所有类

IBM Cognos 8 SDK 由大约 500 个类组成。《IBM Cognos 8 SDK 开发人员指南》在“类”这一章中详细介绍了各个类。

IBM Cognos 8 类可以分为两组：

• 表示内容库对象的类
• 实现内容库对象属性的类
  

8.1 表示内容库对象的类

表示内容库对象的类与 IBM Cognos 8 SDK 应用程序关系最为密切。内容库布局中也提供了相同的类。classEnum 枚举集中也定义了它们。

除了 classEnum 中列出的类之外，还有其他一些类可用于为其他类定义公共属性。这些类被称作抽象类。IBM Cognos 8 SDK 提供了一些抽象类，但目前最重要的包括：

• baseClass — 定义适用于 classEnum a 中所有类和上述类的属性。
• uiClass — 定义可通过 IBM Cognos 8 Connection 操作的属性。classEnum 中列出的许多类都继承自这个类。
• baseReport — 继承自 uiClass.。 包含运行和管理报表的公共属性。
• authoredReport. — 继承自 baseReport。包含特定于某个报表的属性。seport specification 是该类的一个属性。
  

术语 object 和 class 经常可以互换使用。在本文档中，术语 class 用作定义，而术语 object 用于表示该定义的物理实例。例如，术语report object 表示 report 类的实际内容库对象。可以通过搜索路径来访问 object 。

8.2 实现内容库对象属性的类

《IBM Cognos 8 SDK 开发人员指南》在“类”这一章中介绍的其余类都用于实现内容库对象的属性。事实上，所有 IBM Cognos 8 SDK 属性都是作为类实现的。IBM Cognos 8 SDK 中并没有“简单”或“本地”数据类型，比如 int、string, 或 boolean。反之，这些数据类型都将通过类来实现。例如：

• booleanProp 类表示本地 boolean 数据类型；
• intProp 类表示本地 intdata 数据类型；
• stringProp 类表示本地 string 数据类型。
  

表示属性的类都可以在 propEnum 枚举集中找到。共有 300 多个表示属性的类。

9 Cognos 8 服务

IBM Cognos 8 服务是 SDK 应用程序与 IBM Cognos 8 服务器之间的接口。截至 IBM Cognos 8 MR2，总共有15 个实现的服务和 4 个保留的服务。

每个 IBM Cognos 8 服务都由特定的功能性用途定义。例如，ContentManagerService 用于访问和操作内容库，ReportService 的功能用于确保报表正在运行，并且 JobService 将负责运行中的作业。

从内部来讲，IBM Cognos 8 服务可以调用另一个 IBM Cognos 8 服务来执行部分任务。例如，如果某个作业包含一个要运行的报表，则 JobService 将调用 ReportService 来运行该报表。

每个 IBM Cognos 8 服务都有相关联的方法，并且每个方法都是方法集的一部分。多个服务可以包含相同的方法。例如，ReportService 和 JobService 都包含 run() 方法。ReportService 将运行报表，而 JobService 将运行作业。

本文档的其余部分将专注于以下两个服务：

• ContentManagerService
• ReportService
  

这两个服务是在典型 IBM Cognos 8 安装中使用最为广泛的服务，SDK 应用程序可使用它们进行登录和注销，以及查询内容库和运行报表。熟悉它们之后，使用 JobService 等其他服务就应该会比较得心应手了。

目前需要特别提到的一个 IBM Cognos 8 服务是 CognosReportNetService。该服务作为 SDK 应用程序的兼容性模式提供，最初是为 IBM Cognos ReportNet 编写的，并且不应用于开发新的 IBM Cognos 8 SDK 应用程序。

要了解 IBM Cognos 8 服务、各服务可用的方法以及如何创建和连接 IBM Cognos 8 服务，请参阅《IBM Cognos 8 SDK 开发人员指南》的“服务”一章。

10 登录和注销

当 SDK 应用程序创建代表 IBM Cognos 8 服务的对象时，该服务会使用在创建对象时指定的 URL 自动连接到 IBM Cognos 8 服务。创建和连接 IBM Cognos 8 服务的过程是相同的，而与所使用的服务无关。

除非允许 Anonymous 访问，否则当 IBM Cognos 8 SDK 应用程序连接到 IBM Cognos 8 服务器时，应用程序将不具备隐式权限或访问许可。IBM Cognos 8 SDK 应用程序需要像交互式用户那样登录。如果允许匿名访问，则 IBM Cognos 8 SDK 应用程序将具备与 Cognos 名称空间中的 Anonymous 用户相同的权限和许可。例如，如果不允许匿名访问，并且 IBM Cognos 8 SDK 应用程序并未登录，则当 SDK 应用程序尝试执行查询内容库或运行报表这样的操作时就会出现异常。

所有登录和注销都是通过 ContentManagerService 使用 logon ( ) 和 logoff ( ) 方法来执行的。任何其他 IBM Cognos 8 服务都不能执行登录或注销操作。

10.1 登录

ContentManagerService 的 logon ( ) 方法接受两个参数，即 credentials 和 roles。

credentials 参数是一个经过编码的 XML 字符串，其格式请参见《IBM Cognos 8 SDK 开发人员指南》的“类”这一章中对 credentials类的描述。

credentials 参数的 XML 格式如下所示：

<credential>        <namespace>                namespace ID as specified in Cognos Configuration        </namespace> <username>                username contained in namespace        </username> <password>                password for username        </password> </credential>

roles 参数用于指定到 Cognos 名称空间中的 role 对象的搜索路径。这些 role 对象的权限将应用于在凭证中指定的用户。如果不需要其他角色，则该参数必须为一个空的数组，而不能是 null。

10.2 在服务之间共享 CAM passport

如果登录成功，则 ContentManagerService 将成为经过验证的服务，并会发回一个字符串（称作CAM Passport）给 BiBusHeader中的 SDK 应用程序。当 SDK 应用程序创建代表 IBM Cognos 8 服务的对象时，该对象将包含一个 BIBusHeader 属性。BIBusHeader 表示用于与 IBM Cognos 8 服务器通信的 SOAP 报头。BIBusHeader 中包含一个 CAM 属性，而该属性又包含一个CAMPassport 属性。logon ( ) 方法返回的 CAM Passport 将存储在 CAMPassport 属性中。

CAM Passport 为何如此重要？在 SDK 应用程序中，CAM Passport 并不会自动传播给可能会在应用程序中使用的其他服务。由于 ContentManagerService 是唯一可以登录和注销的服务，因此需要能够将 CAM Passport 分配给 SDk 应用程序可能需要的其他服务（比如 ReportService）。为此，只需将 ContentManagerService 的 BIBusHeader 复制到其他服务的 BIBusHeader 中，从而使该服务变为经过验证的服务。

随 IBM Cognos 8 SDK 一同安装的样例展示了如何连接到 IBM Cognos 8 服务，如何使用 ContentManagerService 登录以及如何将 BIBusHeader 从 ContentManagerService 复制到另一个服务。

10.2.1 Java 样例

以下 Java 样例文件展示了如何登录和共享 CAM Passport：

• <install_location>/sdk/java/Common/CRNConnect.java
• <install_location>/sdk/java/Security/Logon.java
  

要连接到 IBM Cognos 8 服务，请参考 CRNConnect.java 中的 connectToCognosServer (String CMURL) 方法。该方法可将所有 IBM Cognos 8 服务连接到同一 URL。

连接到服务之后， Logon.java 文件中的 quickLogon ( ) 方法将展示如何创建 XML 凭证并调用 ContentManagerService 的 logon() 方法。

要复制 BIBusHeader，请参考 CRNConnect.java 中的 getReportService ( ) 方法。详细查看 CRNConnect.java 会发现一些 get____Service ( ) 形式的方法，其中“____”可以填入 IBM Cognos 8 服务名。将 BIBusHeader 从 ContentManagerService 复制到另一个 IBM Cognos 8 服务的过程是相同的，对于任何服务都是如此。

10.2.2 C# 样例

以下 C# 样例文件展示了如何登录和共享 CAMPassport：

• < insta l lOlocation/sd k/csha rp/Sa m pl esCom mon/Sa m pl esConnect.cs
• < insta l lOlocation/sd k/csha rp/Sa m pl esCom mon/Sa m pl esLogon .cs
  

如 SamplesConnect.cs 所示，要连接到 Cognos 8 服务，只需要设置 Cognos 8 服务对象的 Url 属性即可。

连接到 IBM Cognos 8 服务之后，specificUserLogon ( ) 方法展示了如何创建 XML 凭证，并调用 ContentManagerService 的 logon() 方法。

要将 BIBusHeader 从 ContentManagerService 复制到另一个服务，只需要使用“=”操作符即可，如 SamplesConnect.cs 最后实现的 get 方法所示。

10.3 注销

SDK 应用程序使用 ContentManagerService 的 logoff ( ) 方法注销。logoff ( ) 方法没有参数。

调用 logoff ( ) 方法时，IBM Cognos 8 服务器会将 CAM passport 设置为无效。这意味着 SDK 应用程序建立的其他经过验证的 IBM Cognos 8 服务将自动注销。随后在保存的 BIBusHeader 中使用 CAM passport 都会返回错误。

如果 SDK 应用程序未明确注销，则会话将保持为活动状态，直到超时为止。SDK 应用程序应该在处理完成时注销。

10.4 更多信息

有关匿名访问、使用 ContentManagerService 建立会话、登录及注销的示例，请参阅 Cognos 最佳实践文档 KB Docs - Accessing And Manipulating The Content Store With The SDK 中链接的文章。

11 查询内容库

有时，IBM Cognos 8 SDK 应用程序会需要查看一个或多个内容库对象。这可以使用 ContentManagerService 来完成。如前所述，只有 classEnum 枚举集中列出的内容库对象才可以检索，可以使用搜索路径来指定它们。

11.1 ContentManagerService.query () 方法

ContentManagerService 的 query(searchPath, properties, sortBy, options) 用于检索内容库中的对象。由于需要返回多个内容库对象，因此 query() 方法会返回一个内容库对象数组。

query() 方法的参数如下所示：

• searchPath 是一个字符串，其中包含到内容库对象的搜索路径。
• properties 是 prop 枚举集中的值构成的一个数组，用于标识内容库对象返回的属性。
• sortBy 是一个 sort 对象数组，用于确定返回数组的排序方式。本文档不会讨论此参数，不过即使没有使用它，仍然应该提供一个空的 sort 对象。
• options 是一个 queryOptions 对象，用于提供关于如何处理数据的各种选项。本文档不会讨论此参数，不过即使没有使用它，仍然应该提供一个空的 queryOptions 对象。
  

在许多示例代码片段中，您都会看到如下所示的 query() 方法：

query(searchPath, properties, new Sort[] 0, new QueryOptions())

注意，sortBy 和 options 参数都是非 null 值。它们是空的对象实例。如果提供 null 值，则会出现错误（异常）。

我们已经全面介绍了如何从内容库中检索对象。IBM Cognos 8 SDK 应用程序中的大多数代码都涉及处理检索到的内容库对象的属性。

11.2 如何返回内容库对象

query (searchPath, properties, sortBy, options) 方法的返回类型是一个 baseClass 对象数组。但是，这并不意味着数组中实际包含baseClass 对象。数组中实际包含的是您所需的内容库对象。返回数组必须是 baseClass 对象，其原因是程序语言（Java、C#、VB.NET）要求数组的所有成员都是相同的类，而唯一适用于所有内容库的类就是 baseClass。要在返回所需类时访问存放在数组中的内容库对象，必须将对象转换为其实际类。在大多数情况下，所返回的内容库对象的实际类都是已知的，因此可以直接转换它们。

如果所返回的类是未知的，则必须确定对象的类，以便能够正确转换。例如， searchPath 将指定返回所有内容库对象，因为特定folder 对象可以返回report、reportView、folder 和 UR( o对象的组合。要确定所返回对象的类，可以使用两种方法。

第一种方法是使用特定于语言的操作符来执行对象级比较。在 Java 中使用“instanceof”操作符，在 C# 中使用“is”操作符，而在VB.NET 中则应该使用“TypeOf”和“Is”的组合。

第二种方法是比较 baseClass 对象的 objectClass 属性与 ClassEnum 中的成员。例如：

if (baseClassObj.getObjectClass().getValue()== ClassEnum.Report)        {        <code to process a Report object>        }if (baseClassObj.getObjectClass().getValue()== ClassEnum.ReportView)        {        <code to process a ReportView object>        }        if (baseClassObj.getObjectClass().getValue()== ClassEnum.Account)        {        <code to process an Account object>        }

11.3 更多信息

有关从内容库中检索对象的各种示例，请参阅 Cognos 最佳实践 文档：KB Docs - Accessing And Manipulating The Content Store ith The SDK。

12 运行示例报表

本节将侧重讨论使用 Report Studio 创建和保存的报表。但是，需要重点注意，其概念同样适用于使用 Query Studio 创建和保存的报表。两者之间的细微差异概括如下：

• Report Studio 将 report 对象保存在内容库中。
• Query Studio 将 query 对象保存在内容库中。
• report 和 query 对象具有相同的属性集。
  

在讨论 IBM Cognos 8 和报表时，术语 report specification （通常简写为 report spec）较为常用。报表规范就是一个可由 IBM Cognos 8 解析并生成报表的 XML 文档。XML 文档在 IBM Cognos 8 之外没有任何意义。报表规范包含大量信息，并且有时极为复杂。关于报表规范的详细信息不在本文的讨论范围之内，但您可以参阅《IBM Cognos 8 SDK 开发人员指南》的“使用报表规范”和“报表规范参考”两章，了解更多信息。

在 IBM Cognos 8 SDK 应用程序上下文之外，报表和报表规范这两个术语有时可以互换使用。但是，对于 IBM Cognos 8 SDK 来说，这种用法就是不正确的。报表是一个内容库对象，也是枚举集 classEnum 的一个成员。报表规范是一个属性，也是枚举集propEnum 的一个成员。有的人可能已经想到，报表规范就是报表类的属性。

《IBM Cognos 8 SDK 开发人员指南》的第3章的“运行报表”一节提供了关于运行报表的相关信息。

12.1 ReportService.run () 方法

要使用 IBM Cognos 8 SDK 运行报表，需要使用 ReportService 的run (objectPath, parameterValues, options) 方法。该方法将执行之前作为 report 或 reportView 对象的一部分保存到内容库中的 XML 报表规范。objectPath 参数是到 report 或 reportView 对象的搜索路径。当用户单击 IBM Cognos 8 Connection 中的 report 或 reportView 对象时便会涉及此对象。

runSpecification(specification, parameterValues, options) 方法将运行通过 specification 参数传递进来的 XML 报表规范。此方法适合实时创建报表规范而不用保存到内容库中的场景。 Report Studio 和 Query Studio 将调用该方法来运行报表。

parameterValues 和 options 参数对于 run ( ) 和 runSpecification () 方法来说是相同的。这两个参数都必须是实际对象，而与它们是否在使用无关。null 值（或空）会造成错误（异常）。

parameterValues 是一个 ParameterValue 对象数组。在数组中的每个项目都映射到报表中的一个提示（prompt）。提示/参数处理有时非常复杂，这不在本文的讨论范围之内。

options 是一个 option 对象数组。应该注意，option object 本身是一个抽象对象，并且只能用于定义供其他对象继承的属性。可用于运行报表的实际选项的列表包含在枚举集 runOptionEnum 中。

一些最常见的运行选项包括：

• outputFormat — 指定生成的输出类型。有效的输出类型可在枚举集 outputFormatEnum 中指定。
• outputEncapsulation — 指定存储输出的位置。有效的输出封装可在枚举集 outputEncapsulationEnum 中指定。
• prompt — 指定是否生成提示页面，以处理未解析的报表参数。处理提示页面以及从 SDK 应用程序中提交提示值不在本文的讨论范围之内。
• primaryWaitThreshold — 在 asynchronous conversion 开始之前等待报表完成的初始时间，以秒为单位。匿名会话将在下一节中讨论。
• secondaryWaitThreshold — 在匿名会话的过程中，等待状态检查的时间，以秒为单位。
• saveOutput — 指定是否应该将报表输出保存到内容库中。
  

有的人可能已经想到，run ( ) 方法将等待报表完成运行，但要重点指出，它并不会永无止尽地等待。运行选项 primaryWaitThreshold将指定 run ( ) 方法的最长等待时间。默认值为 7 秒。如果经过这段时间之后报表输出仍未就绪，则 run ( ) 方法将完成，并且 IBM Cognos 8 SDK 应用程序将继续处理。run ( ) 后面的其他代码块用于处理长时间运行的报表。这将在下一节介绍匿名会话时讨论。

考虑到完整性， EventManagementService 还包含 runAt (startTime, objectPath, parameterValues, options) 方法。该方法的行为与 run (objectPath, parameterValues, options) 方法相同，唯一的区别是在 startTime 参数中的指定的运行报表的时间，并且输出将保存在内容库中。runAt ( ) 方法不在本文的讨论范围之内。

12.2 匿名会话

报表有时具有极大的动态性，并且其性能和表示经常由外部因素决定。这些因素包括检索的数据量、报表所需的格式化以及维持通信套接字的活动性。每个因素又受到访问环境的用户数量以及环境中的硬件负荷程度的影响。在诸多因素的影响下，要确定运行特定报表所需的时间是不可能的。除此之外，交互式报表和提示等产品特性还会增加生成报表的复杂性。要让 IBM Cognos 8 SDK 应用程序能够在如此复杂的环境中运行报表，使用匿名会话势在必行。

刚开始接触 IBM Cognos 8 SDK 时，匿名会话这个概念可能要比任何其他话题更加令人迷惑，但全面理解匿名会话是生产质量应用程序所不可或缺的。此外还需要注意，匿名会话并不仅仅适用于运行报表。它还适用于实现 run ( ) 方法的所有其他 IBM Cognos 8 服务。

广泛使用匿名会话的一个应用程序示例是 Cognos Viewer。匿名会话中的一些比较可见的方面包括在等待输出时使用的旋转沙漏、提示页面的表示、提示值的提交以及 HTML 报表中的翻页。

《IBM Cognos 8 SDK 开发人员指南》在“运行任务”一章的“理解匿名会话”一节中详细信息讨论了匿名会话。本节将列举一些运行报表的典型匿名会话。

即便没有提示的简单报表也需要一些时间运行。而报表中经常会包含大量数据。如上一节所述，primaryWaitThreshold 用于确定 run ( ) 方法等待报表输出的时间量。如果经过这么长的时间而报表输出仍未就绪，则 IBM Cognos 8 SDK 应用程序必须等待并保持与 IBM Cognos 8 服务器同步，直到输出就绪为止。这将通过使用 ReportService 的 wait() 方法来完成。IBM Cognos 8 SDK 应用程序将保留在 wait() 方法中，直到报表输出就绪或者经过运行选项 secondaryWaitThreshold 中指定的时间量。secondaryWaitThresholdis 的默认值是 30 称。IBM Cognos 8 SDK 应用程序通常会遍历 wait() 方法直到报表输出就绪。

《IBM Cognos 8 SDK 开发人员指南》指明可以将等待阀值设置为 0。这表示没有匿名会话并且 IBM Cognos 8 SDK 应用程序将一直等待直到报表数据返回或出现错误。在生产质量应用程序中，等待不确定的时间通常会造成不利的影响。这种方式非常被动，并且难以应对错误。此外，应用程序通常需要额外的代码来管理其他时间敏感资源，比如通信套接字。使用匿名会话来主动管理报表处理是更加理想的方式。

请将等待阀值设置为 0，或者设置为较高的值以便于进行学习，但强烈建议不要在生产环境中的 IBM Cognos 8 SDK 应用程序上采用这样的设置。所有等待阀值都以秒为单位。

12.3 如何返回报表内容

run ( ) 方法和 wait() 方法都返回一个 asynchReply 对象。asynchReply 对象有多种用途，这将由匿名会话的状态决定。

如果报表尚未完成，则 asynchReply 对象主要用作匿名会话中的状态跟踪符，并且将由 wait() 方法进行更新。

如果报表已经完成，则 asynchReply 对象的 details 属性将包含一个 asynchDetailReportOutput 对象。根据运行选项的设置，asynchDetailReportOutput 对象将包含实际的报表输出或输出在内容库中的存储位置的搜索路径。

运行选项 saveOutput、outputFormat 和 outputEncapsulation 是确定报表输出存储位置以及 IBM Cognos 8 SDK 应用程序是否需要访问此输出的主要因素。

如果运行选项 saveOutput 为真，则

• 运行选项 outputEncapuslation 将被忽略。
• 可以指定一种或多种输出格式。
• 报表输出将作为 reportVersion 对象的一部分保存到内容库中。
• reportVersion 对象将使用时间戳命名，并且将成为已运行的 report对象的子对象。
• 此 reportVersion 对象将包含一个或多个子 output 对象。根据outputFormat 运行选项中指定的每种输出格式，分别创建一个output 对象。
• 可以通过 asynchDetailReportOutput 的 getOutputObjects() 方法来获取 output 对象列表。
  

注意，runSpecif icat ion ( ) 方法可能未保存输出，因为内容库中没有相应的 eport 对象在其中的 reportVersion 对象中保存输出。

如果运行选项 saveOutputis 为假，则

• 如果指定了多种输出，则会生成一个错误（异常）并且报表将不会运行。
• 报表输出将根据运行选项 outputEncapsulation 的值存储。
  • OutputEncapsulationEnum.none
    • 输出将在 asynchDetailReportOutput 对象中返回，并且可以通过 getOutputPages() 方法访问。
      
  • OutputEncapsulationEnum.URL
    • asynchDetailReportOutput 对象的 getOutputPages() 方法将包含一个指向报表输出的 URL。
    • 此外，asynchDetailReportOutput 对象的 getOutputObjects() 方法将包含一个保存报表输出的临时内容库对象的完整搜索路径。
      
  • OutputEncapsulationEnum.URLQueryString
    • asynchDetailReportOutput 对象的 getOutputPages() 方法将仅包含 URL 的查询字符串。URL 查询字符串通常紧跟在“?”后面，这在 URL 的路径部分中较为常见。
    • 此外，asynchDetailReportOutput 对象的 getOutputObjects() 方法将包含保存报表输出的临时内容库对象的完整搜索路径。
      
  • OutputEncapsulationEnum.HTML
    • 可以通过 asynchDetailReportOutput 对象的 getOutputPages() 方法来访问 HTML 输出，然后将返回实际报表输出。如果输出格式不是 HTML，则引用其报表输出的 HTML 页面将被返回。
      
    
    
  
  

从此列表中可以看出，指定除“none”之外的任何 outputEncapsulation 值都会造成报表输出存储在临时内容库对象中。如果所运行的报表非常大，则不存储报表输出会造成 IBM Cognos 8 SDK 应用程序在尝试一次检索所有报表输出时出现内存不足的问题。如果报表输出存储在内容库中，则可以以较小的块为单位来查询内容库对象和检索输出。

12.4 更多信息

本节将提供运行报表和检索输出方面的基本知识。有关运行报表的各种示例，请参阅 Cognos 最佳实践 文档：KB Docs - Reporting Using The SDK。

13 结束语

本文档中的信息提供了关于 IBM Cognos 8 SDK 的基本知识。掌握这些基本知识之后，您可以尽情查阅整个 IBM Cognos 8 SDK 文档库，并利用其他 IBM Cognos 8 服务来构建健壮的 SDK 应用程序。

该贴已经同步到 xiaoerp的微博