®

Course Guide
IBM Cognos Analytics:
Architecture and Logging (v11.0)
Course code B6019 ERC 1.0

IBM Training
 Preface

June 2016
NOTICES
This information was developed for products and services offered in the USA.
IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for
information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to
state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not
infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any
non-IBM product, program, or service. IBM may have patents or pending patent applications covering subject matter described in this document.
The furnishing of this document does not grant you any license to these patents. You can send license inquiries, in writing, to:
IBM Director of Licensing
IBM Corporation
North Castle Drive, MD-NC119
Armonk, NY 10504-1785
United States of America
The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law:
INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND,
EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT,
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in
certain transactions, therefore, this statement may not apply to you.
This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these
changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the
program(s) described in this publication at any time without notice.
Any references in this information to non-IBM websites are provided for convenience only and do not in any manner serve as an endorsement of
those websites. The materials at those websites are not part of the materials for this IBM product and use of those websites is at your own risk.
IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you. Information
concerning non-IBM products was obtained from the suppliers of those products, their published announcements or other publicly available
sources. IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM
products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products.
This information contains examples of data and reports used in daily business operations. To illustrate them as completely as possible, the
examples include the names of individuals, companies, brands, and products. All of these names are fictitious and any similarity to the names and
addresses used by an actual business enterprise is entirely coincidental.
TRADEMARKS
IBM, the IBM logo, Cognos, DB2, TM1 and ibm.com are trademarks or registered trademarks of International Business Machines Corp., registered
in many jurisdictions worldwide. Other product and service names might be trademarks of IBM or other companies. A current list of IBM trademarks
is available on the web at “Copyright and trademark information” at www.ibm.com/legal/copytrade.shtml.
Adobe, and the Adobe logo are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States, and/or other
countries.
Java and all Java-based trademarks and logos are trademarks or registered trademarks of Oracle and/or its affiliates.
Linux is a registered trademark of Linus Torvalds in the United States, other countries, or both.
Microsoft, Windows, and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both.
UNIX is a registered trademark of The Open Group in the United States and other countries.
© Copyright International Business Machines Corporation 2016.
This document may not be reproduced in whole or in part without the prior written permission of IBM.
US Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

© Copyright IBM Corp. 2010, 2016 P-2

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Preface

Contents
Preface................................................................................................................. P-1
Contents ............................................................................................................. P-3
Course overview............................................................................................... P-11
Verify services used in the course environment................................................ P-12
Document conventions ..................................................................................... P-13
Exercises.......................................................................................................... P-14
Additional training resources ............................................................................ P-15
IBM product help .............................................................................................. P-16
Introduction and Service-Oriented Architecture................................. 1-1
Unit objectives .................................................................................................... 1-3
IBM Cognos Analytics architecture ..................................................................... 1-4
Component definitions ........................................................................................ 1-5
Two languages, two approaches ........................................................................ 1-6
What is Java EE? ............................................................................................... 1-7
Examine IBM Cognos Analytics servlets ............................................................ 1-8
Examine 32-bit vs. 64-bit .................................................................................... 1-9
Examine 64-bit support..................................................................................... 1-10
Examine 64-bit support benefits ....................................................................... 1-11
List core install components ............................................................................. 1-12
List companion installs ..................................................................................... 1-15
Overview of core install components ................................................................ 1-16
Describe gateways ........................................................................................... 1-17
Explore gateway requests ................................................................................ 1-19
Describe the Application Tier install component ............................................... 1-20
Describe IBM Cognos Content Database ......................................................... 1-21
Describe Service-Oriented Architecture (SOA) ................................................. 1-22
Describe SOA assets ....................................................................................... 1-23
Examine SOA in IBM Cognos........................................................................... 1-24
What are IBM Cognos Services?...................................................................... 1-25
Explain SOA communication in IBM Cognos 11 ............................................... 1-26
Examine external IBM Cognos Analytics services ............................................ 1-27
Examine add-on installs ................................................................................... 1-28
Demonstration 1: Explore an IBM Cognos Analytics environment .................... 1-29
Installation map ................................................................................................ 1-36
Demonstration 2: Set up the TCPMonitor utility and perform a request ............ 1-37
Unit summary ................................................................................................... 1-42

© Copyright IBM Corp. 2010, 2016 P-3

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Preface

Explore the IBM Cognos Dispatcher ................................................... 2-1

Unit objectives .................................................................................................... 2-3
What is a thread? ............................................................................................... 2-4
What is a servlet? ............................................................................................... 2-5
What is a process? ............................................................................................. 2-6
What is the IBM Cognos Dispatcher? ................................................................. 2-7
Examine the dispatcher and the BIBus ............................................................... 2-8
Describe the dispatcher ...................................................................................... 2-9
What is the purpose of request routing? ........................................................... 2-10
Describe request routing concepts ................................................................... 2-11
Describe the role of the gateway ...................................................................... 2-12
Describe dispatcher cluster information ............................................................ 2-13
Explore dispatcher cluster information details................................................... 2-14
Demonstration 1: Review the output of p2plbDiag ............................................ 2-15
Describe front dispatchers ................................................................................ 2-20
Describe the dispatcher request queue ............................................................ 2-21
Examine the details of the request queue ......................................................... 2-22
Considerations for the request queue ............................................................... 2-23
What is a conversation? ................................................................................... 2-24
Explore the benefits of conversations ............................................................... 2-25
Examine the usual conversation ....................................................................... 2-26
What are asynchronous conversations? ........................................................... 2-27
What are grouped conversations ...................................................................... 2-28
Describe request affinity ................................................................................... 2-29
Define request affinity assignments .................................................................. 2-30
Review request routing ..................................................................................... 2-31
Consider customization .................................................................................... 2-32
What load balancing modes are available? ...................................................... 2-33
Explain weighted round robin mode ................................................................. 2-34
Weighted round robin in IBM Cognos 11 .......................................................... 2-35
Explain cluster compatible mode ...................................................................... 2-37
What is advanced routing? ............................................................................... 2-39
What are server groups? .................................................................................. 2-40
Server group considerations ............................................................................. 2-41
Example of server groups................................................................................. 2-42
Describe routing sets ........................................................................................ 2-43
What are routing rules? .................................................................................... 2-44
Routing rules considerations ............................................................................ 2-45
Explain advanced routing ................................................................................. 2-46

© Copyright IBM Corp. 2010, 2016 P-4

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Preface

Describe steps of the routing process............................................................... 2-47

Routing process: Example 1 ............................................................................. 2-49
Routing process: Example 2 ............................................................................. 2-51
Things to remember ......................................................................................... 2-53
What is Content Manager Cache Service? ....................................................... 2-54
Describe CMCS details .................................................................................... 2-55
Service a primary request ................................................................................. 2-56
Service a secondary request ............................................................................ 2-57
Explain CMCS settings ..................................................................................... 2-58
Describe timers ................................................................................................ 2-59
Unit summary ................................................................................................... 2-60
Exercise 1: Review the server groups (optional)............................................... 2-61
Examine IBM Cognos Services ............................................................ 3-1
Unit objectives .................................................................................................... 3-3
What is Content Manager Service? .................................................................... 3-4
What does Content Manager Service support? .................................................. 3-6
Report Service and Batch Report Service .......................................................... 3-7
Introduce BIBusTKServerMain ........................................................................... 3-8
Explain report execution in IBM Cognos ............................................................. 3-9
Describe server affinity: Low............................................................................. 3-10
Describe server affinity: High ............................................................................ 3-11
Describe server affinity: Absolute ..................................................................... 3-12
Describe affinity connections ............................................................................ 3-13
Example of affinity connections ........................................................................ 3-14
Describe affinity connection assignment........................................................... 3-15
Management of affinity connection assignment ................................................ 3-16
Explain affinity connection configuration ........................................................... 3-17
Describe scheduling ......................................................................................... 3-18
Services that implement the Target Service API............................................... 3-20
Set Target Services properties ......................................................................... 3-22
Explain Monitor Service properties ................................................................... 3-23
Explain Batch Report Service properties .......................................................... 3-24
Explain Content Manager Service properties.................................................... 3-26
Overview of services ........................................................................................ 3-27
Service-Oriented Architecture implications ....................................................... 3-30
Explain Cognos Graphics Service .................................................................... 3-31
Describe Cognos Graphics Service .................................................................. 3-32
Describe the Current Default Engine ................................................................ 3-33
Configure Cognos Graphics Service................................................................. 3-34
Configure CGS parameters .............................................................................. 3-35
Explain Presentation Service (PRS) ................................................................. 3-37

© Copyright IBM Corp. 2010, 2016 P-5

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Preface

Describe PRS ................................................................................................... 3-38

Explain Report Data Service (RDS) .................................................................. 3-39
What components use RDS? ........................................................................... 3-40
What is Metadata Service (MDS)? ................................................................... 3-41
Explain Relational Metadata Service (RMDS) .................................................. 3-42
Configure RMDS .............................................................................................. 3-43
What is Dynamic Query Mode? ........................................................................ 3-45
OLAP functionality for Relational sources ......................................................... 3-47
Dynamic Query Mode connectivity ................................................................... 3-49
OLAP DQM connectivity ................................................................................... 3-50
Relational and DMR DQM connectivity............................................................. 3-51
Describe QueryService..................................................................................... 3-52
Describe the QueryService properties .............................................................. 3-54
Additional Query Service information................................................................ 3-56
Describe Repository Service (REPOS)............................................................. 3-57
Explain REPOS ................................................................................................ 3-59
Configure REPOS ............................................................................................ 3-60
What is Cognos Access Manager Service? ...................................................... 3-62
Describe Authentication Providers .................................................................... 3-63
Unit summary ................................................................................................... 3-64
Exercise 1: Observe the effects on a dispatcher when running multiple report
server instances. ............................................................................................. 3-65
Explore Java memory management .................................................... 4-1
Unit objectives .................................................................................................... 4-3
Review Java components in IBM Cognos .......................................................... 4-4
High level architectural view ............................................................................... 4-5
What is Java? ..................................................................................................... 4-6
Describe the Java Runtime Environment ............................................................ 4-7
Examine the JRE process memory layout .......................................................... 4-8
Example of JRE memory management .............................................................. 4-9
Why is Java memory management important? ................................................. 4-10
Explore concepts of memory management....................................................... 4-11
JVM settings ..................................................................................................... 4-12
Explain Garbage Collection .............................................................................. 4-14
Considerations of Garbage Collection .............................................................. 4-16
What is IBM JRE Garbage Collection? ............................................................. 4-17
Describe fragmentation concerns ..................................................................... 4-18
Log Garbage Collection .................................................................................... 4-19
Verbose GC output of IBM JRE: Example 1 ..................................................... 4-20
Verbose GC output of IBM JRE: Example 2 ..................................................... 4-21

© Copyright IBM Corp. 2010, 2016 P-6

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Preface

Enable Verbose GC in IBM Cognos 11: Example using Tomcat with

Command Line ................................................................................................ 4-22
Enable Verbose GC in IBM Cognos 11: Example using Tomcat as a Service .. 4-23
Enable Verbose GC: CGS and DQM ................................................................ 4-24
Enable GC Logging in WAS ............................................................................. 4-25
Tuning GC: IBM JRE ........................................................................................ 4-26
JVM Tuning and Dynamic Cubes ..................................................................... 4-27
Configure the JVM for Query Service ............................................................... 4-29
Tips on tuning settings...................................................................................... 4-30
Phases of Dynamic Cubes operation................................................................ 4-32
Analysis of JVM Garbage Collection................................................................. 4-33
What happens in a JRE crash? ........................................................................ 4-35
What should you do if Java hangs? .................................................................. 4-36
Use tools to monitor Java ................................................................................. 4-37
Unit summary ................................................................................................... 4-38
Examine Audit logging and Indication Processing Facility logging . 5-1
Unit objectives .................................................................................................... 5-3
What are Installation logs? ................................................................................. 5-4
Review installation logs ...................................................................................... 5-5
Explore the Transfer log ..................................................................................... 5-6
Explore the Installation Configuration log ........................................................... 5-7
Explore the Runtime log ..................................................................................... 5-8
Explore the Content Manager Results logs ........................................................ 5-9
Explore logging of Content Store Hierarchy creation ........................................ 5-10
Explore logging of creation of initial Content Store objects ............................... 5-11
Explore properties of IBM Cognos Configuration .............................................. 5-12
Logging of IBM Cognos Configuration .............................................................. 5-13
What is the cogstartup.xml file? ........................................................................ 5-14
What is the coglocale.xml file? ......................................................................... 5-15
What is Audit logging in IBM Cognos 11? ......................................................... 5-16
Explore the basic architecture of Audit logging ................................................. 5-17
Set logging levels ............................................................................................. 5-18
Explain Audit logging levels .............................................................................. 5-19
Demonstration 1: Set logging levels ................................................................. 5-20
What is Native Query logging? ......................................................................... 5-25
Explain Audit logging destinations .................................................................... 5-26
Where are destinations stored? ........................................................................ 5-27
Explore the File log........................................................................................... 5-28
Explore the Windows Event log ........................................................................ 5-30
Explore the UNIX System log ........................................................................... 5-31
What is the Remote Log Server?...................................................................... 5-32

© Copyright IBM Corp. 2010, 2016 P-7

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Preface

Example of Remote Log Server Process .......................................................... 5-33

Exercise 1: Configure a Windows Event Log and review the Runtime log ........ 5-34
What is IPF logging? ........................................................................................ 5-40
Explore the basic architecture of IPF logging.................................................... 5-41
What are IPF indications? ................................................................................ 5-42
What are the fields of Audit and Trace indications? .......................................... 5-43
Applicability of Audit and Trace indication fields ............................................... 5-45
What are the fields of Performance indication? ................................................ 5-46
What are IPF Client logs?................................................................................. 5-48
Explain IPF Client logging ................................................................................ 5-49
When to use ipfXXXXclientconfig.xml ............................................................... 5-51
Describe SDS logging ...................................................................................... 5-53
Most commonly used IPF traces ...................................................................... 5-54
Unit summary ................................................................................................... 5-55
Exercise 2: Configure IPF logging .................................................................... 5-56
Perform dye tracing .............................................................................. 6-1
Unit objectives .................................................................................................... 6-3
What is dye tracing? ........................................................................................... 6-4
What are the requirements of JMX connectivity? ................................................ 6-5
Add an IPF filter.................................................................................................. 6-6
Unit summary ..................................................................................................... 6-7
Exercise 1: Perform dye tracing.......................................................................... 6-8
Explore Dynamic Query Mode ............................................................. 7-1
Unit objectives .................................................................................................... 7-3
Available Dynamic Query Mode logging ............................................................. 7-4
Describe XQE log files........................................................................................ 7-5
IPF logging for DQM ........................................................................................... 7-8
Describe QFS logging for DQM .......................................................................... 7-9
Enable DQM BAPI trace for SAP BW ............................................................... 7-10
What is Cognos DQA? ..................................................................................... 7-11
What can you do with IBM Cognos DQA? ........................................................ 7-12
Review the IBM Cognos DQA Graph legend .................................................... 7-13
Explore IBM Cognos DQA views ...................................................................... 7-14
Explore Aggregate Advisor ............................................................................... 7-16
Unit summary ................................................................................................... 7-18
Exercise 1: Enable DQM, publish a package, and review the logs created....... 7-19
Exercise 2: Use IBM Cognos Dynamic Query Analyzer to analyze a query ...... 7-32

© Copyright IBM Corp. 2010, 2016 P-8

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Preface

Explore component logging ................................................................. 8-1

Unit objectives .................................................................................................... 8-3
Report Server (RSVP) trace ............................................................................... 8-4
BIBus trace......................................................................................................... 8-5
Trace the Dispatcher .......................................................................................... 8-6
Explore Query Framework logging ..................................................................... 8-7
Describe the Dispatcher Command Console ...................................................... 8-8
Gateway trace .................................................................................................... 8-9
Demonstration 1: Perform a Gateway trace ...................................................... 8-10
Why use a UDA trace? ..................................................................................... 8-14
Describe methods to enable UDA traces .......................................................... 8-16
Explore UDA trace and environment variables ................................................. 8-18
Describe common trace layers and categories ................................................. 8-19
Example of a UDA trace ................................................................................... 8-20
Activate UDA trace with session variables ........................................................ 8-21
Activate UDA trace with IPF file ........................................................................ 8-22
Example UDA output ........................................................................................ 8-23
What is UDATest? ............................................................................................ 8-24
UDATest scenario 1 ......................................................................................... 8-25
UDATest scenario 2 ......................................................................................... 8-26
UDATest scenario 3 ......................................................................................... 8-27
UDATest scenario 4 ......................................................................................... 8-28
UDATest scenario 5 ......................................................................................... 8-29
UDATest scenario 6 ......................................................................................... 8-30
Exercise 1: Explore UDA Trace and UDATest (optional) .................................. 8-31
What is Perf.QFS? ........................................................................................... 8-48
Activate Perf.QFS............................................................................................. 8-49
Describe Perf.QFS output ................................................................................ 8-50
Exercise 2: Perform Perf.QFS logging .............................................................. 8-51
Unit summary ................................................................................................... 8-62

© Copyright IBM Corp. 2010, 2016 P-9

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Preface

Examine additional tools and special task logging ............................ 9-1

Unit objectives .................................................................................................... 9-3
IBM Cognos Analytics Content Manager Browser Tool ...................................... 9-4
IBM Cognos Analytics Content Manager Size Tool ............................................ 9-5
IBM Cognos Framework Manager Tool .............................................................. 9-6
IBM Cognos Analytics Content Store Information Tool ....................................... 9-7
System Overview Diagnostic Tool ...................................................................... 9-8
Demonstration 1: Explore diagnostic tools ........................................................ 9-10
IBM Cognos Log Viewer utility .......................................................................... 9-18
Describe cm_tester .......................................................................................... 9-19
CMTools utility .................................................................................................. 9-20
Demonstration 2: Explore the IBM Cognos Log Viewer and CMTools utilities .. 9-21
Drill Through Assistant ..................................................................................... 9-26
Use diagnostic URL commands ....................................................................... 9-28
Analyze logs with I.C.E.T.E.A ........................................................................... 9-29
Demonstration 3: Analyze logs with I.C.E.T.E.A. .............................................. 9-30
Unit summary ................................................................................................... 9-35
Exercise 1: Examine URLs available for troubleshooting.................................. 9-36

© Copyright IBM Corp. 2010, 2016 P-10

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Preface

Course overview
Preface overview
This course is designed to teach participants how to identify components and sub-
components of the IBM Cognos Analytics architecture and how to use tools and
techniques to provide a foundation to troubleshoot issues. Through lecture and
interactive exercises participants will identify IBM Cognos Analytics components,
examine how these components interact with Java, and will explore logging to assist
when troubleshooting issues.
Intended audience
• Administrators responsible for administering the IBM Cognos Analytics 11.0
environment
Topics covered
Topics covered in this course include:
• Introduction and Service-Oriented Architecture
• Explore the IBM Cognos Dispatcher
• Examine IBM Cognos services
• Examine Java memory management
• Examine audit logging and Indication Processing Facility logging
• Perform dye tracing
• Explore Dynamic Query Mode
• Explore component logging
• Examine additional tools and special task logging
Course prerequisites
Participants should have:
• IBM Cognos Analytics: Administration (v11.0) course or equivalent experience
administering the IBM Cognos Analytics environment

© Copyright IBM Corp. 2010, 2016 P-11

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Preface

Verify services used in the course environment

The environment provided in this course requires the following services to be started
before you begin performing demonstrations and exercises:

• Apache Directory Server - default

• DB2-DB2COPY1 - DB2
• DB2DAS - DB2DAS00
• World Wide Web Publishing Service
• IBM Cognos Full:9315
• IBM Cognos DispCM:9320
If any of the services are not running, start them and then close the Services window.
Be patient when starting these services, as they will take some time.
Note: Always start Apache Directory Server - default before the IBM Cognos Services,
and start IBM Cognos Full:9315 completely before starting
IBM Cognos DispCM:9320.
When starting the IBM Cognos services, a message will appear about not starting the
service in a timely fashion; close the message and wait for two minutes before you click
Refresh on the Services toolbar. You may have to refresh in two minute increments to
see a status of Started.

© Copyright IBM Corp. 2010, 2016 P-12

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Preface

Document conventions
Conventions used in this guide follow Microsoft Windows application standards, where
applicable. As well, the following conventions are observed:
• Bold: Bold style is used in demonstration and exercise step-by-step solutions to
indicate a user interface element that is actively selected or text that must be
typed by the participant.
• Italic: Used to reference book titles.
• CAPITALIZATION: All file names, table names, column names, and folder names
appear in this guide exactly as they appear in the application.
To keep capitalization consistent with this guide, type text exactly as shown.

© Copyright IBM Corp. 2010, 2016 P-13

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Preface

Exercises
Exercise format
Exercises are designed to allow you to work according to your own pace. Content
contained in an exercise is not fully scripted out to provide an additional challenge.
Refer back to demonstrations if you need assistance with a particular task. The
exercises are structured as follows:
The business question section
This section presents a business-type question followed by a series of tasks. These
tasks provide additional information to help guide you through the exercise. Within
each task, there may be numbered questions relating to the task. Complete the
tasks by using the skills you learned in the unit. If you need more assistance, you
can refer to the Task and Results section for more detailed instruction.
The task and results section
This section provides a task based set of instructions that presents the question as
a series of numbered tasks to be accomplished. The information in the tasks
expands on the business case, providing more details on how to accomplish a task.
Screen captures are also provided at the end of some tasks and at the end of the
exercise to show the expected results.

© Copyright IBM Corp. 2010, 2016 P-14

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Preface

Additional training resources

• Visit IBM Analytics Product Training and Certification on the IBM website for
details on:
• Instructor-led training in a classroom or online
• Self-paced training that fits your needs and schedule
• Comprehensive curricula and training paths that help you identify the courses
that are right for you
• IBM Analytics Certification program
• Other resources that will enhance your success with IBM Analytics Software
• For the URL relevant to your training requirements outlined above, bookmark:
• Information Management portfolio:
http://www-01.ibm.com/software/data/education/
• Predictive and BI/Performance Management/Risk portfolio:
http://www-01.ibm.com/software/analytics/training-and-certification/

© Copyright IBM Corp. 2010, 2016 P-15

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Preface

IBM product help

Help type When to use Location

Task- You are working in the product and IBM Product - Help link
oriented you need specific task-oriented help.

Books for You want to use search engines to Start/Programs/IBM

Printing find information. You can then print Product/Documentation
(.pdf) out selected pages, a section, or the
whole book.
Use Step-by-Step online books
(.pdf) if you want to know how to
complete a task but prefer to read
about it in a book.
The Step-by-Step online books
contain the same information as the
online help, but the method of
presentation is different.

IBM on the You want to access any of the

Web following:

• IBM - Training and Certification • http://www-01.ibm.com/

software/analytics/training-
and-certification/
• Online support • http://www-947.ibm.com/
support/entry/portal/
Overview/Software
• IBM Web site • http://www.ibm.com

© Copyright IBM Corp. 2010, 2016 P-16

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
Introduction and Service-Oriented Architecture

Introduction and
Service-Oriented Architecture

IBM Cognos Analytics 11.0

© Copyright IBM Corporation 2016

Course materials may not be reproduced in whole or in part without the written permission of IBM.
 Unit 1 Introduction and Service-Oriented Architecture

© Copyright IBM Corp. 2010, 2016 1-2

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 1 Introduction and Service-Oriented Architecture

Unit objectives
• Identify IBM Cognos 11 architectural components
• Describe Service-Oriented Architecture in IBM Cognos

Introduction and Service-Oriented Architecture © Copyright IBM Corporation 2016

Unit objectives

© Copyright IBM Corp. 2010, 2016 1-3

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 1 Introduction and Service-Oriented Architecture

IBM Cognos Analytics architecture

• Examine components
 C:\Training\B6019\01-Intro_and_SOA\Cognos Analytics 11.0.1
Archtecture_diagram.jpg

Introduction and Service-Oriented Architecture © Copyright IBM Corporation 2016

IBM Cognos Analytics architecture

The IBM Cognos 11 architecture diagram is provided for your reference, as you
progress through this unit, and others in the course, to help you understand the
architecture of the IBM Cognos Analytics system.
In addition to the course reference card, at the end of this unit is a comprehensive list of
acronyms that you may find helpful to refer to as you review the diagram, and the
content of this course.

© Copyright IBM Corp. 2010, 2016 1-4

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 1 Introduction and Service-Oriented Architecture

Component definitions
• IBM Cognos Analytics 11 is composed of many components:
 development component
− coded in Java or C++
 component stack or product component
 install component

Introduction and Service-Oriented Architecture © Copyright IBM Corporation 2016

Component definitions
IBM Cognos 11 is a mix of development components coded in Java or C++. This is
important in understanding the deployment in your environment, to help you when
troubleshooting.
A development component is the smallest entity in the product, and is often referred to
by an acronym such as XTS (XML Transformation Service), CQE (Cognos Query
Engine), and RQP (Relational Query Planner).
A set of development components constitute a product component, often referred to by
an acronym. For example, CAM (Cognos Access Manager) consists of AAA
(Authentication Authorization Accounting), CRP (Cryptography), and AutoCA (Auto
Certificate Authority, the IBM Cognos Analytics certificate authority).

© Copyright IBM Corp. 2010, 2016 1-5

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 1 Introduction and Service-Oriented Architecture

Two languages, two approaches

C++ Java

compiled language interpreted language

different source code for different compiled to platform independent

target platform (OS) bytecode

compiled executable fixed to bytecode is not executable;

target platform requires JRE

compiled executable is able to run JRE is platform dependent,

directly provided by OS vendors

Introduction and Service-Oriented Architecture © Copyright IBM Corporation 2016

Two languages, two approaches

While C++ executables are standalone, Java applications require a runtime
environment. This runtime environment is called the Java Runtime Environment (JRE).
Since parts of a JRE implementation are coded in C++ and/or an assembler, a JRE is
platform specific and will leverage all hardware features of that platform.
The advantages of Java are better adapted to a Service-Oriented Architecture
environment than C++.

© Copyright IBM Corp. 2010, 2016 1-6

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 1 Introduction and Service-Oriented Architecture

What is Java EE?

• Defines a platform of specifications and APIs in an enterprise
application.
• Includes functional components.
• Java EE server:
 Java application server or application server
 Provides runtime environment for Java EE applications
 Coded in Java

Introduction and Service-Oriented Architecture © Copyright IBM Corporation 2016

What is Java EE?

Java application servers (Java EE (Java Platform, Enterprise Edition) servers) are
complex and designed for enterprise-class applications. The Java EE server is actually
a Java program itself, and therefore requires a Java Runtime Environment (JRE).
Java EE includes scalable, distributed, transactional, and fault tolerant applications.
Included in Java EE are functional components such as connections to databases or
networks, and transaction handling. Java EE includes the following common Java
specifications:
• Java Servlets
• Enterprise Java Beans (EJB)
• JavaServer Pages (JSP): a technique where Java code is compiled into a servlet
at runtime
Enterprise-class applications involve thousands of users and petabytes of data. Just
because an application can run on a laptop is not an indication that that is how it would
behave in a large enterprise.
Java EE servers are sometimes called app servers, or application servers.

© Copyright IBM Corp. 2010, 2016 1-7

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 1 Introduction and Service-Oriented Architecture

Examine IBM Cognos Analytics servlets

• IBM Cognos Analytics operates with two Java servlets running in a
Java servlet container.

Report Service Dispatcher Content Manager

(C++) (Java Servlet) (Java Servlet)
Batch report
Service (C++) Services
Java Servlet container

Websphere Liberty Profile (default)

• You can configure IBM Cognos Analytics to use a third-party

application server other than WebSphere Liberty Profile.

Introduction and Service-Oriented Architecture © Copyright IBM Corporation 2016

Examine IBM Cognos Analytics servlets

The Content Manager servlet and dispatcher servlet run within the Java servlet
container configured for IBM Cognos Analytics. By default, IBM Cognos Analytics
installs and uses IBM WebSphere Liberty Profile as the default servlet container. You
can also configure IBM Cognos Analytics to use another Java application server, such
as JBoss Application Server, Oracle/BEA WebLogic Server, or WebSphere Application
Server. For more information on supported third-party application servers, refer to the
supported environments available on http://www-
01.ibm.com/support/docview.wss?uid=swg27014782#sw_env.
The report and batch report services are C++ applications running as child processes of
the dispatcher, but do not run within the servlet container. All other services are Java
based and run within the servlet container.

© Copyright IBM Corp. 2010, 2016 1-8

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 1 Introduction and Service-Oriented Architecture

Examine 32-bit vs. 64-bit

• Addressable memory capacity:
 32-bit = 4 Gigabytes (GB) addressable memory
 64-bit = 18.45 Exabytes (EB) of addressable memory
• IBM Cognos 11 supports:
 32-bit and 64-bit hardware
 32-bit OS*
 64-bit OS*

* Refer to Supported Environments in Product Documentation.

Introduction and Service-Oriented Architecture © Copyright IBM Corporation 2016

Examine 32-bit vs. 64-bit

IBM Cognos 11 is affected by bitness mostly with regards to available memory.

© Copyright IBM Corp. 2010, 2016 1-9

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 1 Introduction and Service-Oriented Architecture

Examine 64-bit support

• Components that leverage 64-bit addressing (beyond 4 GB RAM):
 Java components running in 64-bit JRE:
− Content Manager, Dispatcher, Dynamic Query QueryService, Graphics Service
engine
 C++ based authentication providers can offer true 64-bit:
− LDAP, Active Directory, SAP
 64-bit Report Server (dynamic query only)
• Components that use 32-bit addressing:
 Report Server (all relational query handling)
 Gateways (ISAPI, apache_mod)

Introduction and Service-Oriented Architecture © Copyright IBM Corporation 2016

Examine 64-bit support

Beginning with the IBM Cognos 10 release, more components of the product moved to
Java, and as a result leveraging larger memory with a 64-bit JRE becomes more
important onwards.

© Copyright IBM Corp. 2010, 2016 1-10

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 1 Introduction and Service-Oriented Architecture

Examine 64-bit support benefits

• Java components:
 Access to more memory (2 GB to 18 EB theoretically)
 Some speed gains due to 64-bit optimized JRE
• C++ coded components:
 Only if specifically compiled for 64-bit

Introduction and Service-Oriented Architecture © Copyright IBM Corporation 2016

Examine 64-bit support benefits

64-bit does not imply twice the speed or 30% speed gain.
Examples of general benefits of 64-bit addressing in C++ include gains in numerical
and logical operations at the CPU level, and CPU and memory controller internal
optimizations due to the higher efficiency of 64-bit processing.
A deep dive into these topics can go beyond the scope of this course. You are
encouraged to research 64-bit benefits on the internet.

© Copyright IBM Corp. 2010, 2016 1-11

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 1 Introduction and Service-Oriented Architecture

List core install components

• Application Tier Components (ATC)
• Gateway (GW)
• Content Manager (CM)
• IBM Cognos Content Database (CCD)
• Framework Manager (FM)

Introduction and Service-Oriented Architecture © Copyright IBM Corporation 2016

List core install components

Application Tier: Server components provide the user interfaces for reporting,
analysis, scorecarding and event management, as well as the server functionality for
routing and processing user requests. The application tier is a combination of C++
applications and Java servlets. Server components include the following:
• IBM Cognos Analytics portal: a Web portal provided with IBM Cognos,
provides a single access point to the corporate data available to its products. It
provides a single point of entry for querying, analyzing, and organizing data, and
for creating reports, scorecards, and events. Users can run all their Web-based
IBM Cognos 11 applications through the IBM Cognos Analytics portal..
• IBM Cognos Administration: a central management interface that contains the
administrative tasks for IBM Cognos Analytics. It provides easy access to the
overall management of the IBM Cognos environment and is accessible through
IBM Cognos Connection. Some administration functionality is also provided within
the IBM Cognos Analytics portal.

© Copyright IBM Corp. 2010, 2016 1-12

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 1 Introduction and Service-Oriented Architecture

• IBM Cognos Analytics - Reporting: allows report authors to create, edit, and
distribute a wide range of professional reports. Authors can also define corporate-
standard report templates for use as well as edit and modify reports created in
older IBM Cognos offerings, such as Query Studio, Analysis Studio, Report
Studio, and Cognos Workspace Advanced. IBM Cognos Analytics - Reporting
also provides access to dimensional, OLAP (online analytical processing) and
dimensionally modeled relational data sources.
• Event Studio: set up agents to monitor your data and perform tasks when
business events or exceptional conditions occur in your data that must be dealt
with. When an event occurs, people are alerted to take action. Agents can publish
details to the portal, deliver alerts by email, run and distribute reports based on
events, and monitor the status of events. For example, a support call from a key
customer or the cancellation of a large order may trigger an event, sending an
email to the appropriate people.
• IBM Cognos Analytics - Dashboards: create sophisticated interactive
dashboards using personal files and Data Modules. You can view and open
favorite dashboards, manipulate the content in the dashboards, and email your
dashboards.
• Dispatcher: A dispatcher starts all IBM Cognos 11 services configured and
enabled on a computer, and routes requests.
• Content Manager: the IBM Cognos 11 service that manages the storage of
application data. This application data includes security, configuration data,
models, metrics, report specifications, and report output. Models are published
from Framework Manager to Content Manager. Content Manager is also used to
retrieve or store report specifications, manage scheduling information and
manage the built-in Cognos security namespace. Content Manager stores
information in a database known as the Content Store. Content Manager is a
Java servlet and requires an application server such as IBM WebSphere Liberty
Profile. IBM Cognos Analytics installs IBM WebSphere Liberty Profile as the
default application server. Note that there can only be one active instance of the
Content Manager and Content Store, but it is possible to have a standby Content
Manager available as a failover system.

© Copyright IBM Corp. 2010, 2016 1-13

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 1 Introduction and Service-Oriented Architecture

• Framework Manager: a metadata modeling tool that drives query generation for
IBM Cognos software. A model is a collection of metadata that includes physical
information and business information for one or more data sources.
• Gateway: one or more gateways can be installed on one or more servers. A
gateway transfers information from one server to another server. For failover, the
gateway can be configured with the location of multiple dispatchers. In IBM
Cognos 11, the gateway component is not required. A gateway component is
only needed when using web-based features, such as Single Sign-On (SSO)
authentication, access to external web servers, or 3rd-party portals.

© Copyright IBM Corp. 2010, 2016 1-14

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 1 Introduction and Service-Oriented Architecture

List companion installs

• IBM Cognos Transformer
• IBM Cognos PowerPlay Server and Client
• IBM Cognos Lifecycle Manager
• IBM Cognos Analysis for Microsoft Excel
• IBM Cognos for Microsoft Office
• IBM Cognos Metric Studio

Introduction and Service-Oriented Architecture © Copyright IBM Corporation 2016

List companion installs

Companion products are not part of the base IBM Cognos 11 install, and require
separate downloads. Some may require additional configuration. There may also be a
cost associated with the additional installs.
IBM Connections is not an IBM Cognos product but an IBM product which has to be
obtained separately. IBM Cognos 11 offers some integration features with this product.

© Copyright IBM Corp. 2010, 2016 1-15

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 1 Introduction and Service-Oriented Architecture

Overview of core install components

Gateway (optional)
(C++ multi-platform)
(cognos.cgi, cognos_isapi.dll, apache_mod)

Servlet Gateway (Java)

Content Framework Transformer

Transformer Manager Manager
Application Tier (C++ multi-platform)
(C++ Windows)
(Java) (C++ Windows)
(C++ multi-platform)

DB2 Database
Java Component (multi-platform)

C++ Component (multi-platform)

C++ Component (Microsoft Windows only)

Introduction and Service-Oriented Architecture © Copyright IBM Corporation 2016

Overview of core install components

IBM Cognos 11 has a three tier architecture: Web Tier (Gateway), Application Tier, and
Database Tier. A Gateway relays to an Application Tier which talks to Content Manager
which talks to the Content Store.
The Gateway component is only required if you plan to use a Single Sign-On (SSO)
environment, access 3rd-party portals, or if you need access to an external web server.
Recall that IBM Cognos 11 is a mixture of 32-bit C++ and Java components, that 64-bit
Java runtime environments are supported, and that the Java components must be
deployed to a Java application server or servlet container.

© Copyright IBM Corp. 2010, 2016 1-16

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 1 Introduction and Service-Oriented Architecture

Describe gateways
• Reside on one or more Web servers.
• Is an extension of a Web server program passing information between
Web servers.
• Types:
 Common Gateway Interface (CGI)
 ISAPI*
 apache_mod* (Apache 1.x, Apache 2, Apache 2.2)
 servlet*

Gateway
(C++ multi-platform)

Servlet Gateway (Java)

* Supports connection pooling.

Introduction and Service-Oriented Architecture © Copyright IBM Corporation 2016

Describe gateways
IBM Cognos supports several types of Web gateways.
• CGI (Common Gateway Interface): The default gateway, CGI can be used for all
supported Web servers. However, for enhanced performance or throughput, you
may choose one of the other supported gateway types. For each request a
cognos.cgi process is executed on the server. CGI gateways are the least
secure.
• ISAPI: ISAPI is used with the Microsoft Internet Information Services (IIS) Web
server. It delivers faster performance for IIS. This gateway supports connection
pooling.
• Apache_mod: You can use an apache_mod gateway with the Apache Web
server. This gateway supports connection pooling.

© Copyright IBM Corp. 2010, 2016 1-17

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 1 Introduction and Service-Oriented Architecture

• Servlet: If your Web server infrastructure supports servlets or you are using an
application server, you can use a Servlet gateway. This gateway supports
connection pooling, 20 by default, configurable in web.xml only.
Establishing and releasing connections is a resource intensive task. IBM Cognos 11
does a lot of connection pooling, a technique used for establishing a pool of resource
connections that applications can share on an application server. Not having
connection pooling is what makes CGI resource intensive and comparatively poor
performing. The Web server manages the number of connections and re-uses them
when possible.
If using IIS, you should use the ISAPI gateway. The setup is the same as CGI. You will
need to modify the index.html and/or default.html in the webcontent directory.

© Copyright IBM Corp. 2010, 2016 1-18

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 1 Introduction and Service-Oriented Architecture

Explore gateway requests

Gateway Dispatcher
(Java)
(C++ multi-platform)
(cognos.cgi, cognos_isapi.dll, servlet
gateway, apache_mod)

Servlet Gateway
(Java)
Content Manager
(Java)

Introduction and Service-Oriented Architecture © Copyright IBM Corporation 2016

Explore gateway requests

When a Gateway receives a request it encrypts passwords to ensure security. The
Gateway will also extract the information needed to submit the request to an IBM
Cognos 11 server. The Gateway attaches environment variables from the Web server,
and adds a default namespace to the request to ensure that the server authenticates
the user in the correct namespace. The Gateway then passes requests to an IBM
Cognos Dispatcher for processing.

© Copyright IBM Corp. 2010, 2016 1-19

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 1 Introduction and Service-Oriented Architecture

Describe the Application Tier install component

• Contains Dispatcher and other components.
• One instance of an Application Tier component is required for a
system.

Dispatcher
(Java)

Introduction and Service-Oriented Architecture © Copyright IBM Corporation 2016

Describe the Application Tier install component

The Application Tier install component is the central piece of the system. You must
have at least one instance of an Application Tier component installed, but many
instances can join a system.

© Copyright IBM Corp. 2010, 2016 1-20

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 1 Introduction and Service-Oriented Architecture

Describe IBM Cognos Content Database

• Provides Apache Derby, open source Java relational database.
• Provides command line administration.
• Information is readily available on Internet.
• Cannot be used as Audit database.
• Do not use as production content store.

Cognos Content
Database

Introduction and Service-Oriented Architecture © Copyright IBM Corporation 2016

Describe IBM Cognos Content Database

Advantages of the IBM Cognos Content Database (CCD) on Apache Derby include a
small footprint, compliance with Java, JDBC, and SQL standards, and that it provides
an embedded JDBC driver that lets you embed Derby in any Java-based solution.
Administration is done through the command line only.
CCD is intended for demonstration and development use, and is not suitable for
enterprise scale applications, and should not be used as a production content store or
Audit database.
Note: In version 11.0, the Ready-to Run option installs a full version of IBM Cognos
Analytics software, Informix 12.0, and Apache Directory Server.

© Copyright IBM Corp. 2010, 2016 1-21

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 1 Introduction and Service-Oriented Architecture

Describe Service-Oriented Architecture (SOA)

• System functionality is exposed as a set of independent services that
can be accessed over a network without knowledge of their underlying
platform implementation.
• Services interact with each other:
 Communication: SOAP over a system bus
 SOAP transports an XML payload over HTTP(S) protocol

Introduction and Service-Oriented Architecture © Copyright IBM Corporation 2016

Describe Service-Oriented Architecture (SOA)

The Java EE paradigm (on the Java application servers) enables the coding of
applications based on Service-Oriented Architecture (SOA). This is different than earlier
application design. With SOA, a service is the entity which offers functionality.
Multiple instances of the same service can exist in the system. Models can be
processed on business needs, rather than technical constraints.
An analogy to help understand this concept of service-oriented architecture:
You just moved into town and you need to find a plumber (service). There are many
plumbers (service instances) which allow you to "load balance", which means that if you
don't reach one, you can call another one. You interact over a network (phone); it is not
important where the plumber learned his craft, or what country the plumber is from, but
whether or not they can do the service that you require.

© Copyright IBM Corp. 2010, 2016 1-22

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 1 Introduction and Service-Oriented Architecture

Describe SOA assets

• Platform independent
• Extendible
• Scalable
• Flexible

Introduction and Service-Oriented Architecture © Copyright IBM Corporation 2016

Describe SOA assets

SOA is platform independent, meaning that a single system can contain services
implemented and hosted on different platforms. You can extend a system by adding
new functionality, by adding a service, without affecting existing components. SOA is
scalable, allowing you to add instances of services to obtain more resources. The
flexibility of SOA allows the system to be configured based solely on service availability,
which can be established based on usage patterns.

© Copyright IBM Corp. 2010, 2016 1-23

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 1 Introduction and Service-Oriented Architecture

Examine SOA in IBM Cognos

• IBM Cognos is based on SOA.
• IBM Cognos Services expose functionality implemented in
development components.
• An IBM Cognos system has one or more physically installed instances.
• Instances can join a system regardless of the OS or application server
they are deployed in .

Introduction and Service-Oriented Architecture © Copyright IBM Corporation 2016

Examine SOA in IBM Cognos

IBM Cognos Services expose the functionality implemented in development
components, including Report Service, Job Service, Agent Service, Delivery Service,
and so on.
Each instance in an IBM Cognos system contains a set of install components, and each
instance offers a specific set of services. Multiple instances of the same IBM Cognos
service may exist in a system.

© Copyright IBM Corp. 2010, 2016 1-24

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 1 Introduction and Service-Oriented Architecture

What are IBM Cognos Services?

• Provide all IBM Cognos 11 functionality.
• Are hosted by a Dispatcher and interact with each other.
• Dispatcher interfaces of all services are Java.
• Each defines one or more handlers
 External and internal services
• Most services are optional.
• Can be arranged according to the general principles of SOA.

Introduction and Service-Oriented Architecture © Copyright IBM Corporation 2016

What are IBM Cognos Services?

An IBM Cognos Service is a Java part which plugs into the Dispatcher, but the
underlying implementation of the service could be Java or C++.
Each IBM Cognos Service defines one or more handlers that describe which type of
requests they can handle. External services can be managed through a UI, and internal
services cannot be managed.
Mandatory services are CM (Content Manager), CAM-AAA (Cognos Access Manager-
Authentication Authorization Accounting), Dispatcher, and Presentation Service. Most
services are optional, based on the required functionality of the overall system.

© Copyright IBM Corp. 2010, 2016 1-25

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 1 Introduction and Service-Oriented Architecture

Explain SOA communication in IBM Cognos 11

• IBM Cognos services communicate using the BIBus.
• Messages:
 SOAP 1.1
 Wrapped in <SOAP-ENV:Envelope> element
 Include BIBusHeader as a component
• BIBus:
 Is a set of protocols
 Governs communications among IBM Cognos services

Introduction and Service-Oriented Architecture © Copyright IBM Corporation 2016

Explain SOA communication in IBM Cognos 11

The BIBus is not software, but is a development component like Content Manager. The
BIBus header in the SOAP message contains user preferences, session information,
message routing information, and other status-like elements.
SOAP is an XML-based protocol that is transported over HTTP, HTTPS, and other
protocols. SOAP is an encapsulation protocol that is used to wrap XML messages.
Messages in SOAP 1.1 have a defined namespace of:
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/".
SOAP 1.2 messages do not have to be of the namespace SOAP_ENV, but they could
be if the SOAP-ENV namespace was defined as xmlns:SOAP-
ENV="http://www.w3.org/2003/05/soap-envelope" (notice the differences in the URL
compared to SOAP 1.1).

© Copyright IBM Corp. 2010, 2016 1-26

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 1 Introduction and Service-Oriented Architecture

Examine external IBM Cognos Analytics services

Platform BI Server
 Content Manager Service  Graphics Service*  (Batch) Report Service
 Agent Service  Content Manager Cache Service*  Query Service*
 Event Management Service  Index XXX Service*
 Delivery Service  Human Task Service*
 Job Service  Annotation Service*
 Monitor Service  Interactive Discovery Visualization
 Metadata Service Service**
 Presentation Service  Repository Service**
 Report Data Service  Relational Metadata Service**

* new services as of IBM Cognos 10.1

** new services as of IBM Cognos 10.2.0

Introduction and Service-Oriented Architecture © Copyright IBM Corporation 2016

Examine external IBM Cognos Analytics services

The platform services are the core services required for the system to work. In fact,
platform services will make use of other platform services. In addition, if you install BI
Server, you would get BI specific services as shown.
Adding companion products may add more services, but the companion products will
also require the platform services.

© Copyright IBM Corp. 2010, 2016 1-27

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 1 Introduction and Service-Oriented Architecture

Examine add-on installs

• Can be added to existing installed instance.
• Usually add new services.
• Examples:
 IBM Cognos PowerPlay Server: PowerPlay Service
 IBM Cognos Metric Studio: Metrics Service, Data Integration Service

Introduction and Service-Oriented Architecture © Copyright IBM Corporation 2016

Examine add-on installs

Installing new products may add new services to the main installed instance of IBM
Cognos Analytics; this is how SOA works.
As of IBM Cognos BI version 10.2.2, IBM Cognos Mobile is part of the core BI server
components, and is also included as part of IBM Cognos Analytics. It does not require
an additional installation.

© Copyright IBM Corp. 2010, 2016 1-28

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 1 Introduction and Service-Oriented Architecture

Demonstration 1
Explore an IBM Cognos Analytics environment

Introduction and Service-Oriented Architecture © Copyright IBM Corporation 2016

Demonstration 1: Explore an IBM Cognos Analytics environment

© Copyright IBM Corp. 2010, 2016 1-29

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 1 Introduction and Service-Oriented Architecture

Demonstration 1:
Explore an IBM Cognos Analytics environment

Purpose:
You want to familiarize yourself with the distributed environment of IBM
Cognos 11 at your company. To do this, you will explore the system and its
configuration.
In this environment, the installation and configuration of components uses a technique
that has these components installed to different directories in the same physical
environment, to simulate a distributed environment.
At the end of this demonstration, there is an installation map that may be a helpful
reference throughout this course.
Important information: Before doing this demonstration, in the BI environment, in the
Taskbar, click Services to ensure that the following services are started:
• Apache Directory Server - default
• DB2-DB2COPY1 - DB2
• DB2DAS - DB2DAS00
• World Wide Web Publishing Service
• IBM Cognos Full:9315
• IBM Cognos DispCM:9320
If any of the services are not running, start them and then close the Services window.
Be patient when starting these services, as they will take some time.
Note: Always start Apache Directory Server - default before the IBM Cognos Services,
and start IBM Cognos Full:9315 completely before starting
IBM Cognos DispCM:9320.
When starting the IBM Cognos services, a message will appear about not starting the
service in a timely fashion; close the message and wait for two minutes before you click
Refresh on the Services toolbar. You may have to refresh in two minute increments to
see a status of Started.

© Copyright IBM Corp. 2010, 2016 1-30

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 1 Introduction and Service-Oriented Architecture

Task 1. Explore the installed instances on the system.

1. From the Start menu, click All Programs.
Notice that there are multiple instances of various IBM Cognos Products
available. The entries that you will work with in this demonstration appear as
follows:

Note that your Start menu may not appear exactly as pictured, but all of the
above folders should exist.
IBM Cognos Analytics DispCM is an install of a Dispatcher and standby Content
Manager. IBM Cognos Analytics Full is a full installation of Dispatcher, Content
Manager, and Gateway. IBM Cognos Analytics Samples is the installation of
sample data for IBM Cognos. IBM Cognos Cube Designer is an install of IBM
Cognos Cube Designer. IBM Cognos Dynamic Query Analyzer is an install of
IBM Cognos Query Analyzer. IBM Cognos Framework Manager is an install of
Framework Manager.
2. Click each instance mentioned in Step 1 and review what is available to you.
Notice that with the exception of IBM Cognos Analytics Samples, there is an
instance of IBM Cognos Configuration for each installation.

© Copyright IBM Corp. 2010, 2016 1-31

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 1 Introduction and Service-Oriented Architecture

3. Under IBM Cognos Analytics Full, click IBM Cognos Configuration, and
then in the Explorer pane, click the Environment node.
A section of the result appears as follows:

You may have to scroll or resize your window to see all the contents shown.
4. In the Explorer pane, click IBM Cognos services, and familiarize yourself with
the services available and the settings that have been configured in this install
instance.
5. In the Explorer pane, under the Data Access node, click Content Manager,
and then click Content Store, and review the settings.
Notice that the Content Store database name is cm, and that it is a DB2
database. You will look at the content store in a later task.
6. Close IBM Cognos Configuration when you have finished reviewing the
settings. Click No if you are prompted to save changes.
7. Repeat steps 3 to 6 for the IBM Cognos Analytics DispCM instance of IBM
Cognos Configuration.
This installation contains a backup Content Manager, in the event that the
Content Manager in the Full installation fails.
8. Close IBM Cognos Configuration when you have finished reviewing the
settings.

© Copyright IBM Corp. 2010, 2016 1-32

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 1 Introduction and Service-Oriented Architecture

9. Repeat step 3 for the following IBM Cognos Configuration instances:

• IBM Cognos Cube Designer
• IBM Cognos Dynamic Query Analyzer
• IBM Cognos Framework Manager
These components have no server components, so steps 4 and 5 are not
necessary here.
10. Close each instance of IBM Cognos Configuration when you have finished
reviewing the settings.
Task 2. Explore the directory structure.
There are different install directories for IBM Cognos that you will use in this course.
• C:\Program Files\IBM\cognos\analytics_full
(64-bit BI Server: Dispatcher, Content Manager, Gateway)
• C:\Program Files\IBM\cognos\ analytics_DispCM
(64-bit BI Server: Dispatcher, Content Manager)
• C:\Program Files\IBM\cognos\dcubemodel
(64-bit Dynamic Cube Designer)
• C:\Program Files\IBM\cognos\dqa
(64-bit Dynamic Query Analyzer)
• C:\Program Files (x86)\IBM\cognos\model
(32-bit Framework Manager)
• C:\Program Files (x86)\IBM\cognos\c10
(32-bit Samples)
1. Start Windows Explorer, and navigate to C:\Program Files\IBM\cognos.
For most of this course, you will be working with the analytics_full directory as
the main IBM Cognos Analytics installation directory reference.
2. Expand analytics_full, and review the directories that reside there.
3. Double-click the logs directory, to review the contents.
You will make use of this directory during the Logging section of this course.
4. On the toolbar click the Back button to go up a level, double-click the
configuration directory, and review the items which reside there.
5. On the toolbar click the Back button to go up a level, and then double-click the
webapps directory, which is where servlet applications reside.
Webapps is a standard name defined in the servlet specification.

© Copyright IBM Corp. 2010, 2016 1-33

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 1 Introduction and Service-Oriented Architecture

6. Expand webapps\p2pd\WEB-INF.
This is where the workings of IBM Cognos 11 reside.
7. Close Windows Explorer.
Task 3. Explore the content store.
1. From the Start menu, navigate to All Programs\IBM Data Studio\Data Studio
4.1.0.0 Client.
Data Studio Client opens (this will take a few moments). If you are prompted to
specify a workspace, leave the default folder path selected, select the Use this
as the default and do not ask again check box, and then click OK.
If a Windows Security Alert dialog box appears containing a message related to
Windows Firewall, click Allow access.
2. Maximize the window, in the Administration Explorer pane on the left side,
and then expand localhost and DB2.
The databases configured that you will use in this course are AUDIT, CM, and
GS_DB.

3. In the Administration Explorer pane, right-click the CM database and click

Connect.
The Properties for CM window opens.
4. If prompted, in the User name box, type C10User, in the Password box, type
Education1, select the Save password check box and then click OK.
You are connected to the CM database (this may take a few moments).
5. In the Administration Explorer pane, expand the CM database (if necessary)
and click the Tables folder.
You can see the tables that are populated in the content store (this may take a
few moments).
If you receive an error or don't see the folder structure when trying to view the
database tables, right-click the CM database, click Disconnect, and then
connect to the database again.

© Copyright IBM Corp. 2010, 2016 1-34

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 1 Introduction and Service-Oriented Architecture

6. Repeat steps 3 to 6 to see the tables in the GS_DB database. In step 4, specify
a user name of db2admin.
This database is populated with items from GO Sales and GO Data Warehouse
that are used when authoring and running reports.
7. When you are finished reviewing the content, close the IBM Data Studio
window. If necessary, select the Always exit without prompt check box and
then click OK.
Results:
You explored the IBM Cognos 11 system and its configuration to become
familiar with the distributed environment you will be using. The environment
contains a distributed IBM Cognos 11 install consisting of one Gateway, two
Dispatchers, one active Content Manager, and one backup Content Manager.

© Copyright IBM Corp. 2010, 2016 1-35

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 1 Introduction and Service-Oriented Architecture

Installation map

VLCASSBASE IBM Cognos 11 Full

Components: Gateway, Samples
Computer name: vclassbase
Web Tier
Port #: 88

IBM Cognos 11 Full IBM Cognos 11 DispCM IBM Cognos 11 FM

Application Components: Application Tier Components: Application Tier Components: Framework
Tier Components/Dispatcher, Dynamic Query Components/Dispatcher Manager
Analyzer, IBM Cognos Cube Designer Computer name: vclassbase Computer name: vclassbase
Computer name: vclassbase Port #: 9320
Port #: 9315
IBM Cognos for Microsoft Office
Components: IBM Cognos for Microsoft
Office

IBM Cognos 11 Full 3rd party software:

Components: Content Manager  IIS Web Server Port #: 88
Data Tier Computer name: vclassbase
Port #: 9315  IBM DB2 Express v10.5.3 (content store db, audit
db, query db) Port #: 50000
IBM Cognos 11 DispCM  Lotus Domino Server (mail server) Port #: 25
Components: Content Manager (standby)
 Apache Directory Server (authentication db) Port
Computer name: vclassbase
#: 389
Port #: 9320

Introduction and Service-Oriented Architecture © Copyright IBM Corporation 2016

Installation map
The installation map provides a virtual topology of where IBM Cognos Analytics
components are installed in the environment used in this course. The tiers are logical.
There is no physical separation of components. All installations are on the same OS,
however the components have been virtually separated by installing to different
directories and by configuring using different port numbers. Apache Directory Server,
IBM DB2 Express 10.5, and IIS Web Server are also installed and configured.
• IBM Cognos 11 Full includes installation of the optional gateway in Web tier
(logical), application tier components\dispatcher in Application Tier (logical), and
Content Manager in Data Tier (logical)
• IBM Cognos 11 DispCM includes installation of application tier
components\dispatcher in Application Tier (logical), and Content Manager in Data
Tier (logical).
• IBM Cognos 11FM includes installation of Framework Manager in Application
Tier (logical)

© Copyright IBM Corp. 2010, 2016 1-36

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 1 Introduction and Service-Oriented Architecture

Demonstration 2
Set up the TCPMonitor utility and perform a request

Introduction and Service-Oriented Architecture © Copyright IBM Corporation 2016

Demonstration 2: Set up the TCPMonitor utility and perform a request

© Copyright IBM Corp. 2010, 2016 1-37

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 1 Introduction and Service-Oriented Architecture

Demonstration 2:
Set up the TCPMonitor utility and perform a request

Purpose:
As an administrator, you want to examine requests and responses for your IBM
Cognos 11 environment. In order to do this, you will set up the TCPMonitor
utility that is bundled with IBM Cognos 11, configure a Listener, and then review
the results.
TCPMonitor is a useful tool to view requests and responses. It can also be set to
simulate a slow connection, allowing you to set Bytes per Pause and Delay in
Milliseconds when you create a new TCP/IP Monitor. This can be useful when testing
Web services.
Task 1. Set Up the TCPMonitor utility.
1. Start Windows Explorer, navigate to
C:\Program Files\IBM\cognos\analytics_full\webapps\p2pd\WEB-INF, and
then double-click tcpmon.bat.
The TCPMonitor window appears.
2. Configure the Listener as follows:
• Listen Port #: 9999
• Target Hostname: vclassbase
• Target Port#: 88

© Copyright IBM Corp. 2010, 2016 1-38

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 1 Introduction and Service-Oriented Architecture

3. Click Add.
4. If a Windows Security Alert dialog box appears, select only the Private
networks, such as my home or work network check box, and then click
Allow access.
A new tab with Port 9999 on it appears in the TCPMonitor window. This will let
you view the HTTP requests and responses in IBM Cognos 11. The Listener is
configured for an unused port.
5. Click the Port 9999 tab.
The Listener has started, and is waiting. On this tab, you will see a list of
requests made to IBM Cognos 11 and can review the HTTP messages for both
the requests and responses in the pane below the list, as they are made to
IBM Cognos 11, when a user is logged on.

Browser TCPMonitor vclassbase:88

Address Listen Port: 9999
http://vclassbase: Target Hostname:
9999 vclassbase
Target Port: 88

© Copyright IBM Corp. 2010, 2016 1-39

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 1 Introduction and Service-Oriented Architecture

Task 2. Connect to IBM Cognos 11 and view the results of

requests and responses.
1. Launch Internet Explorer, and then resize the browser window and adjust the
layout of windows on your monitor, so that you can see both the browser and
TCPMonitor windows.
2. In the browser Address box, type http://vclassbase:9999/ibmcognos/bi/ and
then press Enter.
You are redirecting the request to the configured listen port of your Listener,
which will act as an intermediary to trap the requests as they are passed
through the gateway. You should see results in TCPMonitor as the connection
is made and the login screen appears in your browser. They will appear similar
to those shown below:

Notice the State column. Be sure to watch as the next step happens, as you will
see Req change to Done. Another state you may see in TCPMonitor is Active.
The middle pane displays requests, and the bottom pane displays responses by
vclassbase:88.
3. In the browser, log in with admin\Education1 credentials, and then review the
results in TCPMonitor. It may take a few moments to log on.

4. In the browser, click Team content , and then navigate to

Samples_DQ\Models, as you observe the messages passing through the
Listener, with each request made.
5. In the browser, navigate to GO Sales (analysis)\Report Studio Report
Samples, and then run the 2011 Sales Summary_DQ report (this will take a
while to complete).
If you receive a timeout-related error, close the Web browser window and
repeat steps 1 to 5 again.

© Copyright IBM Corp. 2010, 2016 1-40

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 1 Introduction and Service-Oriented Architecture

6. Review the results in TCPMonitor.

The buttons at the bottom of TCPMonitor let you configure the messages to be
XML formatted, saved, and resent. You can also switch the layout of the
message windows. If you develop Web services, this type of monitoring enables
you to review the requests without stopping or starting the server.
7. When you have finished reviewing requests and responses in TCPMonitor,
close the browser window, close TCPMonitor and then close Windows
Explorer.
In your environment, you could configure TCPMonitor to trace SOAP requests
and responses, by pointing the Listener to a modified WSDL (Web Services
Description Languages) file. This option is available if IBM Cognos SDK is
installed in your environment, or if you have a third-party WSDL file in your
environment.
Results:
You used TCPMonitor to trace and view requests and responses, such as when
users log in to use IBM Cognos 11.

© Copyright IBM Corp. 2010, 2016 1-41

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 1 Introduction and Service-Oriented Architecture

Unit summary
• Identify IBM Cognos 11 architectural components
• Describe Service-Oriented Architecture in IBM Cognos

Introduction and Service-Oriented Architecture © Copyright IBM Corporation 2016

Unit summary

© Copyright IBM Corp. 2010, 2016 1-42

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 1 Introduction and Service-Oriented Architecture

Reference of Acronyms:
AAA Authentication Authorization Accounting
ACL Access Control List
ADO Active X Directory Objects
API Application Interface
AR Active Report
ATC Application Tier Components
BAPI Business Application Programming Interface
BIBUS Communication between services (protocol)
BME BMT Engine
BMT Batch Metadata Tool
BMTFW Batch Metadata Tool Framework Manager
BMTFW BMT UI Framework
CAF Cognos Application Firewall
CAM Cognos Access Manager
CATALINA_OPTS Variable for Apache Tomcat
CCD Cognos Content Database
CFX GetCFXHandler
CGI Common Gateway Interface
CM Content Manager
CMM Metric Studio
COBRA Common Object Request Broker Architecture
CQE Cognos Query Engine
CRP Cryptography
CRX Cognos Report Expression
CSK Common Symmetric Keystore
DA&M Data Access and Modeling
DIS Data Integration Service
DISP Dispatcher
DLS Delivery Service
DMB Dynamic MOLAP Builder
DMR Dimensionally Modeled Relational
DOM Document Object Model
DQA Dynamic Query Analyzer
DQM Dynamic Query Mode
DRU Dynamic Reportspec Updater
EMS Event Management Service
ES Event Studio
FFP Full Fidelity Publish
FM Framework Manager
FMMD Framework Manager MetaData

© Copyright IBM Corp. 2010, 2016 1-43

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 1 Introduction and Service-Oriented Architecture

FMEE Framework Manager Expression Editor

FMUI Framework Manager User Interface
GMT Greenwich Mean Time
GS Graphics Service
GUI Graphical User Interface
GUID Globally Unique Identifier
GW Gateway
HTTP Hypertext Transfer Protocol
HTTPS Hypertext Transfer Protocol Secure
HTS Human Task Service
HWM Heavy Weight Modeling
IDViz Interactive Discovery Visualization
IETF Internet Engineering Task Force
IIOP Internet Inter-ORB Protocol
IIS Microsoft Internet Information Services
IPF Indication Processing Facility
IPRF In-Process Request Factor
ISAPI Internet Server Application Programming Interface
Java EE Java Platform, Enterprise Edition
JDBC Java Database Connectivity
JBOSS JBOSS Applicaton Server
JMS Job Management Service
JNI Java Native Interface
JS Java Scheduler
JSM Java Schedule Manager
JRE Java Runtime Environment
JSON JavaScript Object Notation
JVM Java Virtual Machine
LOG4J Java-based logging utility
LWM Light Weight Modeling
MDDS Multidimensional Data Services
MDF Meta Data Framework
MDX Multidimensional Expression Language
MFW Metadata Framework
MS Monitor Service
MM Metrics Manager
MMS Metrics Manager Service
MOB Mobile, Mobile Service
MOLAP Multidimensional Online Analytical Processing
MQP Metadata Query Planner
OQP OLAP Query Planner
OSGI Open Services Gateway Initiative

© Copyright IBM Corp. 2010, 2016 1-44

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 1 Introduction and Service-Oriented Architecture

PDF Portable Document Format

POGO Dispatcher
PP PowerPlay
PPDS PowerPlay Data Services
PPDSWeb PowerPlay Data Service Web
PPDSrm PowerPlay Data Services Remote
PPDSrms PowerPlay Data Services Remote Service
PPES PowerPlay Enterprise Server
PPRP PowerPlay Report Processor (PDF)
PPRS PowerPlay Report Service
PRS Presentation Service
PWQ PWQHandler
PWR PWRHandler
QECL Query Engine Common Library
QF Query Framework
QFW Query Framework Components
QFW/QFWP Query Framework
QFWP Query Framework Planner
QRD Query Result Definition
RFC Remote Function call
RMI Remote Methods Invocation
RMP Reporter Mode Provider
RQP Relational Query Planner
RSAPI Result Set Application Programming Interface
RSVP Report Server Manager
RTM Release to Manufacturing
RTM Run time Model
SDK Software Development Kit
SLWM Shared Lightweight Modeling
SMTP Simple Mail Transfer Protocol
SOA Service Oriented Architecture
SOAP Simple Object Access Protocol
SQL Structured Query Language
SSO Single Sign-On
TR, TRAN Transformer
UI User Interface
UDA Universal Data Access
URI Uniform Resource Identifier
URL Uniform Resource Locator
XML Extensible Markup Language
XSL Extensible Stylesheet Language

© Copyright IBM Corp. 2010, 2016 1-45

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 1 Introduction and Service-Oriented Architecture

XTS XML Transformation Service component used to generate

HTML pages. (xts.run, seen in IBM Cognos URLs). Different
from PRS.
XXS Cross Site Scripting

© Copyright IBM Corp. 2010, 2016 1-46

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
Explore the IBM Cognos Dispatcher

Explore the
IBM Cognos Dispatcher

IBM Cognos Analytics 11.0

© Copyright IBM Corporation 2016

Course materials may not be reproduced in whole or in part without the written permission of IBM.
 Unit 2 Explore the IBM Cognos Dispatcher

© Copyright IBM Corp. 2010, 2016 2-2

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 2 Explore the IBM Cognos Dispatcher

Unit objectives
• Describe IBM Cognos Dispatcher
• Describe request routing and the routing process
• Describe Content Manager Cache Service

Explore the IBM Cognos Dispatcher © Copyright IBM Corporation 2016

Unit objectives

© Copyright IBM Corp. 2010, 2016 2-3

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 2 Explore the IBM Cognos Dispatcher

What is a thread?
• Unit of processing time scheduled by the operating system

Explore the IBM Cognos Dispatcher © Copyright IBM Corporation 2016

What is a thread?
Threads, or threads of execution, are the smallest unit of processing time that is
scheduled by the operating system (OS). You can have more than one thread of
execution in a process. Multiple threads can share resources, as subsets of a process,
but processes handle resources differently than threads and are typically independent.
Multi-threading can be handled by the OS distributing to different Central Processing
Units (CPU). Programs must be carefully designed in such a way that all the threads
can run at the same time without interfering with each other.

© Copyright IBM Corp. 2010, 2016 2-4

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 2 Explore the IBM Cognos Dispatcher

What is a servlet?
• Multi-threaded program
• Handles HTTP requests sent to it in one or multiple threads
• Responds by HTTP

Explore the IBM Cognos Dispatcher © Copyright IBM Corporation 2016

What is a servlet?
Servlets will use threads within the application server process scope, proportional to the
number of requests sent to it. Servlets are the application tier equivalent to CGI
programs in the Web tier, as they typically do not implement business logic.
A servlet is a Java program which runs in a specific environment, the servlet container
as defined by the Java EE framework. The Java EE framework is typically implemented
by a Java application server like WebSphere, or JBOSS.
A servlet cannot be run stand-alone but rather runs within the process of the container,
and serves the single purpose to accept a request received by the servlet container and
passed to it.

© Copyright IBM Corp. 2010, 2016 2-5

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 2 Explore the IBM Cognos Dispatcher

What is a process?
• An instance of a computer program that is being executed.
• It executes instructions.

Explore the IBM Cognos Dispatcher © Copyright IBM Corporation 2016

What is a process?
While a program itself is a passive collection of instructions, a process is something
which executes those instructions. Several processes can be associated with the same
program, although each would execute independently. A single process is always
assigned to a single physical CPU.

© Copyright IBM Corp. 2010, 2016 2-6

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 2 Explore the IBM Cognos Dispatcher

What is the IBM Cognos Dispatcher?

• Java servlet
• Multi-threaded
• Available in Application Tier and Content Manager install components
• Interface to BIBus for local IBM Cognos services

Dispatcher
(Java)
Servlet name: dispatcher

Content Manager (CM)

(Java)

Servlet name: CM Servlet

Explore the IBM Cognos Dispatcher © Copyright IBM Corporation 2016

What is the IBM Cognos Dispatcher?

The IBM Cognos Dispatcher hosts IBM Cognos services exposed by the components
of the installed service. The dispatcher starts all local services as configured in IBM
Cognos Configuration, with the exception of the Content Manager service, which is
separate.

© Copyright IBM Corp. 2010, 2016 2-7

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 2 Explore the IBM Cognos Dispatcher

Examine the dispatcher and the BIBus

BIBus
Dispatcher
(Java) Dispatcher
(Java)
Application Tier Application Tier
Report Server PowerPlay Server
Content Manager
(C++) (C++) (Java)

Dispatcher
(Java)
Dispatcher
Dispatcher (Java)
Application Tier (Java)
Report Server Application Tier
Application Tier
(C++) Report Server PowerPlay Server
Content Manager
(Java) (C++) (C++)

Explore the IBM Cognos Dispatcher © Copyright IBM Corporation 2016

Examine the dispatcher and the BIBus

Only dispatchers sit on the BIBus. All inter-system communication travels this bus,
although services require a dispatcher to gain access to the BIBus. In other words, all of
the installations use the BIBus to communicate with each other, and all communication
is done through the dispatchers.
The diagram shows multiple installed instances with different sets of install
components.

© Copyright IBM Corp. 2010, 2016 2-8

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 2 Explore the IBM Cognos Dispatcher

Describe the dispatcher

• Registers with Content Manager service on startup
• Implements request routing

Dispatcher
(Java)

Application Tier Application Tier

Report Server PowerPlay Server
(C++) (C++)

Dispatcher
(Java)

Content Manager
(Java)

Explore the IBM Cognos Dispatcher © Copyright IBM Corporation 2016

Describe the dispatcher

As the dispatcher registers with the Content Manager service, it enables built-in failover
handling, and the dispatcher is assigned a unique ID. The registration can be revoked
through IBM Cognos Administration, as in the case of a server name change during
migration.
The dispatcher implements request routing as an internal service, and then forwards
the requests to locally hosted service instances. The dispatcher can also forward
requests to other dispatchers on the BIBus hosting remote service instances.
For the dispatcher to route requests to remote dispatchers through the BIBus, each
dispatcher requires knowledge about other dispatchers in the system, the services
hosted by the other dispatchers, and the status of the services on the other dispatchers.
You will explore this in Demonstration 1: Review the Output of p2plbDiag.
If a dispatcher fails or is unavailable, requests for that dispatcher are routed to the next
available dispatcher until the failed dispatcher updates its status to active again. For this
to work dispatchers require knowledge about other dispatchers in the system, and a
mechanism to determine whether a dispatcher is available or down; this is done by
registration in the content store through the Content Manager service.

© Copyright IBM Corp. 2010, 2016 2-9

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 2 Explore the IBM Cognos Dispatcher

What is the purpose of request routing?

• Delivers client requests to the correct IBM Cognos service as quickly
as possible.
• Is influenced by:
 Load balancing
 External factors
 Configuration items

Explore the IBM Cognos Dispatcher © Copyright IBM Corporation 2016

What is the purpose of request routing?

Request routing is the task of delivering client requests, and is influenced by many
factors and underlying concepts.
Load balancing may be affected by the targeted service or the number of available
instances of that service. External factors such as system load, dispatcher hardware
resources, or external routing software or hardware, may influence the request routing
of a dispatcher. Advanced routing configuration based on user identity or packages
used can also impact request routing.

© Copyright IBM Corp. 2010, 2016 2-10

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 2 Explore the IBM Cognos Dispatcher

Describe request routing concepts

• Role of gateway
• Cluster information
• Front dispatchers
• Request queue
• Conversations
• Request affinity
• Customizations

Explore the IBM Cognos Dispatcher © Copyright IBM Corporation 2016

Describe request routing concepts

Over the next few pages, the request routing concepts listed in the slide will be
presented.

© Copyright IBM Corp. 2010, 2016 2-11

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 2 Explore the IBM Cognos Dispatcher

Describe the role of the gateway

• Relays request to a single dispatcher.
• Does not load balance or route.
• List of dispatchers in gateway configuration is for
fail-over only.
• Pings all configured dispatchers every 30 seconds or on forward
failure.

Explore the IBM Cognos Dispatcher © Copyright IBM Corporation 2016

Describe the role of the gateway

The dispatcher list for a gateway is specified in IBM Cognos Configuration. The
gateway will work down the list in the order specified, so if the first dispatcher is not
available, the gateway tries the second dispatcher, and so on.
If the gateway pings a dispatcher, and encounters a second failed attempt to connect,
that dispatcher is marked as unavailable for this cycle.

© Copyright IBM Corp. 2010, 2016 2-12

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 2 Explore the IBM Cognos Dispatcher

Describe dispatcher cluster information

• Dispatcher cluster information includes:
 List of dispatchers registered to the system
 Server groups they are assigned to
 IBM Cognos services hosted by each dispatcher and the running state of
those services
• The dispatcher cluster information provides each dispatcher with a
landscape of the system.

Explore the IBM Cognos Dispatcher © Copyright IBM Corporation 2016

Describe dispatcher cluster information

As part of their start-up, each dispatcher registers itself with Content Manager by
querying the Content Manager service for dispatcher cluster information, and then the
dispatcher joins the system. With the dispatcher cluster information, a dispatcher can
eventually forward requests to remote dispatchers and services that are based on it.
The Content Manager service is the keeper and creator of the dispatcher cluster
information.
Cluster refers to an entity where several servers are joined together. When a dispatcher
registers with Content Manager, they are essentially reporting their part that Content
Manager will put into the larger system.
Server group is a property of a dispatcher, and will be mentioned later in this unit.

© Copyright IBM Corp. 2010, 2016 2-13

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 2 Explore the IBM Cognos Dispatcher

Explore dispatcher cluster information details

• Updated automatically.
• Dispatchers query CM service for the cluster information.
• Can take up to one minute to be propagated to all dispatchers in the
IBM Cognos system.
• Accessible through:
 http://<INTERNAL_DISP_URI>/p2plbDiag
 Any dispatcher on the IBM Cognos system

Explore the IBM Cognos Dispatcher © Copyright IBM Corporation 2016

Explore dispatcher cluster information details

The dispatcher cluster information updates automatically when a new dispatcher is
added to the system or removed from the system. Dispatchers will query the CM
service at regular intervals to signal that they are active and to update their local cluster
information.
INTERNAL_DISP_URI refers to the internal dispatcher URI from IBM Cognos
Configuration. In a default install this will be
http://localhost:9300/p2pd/servlet/dispatch/p2plbDiag.
p2plbDiag shows information about a specific dispatcher including GUID and server
group, all known dispatchers, and load balancing statistics.

© Copyright IBM Corp. 2010, 2016 2-14

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 2 Explore the IBM Cognos Dispatcher

Demonstration 1
Review the output of p2plbDiag

Explore the IBM Cognos Dispatcher © Copyright IBM Corporation 2016

Demonstration 1: Review the output of p2plbDiag

© Copyright IBM Corp. 2010, 2016 2-15

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 2 Explore the IBM Cognos Dispatcher

Demonstration 1:
Review the output of p2plbDiag

Purpose:
You want to use p2plbDiag to review information about a specific dispatcher
including GUID and server group, all known dispatchers, and load balancing
statistics.
At the beginning of this demonstration, only the IBM Cognos Full:9315 dispatcher
needs to be running. Stop the IBM Cognos DispCM:9320 dispatcher service if it is
running, before you begin this demonstration.
Task 1. Access p2plbDiag and log on.
1. Launch Internet Explorer, in the Address box, type
http://vclassbase:9315/p2pd/servlet/dispatch/p2plbDiag, and then press
Enter.
2. Log in as admin/Education1.
If you are prompted to turn AutoComplete on, click No.
Task 2. Review the results of p2plbDiag and the current
system.
1. Use the results to answer the following:
• Dispatcher:
• GUID:
• Content Manager (CM):
• Server Group:
• Load Balancing Mode:
• Disabled Services:
• Are there multiple dispatchers available?

© Copyright IBM Corp. 2010, 2016 2-16

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 2 Explore the IBM Cognos Dispatcher

A section of the result appears similar to the following:

The information here should match up with your configuration settings in IBM
Cognos Administration. You can use this as a quick way to find out if the
Dispatcher is available; you can also determine this in IBM Cognos
Administration.
If you see two dispatchers (http://vclassbase:9315/p2pd and
http://vclassbase:9320/p2pd) listed on this page, you may need to:
a) Close the Web browser.
b) Stop the IBM Cognos DispCM:9320 service if it is not already stopped.
c) Restart the IBM Cognos Full:9315 service.
d) Wait 60 seconds.
e) Reopen the Web browser and browse to
http://vclassbase:9315/p2pd/servlet/dispatch/p2plbDiag again (logging
on as admin/Education1 when prompted).
Now that you can see one Dispatcher is registered and available in the
environment, what will happen if another Dispatcher is running? Will the
registered Dispatcher display in p2plbDiag?
2. Close the browser window.

© Copyright IBM Corp. 2010, 2016 2-17

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 2 Explore the IBM Cognos Dispatcher

Task 3. Start the second dispatcher and observe the result.

1. In the Taskbar, click the Services icon, and then start the IBM Cognos
DispCM:9320 service.
It will take a few minutes to start the service, and you may get a message
indicating that the service did not start in a timely fashion (click OK to dismiss
this message). Wait until this instance has fully started (you may do a refresh of
the display every two minutes) before proceeding to the next step.
2. When the service has started successfully, in Internet Explorer, go to
http://vclassbase:9315/p2pd/servlet/dispatch/p2plbDiag, and log in (if
prompted) as admin/Education1.
If you are prompted to turn AutoComplete on, click No.
A section of the result appears similar to the following:

© Copyright IBM Corp. 2010, 2016 2-18

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 2 Explore the IBM Cognos Dispatcher

3. Use the result to answer the following:

• What is the result of the number of available dispatchers?
• What does this say about the output of p2plbDiag and registered
dispatchers?
The dispatchers displayed in p2plbDiag are only active dispatchers. Dispatchers
that are registered to the Content Manager service are not displayed in
p2plbDiag unless they are currently available.
4. Close the browser window, and the Services window.
Results:
You used p2plbDiag to review information about a specific dispatcher,
including GUID and server group, all known dispatchers, and load balancing
statistics.

© Copyright IBM Corp. 2010, 2016 2-19

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 2 Explore the IBM Cognos Dispatcher

Describe front dispatchers

• First dispatcher to touch on a request.
• May require specific IBM Cognos services to be available to handle
some requests.
• Multiple front dispatchers can exist if there are multiple gateways.
• Start request routing.

Explore the IBM Cognos Dispatcher © Copyright IBM Corporation 2016

Describe front dispatchers

The list of dispatcher URIs for a gateway configuration should only contain those
dispatchers that are capable of acting as a front dispatcher that can offer the required
services. All gateways could have the same front dispatcher, but that would always
funnel requests to a single dispatcher and hinder efficient failover as well as introduce a
single point of failure. A front dispatcher is a dispatcher that is referred to by a gateway
and one that interacts directly with external clients such as SDK apps.
The theoretical reason that this is important is that certain services must be enabled on
a Front Dispatcher. In practice this is not an issue because all services are turned on by
default after an install. However, one of these required services is the
DispatcherService() and a Content Manager only install does not enable the
DispatcherService() so what this means is that you should not configure a Gateway to
use a dispatcher from a CM-only install. This is intentional, and should not be changed
under normal circumstances. A front dispatcher will need to run the Presentation
service for SSO (Single Signon).

© Copyright IBM Corp. 2010, 2016 2-20

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 2 Explore the IBM Cognos Dispatcher

Describe the dispatcher request queue

• Each dispatcher manages a queue for requests.
• Request queues develop due to:
 Demand being greater than resource provided
 Time intensive requests
 Inappropriate tuning of capacity and process allocation across dispatchers

Explore the IBM Cognos Dispatcher © Copyright IBM Corporation 2016

Describe the dispatcher request queue

If the number of execution type requests for a certain service is greater than the number
of requests which can be handled at a time by that service at the given dispatcher, then
a dispatcher request queue is developed. This is also the case for long running
database or cube queries that are time intensive, or if capacity tuning is not done
properly.

© Copyright IBM Corp. 2010, 2016 2-21

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 2 Explore the IBM Cognos Dispatcher

Examine the details of the request queue

• Latency
• Monitored in IBM Cognos Administration tool

Explore the IBM Cognos Dispatcher © Copyright IBM Corporation 2016

Examine the details of the request queue

The amount of time a request has spent in the queue is called latency.
Note: The values displayed on the service monitoring page in the IBM Cognos
Administration console are 30 to 60 seconds behind the actual activity. This is
not real-time monitoring.

© Copyright IBM Corp. 2010, 2016 2-22

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 2 Explore the IBM Cognos Dispatcher

Considerations for the request queue

• Resolution of queues may not be required.
• Queues should be managed to avoid bigger problems later.

Explore the IBM Cognos Dispatcher © Copyright IBM Corporation 2016

Considerations for the request queue

Resolution of queues may not be required if performance is within usage expectations.
Examples of specific resolutions to manage queues include:
• add service instances (a benefit of SOA)
• provide more resources to process more requests for that particular local service
• in a distributed environment, monitor and tune process capacity for optimal
request dispatching
• design queries and reports for better performance
• scale the system up or out by adding more hardware capacity
For more information, refer to the IBM Cognos System Management Methodology
(SMM) on developerWorks. At time of printing, this is available on developerWorks on
the IBM Web site at
http://www.ibm.com/developerworks/data/library/cognos/infrastructure/cognos_specific/
page587.html. This is a group of documents and examples provided to administrators
for information and techniques in using IBM Cognos Administration.

© Copyright IBM Corp. 2010, 2016 2-23

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 2 Explore the IBM Cognos Dispatcher

What is a conversation?
• Sequence of requests sent from the client to a specific service.
• Example of conversation, running an HTML report:
 Database connectivity prompts
 Parameter selection prompts
 Query execution status updates
 Paging through HTML output

Explore the IBM Cognos Dispatcher © Copyright IBM Corporation 2016

What is a conversation?
In many situations, an operation is processed using a sequence of requests sent from
the client to a specific service. This sequence of requests is known as a conversation.

© Copyright IBM Corp. 2010, 2016 2-24

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 2 Explore the IBM Cognos Dispatcher

Explore the benefits of conversations

• Avoid browser and network timeout.
• Allows user actions during execution (such as cancel).
• Allows detection of server failure and recovery.
• Allows detection of client abandonment.

Explore the IBM Cognos Dispatcher © Copyright IBM Corporation 2016

Explore the benefits of conversations

The system operates most efficiently when all of the requests in a conversation are
handled by the same instance of the targeted service. Request routing must support
this as a priority.

© Copyright IBM Corp. 2010, 2016 2-25

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 2 Explore the IBM Cognos Dispatcher

Examine the usual conversation

• Starts with primary request such as run().
• Subsequent requests such as nextPage() within the same conversation
are secondary requests.
• If preferred service instance unavailable, secondary request can be
fulfilled by any other instance of the targeted service.

Explore the IBM Cognos Dispatcher © Copyright IBM Corporation 2016

Examine the usual conversation

A primary request, such as run(), can be fulfilled equally well by any instance of the
requested service; these are known as low-affinity requests.
Secondary requests can be fulfilled best by the same instance of the targeted service
that handled the previous primary or secondary request; these are known as high-
affinity requests.
If the preferred service instance is not available, routing to the non-preferred service
instance is known as failover. Requests fulfilled by the non-preferred service instance
will run slower since the service must first recreate the conversation state.

© Copyright IBM Corp. 2010, 2016 2-26

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 2 Explore the IBM Cognos Dispatcher

What are asynchronous conversations?

• If the primary or secondary request cannot complete within the Primary
Wait Threshold, the service returns a status of Working in the response
to the client, and processes the request asynchronously.
• Client then issues heartbeat requests such as wait() until the service
has completed work on previous primary or secondary request.
• Dispatcher cancels asynchronous conversation if no heartbeats are
received within Secondary Wait Threshold.

Explore the IBM Cognos Dispatcher © Copyright IBM Corporation 2016

What are asynchronous conversations?

When the request is processed asynchronously, it is commonly referred to as going
asynchronous. The default length of the Primary Wait Threshold is 7 seconds.
Heartbeats must be served by the same service instance that still works the primary or
secondary request (no failover is possible); these requests are known as
absolute-affinity requests.
The dispatcher will cancel an asynchronous conversation if a heartbeat is not received
from the client within the Secondary Wait Threshold, such as when a user has
abandoned the conversation, or cancelled the request by calling cancel(). These
requests are known as control-affinity requests, and are like absolute-affinity requests
but are not queued by the dispatcher. The default length of the Secondary Wait
Threshold is 30 seconds.
There is nothing that the end user should need to do when a conversation ends for
whatever reason. The dispatcher and the other services are aware of
abandoned/cancelled/completed conversations and will do whatever they need to do to
release resources that they have allocated to that conversation. No cleanup needs to
be done for abandoned conversations.

© Copyright IBM Corp. 2010, 2016 2-27

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 2 Explore the IBM Cognos Dispatcher

What are grouped conversations?

• Conversations can be grouped
 multiple runSpecification() requests may be issued to test reports
 can leverage Report Server caching

Explore the IBM Cognos Dispatcher © Copyright IBM Corporation 2016

What are grouped conversations

If during IBM Cognos Analytics authoring sessions, many runSpecification() requests
are issued to test reports, you can leverage report server caching if all of these primary
requests are sent to the same instance of ReportService. These requests are known as
session-affinity requests.
You can disable session caching at the server level or at the package or report level.
Refer to the IBM Cognos Version 11.0.0 Administration and Security Guide for more
information.

© Copyright IBM Corp. 2010, 2016 2-28

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 2 Explore the IBM Cognos Dispatcher

Describe request affinity

• Requests handled by the dispatcher.
• A request has affinity or is subject to load balancing.
• Primary requests are low affinity.
• Secondary requests usually have an affinity.

<bus:conversationContext xsi:type="bus:conversationContext">
<id>yMdhMlysGsGhw9hqqqd24hhCdMvqClvv9hdd9G99</id>
<nodeID>2015-03-19_14:26:53.641_165</nodeID>
<processID>1</processID>
<affinityStrength>5000</affinityStrength>
<status>complete</status>
</bus:conversationContext>

Explore the IBM Cognos Dispatcher © Copyright IBM Corporation 2016

Describe request affinity

Conversations imply affinity, a measure of how important it is to route a request to a
specific instance of an IBM Cognos service and hence to the dispatcher hosting that
instance.
Request affinity is denoted in the suffix of the SOAPAction header, which is set and
handled internally.
The <bus:conversationContext> element of a BIBus SOAP message contains
information about the affinity request such as the dispatcher ID, affinity strength and
status of the conversation.
The example in the slide is a sample conversationContext header.
Request affinity is different from server affinity, which will be covered later for
BIBusTKServerMain (Report Server). Request affinity relates to requests being handled
by the dispatcher. The affinity concept contradicts load balancing; a request either has
affinity or it is subject to load balancing. Request affinity is handled internally and cannot
be manipulated.

© Copyright IBM Corp. 2010, 2016 2-29

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 2 Explore the IBM Cognos Dispatcher

Define request affinity assignments

• (none) or low affinity
• .high
• .session
• .absolute
• .control

Explore the IBM Cognos Dispatcher © Copyright IBM Corporation 2016

Define request affinity assignments

In the case of the assignment of no or low affinity, the dispatcher is free to route the
request to any running instance of a service.
With high affinity, the dispatcher should try to route the request to the dispatcher that is
specified by the node ID. If the requested dispatcher is not available then this request is
treated as having no affinity. The node ID in the BIBusHeader is mandatory.
Session affinity is the same as high affinity, except the node ID in the BIBusHeader is
optional. If no node ID is specified, this request is treated as having no affinity.
For absolute affinity, the dispatcher must route the request to the dispatcher specified
by the node ID. If the specified dispatcher is not available, the request will fail and a
SOAP Fault is returned. The dispatcher can queue these requests.
Control affinity is the same as absolute affinity, with the difference that it is never
queued. This is reserved for system operations such as cancel(), and these requests
cannot be queued at the dispatcher.

© Copyright IBM Corp. 2010, 2016 2-30

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 2 Explore the IBM Cognos Dispatcher

Review request routing

• Only dispatchers implement request routing.
• Requests handled in conversations:
 primary and secondary requests
 secondary requests usually have an affinity
• Dispatchers can queue requests except control affinity requests.
• Request routing can be customized.

Explore the IBM Cognos Dispatcher © Copyright IBM Corporation 2016

Review request routing

Gateways do not contribute to request routing; only dispatchers implement request
routing. Dispatchers queue requests if they cannot be processed fast enough.

© Copyright IBM Corp. 2010, 2016 2-31

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 2 Explore the IBM Cognos Dispatcher

Consider customization
• Improve performance.
• Implement specific requirements.
• Implement by runtime configuration.
• Use care when customizing request routing.

Explore the IBM Cognos Dispatcher © Copyright IBM Corporation 2016

Consider customization
Customizations can be implemented by runtime configuration, and include load
balancing modes and advanced routing.
Customizing request routing is delicate, as a configuration based on uninformed
decisions can hinder performance. Implementation complexity differs from system to
system and should be evaluated beforehand, as there may be other approaches to
consider.

© Copyright IBM Corp. 2010, 2016 2-32

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 2 Explore the IBM Cognos Dispatcher

What load balancing modes are available?

• Weighted Round Robin
• Cluster Compatible

Explore the IBM Cognos Dispatcher © Copyright IBM Corporation 2016

What load balancing modes are available?

Only primary requests are subject to load balancing.
Load balancing is set in the Load balancing mode property of a dispatcher. All
dispatchers in a single system must have the same setting.
The Processing capacity property is located in the IBM Cognos Administration console,
on the Configuration tab, in the properties of the target dispatcher. The Processing
capacity value is arbitrarily assigned based on hardware resources of the dispatcher
host system. Although fractional numbers can be used they should be avoided.

© Copyright IBM Corp. 2010, 2016 2-33

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 2 Explore the IBM Cognos Dispatcher

Explain weighted round robin mode

GW

A C

Explore the IBM Cognos Dispatcher © Copyright IBM Corporation 2016

Explain weighted round robin mode

Weighted round robin (WRR) is the default algorithm where requests are distributed
equally between all dispatchers, one after another. The weighted variant allows a
dispatcher to have higher capacity than another dispatcher. The processing capacity
setting of a dispatcher determines the weight, with the default is set as 1.0.
If Dispatcher A has a weight of 2 and Dispatcher B has a weight of 1, Dispatcher A
would receive twice as many requests as Dispatcher B. This method is used to account
for different hardware resources in a multi-server environment.

© Copyright IBM Corp. 2010, 2016 2-34

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 2 Explore the IBM Cognos Dispatcher

Weighted round robin in IBM Cognos 11

GW

A C

Explore the IBM Cognos Dispatcher © Copyright IBM Corporation 2016

Weighted round robin in IBM Cognos 11

In IBM Cognos Analytics 11 there is an additional factor to weighted round robin:
In-Progress Request Factor (IPRF). This is configured as an advanced property of a
dispatcher and applies to all services or particular service(s) of a dispatcher. IPRF
specifies the factor by which the number of requests (of a particular service) that are
executing or waiting at a particular dispatcher or dispatcher queue should influence the
weighted round robin. This helps to prevent overloading slow dispatchers and service
instances. IPRF allows adaptive influence to the algorithm and automatically adjusts to
the system load.
In example on the slide, assume that the ReportService on Dispatcher A has been
assigned 4 long runners (for example, still executing after 10 minutes); it would be
suboptimal to assign another request for ReportService to A even if WRR has
concluded that it should go to A. The IPRF will negatively influence A's weight, thus
leading to the request being assigned elsewhere.

© Copyright IBM Corp. 2010, 2016 2-35

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 2 Explore the IBM Cognos Dispatcher

For information on tuning the weighted round robin load balancing using the processing
capacity and inProgressRequestFactor, go to:
• http://www.ibm.com/support/knowledgecenter/SSEP7J_11.0.0/com.ibm.swg.ba.c
ognos.ug_cra.11.0.0.doc/t_balancerequestsamongdispatchers.html%23Balance
RequestsAmongDispatchers?lang=en
IPRF applies on top of WRR, is off by default and has to be enabled explicitly. IPRF can
be set for a single service or all services. The best practice is to use a value of 2.0. 0.0
means normal WRR.
For example: WRR treats every primary request equally. There is no way the routing
can know how long a certain request will take. This can lead to overloading a certain
service instance/dispatcher although capacity is properly set; IPRF was introduced to
alleviate this kind of issue.

© Copyright IBM Corp. 2010, 2016 2-36

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 2 Explore the IBM Cognos Dispatcher

Explain cluster compatible mode

Example:
GW  poor setup; not all nodes
run similar services
 request for Service S is
assigned to Dispatcher A by
external mechanism X
 S is not available locally, so
the fall-back of Weighted
X Round Robin is used; it will
be assigned to Dispatcher B
eventually
 this is a case of double
routing

A B C

S
Explore the IBM Cognos Dispatcher © Copyright IBM Corporation 2016

Explain cluster compatible mode

The load balancing mode of cluster compatible supersedes routing, as it gives
precedence to local processing. The dispatcher tries to assign a request to a local
instance of the requested service first, if this fails, the internal weighted round robin load
balancing is used. Cluster compatible mode is used for environments where load
balancing between dispatchers is performed externally, such as clustered WebSphere
deployments.
In this mode, all dispatchers are required to host identical sets of IBM Cognos services.
You should not modify the service configuration on the running instances. Requests
which are not subject to load balancing will still get routed by the dispatcher.

© Copyright IBM Corp. 2010, 2016 2-37

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 2 Explore the IBM Cognos Dispatcher

Only WebSphere clustering is supported.

The concept of a cluster implies the same services are on each participating dispatcher
because a single application tier files package is deployed to multiple instances of the
application server. The application server treats them as equal and applies its own
external load balancing based on its metrics. The application server is not aware of
different service configurations per dispatcher/node which could occur due to
configuration in IBM Cognos Administration. The phrase "external load balancing
between dispatchers" can involve external load balancers, software or hardware, or
even external load balancers in front of gateways which use different front dispatchers
to forward their requests to.
Service configuration changes to an instance that is running could cause cluster
compatible load balancing to fail as all of the instances will no longer be identical.

© Copyright IBM Corp. 2010, 2016 2-38

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 2 Explore the IBM Cognos Dispatcher

What is advanced routing?

• Provides flexibility.
• Requires planning and testing.
• Increases maintenance complexity.
• Works with server groups and routing sets.

Explore the IBM Cognos Dispatcher © Copyright IBM Corporation 2016

What is advanced routing?

Advanced routing can serve advanced configuration requirements where execution
type requests should be routed to specific sets of dispatchers based on the group or
role that the executing user is a member of, or the package used for the execution. This
is an example of a setup for charge-back accounts, which is used for tracking
computing resource usage by business departments or projects, such as a Marketing
Department or Summer Promotions project.
Advanced routing can also be based on data source availability or on packages which
reference specific data sources.

© Copyright IBM Corp. 2010, 2016 2-39

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 2 Explore the IBM Cognos Dispatcher

What are server groups?

• Dispatchers are arranged in server groups.
• Default server group contains all dispatchers.
• Define additional explicitly named server groups for advanced routing.
• Define associations for request execution, as in clusters.
• Saved in the content store.

Explore the IBM Cognos Dispatcher © Copyright IBM Corporation 2016

What are server groups?

Each dispatcher is a member of a single server group. There is an unnamed default
server group that initially contains all dispatchers, but it is invisible and cannot be
managed like other server groups.
Server groups define association for request execution which can include application
clusters, Charge-Back scenarios (either by user or by application), and provide
heterogeneous database access (not all machines may have access to all databases).
Server groups are saved in the Content Store (the central repository of the system) and
are managed through IBM Cognos Administration. Folders defined in IBM Cognos
Administration to contain dispatchers do not automatically imply server groups.
Whenever requests have a target Server Group defined, it will route to that group, but
Server Groups will be ignored if there is no specific target Server Group, and instead,
the current Server Group would be used.

© Copyright IBM Corp. 2010, 2016 2-40

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 2 Explore the IBM Cognos Dispatcher

Server group considerations

• Content Manager should be in the default server group.
• What comes to the server group stays in that server group
 advanced routing exception

Explore the IBM Cognos Dispatcher © Copyright IBM Corporation 2016

Server group considerations

With the exception of advanced routing, what comes to a server group stays in that
server group, where the request will be handled in the server group that the dispatcher
to receive the request initially is a member of. Not all dispatchers can handle all types of
requests due to services that are available.
From this it becomes clear that load balancing only happens within a server group.

© Copyright IBM Corp. 2010, 2016 2-41

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 2 Explore the IBM Cognos Dispatcher

Example of server groups

Default
Dispatcher 1 Dispatcher 3

Dispatcher 5
Server Group 1 Server Group 2
CM
Dispatcher 2 Dispatcher 4

Explore the IBM Cognos Dispatcher © Copyright IBM Corporation 2016

Example of server groups

One scenario:
• Server Group 1: handles sales reports
• Server Group 2: handles marketing reports
• Default: Rest of the users

© Copyright IBM Corp. 2010, 2016 2-42

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 2 Explore the IBM Cognos Dispatcher

Describe routing sets

• Group routing set
• Role routing set
• Package routing set

Explore the IBM Cognos Dispatcher © Copyright IBM Corporation 2016

Describe routing sets

Routing sets allow advanced routing to route execution type requests based on groups,
roles or packages. A routing set is a label assigned to a set of requests based on
different purposes. A group routing set is based on requests from a group from any
namespace. A role routing set is based on roles from any namespace. A package
routing set is based on packages.

© Copyright IBM Corp. 2010, 2016 2-43

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 2 Explore the IBM Cognos Dispatcher

What are routing rules?

• Link routing sets to a server group.
• Stored in a global list.
• Parsed in sequence.

Explore the IBM Cognos Dispatcher © Copyright IBM Corporation 2016

What are routing rules?

A routing rule consists of three conditions logically concatenated by AND, and a target
server group. Each condition can reference a routing set of a specific type, or remain
neutral (any package\group\role).
In routing rules, the first match is used, and subsequent rules are ignored. The request
will fail if the target server group does not exist or the requested service does not exist
in that server group.
The slide shows the ordered list of routing rules. You can specify the routing rules in
IBM Cognos Administration\Configuration\Dispatchers and Service\Toolbar\Specify
Routing Rules. In this example routing sets are defined to server groups named
Group 32 and Group 64.

© Copyright IBM Corp. 2010, 2016 2-44

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 2 Explore the IBM Cognos Dispatcher

Routing rule considerations

• Request matches routing rule if:
 executed by member of a group/role which is assigned to referenced
group/role routing set.
 report executed based on package which is part of referenced package
routing set.

Explore the IBM Cognos Dispatcher © Copyright IBM Corporation 2016

Routing rules considerations

Routing rules affect non-affine requests for all executing services such as:
• (Batch)ReportService
• PPESService (PowerPlay Enterprise Server)
• GraphicsService
• MetadataService (MDS)

© Copyright IBM Corp. 2010, 2016 2-45

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 2 Explore the IBM Cognos Dispatcher

Explain advanced routing

• Content manager matches routing rules.
• Sender of execution request supplies target server group information.
• Advanced routing takes precedence over load balancing.

Explore the IBM Cognos Dispatcher © Copyright IBM Corporation 2016

Explain advanced routing

The sender of an execution request supplies the target server group information, such
as needing the Presentation Service for interactive reports, or the Monitoring Service for
batch reports. The sender queries the Content Manager Service for the object to
execute, and the response will contain target server group information if applicable. The
sender adds the target server group to the BIBusHeader of the request, and then
passes the request to its local dispatcher.
The dispatcher routes accordingly, keeping in mind that advanced routing takes
precedence over load balancing.
The matching of routing rules is performed by Content Manager, not by a dispatcher.

© Copyright IBM Corp. 2010, 2016 2-46

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 2 Explore the IBM Cognos Dispatcher

Describe steps of the routing process

1. Identify target service.

2. Determine if request is for content manager service.

3. If absolute affinity request, route to requested dispatcher.

4. From cluster information, deduce set of potential target dispatchers

request could be assigned to.

5. Within the cluster view, try assigning affine requests to desired dispatcher.
If this fails, treat request as non-affine.

6. If cluster compatible load balancing enabled, look for a local instance of

requested service. If local dispatcher is within the cluster view, assign
there, else continue to Step 7.

7. Evaluate load balancing (weighted round-robin) within the cluster view.

Explore the IBM Cognos Dispatcher © Copyright IBM Corporation 2016

Describe steps of the routing process

Step 1. The targeted IBM Cognos service is identified based on the following
information in this order:
1. SOAPAction header (E.g. http://developer.cognos.com/schemas/reportService/1)
2. Service Mappings
3. b_action variable in an HTML FORM or URL parameter
4. element in the path component of the URL of the request (such as /cgi-
bin/cognosisapi.dll/gd/) used to retrieve pre-rendered output such as a chart
If none of the above, the request is forwarded to the Presentation service to display the
IBM Cognos Analytics Welcome page.
Step 2. Is this a request for the Content Manager service? If so, forward the request to
the active Content Manager Service.
Step 3. If this is this is an absolute affinity request, route to the requested dispatcher.

© Copyright IBM Corp. 2010, 2016 2-47

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 2 Explore the IBM Cognos Dispatcher

Step 4. From the cluster information, deduce the set of potential target dispatchers the
request could be assigned to. This set of target dispatchers is known as the cluster
view (CV). If advanced routing is configured, this will be the set of dispatchers within the
requested server group, otherwise the request goes to the default server group.
Advanced routing will simply limit the set of potential target dispatchers. Since every
dispatcher has the cluster information available, it can deduct the set of dispatchers
belonging to a certain server group.
Step 5. Within the cluster view, try assigning affine requests to the desired dispatcher. If
this fails, treat request as non-affine. Affinity means the dispatcher tries to assign the
request to a certain dispatcher as indicated by the NodeID in the BIBusHeader. If that
fails, it is treated as non-affine, or having no affinity.
Step 6. If cluster compatible load balancing is enabled, look for a local (on this
dispatcher) instance of the requested service. If the local dispatcher is within the cluster
view, assign there, otherwise continue to Step 7. For cluster compatible load balancing
there is always an attempt to assign the request to a local instance of the requested
service. If this does not exist or the local dispatcher is not within the Cluster View, the
request is load balanced. This will precede advanced routing because although the
request should go to a specific server group, it could remain local. This adds to the point
that it is illogical to have server groups in a cluster which are used to model different
service layouts and/or resources. In a cluster, all nodes are considered equal.
Step 7. Evaluate load balancing (weighted round robin) within the cluster view. How
many instances of the identified IBM Cognos service are active in the current server
group?
= 0 - produce error
= 1 - assign request to IBM Cognos service
> 1 - evaluate weighted round robin and assign

© Copyright IBM Corp. 2010, 2016 2-48

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 2 Explore the IBM Cognos Dispatcher

Routing process: Example 1

GW

AR

A C

D
Affine Request

Dispatchers
Explore the IBM Cognos Dispatcher © Copyright IBM Corporation 2016

Routing process: Example 1

Scenario: An affine request for Dispatcher C hits Dispatcher B.
Using the steps provided on the previous pages as a guideline, what happens? A
possible explanation is provided on the next page.

© Copyright IBM Corp. 2010, 2016 2-49

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 2 Explore the IBM Cognos Dispatcher

1. Identify the target service.

2. Determine if the request is for the Content Manager service.
3. If it is an absolute affinity request, route it to the requested dispatcher.
4. From cluster information, deduce set of potential target dispatchers that the
request could be assigned to. (Cluster view = A, B, C, D)
5. Within the cluster view, try assigning affine requests to the desired dispatcher. If
this fails, treat the request as non-affine. (Try to route to C, but service is down.)
6. If cluster compatible load balancing is enabled, look for a local instance of the
requested service. If a local dispatcher is within the cluster view, assign there.
(Does not apply in this case.)
7. Evaluate load balancing (weighted round robin) within the cluster view. Evaluate
load balancing within default server group and assign.

© Copyright IBM Corp. 2010, 2016 2-50

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 2 Explore the IBM Cognos Dispatcher

Routing process: Example 2

GW

NR
Server Group 1 Server Group 2
B

A C

Cluster Compatible Dispatchers Non-affine Request

Non-Cluster Compatible Dispatchers

Explore the IBM Cognos Dispatcher © Copyright IBM Corporation 2016

Routing process: Example 2

Scenario: Dispatchers A, B, and C are cluster-compatible.
Server Group 1: Dispatcher A
Server Group 2: Dispatchers B, C
External load balancing is assigned. A non-affine request for a service in Server
Group 2 goes to Dispatcher A.
Using the steps provided on the previous pages as a guideline, what happens? A
possible explanation is provided on the next page.

© Copyright IBM Corp. 2010, 2016 2-51

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 2 Explore the IBM Cognos Dispatcher

1. Identify the target service.

2. Determine if the request is for the Content Manager service.
3. If it is an absolute affinity request, route it to the requested dispatcher.
4. From cluster information, deduce set of potential target dispatchers that the
request could be assigned to. (Cluster view = B, C)
5. Within the cluster view, try assigning affine requests to the desired dispatcher. If
this fails, treat the request as non-affine. (Does not apply in this case.)
6. If cluster compatible load balancing is enabled, look for a local instance of the
requested service. If a local dispatcher is within the cluster view, assign there.
Try assigning to service on Dispatcher A. Dispatcher A is not in the Cluster View
(B,C), so this will fail, regardless of whether the service does exist on
Dispatcher A.
7. Evaluate load balancing (weighted round robin) within the cluster view. Evaluate
load balancing within Server Group 2 and assign.

© Copyright IBM Corp. 2010, 2016 2-52

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 2 Explore the IBM Cognos Dispatcher

Things to remember
• Requests for Content Manager service get routed to active Content
Manager.
• What comes to a server group stays in that server group unless
advanced routing applies.
• Load balancing only happens within a server group.
• Secondary requests are usually not subject to load balancing as they
have an affinity assigned to them.
• Advanced routing applies to requests for execution type services.

Explore the IBM Cognos Dispatcher © Copyright IBM Corporation 2016

Things to remember
There is only one active Content Manager in an IBM Cognos system.
For advanced routing, be aware of how the Cluster View is built.
Only service instances within the same server group are available for load balancing.
Load balancing never routes a request to a different server group, as only advanced
routing can do that, however advanced routing happens before load balancing takes
place.
Advanced routing applies to requests for execution type services which include Batch
Report service, Graphics service, PPES service, and Metadata service.

© Copyright IBM Corp. 2010, 2016 2-53

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 2 Explore the IBM Cognos Dispatcher

What is Content Manager Cache Service?

• Each dispatcher maintains a local cache for objects retrieved from
Content Manager service.
• IBM Cognos Services will verify CMCS is available on the local
dispatcher, and then will query the local CMCS instead of Content
Manager service.

Explore the IBM Cognos Dispatcher © Copyright IBM Corporation 2016

What is Content Manager Cache Service?

The local cache on a dispatcher for objects retrieved from Content Manager service is
implemented by the ContentManagerCacheService (CMCS). This is used to decrease
load on the active Content Manager and improve the speed execution. Objects subject
to caching are Report, ReportCache, Package, Model, PackageConfiguration,
ModelView, DataSourceSignon, Account and Session. A best practice is to enable this
service on all dispatchers which run the Dispatcher service.
After having verified CMCS is available on the local dispatcher, IBM Cognos services
will query the local CMCS instead of CM Service.
CMCS is a feature introduced in IBM Cognos 10.1.1. Memory is taken from the Java
heap, and there is no JNI heap involved.
It is best practice to have CMCS enabled on all dispatchers which run the Dispatcher
service or in other words all possible front dispatchers. Therefore, this excludes
dispatchers of a Content Manager only install.
If this service is not available on a dispatcher which initially handles a request, there will
be no caching for that request.

© Copyright IBM Corp. 2010, 2016 2-54

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 2 Explore the IBM Cognos Dispatcher

Describe CMCS details

• Serves a primary or secondary request
• CacheContext
• Validator

Explore the IBM Cognos Dispatcher © Copyright IBM Corporation 2016

Describe CMCS details

CMCS either serves a primary or secondary request for some IBM Cognos service or
requests sent by other CMCS instances.
Each data item in the cache has context (CacheContext). This context is used to
evaluate if it matches a given query. The context may tie the item to a session or not, so
data may be shared across sessions if not subject to security.
A Validator is an object attached to each data item by CM. It allows probing for the
validity of cached data by using lightweight CM queries only. So it is validation over
querying an actual CM object which again saves load to the CM.
When CMCS has found an object in its cache, it has to ensure freshness. For that, it
validates the data if necessary. The CM query required for that is minimal though it
exists. To reduce the amount of validation queries, Validators may linger, so within the
linger timeout data will not be validated again. This is to serve high frequency queries to
the same objects. It carries some risk though, which will be presented on the Explain
CMCS Settings page.

© Copyright IBM Corp. 2010, 2016 2-55

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 2 Explore the IBM Cognos Dispatcher

Service a primary request

• If requested data is not in local cache or Validator is expired:
 query CM to fill cache; CM will supply the data and the automatically
attached Validator for it
 create CacheContext
 reset linger timer
• If linger timer is expired:
 validate the data by issuing a light-weight CM query
 reset linger timer
• Respond to query, attach CacheContext.
• Completed.

Explore the IBM Cognos Dispatcher © Copyright IBM Corporation 2016

Service a primary request

The slide lists a pseudo-code rundown of steps which the CMCS executes when
serving requests.

© Copyright IBM Corp. 2010, 2016 2-56

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 2 Explore the IBM Cognos Dispatcher

Service a secondary request

• If requested data is not in local cache:
 if request has CacheContext attached
− from CacheContext, retrieve address of remote CMCS with data and access of
that instance rather than CM Service
− add data to local cache and reset local linger timer
 else:
− query CM to fill cache; CM will supply data and the automatically attached
Validator for it
− create CacheContext and reset linger timer
 if linger timer is expired:
− validate data by issuing a light-weight CM query
− reset linger timer
 Respond to query, attach CacheContext.
 Completed.

Explore the IBM Cognos Dispatcher © Copyright IBM Corporation 2016

Service a secondary request

Linger time is how long the item in the cache lingers around.

© Copyright IBM Corp. 2010, 2016 2-57

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 2 Explore the IBM Cognos Dispatcher

Explain CMCS settings

• Memory limit
 set memory limit to 0 to disable CMCS
• Linger timer

Explore the IBM Cognos Dispatcher © Copyright IBM Corporation 2016

Explain CMCS settings

The memory limit for CMCS determines the maximum amount of Java heap taken from
the JRE hosting the Dispatcher for the cache. The cache size is dynamic. To disable
the CMCS, set the memory limit to zero (0).
Add an advanced parameter to CMCS, for the linger timer with the
DISP.contentManagerCacheService.cacheValidatorTimeToLinger property. The value
is in ms (milliseconds), with a default value of 30000. This setting determines the linger
time before data is validated again. This implies that changes within 30 seconds are not
automatically anticipated by CMCS.
Linger can lead to issues; if cache entries, for example, change frequently then lowering
the linger timeout may be required.

© Copyright IBM Corp. 2010, 2016 2-58

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 2 Explore the IBM Cognos Dispatcher

Describe timers
• Validation timer:
DISP.contentManagerCacheService.cacheValidatorTimeToLive
• Account inactivity timer:
DISP.contentManagerCacheService.accountInactivityTimer

Explore the IBM Cognos Dispatcher © Copyright IBM Corporation 2016

Describe timers
The validation timer determines how long data objects remain in the cache. After the
validation timer expires, objects are considered invalid and have to be fetched from the
CM again. Add the advanced parameter to CMCS for the validation timer, with the
DISP.contentManagerCacheService.cacheValidatorTimeToLive property. The value is
in ms, and the default value is 900000.
The account inactivity timer determines how long data for this session is cached. If the
session is idle for longer than the inactivity timer, all data cached for that account is
purged from the cache. This is a security and resource saving feature. Add the
advanced parameter to CMCS for the account inactivity timer, with the
DISP.contentManagerCacheService.accountInactivityTimer property. The value is in
ms, and the default value is 900000.

© Copyright IBM Corp. 2010, 2016 2-59

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 2 Explore the IBM Cognos Dispatcher

Unit summary
• Describe IBM Cognos Dispatcher
• Describe request routing and the routing process
• Describe Content Manager Cache Service

Explore the IBM Cognos Dispatcher © Copyright IBM Corporation 2016

Unit summary

© Copyright IBM Corp. 2010, 2016 2-60

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 2 Explore the IBM Cognos Dispatcher

Exercise 1
Review the server groups (optional)

Explore the IBM Cognos Dispatcher © Copyright IBM Corporation 2016

Exercise 1: Review the server groups (optional)

© Copyright IBM Corp. 2010, 2016 2-61

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 2 Explore the IBM Cognos Dispatcher

Exercise 1:
Review the server groups (optional)

As an administrator, you have configured server groups in your environment to let you
define advanced routing rules. You will review these settings in your environment using
p2plbDiag, and you will review the routing sets.
You will use p2plbDiag to review:
• The dispatcher vclassbase:9315/p2pd settings: What server group does the
dispatcher belong to?
• The dispatcher vclassbase:9320/p2pd settings: What server group does the
dispatcher belong to?
You will use IBM Cognos Administration to review:
• The dispatcher vclassbase:9315/p2pd settings: What server group does the
dispatcher belong to?
• The dispatcher vclassbase:9320/p2pd settings: What server group does the
dispatcher belong to?
You will use the IBM Cognos Analytics portal to review the routing sets for the
packages in:
• Team content\Samples\Models
• Team content \Samples_DQ\Models
• Team content \Samples_Dynamic_Cubes
You will use IBM Cognos Administration to review:
• the defined routing rules

For more information about where to work and the exercise results, refer to the Tasks
and Results section that follows. If you need more information to complete a task, refer
to earlier demonstrations for detailed steps.

© Copyright IBM Corp. 2010, 2016 2-62

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 2 Explore the IBM Cognos Dispatcher

Exercise 1:
Tasks and Results
The IBM Cognos Full:9315 dispatcher and the IBM Cognos DispCM:9320 dispatcher
should be running at the beginning of this exercise.
Task 1. Review the server groups in p2plbDiag.
• Launch Internet Explorer, and then go to
http://vclassbase:9315/p2pd/servlet/dispatch/p2plbDiag.
• Log in using admin/Education1 credentials.

The server group name is displayed for this dispatcher: Group 64, and the
second server group Group 32 is displayed for the vclassbase:9320/p2pd
dispatcher.
• Close the browser window when you have finished viewing the results.

© Copyright IBM Corp. 2010, 2016 2-63

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 2 Explore the IBM Cognos Dispatcher

Task 2. Review the server group settings in IBM Cognos

Administration.
• Launch Internet Explorer, go to http://vclassbase:88/ibmcognos/bi/, and then
log in as admin/Education1.

• Launch Administration console from the Manage tab.

• On the Status tab, click System. It may take a few moments for the Status tab to
refresh.
• In the upper-left corner of the Scorecard pane, click the All servers arrow to
display the Change view menu, and then click All dispatchers.

You can also set the server group property at the system level, rather than at this
level of detail.
• Next to the http://vclassbase:9315/p2pd dispatcher, click the Actions arrow,
and then click Set properties.
• Click the Settings tab, and then from the Category list, click Tuning.
• Notice that for the Server group property, in the Value column box, Group 64 is
the name of the server group.
This is where you can configure the Server group name when defining your
environment; you could also set this on the Configuration tab, on the Dispatchers
and Services pane.
You can assign multiple dispatchers to a server group.
• Click Cancel to close the Set properties dialog box.
• Optionally, repeat the steps to review the Server group property for the
http://vclassbase:9320/p2pd dispatcher.
These server group names can be used when you define routing rules.
• Close the IBM Cognos Administration browser tab.

© Copyright IBM Corp. 2010, 2016 2-64

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 2 Explore the IBM Cognos Dispatcher

Task 3. Review package routing sets that use the server

groups.
• On the Welcome browser tab, click Team content, and then navigate to
Samples\Models.
• Beside GO data warehouse (analysis), click the ellipsis, and then click
Properties.
• Expand the Advanced section.
• Beside Advanced routing, click Set.
Notice the current assigned routing set is 64.
This environment was configured to name the routing sets to align with the server
group names. The other option available is 32. The server groups have
dispatchers that are configured to handle either 32-bit ReportServer service
queries or 64-bit ReportServer service queries, as you cannot run both on the
same dispatcher.
All reports in this package, GO data warehouse (analysis) use the 64-bit
ReportServer for queries.
• Click Cancel to close the Assign routing sets dialog box.
• Optionally, repeat the steps to review the routing sets for any package in the
following Team content packages in:
• Samples_DQ\Models
• Samples_Dynamic_Cubes

© Copyright IBM Corp. 2010, 2016 2-65

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 2 Explore the IBM Cognos Dispatcher

Task 4. Review the routing rules.

• Launch Administration console, and then click the
Configuration tab\Dispatchers and Services pane.

• On the toolbar, click Specify Routing Rules .

Notice that in the Routing rules pane, there are two package-based routing sets
defined.
Also notice that routing sets can also be defined for groups and for roles.
For packages using routing set 32, notice that it is routed to the server group
"Group 32", which has dispatchers that are configured to use the 32-bit
ReportServer for queries.
Packages using routing set 64 are routed to "Group 64", which has dispatchers
that are configured to use the 64-bit ReportServer for queries.
• Click Cancel to close the Specify the routing rules dialog box, and then close
all browser tabs.

© Copyright IBM Corp. 2010, 2016 2-66

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
Examine IBM Cognos Services

Examine IBM Cognos

Services

IBM Cognos Analytics 11.0

© Copyright IBM Corporation 2016

Course materials may not be reproduced in whole or in part without the written permission of IBM.
 U n i t 3 E x a m i n e I B M C o g n o s S e r vi c e s

© Copyright IBM Corp. 2010, 2016 3-2

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 3 E x a m i n e I B M C o g n o s S e r vi c e s

Unit objectives
• Identify IBM Cognos Services
• Explore the architecture in IBM Cognos 11

Examine IBM Cognos Services © Copyright IBM Corporation 2016

Unit objectives

© Copyright IBM Corp. 2010, 2016 3-3

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 3 E x a m i n e I B M C o g n o s S e r vi c e s

What is Content Manager Service?

• Is implemented by the Content Manager (CM) component.
• Manages storage of IBM Cognos application data in central repository
Content Store (CS).

Dispatcher
(Java)

Content Manager
(Java)

Content Store

Examine IBM Cognos Services © Copyright IBM Corporation 2016

What is Content Manager Service?

CM is a Java Servlet and therefore must be deployed to a Servlet Container. If CM is
installed separately, the component comes bundled with a dedicated dispatcher which
is deliberately configured to not offer the Dispatcher service.
The CM service manages the storage of IBM Cognos application data in a central
repository known as the Content Store. Application data contains security (authorization
only), configuration data, models, metrics, report specifications, report output, and
more. The CM service automatically creates the Content Store tables and indexes on
first startup.

© Copyright IBM Corp. 2010, 2016 3-4

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 3 E x a m i n e I B M C o g n o s S e r vi c e s

Content Store is connected by JDBC (Type2/Type4). Type 2 JDBC drivers require a

local DB client; Type 4 JDBC drivers are standalone and usually only require JAR files.
Type 4 JDBC is supported for DB2 in IBM Cognos BI 10.2.2 and later.
The information stored by Content Manager includes:
• Reports: Specifications, properties, security settings, outputs.
• Report Packages: Metadata, reports, folders.
• Metric Packages: Metadata, scorecards, folders.
• Agents: Conditions, schedules, tasks used to monitor events and deliver
notifications. This includes the list of recently detected instances of an event.
• Server Configuration: Cognos namespace and information about contacts,
directory information, distribution lists, data sources, printers.
• Personal User Information: My Content.
• Language Information: Names, descriptions.

© Copyright IBM Corp. 2010, 2016 3-5

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 3 E x a m i n e I B M C o g n o s S e r vi c e s

What does Content Manager Service support?

• Failover through standby redundancy:
 multiple Content Manager install components installed in single IBM Cognos
system
 on initialization CM registers itself in Content Store database
 first CM registered becomes the active CM, all others which register
subsequently become standby
 if the active CM becomes unavailable, a standby CM will take over
 all non-local dispatchers will try to open a socket to the active CM every 5
seconds
 cluster information update every 30 seconds
 active CM can be specified using IBM Cognos Administration
• Does not support horizontal scaling.

Examine IBM Cognos Services © Copyright IBM Corporation 2016

What does Content Manager Service support?

Multiple content managers can be installed on the same computer or across different
computers. There are many considerations involved in such a decision, factors such as
hardware failover and redundancy requirements, number of processors in a machine,
and so on.
Horizontal scaling is leveraging multiple systems to work together in parallel with each
system has its own operating system and one or more processors. Therefore it is not
possible to have multiple primary content managers working at once.

© Copyright IBM Corp. 2010, 2016 3-6

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 3 E x a m i n e I B M C o g n o s S e r vi c e s

Report Service and Batch Report Service

Dispatcher
(Java) Report Server

Report Batch Report Port to port

BIBusTKServerMain
communication
Service Service
(C++ Multiplatform)
Content Manager
(Java)

Examine IBM Cognos Services © Copyright IBM Corporation 2016

Report Service and Batch Report Service

The Report service and Batch report service are implemented by C++ based
components which are referred to as report server (functional component).
Report service and Batch report service are two different service registrations which link
back to the same implementation in report server. Report service processes interactive
report executions, and Batch report service processes report executions triggered by
schedules and background requests. They are controlled by settings in the
reportservice.xml and batchreportservice.xml files, as well as other configuration files.
Report server instances run inside a separate process managed by the dispatcher. The
process name is BIBusTKServerMain, and an instance of BIBusTKServerMain is often
referred to as a BIBus. This is different from the BIBus protocol, which is SOAP over
HTTP.
Multiple instances of Report server can be spawned by a single dispatcher.

© Copyright IBM Corp. 2010, 2016 3-7

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 3 E x a m i n e I B M C o g n o s S e r vi c e s

Introduce BIBusTKServerMain
• Communication between dispatcher and Report server instances is by
TCP port to port connection.
• Report server instances:
 can be pre-started
 get spawned and destroyed dynamically
 linger; flagged for termination
 multi-threaded; number of threads is configurable
• Report server threads:
 can be used for internal operation
 can be dedicated to request processing only
 called affinity connections

Examine IBM Cognos Services © Copyright IBM Corporation 2016

Introduce BIBusTKServerMain
The protocol used for port to port connection is XML-based. A random port from the
OS's ephemeral port range is allocated at run-time, for the port-to-port communication.
An ephemeral port is a temporary port that can be assigned.
Threads may be distributed among cores in a multi-core CPU. Threads will typically not
spawn across CPUs, although exceptions may apply depending on the CPU
architecture.
To leverage multiple CPUs, usually multiple processes are required.

© Copyright IBM Corp. 2010, 2016 3-8

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 3 E x a m i n e I B M C o g n o s S e r vi c e s

Explain report execution in IBM Cognos

• Conversation, an operation consisting of multiple steps
• Two phases
 synchronized
 asynchronous
• Each step is a different request
• Requests of a conversation have affinity assigned
 primary request of a conversation: low affinity
 secondary requests of a conversation: high affinity

Examine IBM Cognos Services © Copyright IBM Corporation 2016

Explain report execution in IBM Cognos

Report execution in IBM Cognos is a conversation. Like any other dispatcher
conversation, it happens in two phases. In the synchronized phase, the client and
server wait for a result for the amount of time specified by the primary wait threshold
(the default is 7 seconds) blocking all participating resources. In the asynchronous
phase, the request progresses at the server, but the client and the dispatcher only ping
for results every now and then (secondary wait threshold, default 30 seconds) and free
resources otherwise.
For request routing, the affinity assigned to requests is the basis of routing conversation
requests to a specific instance of (Batch)Report Service (request affinity). For the local
dispatcher or Report service, this affinity determines to which instance of report server
the request has to be assigned (server affinity).
In the context of a conversation, the term server refers to both the target IBM Cognos
Service and the dispatcher which routed the request to the service. Both will hold on to
a thread for the duration of the primary wait threshold. For more information about
conversations, refer to Unit 2: Explore the IBM Cognos Dispatcher, on the topic
Conversations.

© Copyright IBM Corp. 2010, 2016 3-9

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 3 E x a m i n e I B M C o g n o s S e r vi c e s

Describe server affinity: Low

• Perform equally well.
• Previously processed requests have no relevance.
• Examples:
 administrative: add objects, refresh
 authoring: query validation
 report execution: querying, processing, prompting

Examine IBM Cognos Services © Copyright IBM Corporation 2016

Describe server affinity: Low

Low affinity requests will operate efficiently on any computer, regardless of the Report
server instance they are assigned to. For example, a report request can run on any
computer in the IBM Cognos 11 system. A low affinity request is used with the following
operations: add, collectParameterValues, execute, getMetadata, getParameters, query,
testDataSourceConnection, update, and validate.

© Copyright IBM Corp. 2010, 2016 3-10

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 3 E x a m i n e I B M C o g n o s S e r vi c e s

Describe server affinity: High

• Specific requests that can benefit from previously processed requests
at this instance.
• Perform optimally if routed to the same report server instance.
• Examples:
 report viewing: return, run again
 HTML report navigation: Top/Bottom page, Page up/down
 report delivery: E-mail, Save, Save As, Print

Examine IBM Cognos Services © Copyright IBM Corporation 2016

Describe server affinity: High

IBM Cognos 11 routes high affinity requests to a specific server regardless of the load
balancing. A high affinity request is used with the following operations: back, email,
firstPage, forward, lastPage, nextPage, previousPage, print, render, save, and saveAs.

© Copyright IBM Corp. 2010, 2016 3-11

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 3 E x a m i n e I B M C o g n o s S e r vi c e s

Describe server affinity: Absolute

• Must be routed to a specific instance of report server, otherwise will fail
• Can be considered secondary requests which fully depend on a
previous request.
• Examples:
 wait (driving an async conversation)
 cancel
 getOutput (retrieve a completed rendered output)
 release (graceful end of a conversation)

Examine IBM Cognos Services © Copyright IBM Corporation 2016

Describe server affinity: Absolute

IBM Cognos 11 routes absolute affinity requests to a specific server, regardless of the
load balancing. An absolute affinity request is used with the following operations: wait,
getOutput, and release.

© Copyright IBM Corp. 2010, 2016 3-12

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 3 E x a m i n e I B M C o g n o s S e r vi c e s

Describe affinity connections

• Pooled by request affinity per service instance.
• Allocation of affinity connections determines the creation of new report
server instances.
• Example:
 by default each report server instance for Report service has 4 low affinity
connections, 2 high affinity connections
 every 3rd low affinity request sent to Report service will trigger a new
instance

Examine IBM Cognos Services © Copyright IBM Corporation 2016

Describe affinity connections

There are two pools for affinity connections, one for high affinity and one for low affinity,
for both Report service and Batch Report service. This means that if both Report
service and Batch report service are enabled for an installed instance, then there are
four pools. Absolute affinity is handled internally and therefore has no separate pool.
The allocation of affinity connections determines the creation of new Report Server
instances. If half the number of the connections of a pool are already allocated, a new
instance of Report Server (BIBusTKServerMain) will be spawned for this service if the
configured maximum of processes has not been reached yet. The affinity connection of
the new instances will get added to the pools thus increasing the sizes of the pool.

© Copyright IBM Corp. 2010, 2016 3-13

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 3 E x a m i n e I B M C o g n o s S e r vi c e s

Example of affinity connections

Dispatcher
(Java)

BIBusTKServerMain BIBusTKServerMain
(C++) (C++)

High

High
Low

Low

Low

Low

Low

Low

Low
Low
Low Affinity = Initial report run, get report properties
High Affinity = Page Down, Bottom in a report
Examine IBM Cognos Services © Copyright IBM Corporation 2016

Example of affinity connections

There will be many instances of BIBusTKServerMain. Each dispatcher may manage
requests for multiple report servers. Low affinity requests can be handled by any report
server. Typically, low affinity requests are used when a report or data movement run is
initially requested.
High affinity requests are ideally handled by a specific report server. Typically, high
affinity requests are for reports that were already requested and may include actions,
such as going to the next page in a report.

© Copyright IBM Corp. 2010, 2016 3-14

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 3 E x a m i n e I B M C o g n o s S e r vi c e s

Describe affinity connection assignment

• Eventually report execution requests get assigned to an affinity
connection of a report server.
• Affinity connections remain assigned or unavailable:
 for the duration of the request
 or the request terminates due to user action or failure

Examine IBM Cognos Services © Copyright IBM Corporation 2016

Describe affinity connection assignment

Eventually report execution requests, get assigned to an affinity connection of a report
server. Affinity connections do not switch servers in mid-request.
If a user terminates the browser session, cancels a request, or logs out of IBM
Cognos 11, the request will terminate.

© Copyright IBM Corp. 2010, 2016 3-15

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 3 E x a m i n e I B M C o g n o s S e r vi c e s

Management of affinity connection assignment

• Dispatcher manages:
 assignment of requests to one specific instance of Report server
 map of Report server affinity connections
• Report servers manage:
 allocation of their affinity connections
 high affinity and low affinity

Examine IBM Cognos Services © Copyright IBM Corporation 2016

Management of affinity connection assignment

The dispatcher manages assignment of requests to one specific instance of report
server spawned for either Report service or Batch report service, and manages a map
of affinity connections on a report server instance, keeping track of assigned
connections vs. available connections.
The report servers manage the allocation of their affinity connections, but are otherwise
bare of assignment logic.

© Copyright IBM Corp. 2010, 2016 3-16

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 3 E x a m i n e I B M C o g n o s S e r vi c e s

Explain affinity connection configuration

• Configured in IBM Cognos Administration:
 affinity is a tuning setting
 peak periods and non-peak periods
 at the dispatcher level
 at the Report service level or Batch report service level
• Must be configured based on solid information:
 monitor the system to learn about load patterns
 leverage audit database for report usage
statistics

Examine IBM Cognos Services © Copyright IBM Corporation 2016

Explain affinity connection configuration

The configuration of affinity connections is one of many important settings involved with
system performance. It must be configured based on solid information. If this is
configured based on uninformed decisions your system can become slow or stop,
because of overloading resources. This is not a simple case of more is better.
For more information on leveraging monitoring the system to learn about load patterns,
refer to the IBM Cognos System Management Methodology (SMM) on the IBM Web
site at
http://www.ibm.com/developerworks/data/library/cognos/infrastructure/cognos_specific/
page587.html.

© Copyright IBM Corp. 2010, 2016 3-17

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 3 E x a m i n e I B M C o g n o s S e r vi c e s

Describe scheduling
• Event Management Service (EMS)
• Monitor Service (MS)
• Delivery Service (DLS)
• Job Service (JS)

Examine IBM Cognos Services © Copyright IBM Corporation 2016

Describe scheduling
Scheduling is handled by several IBM Cognos services.
EMS monitors the global Scheduler Queue and detects when a scheduled task is due
to execute. If a background task is due to be run, EMS creates an entry in the global
Task Queue using a local JDBC connection to the Notification Database, and executes
legacy code which adds a notification about the task to be executed to the JMS queue.
Multiple instances of EMS will scale horizontally and can be run independently from
other scheduling or target services. Server Groups are irrelevant to EMS.
MS runs background tasks and monitors their execution. It maintains and updates the
system global TaskState queue (pending, running, complete, failed). MS uses the
capacity mechanism to implement Auto-Load Balancing. It watches the Task queue
and takes on tasks if an instance of the required Target Service is available locally and
has free capacity. MS will pull tasks from the queue destined for the Server Group it is
running in or tasks which have no Server Group assigned.

© Copyright IBM Corp. 2010, 2016 3-18

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 3 E x a m i n e I B M C o g n o s S e r vi c e s

If there is no instance of a desired Target Service available locally, or there is no

capacity the task will not be taken off the Task Queue by this instance of Monitor
Service and may remain pending.
DLS sends emails to an external SMTP server on behalf of other services, such as the
report service, job service, agent service, or data integration service.
JS handles a set of tasks known as a Job. This service runs jobs by signaling the
Monitor service to run job steps in the background. Steps include reports, other jobs,
import, exports, and so on.
These scheduling services exchange data through system-global queues stored in
relational database tables (the Notification Database):
• Task-state Queue: contains the state of a task passed to MS
• Task Queue: all tasks currently handled by MS
• Scheduler Queue: stores schedule runtime information

© Copyright IBM Corp. 2010, 2016 3-19

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 3 E x a m i n e I B M C o g n o s S e r vi c e s

Services that implement the Target Service API (1 of 2)

• Services which implement the Target Service API:
 Batch report service (reports)
 Job service (jobs, set of reports)
 Agent service (agents)
 Delivery service (sending emails)
 Content Manager service (deployments)
 IndexUpdate/Data Services (index update/creation)

Examine IBM Cognos Services © Copyright IBM Corporation 2016

Services that implement the Target Service API

An API is provided for other IBM Cognos services which want to have their requests
enabled for background processing. Services which leverage this API are called Target
Services. Examples of Cognos tasks and objects that can be scheduled through the
Target Service API are reports, jobs, agents, and email.
Target Services are also required to implement the AsyncAPI so that their requests can
be processed in the background through asynchronous conversations. The AsyncAPI
defines conversations.

© Copyright IBM Corp. 2010, 2016 3-20

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 3 E x a m i n e I B M C o g n o s S e r vi c e s

Services that implement the Target Service API (2 of 2)

• Job Service (JS)
 governs the execution of jobs
 splits the job into steps, passes them to the MS for execution
• Delivery Service (DS)
 builds SMTP compliant emails from data passed, and passes to a
configured mail server
• Agent Service (AS)
 runs agent actions

Examine IBM Cognos Services © Copyright IBM Corporation 2016

A job is defined as set of tasks, although a task can be another job.

© Copyright IBM Corp. 2010, 2016 3-21

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 3 E x a m i n e I B M C o g n o s S e r vi c e s

Set Target Services properties

• Define a capacity by a configurable number of connections (threads) to
be used to execute work
 separate settings for peak and non-peak period
 define status by evaluation free vs. busy connections

Examine IBM Cognos Services © Copyright IBM Corporation 2016

Set Target Services properties

Target Services properties are configurable as Dispatcher properties, and settings can
be configured through IBM Cognos Administration at the service level.
The Target Services require an instance of MS to be assigned work. If separated from
MS, they will not be assigned any load for background processing.
A 24 hour day is split into two periods: Peak and Non-Peak.

© Copyright IBM Corp. 2010, 2016 3-22

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 3 E x a m i n e I B M C o g n o s S e r vi c e s

Explain Monitor Service properties

• Job: a runnable task
• 1 scheduled report is 1 task (job)
• 1 job (set of tasks) containing 100 reports is 1 task, which when
passed to the Job service will eventually become 100 tasks

Examine IBM Cognos Services © Copyright IBM Corporation 2016

Explain Monitor Service properties

Administrators can set the start of a peak period and the start of a non-peak period.
This allows configuration of the number of Monitor Runners, or connections, for peak
and non-peak periods.

© Copyright IBM Corp. 2010, 2016 3-23

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 3 E x a m i n e I B M C o g n o s S e r vi c e s

Explain Batch Report Service properties

• Define number of reports which can run in parallel at a time.
• Ensure Monitor service can supply enough reports.

Examine IBM Cognos Services © Copyright IBM Corporation 2016

Explain Batch Report Service properties

The Batch report service (BRS) executes reports. Administrators can configure the
affinity connections and number of processes for the BRS. This effectively defines the
number of reports which can run in parallel at a time for the BRS.
For optimal performance make sure the MS can supply enough reports, which is the
number of Jobs (Monitor Runners) as specified on the previous page.
In this example, BRS would be able to run 4 reports at a time, of 2 processes with 2 low
affinity connections each. The high affinity connections would only be used for
secondary requests.
Refer to the Describe Server Affinity: High topic in this unit. High affinity could be tuned
for requests such as email, print, save.

© Copyright IBM Corp. 2010, 2016 3-24

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 3 E x a m i n e I B M C o g n o s S e r vi c e s

A good analogy might be to imagine a sink into which water pours from a faucet. If the
drain is too small, the sink will overflow. If the drain is too big, the sink will run dry and
the faucet cannot provide enough water.
The Monitor Runners are the faucet, the number of batch processes and their affinity
connections define the drain size.
If the drain is too small: Too many Monitor Runners and the requests that they send to
BRS are backing up on the dispatcher queue.
If the drain is too big: Too many reports get executed at the same time, overloading the
available resource.

© Copyright IBM Corp. 2010, 2016 3-25

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 3 E x a m i n e I B M C o g n o s S e r vi c e s

Explain Content Manager Service properties

• Capacity is defined by a maximum number of connections for
ContentManager Service (CM Service)
 defines the number of deployment/ ContentManager maintenance tasks this
particular CM Service instance can handle in parallel, along with all other
duties of CM Service

Examine IBM Cognos Services © Copyright IBM Corporation 2016

Explain Content Manager Service properties

The CM Service runs deployments and Content Manager maintenance tasks.
Since there is only one active instance of CM Service, the capacity should be defined
cautiously.

© Copyright IBM Corp. 2010, 2016 3-26

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 3 E x a m i n e I B M C o g n o s S e r vi c e s

Overview of services

IBM Cognos Analytics portal, SDK,

CMS

4 Dispatcher

Event Management
2 1 Capacity Manager
Service
3 Monitor Scheduling API
Service
5 6
Task State Batch
Engine Monitor Agent Job Delivery
Report
Content
Runners Service Service Service
Service
Manager
Service
Job
Content Store Builder

Task +
Scheduler
TaskState
Queue JMS
Queue
Queue

Examine IBM Cognos Services © Copyright IBM Corporation 2016

Overview of services
The process flow for scheduled tasks is as follows:
1. A user creates a schedule, either through IBM Cognos Analytics or some other
client. A scheduler object is created in the Content Store by sending a create
request to Content Manager Service.
2. The Content Manager Service calls the Event Management Service, replicating
the scheduler objects from the Content Store into the Scheduler queue.
3. Each instance of EMS runs a scheduler thread which polls the Scheduler
queue. By design, EMS figures out the next runtime of a task once it is added to
the queue and waits until due time. Once it wakes up, it starts a transaction to
pull the task from the Scheduler queue and move it to the Task queue through
the Monitor service. The task will be entered into the Task queue in a PENDING
state.
4. Another scenario where tasks are created and passed to MS is where a user
selects "Run now" for saved reports (run and save). IBM Cognos Analytics will
call MS directly, which will lead to the task being queued in PENDING state.

© Copyright IBM Corp. 2010, 2016 3-27

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 3 E x a m i n e I B M C o g n o s S e r vi c e s

5. MS has a poll interval (30s hardcoded) after which it will investigate for tasks to
take on. MS will only take on tasks for locally available Target Services for this
particular server group MS runs in which have free capacity. Capacity
information for the local target services is gathered through the Capacity
Mechanism.
In addition, any call to the MS will trigger an investigation of the TaskQueue. A
third trigger for an MS instance to investigate the TaskQueue is the legacy JMS
queue notification being received.
Once MS picks up a task it is granted that there is a target service with free
capacity to assign this task to.
MS checks for an authenticated session. For scheduled tasks it will create a
new session leveraging the trusted credentials saved with the schedule. For
"saved reports" the credentials for the current session are used.
Next the task status is updated to EXECUTING and the task is assigned to the
target service which uses the AsyncAPI to execute the task.
The Monitor Service updates the task state based on the response received
from the target service. If a cancel was issued in between the processing ends
here and the task is cancelled. The result can be succeeded or failed.
6. If the Report has email output then BRS employs DLS to add an item to the
JMS SMTP Queue. This queue is worked by all DLS instances in a system. A
DLS instance will pick up the item and pass it to a configured SMTP server after
which the runtime state of a task is updated finally.
Upon completion of the task execution, the Monitor service will write out the
history records from its internal store to Content Manager. It keeps the history
internally when tasks fail, in case the user wants to restart any failed tasks.
Periodically the history records for failed tasks are removed, based on the
retention rules stored for that task in Content Manager.

© Copyright IBM Corp. 2010, 2016 3-28

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 3 E x a m i n e I B M C o g n o s S e r vi c e s

Additional Information:
• JMS: Java Message Service.
• JMS queue: Where scheduled items are stored. The JMS queue is internal but
makes use of the data in the NC table NC_JMSQUEUE.
• JMS SMTP queue: This is an internal queue that sits in memory and cannot be
seen or manipulated like the JMS queue.
• SMTP: Simple Mail Transfer Protocol.
• EMS has a queue: jmsqueue. The EMS thread which picks the executables
which need to execute now puts them into this queue. At this moment, the
activities/executables are invisible to the user and administrators; they are neither
pending nor executing.
• MS has a queue: monitor queue. This queue contains all the activities which are
to be executed by monitor runners. At this point they are pending. From this
queue, a monitor runner will pick up an activity, which at that time becomes
executing.

© Copyright IBM Corp. 2010, 2016 3-29

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 3 E x a m i n e I B M C o g n o s S e r vi c e s

Service-Oriented Architecture implications

• Target Services will not be assigned tasks if they are separated from
Monitor Service (MS):
 without MS, deployments and Content Manager maintenance tasks will not
work.
 there must be at least one instance of MS next to CM.
• MS is lightweight with regards to performance; more instances can
help overall performance.
• All installed instances running Target Services must run Monitor
Service.

Examine IBM Cognos Services © Copyright IBM Corporation 2016

Service-Oriented Architecture implications

Server Groups are fully respected; each Server Group requires at least one instance of
MS and desired Target Services on the same install.
Target Services can be separated from each other as long as an instance of MS is
available next to them, and they remain in the same Server Group.
Example of a single Server Group scenario:
• Dispatcher 1: MS+JS
• Dispatcher 2: MS+DLS
• Dispatcher 3: MS+BRS+EVS

© Copyright IBM Corp. 2010, 2016 3-30

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 3 E x a m i n e I B M C o g n o s S e r vi c e s

Explain Cognos Graphics Service

• Legacy Engine
 runs in-process as part of BIBusTKServerMain
• Current Default Engine
 runs in own JVM as a separate process
 used by IBM Cognos Analytics by default

Examine IBM Cognos Services © Copyright IBM Corporation 2016

Explain Cognos Graphics Service

IBM Cognos 11 offers two alternate graphic engines to use, the legacy engine and the
current default engine.

© Copyright IBM Corp. 2010, 2016 3-31

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 3 E x a m i n e I B M C o g n o s S e r vi c e s

Describe Cognos Graphics Service

Dispatcher

Cognos Graphics Service Interface IBM Cognos Analytics Interface

cgsLauncher
BIBusTKServerMain

BIBusTKServerMain
Current Default
Engine CGS BIBusTKServerMain
(JVM, multi-threaded) (Legacy
Current Default Engine) CGS
Engine (Legacy
Engine) CGS
(JVM, multi-threaded)
(Legacy
Current Default Engine)
Engine
(JVM, multi-threaded)

Examine IBM Cognos Services © Copyright IBM Corporation 2016

Describe Cognos Graphics Service

The current default engine is very much like ReportService. The Cognos Graphics
Service (CGS) interface consists of handlers registered to the dispatcher. These
handlers are partially using the ones from BIBusTKServerMain, which you are now
familiar with the concept.
CGSLauncher is used to spawn JVMs which host the current default engine. In Report
service the dispatcher invokes BIBusTKServerMain directly, however for CGS there is
some additional redirection. In Windows environments, cgslauncher.exe is called which
will call a JVM, and in non-Windows environments cgsServer.sh script is called when
needed.
The current default engine will use a configurable number of threads (number of low
affinity connections from Service properties).
The Current Default Engine Java process will not be recognizable on *IX, but will be
recognizable only by the command which invoked it. On Windows, the
cgsLauncher.exe in Task Manager is, in fact, the JRE.
The Current Default Engine Java processes will terminate if idle for 5 minutes
(configurable in cgsService.xml).

© Copyright IBM Corp. 2010, 2016 3-32

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 3 E x a m i n e I B M C o g n o s S e r vi c e s

Describe the Current Default Engine

• Invoked through cgsLauncher (cgsLauncher.exe, cgsServer.sh)
 uses BIBusTKServerMain
• cgsLauncher will start configured number of processes for CGS
 new instances will get spawned until configured limit for number of
processes is reached.
 processes are JVMs.
 JVM arguments can be edited.
 CGS JVMs will use configured number of threads.

Examine IBM Cognos Services © Copyright IBM Corporation 2016

Describe the Current Default Engine

The current default engine is written in Java, and invoked through cgsLauncher, which
is a C++ process that starts when the product starts. cgsLauncher uses the
BIBusTKServerMain interface, which is the same interface as Report server, and is
controlled by the dispatcher. There is port to port communication through the
dispatcher, and it will terminate if it is idle too long (the default is set to 5 minutes).
JVM runs within JRE, and JRE runs within JDK. JVM and JRE sometimes used
synonymously.

© Copyright IBM Corp. 2010, 2016 3-33

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 3 E x a m i n e I B M C o g n o s S e r vi c e s

Configure Cognos Graphics Service

Examine IBM Cognos Services © Copyright IBM Corporation 2016

Configure Cognos Graphics Service

Requests for Cognos Graphics Service (CGS) are conversations, which is to say that
they can go asynchronous and this implies they are high affinity requests. These
requests are subject to queuing.
CGS can be configured in IBM Cognos Administration, and the properties are similar to
ReportService. Initial requests to CGS are subject to load balancing and advanced
routing because they are not affine.

© Copyright IBM Corp. 2010, 2016 3-34

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 3 E x a m i n e I B M C o g n o s S e r vi c e s

Configure CGS parameters

• cgsService.xml has several parameters as JVM arguments
 linger_process
 prestart_process
 idle_process_check_interval_ms
 idle_process_max_idle_ticks
 report_server_port (should be 0 for dynamic ports)
 server_port (should be 0 for dynamic ports)

Examine IBM Cognos Services © Copyright IBM Corporation 2016

Configure CGS parameters

The parameters are in ..\webapps\p2pd\WEB-INF\services\cgsService.xml. (.. is the
install directory for IBM Cognos Analytics).
Since this is Java there are many tools available to hook to the JRE. Use Java
monitoring on the current default engine processes to monitor performance.

© Copyright IBM Corp. 2010, 2016 3-35

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 3 E x a m i n e I B M C o g n o s S e r vi c e s

• linger_process: The minimum number of processes to keep in memory once

they are started.
• prestart_process: Should the CGSServer be started at initialization time rather
than on-demand?
• idle_process_check_interval_ms: Time period between checks for idle or
expired processes (in ms). Every time you check an idle process you bump its
tick count. Every time you use a process the count is reset to 0. If the count ever
reaches the value of idle_process_max_idle_ticks (below) the process is
destroyed.
• idle_process_max_idle_ticks: number of idle check ticks before an idle process
is killed.
• report_server_port and server_port: The port the CGSServer is listening to. 0
(zero) should be used if the dispatcher spawns the process and uses a
dynamically assigned port.

© Copyright IBM Corp. 2010, 2016 3-36

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 3 E x a m i n e I B M C o g n o s S e r vi c e s

Explain Presentation Service (PRS)

• Uses underlying components
 XTS (generate pages based on XML style templates)
 Fragments (XML based composition of pages)
• Generates HTML output to be viewed in browser client
• Proxies requests for other services
 Report Data Service (RDS): ATOM Feeds
 Cognos Portal Services (CPS): WSDL, WSRP

Examine IBM Cognos Services © Copyright IBM Corporation 2016

Explain Presentation Service (PRS)

PRS uses several underlying components to support different techniques for page
generation, like XTS (XML Transformation Service) and Fragments.
PRS generates HTML output to be viewed in browser client for IBM Cognos Analytics,
Event Studio, and IBM Cognos Administration. XTS is not Event Studio, but that UI will
send back requests to XTS, which will then employ the underlying engines to generate
the output for that UI.
Presentation Service is the central IBM Cognos Service when interacting with browser
clients. SDK clients would not require XTS necessarily. XTS is not Presentation
Service, but is a server-based service component used to generate HTML pages in the
IBM Cognos Analytics portal. Sometimes XTS and PRS get used interchangeably
which is incorrect. XTS is based on XML and XSLT.

© Copyright IBM Corp. 2010, 2016 3-37

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 3 E x a m i n e I B M C o g n o s S e r vi c e s

Describe PRS
• Requires local dispatcher service to be enabled.
• Rule: if a gateway is involved, PRS is also involved.

Examine IBM Cognos Services © Copyright IBM Corporation 2016

Describe PRS
PRS is mandatory for front dispatchers, particularly if Single Sign-On (SSO) is
configured. This is because XTS is required when handling User and System
Recoverable parameters which are part of the process to render the HTML pages for
login and to select a namespace.
PRS is unavailable on CM only installs, as PRS requires the local dispatcher service to
be enabled. Therefore a basic rule is that if a gateway is involved, then PRS is also
involved. There are exceptions to this rule, as listed in the slide.
IBM Cognos Analytics is rendered by AJAX-based techniques. AJAX is a design
approach and a set of techniques for delivering rich Internet applications (RIAs) using
open web formats, for example, HTML, CSS and JavaScript; and rendering using a
browser engine.

© Copyright IBM Corp. 2010, 2016 3-38

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 3 E x a m i n e I B M C o g n o s S e r vi c e s

Explain Report Data Service (RDS)

• RDS exposes IBM Cognos content in Web 2.0 formats.
• Supports REST and SOAP interfaces.
• Data can be retrieved as:
 XML (Simple/layout data)
 HTML including Fragments
 JSON

Examine IBM Cognos Services © Copyright IBM Corporation 2016

Explain Report Data Service (RDS)

RDS is implemented by a Development component called Cognos Content
Service (CCS). The API is a separate product known as Cognos Mashup
Services (CMS).
RDS exposes IBM Cognos content (reports, dashboards, analyses) in Web 2.0 formats
for mashing it up with other applications data.
RDS makes use of Report service, Metric service, PowerPlay service, and Query
service.
Representational State Transfer (REST): A software architectural style for distributed
hypermedia systems like the World Wide Web. The term is also often used to describe
any simple interface that uses XML (or YAML, JSON, plain text) over HTTP without an
additional messaging layer such as SOAP.

© Copyright IBM Corp. 2010, 2016 3-39

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 3 E x a m i n e I B M C o g n o s S e r vi c e s

What components use RDS?

• IBM Cognos for Microsoft Excel
• IBM Cognos Mobile
• IBM Cognos for Microsoft Office

Examine IBM Cognos Services © Copyright IBM Corporation 2016

What components use RDS?

© Copyright IBM Corp. 2010, 2016 3-40

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 3 E x a m i n e I B M C o g n o s S e r vi c e s

What is Metadata Service (MDS)?

• Implemented in C++, runs in separate executable:
 BmtMDProviderMain
• Based on the BIBusTKServerMain model:
 has affinity connections (4 low only)
 a single instance is spawned upon startup by dispatcher
 terminates if idle for 5 minutes, restarted as required

Examine IBM Cognos Services © Copyright IBM Corporation 2016

What is Metadata Service (MDS)?

MDS serves metadata requests for Query, Update, Test data base connections,
lineage and more. Theoretically MDS can take up the maximum allowed process space
but usually remains small in memory, smaller than Report server instances.

© Copyright IBM Corp. 2010, 2016 3-41

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 3 E x a m i n e I B M C o g n o s S e r vi c e s

Explain Relational Metadata Service (RMDS)

• RMDS interfaces to the component of the DQM engine (RELMD)
which connects to data sources via JDBC and provides metadata.
• Used exclusively by:
 Framework Manager in "dynamic" mode
 IBM Cognos Cube Designer (CD)
• Queries run on the server, not on the client.
 no local DB client install is required for installs of FM or CD
 a JDBC driver is required on Dispatchers running RMDS.
 the data source requires JDBC connectivity only.
• Use is governed by the "Import relational metadata" capability.

Examine IBM Cognos Services © Copyright IBM Corporation 2016

Explain Relational Metadata Service (RMDS)

This is a new service as of IBM Cognos BI version 10.2.0 which is logically an interface
to RELMD, a component shared by XQE that retrieves metadata from DQM data
sources via JDBC. The service is used exclusively by CD and FM.
Using RELMD is quite different from CQM modeling.
• FM in mixed mode uses a local (client) UDA stack and therefore requires DB
clients to be installed locally.
• Dynamic mode uses the RMDS which runs the queries on the server:
• no local (client) DB clients are required
• requires JDBC connectivity only, running on the Application Tier hosting
RMDS
• requires JDBC driver, although QueryService might be disabled on the same
node
The new Import relational metadata capability controls who can pull metadata. The
capability does not control availability or start of FM or CD.

© Copyright IBM Corp. 2010, 2016 3-42

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 3 E x a m i n e I B M C o g n o s S e r vi c e s

Configure RMDS

Examine IBM Cognos Services © Copyright IBM Corporation 2016

Configure RMDS
With RMDS, there is no horizontal scaling and routing, or fail-over. RMDS is required on
Dispatchers referenced in IBM Cognos Configuration for FM and IBM Cognos Cube
Designer installations, and is not required anywhere else.
RMDS does not require Query Service, and RMDS properties are different than the
Metadata Service properties:
• RMDS handles asynchronous conversations
• has batch processing capacity (# connections)
No separate process is being spawned, as work is done in a JVM context of the
Dispatcher.

© Copyright IBM Corp. 2010, 2016 3-43

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 3 E x a m i n e I B M C o g n o s S e r vi c e s

Each instance of RDMS is stand-alone. It uses a local disk cache (../temp directory) and
handles requests sent to it through the External Dispatcher URL.
Metadata Service is separate from RDMS and is still required in a system. Metadata
Service is required in a system for serving FM mixed mode.
The number of low affinity connections determines how many clients can be served in
parallel. Additional requests will possibly be queued at Dispatcher and eventually time
out.

© Copyright IBM Corp. 2010, 2016 3-44

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 3 E x a m i n e I B M C o g n o s S e r vi c e s

What is Dynamic Query Mode?

• Dynamic Query Mode (DQM) is an enhanced Java based query mode
which offers the following key capabilities:
 query optimizations
 performance improvement through balanced local query processing
facilities
 security-aware caching
 ability to take full advantage of a 64-bit environment
 ease of maintenance with query visualization

Examine IBM Cognos Services © Copyright IBM Corporation 2016

What is Dynamic Query Mode?

Query Optimizations: The optimization of the queries is achieved through the advanced
application of strict query planning rules. These planning rules incorporate the next
generation planning approach which is more streamlined and produces higher quality
and faster-to-execute queries. The query planning process is also in itself optimized to
make better use of metadata and expression level caches, including plan caches which
provide higher application throughput.
Performance Improvement through Balanced Local Processing Facilities: The Dynamic
Query Mode makes intelligent, rules based and system load based decisions on which
parts of a query should be executed locally in the application server versus remotely in
the database server. This ensures that users have the highest functionality possible
regardless of whether the underlying data source supports the analytics report intent. In
addition, the Dynamic Query Mode contains a fine grained metadata and cell data
cache which is trickle fed and a higher cache hit ratio than was previously possible. In
addition the queries which are sent to remote data sources are further optimised by the
execution layer based on cache content and advanced null suppression logic.

© Copyright IBM Corp. 2010, 2016 3-45

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 3 E x a m i n e I B M C o g n o s S e r vi c e s

Security-Aware Caching: The caching logic available in Dynamic Query Mode is able,
when connected to secured metadata sources, to determine the secured access
capabilities of each user as they access the data source. This information is then used
to optimize the memory usage and internal representation of that user’s secured view of
the data source metadata. Security can also be setup so that entire OLAP dimensions
can be shared providing cache reuse and performance gains.
Ability to take Full Advantage of a 64-bit Environment: The Dynamic Query Mode is
able to fully take advantage of a 64-bit environment. When an IBM Cognos 11 64-bit
install is deployed to a 64-bit Java Virtual Machine (JVM), the Dynamic Query Mode is
substantiated in its own 64-bit JVM. This allows DQM to leverage the 64-bit address
space for query processing, metadata caching and data caching. The 64-bit DQM also
has the ability to leverage the 64-bit data source client libraries when performing
non-JDBC Type 4 connections.
Ease of Maintenance with Query Visualization through IBM Cognos Dynamic Query
Analyzer: Query visualization allows system administrators to analyse the queries
generated by the Dynamic Query mode and visually see how they will be processed.
These visualizations include cost based information derived from the query execution.
This information permits the rapid identification of model and query optimizations which
could be applied in order to achieve better performance. The visualizations are
consumed as a log file by the stand alone IBM Cognos Query Analyzer application.

© Copyright IBM Corp. 2010, 2016 3-46

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 3 E x a m i n e I B M C o g n o s S e r vi c e s

OLAP functionality for Relational sources

• DQM provides users with a true OLAP experience over relational data.
 DMR
 ROLAP
• Improved ad-hoc analysis capabilities through:
 default member sorting
 improved suppression
 aggregate limitations removed
 nulls as zeros in arithmetic operations
 FIRST / LAST aggregate rules respect presence of NULL values

Examine IBM Cognos Services © Copyright IBM Corporation 2016

OLAP functionality for Relational sources

DQM applies advanced OLAP caching techniques to enhance performance of
dimensionally modeled relational packages. The use of caching reduces the frequency
of database queries, thus minimizing the database server workload required to service
the IBM Cognos application.
With OLAP over Relational (ROLAP), DQM specifies a natural order to all result sets. If
no specific ordering is specified in the Framework Manager model, the members are
sorted by default in ascending order by the member caption. If there are duplicate
captions, they those are sorted by business key.

© Copyright IBM Corp. 2010, 2016 3-47

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 3 E x a m i n e I B M C o g n o s S e r vi c e s

With DQM, suppression is pushed to the OLAP provider. Queries which are sent to
remote data sources are optimized by the execution layer based on cache content and
advanced null suppression logic. Suppressing rows and columns that contain only null
values makes a report easier to read. For example, a product that has no sales for a
given quarter may result in a very large report with thousands of cells that contain no
data. The time required to evaluate a table to determine which rows and columns
contain only null values is mainly determined by the number of cells in the table. Other
factors such as the nesting levels on the axes and the use of complex calculated
columns might also affect the time.
OLAP over Relational provides the ability to perform complex aggregate computations,
and lifts previous aggregation limits which resulted in '--' or 'unknown' being displayed,
such as when using Count Distinct as a summary.
Regarding First and Last aggregation rules to respect empty cells, previously, if you
asked for the sales from the last period of a quarter and there were no sales for a
product in that period, there would be no result to return. Instead of reporting zero, for
the period in question, the sales for the last period in which there were sales would
have been reported. With DQM, the query will return a zero for the specified period.
An example of performance metrics: with DQM for ROLAP: some tests showed an 85%
performance improvement, with an average query time for compatible mode being 125
seconds, improving to 15 seconds average query time for DQM. Results will differ,
depending on the environment and the queries being run.

© Copyright IBM Corp. 2010, 2016 3-48

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 3 E x a m i n e I B M C o g n o s S e r vi c e s

Dynamic Query Mode connectivity

• Supports connectivity to supported OLAP and relational data sources.
• OLAP connectivity is done through the native client libraries of the data
source vendor.
• Supported relational data sources can remain in compatible query
mode or further modeled dimensionally to provide an OLAP-style
experience as dynamic query mode.
• Relational connectivity is done through JDBC.

Examine IBM Cognos Services © Copyright IBM Corporation 2016

Dynamic Query Mode connectivity

OLAP data source connections through DQM require a native client install. These
native client installs can be either 32-bit or 64-bit as long as they match the bit depth of
the DQM. For instance a 32-bit DQM requires a 32-bit SAP BW client library install
while a 64-bit DQM would require a 64-bit SAP BW library, if that was the vendor
database used.
Relational data source connectivity is done as a JDBC Type 4 connection with the
exception of Oracle connections, which can be established as either Type 2 or Type 4
JDBC connections. Type 4 JDBC connections do not require the install of any native
client libraries. Connectivity is established through the vendor JDBC driver which is
copied to the ..\v5dataserver\lib directory and the p2pd\WEB-INF\lib directory. The
Oracle Type 2 JDBC connection also requires the Oracle native library install in
conjunction with the Oracle JDBC driver.

© Copyright IBM Corp. 2010, 2016 3-49

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 3 E x a m i n e I B M C o g n o s S e r vi c e s

OLAP DQM connectivity

• Supported OLAP technologies:
 IBM Cognos Dynamic Cubes
 IBM Cognos TM1
 SAP BW
 Microsoft SSAS
 Oracle Essbase

Examine IBM Cognos Services © Copyright IBM Corporation 2016

OLAP DQM connectivity

The data source specific capabilities files can be located within the ..\configuration\xqe
directory. These files help govern the decision making process of DQM during the
query planning phase. General OLAP behavior is defined within the OLAP.properties
file which is used in conjunction of the data source specific capabilities file, such as
bw.properties for SAP BW, eb.properties for Essbase, yk.properties for MSSAS, and so
on.
These files should only be changed under the direction of IBM Cognos Support.

© Copyright IBM Corp. 2010, 2016 3-50

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 3 E x a m i n e I B M C o g n o s S e r vi c e s

Relational and DMR DQM connectivity

• Supported relational data sources:
 IBM DB2
 IBM Netezza
 Microsoft SQL Server
 NCR Teradata
 Oracle

Examine IBM Cognos Services © Copyright IBM Corporation 2016

Relational and DMR DQM connectivity

The data source specific capabilities files can be located within the ..\configuration\xqe
directory. These files help govern the decision making process of DQM during the
query planning phase. For relational queries, DQM uses the general vendor capabilities
in conjunction with the vendor version specific capabilities to help with the query
planning.
For example, DQM would use:
• db2.sql.properties and db2.sql9.7.properties when connecting to IBM DB2 9.7
• netezza.properties and netezza5.0.properties when connecting to
IBM Netezza 5.0
For DMR queries, the DQM behavior is the same as the above in addition to using the
dmr.properties file. These files should only be changed under the direction of IBM
Cognos Support.

© Copyright IBM Corp. 2010, 2016 3-51

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 3 E x a m i n e I B M C o g n o s S e r vi c e s

Describe QueryService

Examine IBM Cognos Services © Copyright IBM Corporation 2016

Describe QueryService
Dynamic Query Mode is also known as QueryService. DQM is coded in Java and runs
within its own JVM. By default this JVM is configured to start with 1GB of memory and
displays as a separate Java process on the operating system. Although there can be
many QueryService services in a multiple server installation, you can only have one
QueryService per IBM Cognos 11 dispatcher. Disable the Query Service if you do not
need it, to save resources.
The Query Service is used as a secondary service by Report Service and Batch Report
Service.

© Copyright IBM Corp. 2010, 2016 3-52

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 3 E x a m i n e I B M C o g n o s S e r vi c e s

The QueryService receives requests from the BIBusTKServerMain process in the form
of a query request, and from this request, plans the query. The planning of the query is
where all the decisions are made to build an optimal query. Once the query is planned,
the query is executed. The result of the query is passed back the BIBusTKServerMain
process which then renders the report requested output.
In IBM Cognos Administration on the Configuration tab, Dispatchers and Services have
a QueryService entry, which is used to configure settings for the Dynamic Query Mode.
The QueryService specific configuration can be found in the ..\configuration\xqe_config.xml
file. This file should only be changed under direction of IBM Cognos Support or
Development.

© Copyright IBM Corp. 2010, 2016 3-53

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 3 E x a m i n e I B M C o g n o s S e r vi c e s

Describe the QueryService properties

Examine IBM Cognos Services © Copyright IBM Corporation 2016

Describe the QueryService properties

The QueryService properties allow for the administration of the Dynamic Query Mode.
Settings of most interest include:
Enable query execution trace? Enabling this trace setting will allow an administrator
to capture the query execution after it has gone through its planning phase. The log this
trace produces is called the run tree log written to the ..\logs\XQE directory. This file
usually accompanied by the profiling log which tracks the time spent in each of parts of
the query execution. As a log is generated for each report that is executed, the log file
adheres to the following naming convention.
• <date>_<timestamp>_reportName/runtreeLog.xml
• <date>_<timestamp>_reportName/profilingLog-#.xml

© Copyright IBM Corp. 2010, 2016 3-54

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 3 E x a m i n e I B M C o g n o s S e r vi c e s

As an example, executing a report called Top_Sales would result in a log file named
2016-02-10_11h33m700s_Top_Sales/runtreeLog.xml, and one or several profiler logs
named 2016-02-10_11h33m700s_Top_Sales/profilingLog-0.xml,
2016-02-10_11h33m700s_Top_Sales/profilingLog-1.xml, and so on.
These files are best viewed with the Dynamic Query Analyzer application which is
described in a later unit.
Initial JVM heap size for the query service (MB) This setting defines how much
memory the DQM Java Virtual Machine will take on startup. The value set here is
passed to the JVM on startup as the –Xms<value> parameter.
JVM heap size limit for the query service (MB) This setting defines the upper
memory limit of the DQM Java Virtual Machine during operation. The value set here is
passed to the JVM on startup as the –Xmx<value> parameter.

© Copyright IBM Corp. 2010, 2016 3-55

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 3 E x a m i n e I B M C o g n o s S e r vi c e s

Additional Query Service information

• DQM Cookbook available on developerWorks at
http://www.ibm.com/developerworks/data/library/
cognos/infrastructure/cognos_specific/page529.html
• DQM Data Source Conformance can be found at http://www-
01.ibm.com/support/docview.wss?uid=swg27047186
• Dynamic Query Analyzer User Guide can be found at http://www-
01.ibm.com/support/docview.wss?uid=swg27047187

Examine IBM Cognos Services © Copyright IBM Corporation 2016

Additional Query Service information

The DQM Cookbook contains a significant amount of detail. It provides background
information and troubleshooting tips as well.

© Copyright IBM Corp. 2010, 2016 3-56

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 3 E x a m i n e I B M C o g n o s S e r vi c e s

Describe Repository Service (REPOS)

• Allows Content Management System (CMS) integration.
• Supports versioning.
• Allows archiving and tracking/auditing.
• Reduces Content Store (CS) size.
• Direct support is for IBM FileNet only, other CMS can be used through
the file system export and import.

Examine IBM Cognos Services © Copyright IBM Corporation 2016

Describe Repository Service (REPOS)

Since IBM Cognos BI 10.1.1, report outputs can be saved and archived in locations
other than in the Content Store.
• The legacy feature of saving to the file system in addition to CS still exists with
limited functionality.
• Support in IBM Cognos BI 10.1.1 was limited. Full support is delivered as of
10.2.2.
Repository Service (REPOS) stores report outputs in one of the supported back-end
repositories accessed as a Cognos data source:
• configurable path in the file system (local + UNC)

© Copyright IBM Corp. 2010, 2016 3-57

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 3 E x a m i n e I B M C o g n o s S e r vi c e s

• IBM FileNet Content Manager (ECM):

• not the same as the Cognos Content Manager component
• offers a file system like structure, similar to a mounted drive
• accessed by the user running Cognos Service
The FileNet system is attached by setting up a Cognos data source for writing. The file
system is a virtual FileNet driver which writes to a file system path to a URL. FileNet is
exposed as a file system, hence the similarity. File system configuration is done in IBM
Cognos Configuration under Global Settings\Alias Root. This is an optional feature, as
storing in CS is still fine.
The legacy feature which uses "Archive Location File System Root" is only providing file
system storage next to storing in CS; the new feature offers both.

© Copyright IBM Corp. 2010, 2016 3-58

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 3 E x a m i n e I B M C o g n o s S e r vi c e s

Explain REPOS
• Part of the Application Tier install
• Client components access directly through URLs generated by the
Presentation Service
• Scales horizontally
• Multiple instances will work jointly
• Dispatcher distributes load
• REPOS requests are not subject to advanced routing
• Local instances preferred when accessed by other services

Examine IBM Cognos Services © Copyright IBM Corporation 2016

Explain REPOS
REPOS comes with the Application Tier install; it is not provided with a Content
Manager only install.
Load balancing is handled by the Dispatcher for REPOS requests. Service registration
has a preference of "cluster compatible" mode. REPOS is only used when accessed by
other Cognos Services for storing data. That is, a request to store something is unlikely
to travel over the BIBus unless it has to (as in the case that no local REPOS instance is
available).
There should be at least two instances of REPOS in a system for fail-over.
REPOS can be disabled if no archiving is used, or if output versions are only going to
be kept in the Content Store.

© Copyright IBM Corp. 2010, 2016 3-59

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 3 E x a m i n e I B M C o g n o s S e r vi c e s

Configure REPOS

• REPOS can consume a lot of memory if not configured properly:

 uses a two-level cache, local to every service instance
− first
level of cache is in Java heap (such as the Dispatcher memory)
− second level of cache is an overflow to the local disk (/temp folder)
• Cache control is only by number of objects (reports, report elements)

Examine IBM Cognos Services © Copyright IBM Corporation 2016

Configure REPOS
It is important to know your report output sizes; reduce the number of objects in the
memory cache.
100 (objects) * 10 MB = 1 GB
Keep in mind that there is a cache for each REPOS instance The REPOS cache is a
potential trap:
• understand your report output size
• outputs will be moved across BIBus and into the memory cache

© Copyright IBM Corp. 2010, 2016 3-60

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 3 E x a m i n e I B M C o g n o s S e r vi c e s

If 100 users pull 100 different outputs from a single instance of REPOS within 20
minutes, they all are going to be loaded into the memory cache using default settings.
Doing the math: 100 * 2 MB = no issue, 100 * 20 MB = possible issues. For two
instances, that might cause half the cache to be built for each instance. Over time
though, it might build up to two full copies of the cache.
In the initial release of 11.0, there is no control over the cache size. You will need to use
the number of objects in your configuration (../configuration/cache/ehcache.xmlis cache
settings file).
The overflow location is the ../temp folder of the local installation.
REPOS should be placed on servers with large RAM (> 8 GB).
Do not put REPOS next to CM or JMS as you do not want to take memory away from
these services. It is better to put REPOS next to a Report Service or a Query Service,
as the hardware that hosts these services usually has larger amounts of RAM.

© Copyright IBM Corp. 2010, 2016 3-61

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 3 E x a m i n e I B M C o g n o s S e r vi c e s

What is Cognos Access Manager Service?

• Internal service that handles authentication
 CAM_AsyncAAService
• Implemented by CAM, a Java component
• Authentication providers remain C++ code
 except Custom Java Authentication Providers (CJAPs)
• Single instance in a system only for IBM Cognos 11

Examine IBM Cognos Services © Copyright IBM Corporation 2016

What is Cognos Access Manager Service?

In IBM Cognos 11, authentication is handled by an internal service. Authentication is
implemented by the CAM service, which is now a Java component. You should be
aware that some authentication providers remain in C++ code, with the exception of
Custom Java Authentication Providers (CJAPs).
In an IBM Cognos 11 system, only a single instance of CAM service will exist, and it
must be run where the Content Manager runs.

© Copyright IBM Corp. 2010, 2016 3-62

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 3 E x a m i n e I B M C o g n o s S e r vi c e s

Describe Authentication Providers

• Each authentication provider is executed in its own C++ process.
• Provide 32-bit and partial true 64-bit support.
• Processes use BIBusTKServer interface:
 started by dispatcher upon startup
(CAM_LPSvr (Legacy Provider Server))
 terminated if idle for 10 min
 processes will be re-spawned as required
 user authenticated session retained even if the process is terminated

Examine IBM Cognos Services © Copyright IBM Corporation 2016

Describe Authentication Providers

Each authentication provider is now executed in its own separate C++ process, with
one process per configured namespace, with the exception of the Cognos namespace.
Having a full range of process memory available to the provider means an increase in
support for the number of active users. On 32-bit installs, 2-3 GB C++ heap per
configured namespace is available, and on 64-bit installs, > 4GB C++ heap per
configured namespace is available.

© Copyright IBM Corp. 2010, 2016 3-63

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 3 E x a m i n e I B M C o g n o s S e r vi c e s

Unit summary
• Identify IBM Cognos Services
• Explore the architecture in IBM Cognos 11

Examine IBM Cognos Services © Copyright IBM Corporation 2016

Unit summary

© Copyright IBM Corp. 2010, 2016 3-64

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 3 E x a m i n e I B M C o g n o s S e r vi c e s

Exercise 1
Observe the effects on a dispatcher when running multiple report server
instances

Examine IBM Cognos Services © Copyright IBM Corporation 2016

Exercise 1: Observe the effects on a dispatcher when running multiple report server
instances.

© Copyright IBM Corp. 2010, 2016 3-65

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 3 E x a m i n e I B M C o g n o s S e r vi c e s

Exercise 1:
Observe the effects on a dispatcher when running multiple
report server instances

As administrator, you want to run multiple Report Server instances to observe the
results in your environment. To do this you will invoke multiple BIBusTKServerMain
processes by running a number of reports simultaneously. You will run reports which
contain current default engine charts, and then monitor the results.
You will do the following:
• Ensure that both dispatchers are running
• Launch Windows Task Manager, and select the Processes tab for monitoring
• Login to IBM Cognos Analytics as admin/Education1, and create a new report
with any package; select Blank when prompted for a report template.
• Ensure that IBM Cognos Analytics is using the current default engine (Application
Bar\More\Options\Advanced, clear Use legacy chart authoring), and then close
IBM Cognos Analytics.
• Create and save a job in My content to run the following reports (which contain
charts) from Team content\Samples_DQ\Models\GO Data Warehouse
(analysis)\Report Studio Report Samples:
• Returns by Failed Orders in 2012_DQ
• Returns by Order Method_DQ
• Monitor the results in Windows Task Manager
• Create and save a job in My content to run the following reports (which contain
charts) from Team content\Legacy_Samples\Samples\Models\GO Data
Warehouse (analysis)\Report Studio Report Samples:
• Returns by Failed Orders in 2012
• Returns by Order Method
Note that these reports are IBM Cognos BI 10.2.2 sample reports, to show the
distinction between Compatible Query Mode (CQM) behavior and Dynamic
Query Mode (DQM) behavior.
• Monitor the results in Windows Task Manager
• Close all open windows

© Copyright IBM Corp. 2010, 2016 3-66

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 3 E x a m i n e I B M C o g n o s S e r vi c e s

Question: What has to be done to monitor this if more than one dispatcher is running?
Answer: You could use routing rules to force the activity to one dispatcher, or through
configuring load balancing, or other configurations. This environment uses routing rules.
For more information about where to work and the exercise results, refer to the Tasks
and Results section that follows.

© Copyright IBM Corp. 2010, 2016 3-67

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 3 E x a m i n e I B M C o g n o s S e r vi c e s

Exercise 1:
Tasks and Results
The IBM Cognos 11 Full:9315 dispatcher and the IBM Cognos 11 DispCM:9320
dispatcher should be running at the beginning of this exercise.
Task 1. Start Windows Task Manager.
• Ensure that both dispatchers are running, and then right-click the Taskbar, and
click Start Task Manager.
• Click the Processes tab, click the Image Name column title to sort alphabetically
ascending, and then review the processes that are running.
Look for instances of BIBusTKServerMain.exe. Also identify instances of
java.exe.
A section of results which may appear are as follows. You may have different
services running in addition to these:

Keep this window open and visible on the desktop as you proceed with the next
task.
Task 2. Run multiple reports.
• Launch Internet Explorer, go to http://vclassbase:88/ibmcognos/bi/, and then
log on as admin/Education1.

• Click New , and then click Report.

• On the Templates and themes page, click Blank, and then click OK.

© Copyright IBM Corp. 2010, 2016 3-68

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 3 E x a m i n e I B M C o g n o s S e r vi c e s

• To review the configuration, on the Application bar, click More , click

Options, on the Advanced tab ensure that the Use legacy chart authoring
check box is not selected, and then click OK.
• On the Application bar, click the down arrow beside New, and then beside New,
click Remove .
You will create jobs to run multiple reports at the same time, so that you can
monitor the results. One job will be for dynamic query based reports, and the
other job will be for compatible query based reports.

• On the Side panel, click Manage , and then click New job.
• In the Name box, type Run Multiple Chart Reports DQM, under Location, click
Select My Folders, and then click Next.
• Under the Steps pane, click Add, and then under the Available entries section
on the left side, click Cognos and navigate to Team
Content\Samples_DQ\Models\GO Data Warehouse (analysis)\Report Studio
Report Samples.
• Click the check boxes for the following reports (which contain charts), click Add
(right yellow arrow) to add the selected entries, and then click OK:
• Returns by Failed Orders in 2012_DQ
• Returns by Order Method_DQ
You may have to navigate to the next page of reports to get both selections.
• To accept the default settings for submission of steps click Next, on the Select
an action page, click Save only, and then click Finish.
• Click Yes to confirm that you want to close the tab.
• On the Manage panel, click New job.
• In the Name box, type Run Multiple Chart Reports CQM, click Select My
Folders, and then click Next.
• Under the Steps pane, click Add, and then under the Available entries section
click Cognos and navigate to Team
content\Legacy_Samples\Samples\Models\GO Data Warehouse
(analysis)\Report Studio Report Samples.
Note that you are using reports from IBM Cognos BI 10.2.2 samples, because
they use Compatible Query Mode (CQM), and you will contrast this behavior
against Dynamic Query Mode (DQM)

© Copyright IBM Corp. 2010, 2016 3-69

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 3 E x a m i n e I B M C o g n o s S e r vi c e s

• Add the following reports (which contain charts):

• Returns by Failed Orders in 2012
• Returns by Order Method
You may have to navigate to the next page of reports to get both selections.
• Click OK to close the Select entries page.
• To accept the default settings for submission of steps click Next, on the Select
an action page, click Save only, click Finish, and then click Yes to confirm you
want to close the tab.
Task 3. Run the jobs, and observe the processes in Windows
Task Manager.
• Ensure that you can see both the Windows Task Manager and IBM Cognos
Analytics windows on your desktop.
Resize and reposition the windows to see both, as necessary.
• In Windows Task Manager, observe the processes that are running, and notice
in particular, if any instances of BIBusTKServerMain.exe and java.exe are
running.

• On the Side panel, click My content .

© Copyright IBM Corp. 2010, 2016 3-70

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 3 E x a m i n e I B M C o g n o s S e r vi c e s

• Point to Run Multiple Chart Reports CQM, click the ellipsis, and then click Run.
Observe the number of instances of BIBusTKServerMain that are spawned.
Question: How many instances were spawned?
More instances of java.exe should be spawned for Graphics service and for
BIBusTKServerMain.
The results appear similar to the following:

• If you have time, you can continue to observe the processes until they are
complete, and they are no longer displayed.
You may refresh the display by periodically pressing F5.

© Copyright IBM Corp. 2010, 2016 3-71

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 3 E x a m i n e I B M C o g n o s S e r vi c e s

• When you have finished your observations, in the browser window, point to Run
Multiple Chart Reports DQM, click the ellipsis, and then click Run.
Observe the number of instances of BIBusTKServerMain and other services that
are spawned.
The results appear similar to the following:

• When you have finished your observations, close all open windows.

© Copyright IBM Corp. 2010, 2016 3-72

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
Explore Java memory management

Explore Java memory

management

IBM Cognos Analytics 11.0

© Copyright IBM Corporation 2016

Course materials may not be reproduced in whole or in part without the written permission of IBM.
 Unit 4 Explore Java memory management

© Copyright IBM Corp. 2010, 2016 4-2

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 4 Explore Java memory management

Unit objectives
• Describe Java memory layout
• Manage Java memory
• Use tools to monitor Java memory

Explore Java memory management © Copyright IBM Corporation 2016

Unit objectives

© Copyright IBM Corp. 2010, 2016 4-3

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 4 Explore Java memory management

Review Java components in IBM Cognos

• IBM Cognos Analytics is a mix of Java and C++.
• New as of IBM Cognos BI 10.2.0: Cognos Graphic Service (CGS),
Dynamic Query Mode (DQM).
• Changed as of IBM Cognos BI 10.2.0: Cognos Access Manager
(CAM), Content Manager.
• Legacy: Content Manager (CM), Dispatcher (DISP).

Explore Java memory management © Copyright IBM Corporation 2016

Review Java components in IBM Cognos

IBM Cognos is moving to more Java components over time.

© Copyright IBM Corp. 2010, 2016 4-4

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 4 Explore Java memory management

High level architectural view

JVM

Dispatcher Content Manager

RSvc CGSvc DQMSvc CAMSvc

BIBusTKServerMain
BIBusTKServerMain

JVM Current Default

BIBusTKServerMain

v5QueryServer

LPSrv
Engine

LPSrv
LPSrv
JVM

Java Component (multi-platform) C++ Component (multi-platform)

Explore Java memory management © Copyright IBM Corporation 2016

High level architectural view

This high level example shows that even a simple install runs three instances of JRE
with IBM Cognos 11. This is one reason why Java is important to understand.

© Copyright IBM Corp. 2010, 2016 4-5

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 4 Explore Java memory management

What is Java?
• An interpreted, object oriented programming language
• Develop once, deploy anywhere
• Low cost code maintenance, single code stream for all platforms
• Standardized
• Optimizable at JRE level with Just-In-Time compilation (JIT)

Explore Java memory management © Copyright IBM Corporation 2016

What is Java?
Java offers a modular structure of code, with objects and classes, where the same
source code can be used for all targets. It can be compiled to platform independent
bytecode, such as .class files which are sometimes zipped into .jar files. Bytecode is not
executable, and requires a run-time environment. There is no direct control of
hardware, and Java needs more resources than machine code.

© Copyright IBM Corp. 2010, 2016 4-6

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 4 Explore Java memory management

Describe the Java Runtime Environment

• Is platform dependent, usually machine code.
• Is implemented by different OS vendors typically.
• Abstracts hardware specifics to developer.
• Implements memory management.
• Is responsible for optimizations (JIT).
• Enables parallelizing threads by mapping to CPU architecture.

Explore Java memory management © Copyright IBM Corporation 2016

Describe the Java Runtime Environment

Memory management (allocation and garbage collection) can be the most critical
configuration of a JRE. The quality and configuration of the JRE directly impacts Java
code performance and stability. Good optimization and memory management can
overlay bad code design, resulting in increased performance for the Java applications.
Bad memory management will negate good code design.

© Copyright IBM Corp. 2010, 2016 4-7

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 4 Explore Java memory management

Examine the JRE process memory layout

JRE Reserved
Java Code Heap
JNI (C++) Heap
(Java memory)

MaxHeapSize Max – MaxHeapSize - MaxPermSize

Process address space

2 GB Max (32 Window systems)

3 GB Max on 64-bit Windows 2003
4 GB Max on UNIX/LINUX
4 GB+ on 64-bit Windows/UNIX/LINUX
JNI = Java Native Interface (used whenever a call to a non-Java code is made)

Explore Java memory management © Copyright IBM Corporation 2016

Examine the JRE process memory layout

A JRE uses a configurable amount of memory within the allowed address space for a
single process on the particular hardware and operating system. This amount is passed
to the JRE upon start in a parameter called -Xmx (MaxHeapSize) and is usually less
than the theoretical maximum. Additionally, a smaller amount is reserved for the JRE
itself.
The MaxHeapSize works much like a slider control; more Java heap means less JNI
heap.

© Copyright IBM Corp. 2010, 2016 4-8

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 4 Explore Java memory management

Example of JRE memory management

Java Code Heap JNI (C++) Heap

Dispatcher

RSvc CGSvc DQMSvc Content

Content Manager
Manager

Cache Service
Crypto
SDS
CAMSvc CMCache

Explore Java memory management © Copyright IBM Corporation 2016

Example of JRE memory management

IBM Cognos 11 uses both heaps, therefore the MaxHeapSize still has a direct impact,
however more Java heap is favorable.
Separating install components to separate instances of application servers helps to
manage memory requirements for Java heap, and in particular for Content Manager.
Having multiple instances of JRE will help to leverage large RAM pools on 32-bit JREs,
and using 64-bit JREs enables even larger Java heaps.

© Copyright IBM Corp. 2010, 2016 4-9

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 4 Explore Java memory management

Why is Java memory management important?

• Defining amount of memory is not sufficient configuration.
• JRE memory management handles allocation and freeing memory in
Java heap.
• JRE interfaces with OS level memory management for optimum
performance.

Explore Java memory management © Copyright IBM Corporation 2016

Why is Java memory management important?

It is important to understand how memory is managed in a JRE in detail because this
significantly impacts the stability and performance of both the JRE and the IBM
Cognos 11 components.
In Java, memory is allocated implicitly when instantiating an object, and there is no
concept of freeing memory or releasing objects explicitly. In addition, the JRE has to
interface with OS level memory management for optimum performance. Allocating and
freeing memory is expensive, and OS level memory management concepts like virtual
memory (paging) can interfere with the JRE memory management.

© Copyright IBM Corp. 2010, 2016 4-10

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 4 Explore Java memory management

Explore concepts of memory management

• Garbage Collection (GC)
 Allocates and frees memory for Java objects within the Java heap but not in
the JNI heap
 GC implementation details are not part of any specification, only the concept
is
 Each JRE vendor implements GC differently
• Virtual Memory
 Memory is reserved from the OS but not committed
 Committed memory dynamically changes due to GC
 Reserved memory is the maximum JRE can allocate
 Enable by specifying –Xms (MinHeapSize) parameter to JRE
 Disabled if –Xms >= –Xmx.

Explore Java memory management © Copyright IBM Corporation 2016

Explore concepts of memory management

A JRE implements two concepts for memory management, garbage collection and
virtual memory. The combination of the two concepts leads to things like a JRE process
reserving 786MB on Win32 but depending on load and components running in that
JRE, the committed size may be considerably less.
For more information on GC and memory, go to
http://download.boulder.ibm.com/ibmdl/pub/software/dw/jdk/diagnosis/GCandMemory-
042005.pdf.
For more information on IBM JVM, go to
http://download.boulder.ibm.com/ibmdl/pub/software/dw/jdk/diagnosis/diag142.pdf.

© Copyright IBM Corp. 2010, 2016 4-11

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 4 Explore Java memory management

JVM settings
• Starting points for 50+ concurrent users include:
 set gcpolicy=gencon to minimize the long pauses for gc

Explore Java memory management © Copyright IBM Corporation 2016

JVM settings
Along with the setting in the slide, consider the following component-specific starting
point settings for JVM:
• Dispatcher IBM JVM (Report Server)
• 64 bit: xms=xmx= 4GB and xmn set to approx. 1/3 of xmx, or 1286MB
• 32 bit: xms=xmx= 1024MB and xmn set to approx. 1/3 of xmx, or 341MB
• Dispatcher IBM JVM (Content Manager, or combined CM+RS)
• 64 bit: xms=xmx= 6 GB and xmn set to approx. 1/3 of xmx, or 2048MB
• 32 bit: xms=xmx= 768MB and xmn set to approx. 1/3 of xmx, or 256MB

© Copyright IBM Corp. 2010, 2016 4-12

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 4 Explore Java memory management

• Graphics Service IBM JVM (IBM Cognos BI v10 and IBM Cognos Analytics only)
• Unix: <cog_install>/bin/cgsServer.sh
• Change "Xmx1g" (default) to "Xmx2g" for 32 bit or "Xmx4g" for 64 bit
• Dynamic query data server IBM JVM (IBM Cognos BI v10 and IBM Cognos
Analytics only)
• <cog_install>/configuration/xqe.config.xml
• set -Xmx and -Xms to the same value, set -Xmn to 1/2 -Xmx
• 64 bit: -Xmx4096m -Xms4096m -Xmn512m (default settings)
• 32 bit: -Xmx2048m -Xms2048m -Xmn512m (default settings)
For DQM, this can be changed in IBM Cognos Administration, in the properties of
the Query Service.

© Copyright IBM Corp. 2010, 2016 4-13

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 4 Explore Java memory management

Explain Garbage Collection (1 of 2)

MinHeapSize (committed)

MaxHeapSize (virtual) Reserved

Memory used before GGC, committed bytes Free memory, virtual bytes

Explore Java memory management © Copyright IBM Corporation 2016

Explain Garbage Collection

This example is to introduce the general concept of GC only, and does not provide
implementation details.
During runtime, Java objects get created in the Java heap, thereby filling it up. If the
Java heap is running low, more committed bytes are requested from the OS, up to the
MaxHeapSize if virtual memory is enabled.
GC is triggered by memory allocation and/or after a period of time. GC leverages
empirical observations about Java memory usage (infant mortality) and is cost intensive
(lowers performance).

© Copyright IBM Corp. 2010, 2016 4-14

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 4 Explore Java memory management

Explain Garbage Collection (2 of 2)

MinHeapSize (committed)

GC

MaxHeapSize (virtual) Reserved

Memory used after GC, new committed bytes

Memory used before GGC, committed bytes Free memory, virtual bytes

Explore Java memory management © Copyright IBM Corporation 2016

To avoid running out of memory, GC must occur in cycles triggered by criteria based on
memory occupation (depending on the vendor and the GC implementation). GC
identifies the objects not referenced by any other objects as garbage. GC will collect
and dump the garbage, freeing up the memory again. The amount of committed bytes
can decrease down to MinHeapSize.

© Copyright IBM Corp. 2010, 2016 4-15

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 4 Explore Java memory management

Considerations of Garbage Collection

• Can cause problems when the JRE does not process code
• Is cost intensive
• Having an optimal GC is key to good performance
• Different GC implementation strategies exist
• Finding the right strategy can be challenging

Explore Java memory management © Copyright IBM Corporation 2016

Considerations of Garbage Collection

Identifying dead objects for GC is expensive and depends on the size of Java heap and
the number of objects.
Different GC implementation strategies exist; depending on the JRE, several strategies
are supported, and can be configured by passing parameters to the JRE upon
initialization.

© Copyright IBM Corp. 2010, 2016 4-16

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 4 Explore Java memory management

What is IBM JRE Garbage Collection?

• 3 step approach to identify dead objects
 Mark
 Sweep
 Compact

Explore Java memory management © Copyright IBM Corporation 2016

What is IBM JRE Garbage Collection?

Mark occurs most frequently, and will mark only the dead objects. This is a quick
process and is not very expensive in terms of processing time.
Sweep happens less frequently, and marked objects will get freed. This is more
expensive than a Mark.
Compact will defragment the memory by collecting all live objects and relocate them to
a contiguous chunk. Compact is the least frequent, as it can be very expensive.

© Copyright IBM Corp. 2010, 2016 4-17

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 4 Explore Java memory management

Describe fragmentation concerns

MaxHeapSize Reserved

Memory used after GC, new committed bytes

Memory used before GC, committed bytes Free memory, virtual bytes

Explore Java memory management © Copyright IBM Corporation 2016

Describe fragmentation concerns

If GC is configured to run too few compacts, fragmentation can occur. It is impossible to
allocate large objects and OutOfMemory errors can occur even though the sum of free
bytes is sufficient.

© Copyright IBM Corp. 2010, 2016 4-18

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 4 Explore Java memory management

Log Garbage Collection

• The log will at least show most crucial information about a GC run.
• From a verbose GC log you can deduct if the configured MinHeapSize
of 768M is a good fit.

[GC 203376K->45888K(227220K), 0.0279463 secs]

[GC 203200K->44599K(227220K), 0.0173486 secs]
[GC 201910K->50273K(227220K), 0.0462307 secs]
[GC 207585K->50437K(227220K), 0.0490736 secs]
…
[GC 203376K->45888K(227220K), 0.0279463 secs]

GC <oldHeapSize> -> <NewHeapSize> (<totalHeapSize>), <timeTakenforGC>

Explore Java memory management © Copyright IBM Corporation 2016

Log Garbage Collection

GC can be logged for basically any JRE by specifying the Verbose GC parameter. The
resulting log will at least show most crucial information about a GC run, including
duration, result (how many bytes have been freed), and some GC implementation
specific detail (this varies by vendor).

© Copyright IBM Corp. 2010, 2016 4-19

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 4 Explore Java memory management

Verbose GC output of IBM JRE: Example 1

System.gc call

<GC(3): GC cycle started Tue Mar 10 08:24:34 2015

<GC(3): freed 58808 bytes, 27% free (1163016/4192768), in 14 ms>
<GC(3): mark: 13 ms, sweep: 1 ms, compact: 0 ms>
<GC(3): refs: soft 0 (age >= 32), weak 0, final 0, phantom 0>

Explore Java memory management © Copyright IBM Corporation 2016

Verbose GC output of IBM JRE: Example 1

All the lines start with GC(3), which indicates that this was the 3rd garbage collection in
this JVM. The first line shows the date and time of the start of the collection. The
second line shows that 58808 bytes were freed in 14 ms, resulting in 27% free space in
the heap. The figures in parentheses show the actual number of bytes that are free and
the total bytes that are available in the heap. The third line shows the times for the
mark, sweep, and compaction phases. In this case, no compaction occurred, so the
time is zero. The last line shows the reference objects that were found during this
garbage collection, and the threshold for removing soft references. In this case, no
reference objects were found.

© Copyright IBM Corp. 2010, 2016 4-20

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 4 Explore Java memory management

Verbose GC output of IBM JRE: Example 2

Allocation failure

<AF[5]: Allocation Failure. need 32 bytes, 286 ms since last AF>

<AF[5]: managing allocation failure, action=1 (0/6172496) (247968/248496)>
<GC(6): GC cycle started Tue Mar 10 08:24:46 2015
<GC(6): freed 1770544 bytes, 31% free (2018512/6420992), in 25 ms>
<GC(6): mark: 23 ms, sweep: 2 ms, compact: 0 ms>
<GC(6): refs: soft 1 (age >= 4), weak 0, final 0, phantom 0>
<AF[5]: completed in 26 ms>

Explore Java memory management © Copyright IBM Corporation 2016

Verbose GC output of IBM JRE: Example 2

An allocation failure does not mean that an error has occurred in the code; it is the
name that is given to the event that triggers when it is not possible to allocate a large
enough chunk from the heap.
The output contains the same four lines that are in the System.gc() verbose output, and
some additional lines.
The lines that start with AF[5] are the allocation failure lines and indicate that this was
the fifth AF collection in this JVM. The first line shows how many bytes were required by
the allocation that had a failure and how long it has been since the last AF. The second
line shows what action the Garbage Collector is taking to solve the AF, and how much
free space is available in the main part of the heap, and how much is available in the
wilderness. The last line shows how long the AF took, including the time taken to stop
and start all the application threads.

© Copyright IBM Corp. 2010, 2016 4-21

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 4 Explore Java memory management

Enable Verbose GC in IBM Cognos 11: Example using Tomcat with

Command Line
• Any JRE, log to console only
set CATALINA_OPTS=-Xmx768m -XX:MaxNewSize=384m -XX:NewSize=192m -
XX:MaxPermSize=128m -verbose:gc %DEBUG_OPTS%

• IBM JRE, log to file

set CATALINA_OPTS=-Xmx768m -XX:MaxNewSize=384m -XX:NewSize=192m -
XX:MaxPermSize=128m –Xverbosegclog:<path+filename> %DEBUG_OPTS%

• Sun JRE (as of 1.4), log to console

set CATALINA_OPTS=-Xmx768m -XX:MaxNewSize=384m -XX:NewSize=192m -
XX:MaxPermSize=128m -verbose:gc –XX:+PrintGCTimeStamps -
XX:+PrintGCDetails %DEBUG_OPTS%

• Sun JRE (as of 1.4), log to file

set CATALINA_OPTS=-Xmx768m -XX:MaxNewSize=384m -XX:NewSize=192m -
XX:MaxPermSize=128m –Xloggc:<path+filename> %DEBUG_OPTS%

Explore Java memory management © Copyright IBM Corporation 2016

Enable Verbose GC in IBM Cognos 11: Example using Tomcat with Command Line
To enable verbose garbage collection, edit the startup_tomcat.bat located in the ..\bin64
directory and add a command line argument to the call. The examples provided are
specific to using Tomcat. If you are not using Tomcat, then other steps apply.

© Copyright IBM Corp. 2010, 2016 4-22

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 4 Explore Java memory management

Enable Verbose GC in IBM Cognos 11: Example using Tomcat as a

Service
• Edit bootstrap_xxxx.xml in the ..\bin64 folder and add a new <param>
element directly after
<param>-Xmx${dispatcherMaxMemory}m</param>
• IBM JRE
<param>-Xmx${dispatcherMaxMemory}m</param>
<param> –Xverbosegclog:../logs/gc.log</param>
…
• Sun JRE
<param>-Xmx${dispatcherMaxMemory}m</param>
<param> –Xloggc:../logs/gc.log</param>

Explore Java memory management © Copyright IBM Corporation 2016

Enable Verbose GC in IBM Cognos 11: Example using Tomcat as a Service

This example requires a restart of the IBM Cognos 11 service.

© Copyright IBM Corp. 2010, 2016 4-23

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 4 Explore Java memory management

Enable Verbose GC: CGS and DQM

• Cognos Graphic Service
 Additional JRE parameters can be put into
− cgsserver.sh (UNIX)
− ..\webapps\p2pd\WEB_INF\services\cgsService.xml (Windows)
• Dynamic Query Mode
 Additional JRE parameters can be put into
− ..\webapps\p2pd\WEB_INF\services\queryService.xml (Windows and UNIX)

Explore Java memory management © Copyright IBM Corporation 2016

Enable Verbose GC: CGS and DQM

© Copyright IBM Corp. 2010, 2016 4-24

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 4 Explore Java memory management

Enable GC Logging in WAS

1. In Administrative Console, expand Servers, click Application Servers, and
then click the desired server.
2. On Configuration tab, under Server Infrastructure, expand Java and
Process Management, and click Process Definition.
3. Under Additional Properties section, click Java Virtual Machine.
4. Select the Verbose garbage collection check box, and then click Apply.
5. At the top of the Administrative Client, click Save to apply changes to the
master configuration.
6. Stop and then restart the Application Server.
7. The verbose garbage collection output is written to either native_stderr.log or
native_stdout.log for the Application Server, depending on the SDK operating
system as follows:
For AIX®, Microsoft® Windows®, or Linux®:
native_stderr.log
For Solaris™ or HP-UX:
native_stdout.log

Explore Java memory management © Copyright IBM Corporation 2016

Enable GC Logging in WAS

WAS is WebSphere Application Server.

© Copyright IBM Corp. 2010, 2016 4-25

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 4 Explore Java memory management

Tuning GC: IBM JRE

• garbage collection frequency is too high until the heap reaches a steady state
 use verbosegc to determine the size of the heap at a steady state and set -Xms to this
value
• heap is fully expanded and the occupancy level is greater than 70%
 increase -Xmx value so that the heap is not more than 70% occupied
 for best performance try to ensure that the heap never pages
 maximum heap size should, if possible, be able to be contained in physical memory
• at 70% occupancy the frequency of garbage collections is too great
 change the setting of -Xminf
 default is 0.3, which tries to maintain 30% free space by expanding the heap
 a setting of 0.4, for example, increases this free space target to 40%, and reduces the
frequency of garbage collections
• pause times are too long
 try using -Xgcpolicy:optavgpause
 this reduces the pause times and makes them more consistent when the heap
occupancy rises
 it does, however, reduce throughput by approximately 5%, although this value varies
with different applications

Explore Java memory management © Copyright IBM Corporation 2016

Tuning GC: IBM JRE

These are some examples of tuning GC for IBM JRE.

© Copyright IBM Corp. 2010, 2016 4-26

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 4 Explore Java memory management

JVM Tuning and Dynamic Cubes

• Dynamic cubes have large, long-lived caches, partially pre-loaded.
• Require much larger heap sizes (may be >120 GB).
• Occupy more of the tenured space in a generational garbage collector.
• May require reduced nursery size.

Explore Java memory management © Copyright IBM Corporation 2016

JVM Tuning and Dynamic Cubes

Dynamic Query is a Java-based engine and can be tuned to optimize JVM
performance. The most common setting that users need to adjust is the maximum java
heap size, but there are many configurables that can be used to tune the JVM for the
specific usage patterns experienced in an enterprise environment. The default settings
generally work well for traditional DQM implementations which tend to use smaller heap
sizes (< 10GB) and have usage consisting of many short-lived transactions with modest
caching.

© Copyright IBM Corp. 2010, 2016 4-27

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 4 Explore Java memory management

The memory allocation pattern of dynamic cubes changes over time. Because dynamic
cubes preload the member and aggregate caches when the cube is started, they
exhibit different patterns while starting/refreshing than while queries are running against
them. During a start/refresh, the cube loads a large number of objects into the JVM
which will stay alive for quite a long time. In a generational garbage collector, these
objects must first survive a number of nursery collections before they are promoted to
tenured space. Since the nursery is optimized to copy small numbers of live objects to
survivor spaces during collections, this behavior causes long pauses for large
nurseries. So, during the load/refresh phase, it is ideal to have a smaller nursery, to
reduce such pauses. However when queries are executing (especially after the caches
are sufficiently warm), it is good to have a larger proportion of nursery space because
the objects created during a query are short lived, so they play well into the nursery
collection policy. Further, a larger nursery is even more useful the higher the user
concurrency because higher concurrency usually causes a higher proportion of the
JVM heap is being used for short-lived objects.

© Copyright IBM Corp. 2010, 2016 4-28

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 4 Explore Java memory management

Configure the JVM for Query Service

Explore Java memory management © Copyright IBM Corporation 2016

Configure the JVM for Query Service

In IBM Cognos Administration, there are eight JVM configurable values available for
tuning the Query Service.
The first four properties allow you to adjust the minimum and maximum sizes of the
overall JVM respective nursery sizes within the overall heap.
For more information on the individual properties, refer to the product documentation.
For more details on heap sizing, refer to
http://publib.boulder.ibm.com/infocenter/javasdk/v6r0/index.jsp?topic=%2Fcom.ibm.jav
a.doc.diagnostics.60%2Fdiag%2Funderstanding%2Fmm_heapsizing_initial.html.

© Copyright IBM Corp. 2010, 2016 4-29

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 4 Explore Java memory management

Tips on tuning settings

• Set initial heap size large enough for normal operation.
• Set the maximum heap size large enough for peak operation plus 15%
for overhead to prevent unnecessary GCs.
• Set initial nursery size to 0.

Explore Java memory management © Copyright IBM Corporation 2016

Tips on tuning settings

Set the initial heap size large enough for normal operation. It should be large enough to
fit all the caches and run most reports at the required level of concurrency. For more
information on hardware requirements, see the document entitled Understanding
Hardware Requirements for Dynamic Cubes in the Business Analytics Proven
Practices Web location at http://www.ibm.com/developerworks/analytics/practices.html.
https://www.ibm.com/developerworks/library/ba-pp-infrastructure-cognos_specific-
page659/
Set the maximum heap size large enough for peak operation plus a small (15%)
overhead to prevent unnecessary GCs. It should be large enough to absorb the
memory spikes that can occur when more data volume-intensive queries are executed
or a higher concurrency is experienced.
Set the initial nursery size to 0 unless there is a problem. This will allow the system to
calculate the initial nursery size as a proportion of the initial heap size. The calculated
proportion has been shown to achieve better performance, especially during and
immediately after the priming phase.

© Copyright IBM Corp. 2010, 2016 4-30

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 4 Explore Java memory management

Set the maximum nursery size to an appropriate level, given your expected amount of
caching, reporting style, and concurrency requirements. The idea is for all the
temporary objects created during report execution to fit in the nursery so they aren't
promoted to tenured space. That way they can take advantage of the nursery's
collection policy. A larger proportion of nursery space to tenured space is required for
higher concurrency and/or data volume-intensive reports with modest caching, than for
lower concurrency and/or simple reports with aggressive caching. For the former, you
may choose to set the maximum nursery size to 50% of the maximum heap. For the
latter, you could leave it set to 0 and the system will calculate it as a smaller proportion
of the maximum heap.
Set the maximum tenured size using the -Xmox setting in the additional arguments to
the maximum heap - maximum nursery. This should generally be large enough to fit all
the caches, plus a 10-20% buffer. Since tenured space is generally increased before
nursery space, this maximum allow the tenured space to expand large enough to fit all
the caches and then allow the nursery space to increase to accommodate queries,
which generally only need short term space.
Set minimum tenured size using the -Xmos setting in the additional arguments to the
same value as maximum tenured space? This will prevent unnecessary GCs for
increasing the size.

© Copyright IBM Corp. 2010, 2016 4-31

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 4 Explore Java memory management

Phases of Dynamic Cubes operation

Unallocated Space =
Maximum Heap - Tenure - Nursery

Tenure

Nursery

Explore Java memory management © Copyright IBM Corporation 2016

Phases of Dynamic Cubes operation

The tuning setting tips should allow the heap proportions to be adjusted automatically
by the JVM so that they are optimal for the distinct phases of dynamic cubes operation.
While there is no theoretical limit on the maximum heap size, performance starts to
degrade as more long-lived objects are added to memory. The theory is that tenured
GC is scanning all the objects to find dead ones and that gets more expensive. Also, it
may be more expensive to allocate objects when there are many objects alive, due to
overhead. GC pauses may become prohibitively long when the heap usage grows
beyond ~120GB, so the initial heap size generally should not be set larger than that
value, and the maximum heap size should not be much larger. Of course, pause time
can also vary due to hardware variances and enterprise environment patterns, and so
this is not a hard limit.

© Copyright IBM Corp. 2010, 2016 4-32

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 4 Explore Java memory management

Analysis of JVM Garbage Collection

• Out of Memory (OOM) messages
• Heapdumps
• Verbose GC logs

Explore Java memory management © Copyright IBM Corporation 2016

Analysis of JVM Garbage Collection

Out of memory (OOM) messages: Severe out of memory conditions can affect the
stability of the Query Service. In such cases, the Query Service will become unavailable
in the portal. In this case, the maximum JVM heap size (and probably the three others)
should be increased, and the Query Service should be restarted.
In the case where the Query Service is able to remain stable, the Query Service will
report the OutOfMemoryError to every user who's action was affected by the error. This
includes report execution as well as admin operations (such as cube cache refreshes).
The error message also includes the current setting for the maximum JVM heap size,
so you can cross reference it to the setting in the portal. For example: "Insufficient
memory. The current JVM maximum heap size of the QueryService is 512MB and may
need to be increased".

© Copyright IBM Corp. 2010, 2016 4-33

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 4 Explore Java memory management

Heapdumps and MAT tool: When an OutOfMemoryError occurs, one or more heap
dump files are generally created in the bin or bin64 directory. These are useful for
looking at the contents of the heap at the time of the error to find the root cause of
issues and can be analyzed with the Memory Analyzer Tool. Information on the
Memory Analyzer Tool is available at:
http://www.ibm.com/developerworks/java/jdk/tools/mat.html.
Verbose GC logs and ISA tool: Verbose GC logging is particularly useful for analyzing
and tuning JVM garbage collection. A detailed set of instructions for how to interpret the
log and use it to tune the JVM is beyond the scope of this course, but it should be noted
that:
• Verbose GC logging is enabled by default
• You can disable it or adjust the size of the log with the dedicated parameters in
the portal
• The IBM Support Assistant tool is useful for analyzing the log (Information on the
ISA tool is available at: http://www-01.ibm.com/software/support/isa/.)
• Large collection times generally indicate insufficient heap/nursery sizes,
suboptimal proportions of nursery and tenured space

© Copyright IBM Corp. 2010, 2016 4-34

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 4 Explore Java memory management

What happens in a JRE crash?

• Dump file called a Java core created
• Depending on the JRE version one of these files is in the ..\bin
directory of the IBM Cognos 11 install
 HS_err_(timestamp).txt
 Javacore_(timestamp).txt

Explore Java memory management © Copyright IBM Corporation 2016

What happens in a JRE crash?

A JRE can crash like any other process, and when that happens, a dump file is created.
Depending on the version of your JRE you will get one of two files in the ..\bin directory
of the IBM Cognos 11 install.
Depending on the JRE, the file will contain local environment info, JRE information,
thread dumps (per thread) in a Stack trace, GC history, memory information, and
ClassLoader information. This file may be required by IBM Cognos Support to help
troubleshoot issues.

© Copyright IBM Corp. 2010, 2016 4-35

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 4 Explore Java memory management

What should you do if Java hangs?

• Force a Java dump or Threaddump:
 Windows: Ctrl+Break (only works in CMD window)
 UNIX: Kill -3 <Java_PID>

Explore Java memory management © Copyright IBM Corporation 2016

What should you do if Java hangs?

Sometimes a Java process churns or hangs, and is unresponsive. To troubleshoot,
force a Java dump or Threaddump to obtain similar information as a Java core file.

© Copyright IBM Corp. 2010, 2016 4-36

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 4 Explore Java memory management

Use tools to monitor Java

• Process Explorer:
 https://technet.microsoft.com/
en-us/sysinternals/processexplorer.aspx
• IBM Support Assistant:
 http://www-01.ibm.com/software/support/isa/

Explore Java memory management © Copyright IBM Corporation 2016

Use tools to monitor Java

© Copyright IBM Corp. 2010, 2016 4-37

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 4 Explore Java memory management

Unit summary
• Describe Java memory layout
• Manage Java memory
• Use tools to monitor Java memory

Explore Java memory management © Copyright IBM Corporation 2016

Unit summary

© Copyright IBM Corp. 2010, 2016 4-38

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
Examine Audit logging and Indication Processing Facility
logging

Examine Audit logging and

Indication Processing Facility
logging

IBM Cognos Analytics 11.0

© Copyright IBM Corporation 2016

Course materials may not be reproduced in whole or in part without the written permission of IBM.
 Unit 5 Examine Audit logging and IPF logging

© Copyright IBM Corp. 2010, 2016 5-2

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 5 Examine Audit logging and IPF logging

Unit objectives
• Describe installation logs and configuration logs
• Explore audit logging
• Explore IPF logging

Examine Audit logging and IPF logging © Copyright IBM Corporation 2016

Unit objectives

© Copyright IBM Corp. 2010, 2016 5-3

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 5 Examine Audit logging and IPF logging

What are installation logs?

• Record activities performed by installation wizard transferring files
 Install
 Error summary
 Installer specification

Examine Audit logging and IPF logging © Copyright IBM Corporation 2016

What are Installation logs?

Creation of these log files is enabled by default. They provide details of the installation
activities of the product.

© Copyright IBM Corp. 2010, 2016 5-4

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 5 Examine Audit logging and IPF logging

Review installation logs

• Transfer Log
• Installation Configuration Log

Examine Audit logging and IPF logging © Copyright IBM Corporation 2016

Review installation logs

You will review the installation logs over the next few pages.

© Copyright IBM Corp. 2010, 2016 5-5

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 5 Examine Audit logging and IPF logging

Explore the Transfer log

Examine Audit logging and IPF logging © Copyright IBM Corporation 2016

Explore the Transfer log

The IBM_Cognos_Analytics_Install_<date>_<time>.log file is located in the ..\logs
directory and contains information on the components that were installed, disk space
information, selections made in the transfer dialogs, and any errors the installation
wizard encountered while transferring components. It also contains the activities that
the installation wizard performed while transferring files.
The example in the slide represents a section of the file contents.

© Copyright IBM Corp. 2010, 2016 5-6

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 5 Examine Audit logging and IPF logging

Explore the Installation Configuration log

Examine Audit logging and IPF logging © Copyright IBM Corporation 2016

Explore the Installation Configuration log

The install_configuration.log file is located in the ..\logs directory and contains
configuration activities during the installation, such as the available port for the
dispatcher.
The example in the slide represents a section of the file contents.

© Copyright IBM Corp. 2010, 2016 5-7

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 5 Examine Audit logging and IPF logging

Explore the Runtime log

Examine Audit logging and IPF logging © Copyright IBM Corporation 2016

Explore the Runtime log

The default IBM Cognos log file, named cogserver.log, records information after you
start the IBM Cognos Analytics service. The information in these files can highlight
problems, or provide information to help diagnose problems in your runtime
environment.
The example in the slide represents a section of the file contents.

© Copyright IBM Corp. 2010, 2016 5-8

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 5 Examine Audit logging and IPF logging

Explore the Content Manager Results logs

• Records activities product performed creating initial Content Store
hierarchy and objects.
• Activities are logged to files CMCreateBaseObjectsScript_results.xml
and CMCreateScript_results.xml in the ..\logs directory.

Examine Audit logging and IPF logging © Copyright IBM Corporation 2016

Explore the Content Manager Results logs

If you see these logs, you will know that Content Store was created.
The Content Manager Results logs may include log files that start with 00x. These
include additional setup information of the Content Store. For example,
002.CMCreatePageletObjects_results.xml shows the setup of the portlets for IBM
Cognos Administration.
Note: In the lab environment used in this course, the logs directory has been cleared,
so you will not see these files.

© Copyright IBM Corp. 2010, 2016 5-9

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 5 Examine Audit logging and IPF logging

Explore logging of Content Store Hierarchy creation

Examine Audit logging and IPF logging © Copyright IBM Corporation 2016

Explore logging of Content Store Hierarchy creation

The CMCreateBaseObjectsScript_results.xml contains the results of the creating the
initial content hierarchy.
If you receive a message that an error was detected while creating the initial content
objects, to troubleshoot the problem, check the
..\logs\CMCreateBaseObjectsScript_results.xml log file to see what was created.

© Copyright IBM Corp. 2010, 2016 5-10

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 5 Examine Audit logging and IPF logging

Explore logging of creation of initial Content Store objects

Examine Audit logging and IPF logging © Copyright IBM Corporation 2016

Explore logging of creation of initial Content Store objects

The CMCreateScript_results.xml contains the results of the creation of the initial
Content Store objects, including security objects.
The element <updateResult xsi:type="SOAP-ENC:Array" SOAP-
ENC:arrayType="cm:baseClass[132]"> tells us that 132 objects (items) were created in
the initial Content Store.
The SOAP message in the slide displays the SOAP response.

© Copyright IBM Corp. 2010, 2016 5-11

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 5 Examine Audit logging and IPF logging

Explore properties of IBM Cognos Configuration

Examine Audit logging and IPF logging © Copyright IBM Corporation 2016

Explore properties of IBM Cognos Configuration

You can explore the properties of IBM Cognos Configuration to obtain system
information such as Java version, Java vendor, Java install path, local host name, local
IP address, IBM Cognos 11 install path, Java system properties, selected environment
variables and installed IBM Cognos 11 components.
In IBM Cognos Configuration, press Ctrl+ F3, and the results will be written to a dialog
box. Here you can review system properties and installed components.

© Copyright IBM Corp. 2010, 2016 5-12

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 5 Examine Audit logging and IPF logging

Logging of IBM Cognos Configuration

• Obtain information on Java path and the loading of JAR files on launch
of IBM Cognos Configuration

Examine Audit logging and IPF logging © Copyright IBM Corporation 2016

Logging of IBM Cognos Configuration

If you cannot open IBM Cognos Configuration, you can double-click cogconfig.bat or
cogconfig.sh in the ..\bin directory (in the ..\bin64 directory for 64-bit installations). You
may encounter this if there is a JVM/JRE issue. The output will be written to a
command window.
To obtain additional information on the launch of IBM Cognos Configuration, in a
command window, run cogconfig.bat or cogconfig.sh with the parameters –log and –d.
This creates a cogconfig_<timestamp>.log in the ..\logs directory, and will provide more
detail on why IBM Cognos Configuration did not load.

© Copyright IBM Corp. 2010, 2016 5-13

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 5 Examine Audit logging and IPF logging

What is the cogstartup.xml file?

• It is located in ..\configuration folder.
• Backups have timestamp suffix.
• It contains IBM Cognos 11 configuration settings.

Examine Audit logging and IPF logging © Copyright IBM Corporation 2016

What is the cogstartup.xml file?

This file contains all of the IBM Cognos configuration settings for a specific installed
instance of IBM Cognos 11.

© Copyright IBM Corp. 2010, 2016 5-14

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 5 Examine Audit logging and IPF logging

What is the coglocale.xml file?

• It is located in ..\configuration folder.
• Backups have timestamp suffix.
• Records configuration choices made in IBM Cognos Configuration for
product and content locales, locale mapping, and currency support.

Examine Audit logging and IPF logging © Copyright IBM Corporation 2016

What is the coglocale.xml file?

If you experience problems with language support in the user interface or in reports,
use these files to track your changes.

© Copyright IBM Corp. 2010, 2016 5-15

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 5 Examine Audit logging and IPF logging

What is Audit logging in IBM Cognos 11?

• Audit Logging provides basic information about user and system
activity:
 User login/logoff
 Report executions
 Schedule executions
 Services start/stop
 Agent execution
 Authorization actions (add/remove permissions)
 Threshold violations (IBM Cognos Administration defined metrics)
 Human Task Service (HTS), Annotation Service (AS) activity

Examine Audit logging and IPF logging © Copyright IBM Corporation 2016

What is Audit logging in IBM Cognos 11?

Audit logging can answer the following questions: Who? When? What? Affecting what
object?
Audit logging is used to:
• audit the operation of a system or users
• monitor usage of reports
• gather usage statistics
• troubleshoot issues in conjunction with other log files
What about reports of users by role, in order to be SOX compliant? This functionality is
not available out of the box. However, the Audit Extension utility can be used to
accomplish this task. It is available from the IBM developerWorks Web site at
http://www.ibm.com/developerworks/data/library/cognos/development/utilities/page574.
html.

© Copyright IBM Corp. 2010, 2016 5-16

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 5 Examine Audit logging and IPF logging

Explore the basic architecture of Audit logging

Content Manager Report Server Dispatcher Mobile Other Services

Log Service (Log Server)

File Event Log Syslog Audit

(Windows) (UNIX)
Database

Logging Auditing

Examine Audit logging and IPF logging © Copyright IBM Corporation 2016

Explore the basic architecture of Audit logging

Components and services provide output generated locally to a local instance of Log
Service which runs on every installed instance and is the first service to start. This
service will collect the input and output it to local destinations.
The log messages are not sent through the BIBus, but are instead passed to the local
service through other means, such as direct port to port communication.
LogService is implemented by a component called Log Server.

© Copyright IBM Corp. 2010, 2016 5-17

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 5 Examine Audit logging and IPF logging

Set logging levels

Examine Audit logging and IPF logging © Copyright IBM Corporation 2016

Set logging levels

Logging levels are configurable through the IBM Cognos Administration UI for each
service. In IBM Cognos Administration, on the Status tab, the System page reveals a
scorecard, metrics, and settings. In the Scorecard pane, click on the server name that
you want to set logging on; for example, click http://<server_name>:port/p2pd for
properties at the dispatcher level.
Logging levels are set based on a service for audit logging in the UI. Since this UI only
reflects services (this is SOA), this is used as the base for defining the settings.
Internally the log level specified for the service will be mapped to components.

© Copyright IBM Corp. 2010, 2016 5-18

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 5 Examine Audit logging and IPF logging

Explain Audit logging levels

• Minimal (default)
• Basic
• Request
• Trace
• Full

Examine Audit logging and IPF logging © Copyright IBM Corporation 2016

Explain Audit logging levels

The Trace and Full levels can generate huge files in a short time, and therefore can
degrade server performance significantly, and should never be used during peak
periods. Because of this, once you gather your required information, you should then
reduce the log level.
The Minimal level is the default, which logs start and stop service logs and runtime
errors.
The Basic level logs the same as the Minimal level and also tracks the following:
Logon/Logoff/Logon Expired logs, Report and query execution logs, Schedule
execution logs, Agent mail, and Build and execution logs.
In addition to logging the same as the Basic level, the Request level logs also includes
SOAP request and response logs.
The Trace level logs the same as the Basic level and includes requests to components
with parameter values or function calls.
The Full level logs all of the above.

© Copyright IBM Corp. 2010, 2016 5-19

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 5 Examine Audit logging and IPF logging

Demonstration 1
Set logging levels

Examine Audit logging and IPF logging © Copyright IBM Corporation 2016

Demonstration 1: Set logging levels

© Copyright IBM Corp. 2010, 2016 5-20

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 5 Examine Audit logging and IPF logging

Demonstration 1:
Set logging levels

Purpose:
You want to configure logging for the system. To become familiar with the
logging available, you will use the IBM Cognos Administration tool.
The IBM Cognos 11 Full:9315 dispatcher and the IBM Cognos 11 DispCM:9320
dispatcher should be running at the beginning of this demonstration.
Task 1. Select a dispatcher to configure.
1. Launch Internet Explorer, go to http://vclassbase:88/ibmcognos/bi/, log on
with admin/Education1 credentials, and then launch IBM Cognos
Administration console.
2. On the Status tab, click System.
3. In the Scorecard pane, click vclassbase, and then click
http://vclassbase:9315/p2pd.
A section of the result appears as follows:

Task 2. Configure the Logging settings.

1. In the Settings pane, expand Logging.
The current logging level is displayed, which is minimal logging for the
dispatcher.
2. To access logging settings at the dispatcher level, click the Set properties icon
on the Settings pane title bar.
3. In the Category list, click Logging.
There are many entries available to configure logging. Each service can be
configured independently across the system.
4. Click Next Page to review more entries, and then click First Page.
Leave IBM Cognos Administration open.

© Copyright IBM Corp. 2010, 2016 5-21

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 5 Examine Audit logging and IPF logging

Task 3. Review the results of minimal logging for the

dispatcher.
Next, you will view the logging results using IBM Cognos Log Viewer, a tool to
simplify analyzing log files in IBM Cognos.
1. Launch Windows Explorer, navigate to C:\Program
Files\IBM\cognos\analytics_full\bin, and then double-click logviewV2.exe.
Optionally, you may want to create a shortcut for IBM Cognos Log Viewer on
the desktop, for your convenience, as it will be used a few times in the course.
2. In IBM Cognos Log Viewer, from the File menu, click Load Cognos Log
File(s), and then double-click cogserver.log.
3. Near the bottom left, click the cogserver.log tab, and then click an entry near
the bottom until details appear in the bottom pane. Scroll through the lower
pane to read the entry details.
You may see information similar to the following (the exact message will differ,
depending on the actions that have occurred in your environment):

Minimal tracing logs start and stop service logs and runtime errors. The most
recent entries that you see should include these types of messages. Notice that
there are no entries for logging on or off, or query executions, as that is not
traced at the minimal level.
4. Close IBM Cognos Log Viewer.
You will work more with this application later.

© Copyright IBM Corp. 2010, 2016 5-22

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 5 Examine Audit logging and IPF logging

Task 4. Modify the logging level to request level tracing.

1. Switch to IBM Cognos Administration, on the Set properties page, for the
Audit logging level for the dispatcher entry, change the value from Minimal
to Request, and then click OK.
2. In the Settings pane, expand Logging.
The new logging level is displayed.

Task 5. Run a report, and observe the results.

1. Switch to the Welcome tab, log off Admin Person, and then log on again with
admin/Education1 credentials.
2. Click Team content, navigate to Samples_DQ\Models\GO Sales
(query)\Report Studio Report Samples, and run the Horizontal
Pagination_DQ report.
3. When the report displays, log off Admin Person.
4. In Windows Explorer, navigate to C:\Program Files\
IBM\cognos\analytics_full\bin, and double-click logviewV2.exe, or use the
Desktop shortcut if you created one.
5. From the File menu, click Load Cognos Log File(s), and then double-click
cogserver.log.

© Copyright IBM Corp. 2010, 2016 5-23

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 5 Examine Audit logging and IPF logging

6. Near the bottom left, click the cogserver.log tab, maximize the window, and
then scroll to the bottom of the log, reviewing the most recent entries.
You may see a message similar to the following:

Notice that there are many more entries that are tracked at this level of logging.
The Request level logs start and stop service logs and runtime errors, tracks
Logon/Logoff/Logon Expired logs, Report and query execution logs, Schedule
execution logs, Agent mail, and Build and execution logs, and includes SOAP
request and response logs.
Task 6. Set the logging state back to Minimal.
1. Switch to IBM Cognos Administration, if prompted, log on as
admin/Education1 and on the Set properties page, for the Audit logging
level for the dispatcher entry, change the value from Request to Minimal,
and then click OK.
2. Close all open windows.
Results:
You used IBM Cognos Administration to explore the logging available in IBM
Cognos 11, and set the audit logging for the Dispatcher service to Request
tracing level.

© Copyright IBM Corp. 2010, 2016 5-24

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 5 Examine Audit logging and IPF logging

What is Native Query logging?

Examine Audit logging and IPF logging © Copyright IBM Corporation 2016

What is Native Query logging?

For Report service, Batch report service and PowerPlay service, there is an additional
setting to enable capturing the SQL/MDX sent to the query engine in audit logging. The
captured SQL/MDX is not necessarily the one sent to the database, as the query
engine might apply changes for various reasons.
The true native SQL/MDX can only be captured at the database side or in UDA trace
(SQL for relational) or MDX debug output.

© Copyright IBM Corp. 2010, 2016 5-25

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 5 Examine Audit logging and IPF logging

Explain Audit logging destinations

• It is the target for audit logging data.
• Several types of destinations are supported for different purposes.
• Multiple destinations can be used at the same time.
• Not every destination will output the same data.

Examine Audit logging and IPF logging © Copyright IBM Corporation 2016

Explain Audit logging destinations

Several types of destinations are supported for different purposes, including database,
files, Windows Event log, UNIX System log (Syslog), and Remote log service.
Depending on the destination, the generated log data will be filtered. Information that
will vary includes the level of detail and the services and components that will be
included.
For information on tables that are available in the audit logging database and what they
are used for, refer to the IBM Cognos Analytics: Enterprise Administration (v11.0)
course, and the IBM Cognos Analytics Administration and Security Guide 11.0.0.

© Copyright IBM Corp. 2010, 2016 5-26

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 5 Examine Audit logging and IPF logging

Where are destinations stored?

• Audit database:
 stores audit logging data in a relational database schema for reporting.
• Destinations are defined in IBM Cognos Configuration.
 default destination is File.
 additional destinations can be defined as required.

Examine Audit logging and IPF logging © Copyright IBM Corporation 2016

Where are destinations stored?

The destination database is commonly referred to as the audit database.
Currently-supported databases include IBM DB2, Microsoft SQL Server, and Oracle.
Some business reasons for audit logging include: to gather usage statistics for reports,
to track the execution of reports, agents, and schedules, and to determine user activity.
IBM Cognos 11 provides a sample Framework Manager model and deployment that is
included in the IBM Cognos Analytics Samples install component. Model files can be
found in the ..\webcontent\samples\models\Audit directory. Sample reports are provided
in a deployment archive file located at
..\webcontent\samples\content\IBM_Cognos_Audit.zip.
The IBM Cognos Analytics Samples are a separate install and do not come with the
base IBM Cognos 11 server install.
The Informix database that is used for the content store database in a Ready to Run!
installation is not supported as an audit database.

© Copyright IBM Corp. 2010, 2016 5-27

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 5 Examine Audit logging and IPF logging

Explore the File log

• Stores output in flat tab delimited file(s)
• No filtering
• Default configuration out of the box
 Log file name is cogserver.log, size 10 MB, single file only

Examine Audit logging and IPF logging © Copyright IBM Corporation 2016

Explore the File log

The destination File stores output in flat tab delimited file(s), for which you can configure
the number and size of the log files. If all files are filled, the oldest one will get deleted
and a new one is created for the most recent output (rolling windows). You will need to
stop, and then start the IBM Cognos service to apply the new configuration settings.
The output is not filtered at all, and contains SQL/MDX if native query logging has been
enabled.
cogserver.log should be the first place to look if something does not work or stops
working. It is unusual to change the default destination, and it is recommended that
name cogserver.log be used for this file.

© Copyright IBM Corp. 2010, 2016 5-28

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 5 Examine Audit logging and IPF logging

The configuration fields are as follows:

• Type: The destination type (not modifiable).
• Log file location: location and file name of the log file. The ../ indicates the install
directory.
• Maximum Size of Log File in MB: Maximum size before a new file will be
created.
• Maximum Number of Full Log Files: The number of log files created. Can be a
value between 1 and 10,000.
If multiple log files get created then the name of the files would be cogserver.1.log,
cogserver.2.log.
The file without any .#.log, for example cogserver.log, will always have the most recent
information.

© Copyright IBM Corp. 2010, 2016 5-29

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 5 Examine Audit logging and IPF logging

Explore the Windows Event Log

• Send audit logging messages to the Windows Event log
• No filtering
• Requires IBM Cognos 11 to be started as a Windows service

Examine Audit logging and IPF logging © Copyright IBM Corporation 2016

Explore the Windows Event log

Logging messages are sent to the Application log; you may have to adjust the
maximum size of the log to suit your environment. Use this when running as a Windows
service to support integration with an Event Log based system management.
No filtering is applied, and it will not include SQL/MDX even if native query logging has
been enabled.
This logging requires IBM Cognos 11 to be started as a Windows service, and does not
work if IBM Cognos 11 is launched with startup.bat. The NT Event log source field is
going to be the name that shows under the Source Column in the Windows Event Log.
This value is modifiable.
If the Event Log source name changes in IBM Cognos Configuration, then the service
will be unregistered with the old name, and the new name will get registered. Restarting
the Windows service is necessary for these settings to take effect. Use startup.bat in
test environments for a quick startup; it will run in a command window.

© Copyright IBM Corp. 2010, 2016 5-30

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 5 Examine Audit logging and IPF logging

Explore the UNIX System log

• Send audit logging messages to the UNIX/LINUX system log (syslog)
• No filtering

Examine Audit logging and IPF logging © Copyright IBM Corporation 2016

Explore the UNIX System log

Use this logging mechanism when running on UNIX/Linux to support integration with
syslog based system management.
No filtering is applied, and it will not include SQL/MDX even if native query logging has
been enabled.
The configuration fields are as follows:
• Syslog host name: The name of the machine for the log file to be generated on.
• Syslog facility: The system component generating the system log. Possible
values are KERN, USER, MAIL, DAEMON, AUTH, SYSLOG, LPR, NEWS,
UUCP, CRON, AUTHPRIV, FTP, LOCAL0, LOCAL1, LOCAL2, LOCAL3,
LOCAL4, LOCAL5, LOCAL6, LOCAL7.

© Copyright IBM Corp. 2010, 2016 5-31

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 5 Examine Audit logging and IPF logging

What is the Remote Log Server?

• Sends locally generated audit logging messages to remote instance of
Log Server through IP protocol
• No filtering
• Federating logs is ambivalent

Examine Audit logging and IPF logging © Copyright IBM Corporation 2016

What is the Remote Log Server?

Use this method to collect and merge log messages from IBM Cognos 11 servers in a
distributed install into one location. Log messages are sent to a remote instance of Log
Server as UDP (User Datagram Protocol) by default, but could be sent by TCP as an
alternative. SSL encryption can be applied.
No filters are applied, and all output is forwarded to the destination Log Server.
Federating, or joining logs is ambivalent, so you get the advantage of all logs in one
location, but this will require more effort to identify an issue on a certain installed
instance. It is suggested to keep local file based destinations and specify Remote Log
Service destinations additionally. If the connection to the remote Log Server is lost, local
recovery files will get created.

© Copyright IBM Corp. 2010, 2016 5-32

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 5 Examine Audit logging and IPF logging

Example of Remote Log Server Process

Installed Instance 1 Installed Instance 2

Component(s) Component(s)

TCP/UDP
Log Server Log Server

Destination Destination

Examine Audit logging and IPF logging © Copyright IBM Corporation 2016

Example of Remote Log Server Process

A component of installed instance 1 sends information to the local Log Service which
sends it to the remote Log service on installed instance 2. Installed instances may not
necessarily be on different servers. The Log service on installed instance 2 will send the
info to one of the output destinations defined for installed instance 2.
Transmission is by TCP or UDP. TCP and UDP are both OSI layer 4 protocols and part
of the Internet Protocols (IP) suite. While TCP is a reliable protocol which supports
integrity checking, preserving the sequence of transmitted data and the confirmation
from the receiver if the data was received completely, this is not supported by UDP.
UDP is a protocol that sends the message and forgets about it on the client side. In
practice UDP is faster but does not guarantee that data reaches the recipient in the
right order or integrity. This can imply losing log messages or receiving them in the
wrong order. Under high loads however, UDP might be a practical choice.

© Copyright IBM Corp. 2010, 2016 5-33

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 5 Examine Audit logging and IPF logging

Exercise 1
Configure a Windows Event Log and review the Runtime log

Examine Audit logging and IPF logging © Copyright IBM Corporation 2016

Exercise 1: Configure a Windows Event Log and review the Runtime log

© Copyright IBM Corp. 2010, 2016 5-34

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 5 Examine Audit logging and IPF logging

Exercise 1:
Configure a Windows Event Log and review the Runtime log

You want to familiarize yourself with the information which is logged to the
cogserver.log file, and compare that to information logged in a Windows Event log for
IBM Cognos 11. You will have to configure a Windows Event log, and then run some
activities in IBM Cognos 11, so that you can compare results between the two logs.
To do this you will:
• In IBM Cognos Administration, set the logging level for the dispatcher to Request.
• in IBM Cognos Configuration of the IBM Cognos 11 Full instance, create a new
resource: Destination, named Windows7; type: Event log
• save the configuration, and restart the services
• perform activities such as running DQM reports in IBM Cognos 11 to populate the
runtime log; logged on with admin/Education1 credentials (you will use DQM as
this is the only server currently running, in the interest of time stopping and
restarting the servers)
• review the logged results in Event Viewer
• review the logged results in C:\Program Files\IBM\cognos\analytics_full\
logs\cogserver.log, using Microsoft Excel
• Return the logging level for the dispatcher to Minimal.
For more information about where to work and the exercise results, refer to the Tasks
and Results section that follows. If you need more information to complete a task, refer
to earlier demonstrations for detailed steps.

© Copyright IBM Corp. 2010, 2016 5-35

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 5 Examine Audit logging and IPF logging

Exercise 1:
Tasks and Results
At the beginning of this exercise, the IBM Cognos Full:9315 dispatcher is running; the
IBM Cognos DispCM:9320 dispatcher is not running. This is solely to reserve system
resources. Stop the IBM Cognos DispCM:9320 dispatcher if it is running.
The audit logging level for the dispatcher should be set to Request.
Task 1. Set audit logging for the dispatcher to Request.
• As admin\Education1, launch IBM Cognos Administration console, and then
on the Status tab, click System.
• In the Scorecard pane, click vclassbase, and then click
http://vclassbase:9315/p2pd.
• Click the Set properties icon on the Settings pane title bar.
• In the Category list, click Logging.
• Set the value for Audit logging level for the dispatcher to Request, and then
click OK.
• Close all browser windows.
Task 2. Configure logging to the Windows Event log.
Currently, your environment is logging to the runtime log, and you also want to log to a
Windows destination, to compare the results.
• From the Start menu, click All Programs, click IBM Cognos Analytics Full, and
then click IBM Cognos Configuration.
• In the Explorer pane, navigate to Environment\Logging.
• Right-click Logging, click New resource, and then click Destination.
• In the New Resource - Destination dialog box, name the destination
Windows7.

© Copyright IBM Corp. 2010, 2016 5-36

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 5 Examine Audit logging and IPF logging

• From the Type list, select Event log, and then click OK.
You have configured logging to the Windows Event log destination.

• Save the configuration and restart the services, closing all messages that appear.
Be patient, as it will take a few minutes for all the underlying services to restart. If
the Lotus Domino Server (CProgramFilesx86IBMLotusDominodata) service is not
running in the Services window, you will see a message in IBM Cognos
Configuration indicating that the mail server cannot be reached. This is
acceptable because you are not using the mail server at this time.
• Close IBM Cognos Configuration when the services have successfully started.
Task 3. Perform activities in IBM Cognos 11 to populate
cogserver.log.
• Launch Internet Explorer, go to http://vclassbase:88/ibmcognos/bi/, and then
log on as admin/Education1.
• In My content, run the job called Run Multiple Chart Reports DQM.
If you did not perform the demonstration earlier in this course that created this job,
you can run a few random dynamic query reports of your choice.
When you run the job, you can monitor the execution by selecting Properties,
selecting the Job tab, expanding Advanced, and then beside Run History, clicking
View.
• After the reports run (this will take a few moments), close the browser window.
Task 4. Review the logged results in Event Viewer.
• To open Event Viewer, from the Start menu, navigate to Control
Panel\Administrative Tools, and then double-click Event Viewer.
• Maximize the window (if necessary), and then in the navigation pane on the left,
expand the Windows Logs folder.
There are five categories of messages for you to view: Application, Security,
Setup, System, and Forwarded Events.

© Copyright IBM Corp. 2010, 2016 5-37

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 5 Examine Audit logging and IPF logging

• Click Application.
It may take some time for the entries to display.
• Under the Source column, double-click an IBM Cognos entry.
The information is displayed for the entry.
• Close the Event Properties window.
• Click the Details tab, click + to expand System, and then review the information.
The results appear similar to the following:

• Scroll through the list of entries in the Application pane, opening an IBM Cognos
entry for each of the following types: Information, Warning, and Error (if
applicable)
• When you have finished reviewing the events, close the Event Viewer window,
close the Administrative Tools window, and then close the Control Panel
window.

© Copyright IBM Corp. 2010, 2016 5-38

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 5 Examine Audit logging and IPF logging

Task 5. Review the logged results in cogserver.log.

• Launch Windows Explorer, navigate to C:\Program
Files\IBM\cognos\analytics_full\logs, and then open cogserver.log with
Microsoft Excel.
The file will be locked, as the server is using it, so open as read only when
prompted. You may also be prompted about the file not loading completely;
accept this message.
If the Text Import Wizard appears, click Finish.
The results appear similar to the following:

• Scroll through the messages, and notice that they include different information
than what was tracked in the Windows Event log.
The information tracked in cogserver.log is collected at a lower level of detail.
• When you have finished reviewing this file, close Microsoft Excel without saving
changes, and then close Windows Explorer.
Task 6. Set audit logging for the dispatcher to Minimal.
• As admin\Education1, launch IBM Cognos Administration console, and then
on the Status tab, click System.
• In the Scorecard pane, click vclassbase, and then click
http://vclassbase:9315/p2pd.
• Click the Set properties icon on the Settings pane title bar.
• In the Category list, click Logging.
• Set the value for Audit logging level for the dispatcher to Minimal, and then
click OK.
• Close all browser windows.

© Copyright IBM Corp. 2010, 2016 5-39

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 5 Examine Audit logging and IPF logging

What is IPF logging?

• Based on Indication Processing Facility (IPF)
• IPF is thin wrapper around log4j
 Many applications use log4j as logging framework
 Update log4j default configuration file for applications that integrate with IBM
Cognos 10

Examine Audit logging and IPF logging © Copyright IBM Corporation 2016

What is IPF logging?

log4j is a Java-based logging utility that allows configuration of what information is
output to log files. It is used primarily as a debugging tool, and is one of several Java
logging frameworks. log4j is part of the Jakarta project of the Apache Software
Foundation.
Although the Apache Jakarta Project has been retired, more information is available at
http://jakarta.apache.org and http://logging.apache.org/log4j/1.2/.

© Copyright IBM Corp. 2010, 2016 5-40

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 5 Examine Audit logging and IPF logging

Explore the basic architecture of IPF logging

Components/Services

Content Manager Report Server Dispatcher Mobile Other Services

IPF Service

Output File Event Log Syslog Supported

(Windows) (Unix)
Databases

Logging

Examine Audit logging and IPF logging © Copyright IBM Corporation 2016

Explore the basic architecture of IPF logging

IPF has a client-server architecture. The IPF Server is configured through IBM Cognos
Configuration and IBM Cognos Administration, and IPF clients use their own
configuration files.
In the diagram, the IPF Clients are the Components/Services.

© Copyright IBM Corp. 2010, 2016 5-41

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 5 Examine Audit logging and IPF logging

What are IPF indications?

• Indication, category
• 3 types
 Audit
 Trace
 Performance

Examine Audit logging and IPF logging © Copyright IBM Corporation 2016

What are IPF indications?

Another word for indication is category. There are 3 types of indications:
• Audit: shows calls that are made from components
• Trace: shows what tasks and function calls are being performed
• Performance: shows the amount of system resources taken for a task

© Copyright IBM Corp. 2010, 2016 5-42

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 5 Examine Audit logging and IPF logging

What are the fields of Audit and Trace indications?

• Host Identity • Step ID • Object Type

• Process ID • Thread ID • Object Path
• Time • Component ID • Status
• TimeZone Offset • Build Number • Message
• Session ID • Level • Log Data
• Request ID • Logger Name
• SubRequest • Operation

Examine Audit logging and IPF logging © Copyright IBM Corporation 2016

What are the fields of Audit and Trace indications?

These fields are what is parsed out to logviewerV2.
Host Identity: Identifies the system on which the indication was generated. It is
expressed as an IP address.
Process ID: The operating system assigned Process ID (PID). The Process ID
provides information that aids in the analysis of process flow and
the correlation of the actions within a component.
Time: Local system time of the event.
TimeZone Offset: Offset from GMT.
Session ID: Represents the session where the definition of a session is the
lifetime of a passport ID and its passport.
Request ID: An ID representing the request.

© Copyright IBM Corp. 2010, 2016 5-43

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 5 Examine Audit logging and IPF logging

SubRequest ID: Subrequest ID of a component.

Step ID: An ID representing the step within a job execution, otherwise it is
empty.
Thread ID: An ID representing the thread where the request is executing.
Component ID: The four character name of the component generating the
indication.
Build Number: Build number of component.
Level: Logging level that this indication was created with.
Logger Name: Component that is processing the indication.
Operation: Action being performed on an object.
Object Type: Object on which the action is being performed. It depends on the
context but often it will be the name of a service that the Component
ID is calling.
Object Path: Path of the object on which the action is being performed. This field
is often empty but when populated it is usually a Content Store
search path or a connection string.
Status: Operations where a start and end indication are written.
Message: Content of what was performed.

© Copyright IBM Corp. 2010, 2016 5-44

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 5 Examine Audit logging and IPF logging

Applicability of Audit and Trace indication fields

Field Name Minimal Basic Request Trace Full

Host Identity Mandatory Mandatory Mandatory Mandatory Mandatory
Process ID Mandatory Mandatory Mandatory Mandatory Mandatory
Time Mandatory Mandatory Mandatory Mandatory Mandatory
TimeZone Mandatory Mandatory Mandatory Mandatory Mandatory
Session ID N/A Mandatory Mandatory Mandatory Mandatory
Request ID Optional Optional Mandatory Mandatory Mandatory
SubRequestID N/A Optional, Conditional Mandatory Mandatory Mandatory
Mandatory*
StepID N/A N/A Conditional Mandatory** Conditional Mandatory** Conditional Mandatory**
Thread ID Mandatory Mandatory Mandatory Mandatory Mandatory
Component ID Mandatory Mandatory Mandatory Mandatory Mandatory
Build Number Mandatory Mandatory Mandatory Mandatory Mandatory
Level Mandatory Mandatory Mandatory Mandatory Mandatory
LoggerName Mandatory Mandatory Mandatory Mandatory Mandatory
operation Mandatory Mandatory Mandatory Mandatory Mandatory
logData Mandatory Mandatory Mandatory Mandatory Mandatory
objectType Optional Mandatory Mandatory N/A N/A
objectPath Optional Optional Mandatory N/A N/A
status Mandatory Mandatory Mandatory N/A N/A
Message Optional, Conditional Optional, Conditional Optional, Conditional N/A N/A
Mandatory*** Mandatory*** Mandatory***

* if RequestID exists **only for jobs *** if error occurs

Examine Audit logging and IPF logging © Copyright IBM Corporation 2016

Applicability of Audit and Trace indication fields

This indicates what fields will show in an indication for specific levels. N/A represents a
field that is not applicable for the given level.

© Copyright IBM Corp. 2010, 2016 5-45

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 5 Examine Audit logging and IPF logging

What are the fields of Performance indication?

• Host Identity* • Component ID* • Commops

• Process ID* • Build Number* • Commio
• Time* • Level* • Elapsed Time
• TimeZone Offset* • Logger Name* • Class ID
• Session ID* • Resource ID • Method ID
• Request ID* • CPU Time • Sequence ID
• SubRequest ID* • Memory • Execution ID
• Step ID* • Disk Operations • StatusLog Data
• Thread ID* • Disk IO

Examine Audit logging and IPF logging © Copyright IBM Corporation 2016

What are the fields of Performance indication?

Fields with an asterisk are identical to audit and trace indications, and the other fields
are specific to performance indications.
There are other logs and traces that capture performance, such as Perf.QFS, UDA.
Resource ID: ID used for internal purposes
CPU Time: Amount of time used by the CPU for processing
Memory: Current memory used by object.
Disk Operations: Count of disk operations made by object.
Disk IO: Total bytes read and written by the object.
Commops: Count of network operations made by an object.
Commio: Total bytes read and written over network links.
Elapsed time: Amount time taken in total to process.
Class ID: Name of object creating the indication.

© Copyright IBM Corp. 2010, 2016 5-46

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 5 Examine Audit logging and IPF logging

Method ID: The name of the method/function from where the indication is being
generated.
Sequence ID: Value to distinguish multiple indications being logged in the same
context.
Execution ID: Unique ID for the indication to distinguish a given indication from
another due to a call to the same component.
Status: Current action represented by the indication.
Log Data: Any custom data that a component wants to log.

© Copyright IBM Corp. 2010, 2016 5-47

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 5 Examine Audit logging and IPF logging

What are IPF Client logs?

• Component-specific IPF logs
• Configuration files have the form
ipfXXXXclientconfig where XXXX
represents component name
• ipfClientConfig.xml
• Files reside in ..\configuration

Examine Audit logging and IPF logging © Copyright IBM Corporation 2016

What are IPF Client logs?

Component specific IPF logs cannot be configured in IBM Cognos Analytics 11, but
instead configuration is done to a file named ipfClientConfig.xml. As more IBM Cognos
components are installed, more ipfXXXXclientconfig files will be installed. Some
component specific IPF files may have different layouts or verbosity levels regarding
comments in them. Most important though, is that they may differ in the way they are
used. Some files require modification beyond renaming them to get output.
When employing internal IPF based logging, enabling a client configuration file will
disable the audit logging configured, including audit DB.
IPF Client logs can be useful to troubleshoot components (all tracing and debugging),
or to troubleshoot performance issues of a component.

© Copyright IBM Corp. 2010, 2016 5-48

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 5 Examine Audit logging and IPF logging

Explain IPF Client logging (1 of 2)

• IPF maintains watch on the ipfclientconfig.xml file pinging for it every
60 seconds.
• Rename the required ipfXXXXclientconfig.xml.sample file to
ipfclientconfig.xml.
• If ipfclientconfig.xml file is found, logging instantly is reconfigured
according to file contents.
• Logs tracing and performance indications.

Examine Audit logging and IPF logging © Copyright IBM Corporation 2016

Explain IPF Client logging

It is best practice to make a copy of the ipfXXXXclientconfig.xml.sample first before you
rename (and edit) the required ipfXXXXclientconfig.xml.sample file to
ipfclientconfig.xml.
If the ipfclientconfig.xml file is found, logging in the system is automatically reconfigured
according to file contents and no restart of IBM Cognos 11 is required. To disable the
logging, rename the file back to what it was before it was renamed to ipfclientconfig.xml.
Only Tracing and Performance indications are generally logged in IPF client logging.
Audit indications must be explicitly enabled and special configuration must be applied
so that Audit indications are sent back to the IPF Server where they are properly written
to the configured Audit output targets.

© Copyright IBM Corp. 2010, 2016 5-49

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 5 Examine Audit logging and IPF logging

Explain IPF Client logging (2 of 2)

• Client configurations impose complete override of audit logging
settings
• Mapping file (..\configuration\ipfstartup.xml) loaded at LogService
startup maps services to components

<service id="dispatcher">
<component id="DISP"/>
<component id="dispatcher"/>
<component id="CAF"/>
</service>

Mapping file

Examine Audit logging and IPF logging © Copyright IBM Corporation 2016

Client configurations impose a complete override of the audit logging settings. Audit
logging configures the IPF Server only and does so only for audit categories, and
ipfclientconfig.xml overrides at the IPF Client.
You may need to customize an ipfclientconfig.xml file to incorporate the audit logging
settings to have tracing and audit logging in parallel. Changes to the files may be
required if your are not running in Tomcat, or if the default log port has been changed.
If Audit logging been enabled, it is best to try to replicate issues in a non-production
environment, so that IPF client logs can be taken without impacting the audit
information in the production environment.
Audit logging is simply a UI-enabled subset of IPF functionality. Internal logging is more
sophisticated and detailed, and its main purpose is for troubleshooting.

© Copyright IBM Corp. 2010, 2016 5-50

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 5 Examine Audit logging and IPF logging

When to use ipfXXXXclientconfig.xml (1 of 2)

Component File to Use Helps Troubleshoot

DISP ipfdispclientconfig.xml.sample Start-up problems (including services started by the

Dispatcher), load balancing, performance
BIBUS ipfBiBusclientconfig.xml.sample Low level communication between Dispatchers and
Report Services
CM ipfCMclientconfig.xml.sample Content Store database access problems
CRP ipfcryptoclientconfig.xml.sample Keystore access and synchronization, access to AutoCA,
SSL/Trust issues, Trusted Request problems
AAA ipfaaaclientconfig.xml.sample Security issues
CAF ipfCAFclientconfig.xml.sample Database access problems, get error details strip by the
CAF secure error feature, get details about CAF
validation failures, get textual descriptions of CAF
configuration failures, debug CAF internal failures
XTS ipfXTSclientconfig.xml.sample Cognos Portal Service (CPS) issues, Event Studio UI
issues
JSM, DLS, ipfSDSclientconfig.xml.sample Scheduling (JSM, JS), E-mail delivery (DLS), Agents
JS, MS, (ASV), Future scheduled events or schedules (EMS),
ASV, EMS Background tasks currently running (MS)

Examine Audit logging and IPF logging © Copyright IBM Corporation 2016

When to use ipfXXXXclientconfig.xml

© Copyright IBM Corp. 2010, 2016 5-51

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 5 Examine Audit logging and IPF logging

When to use ipfXXXXclientconfig.xml (2 of 2)

Component File to Use Helps Troubleshoot

RSVP ipfRSVPclientconfig.xml.sample Report Service / Batch Report Service, reports and queries,
performance
CQE ipfCQEclientconfig.xml.sample See notes
MDDS ipfMDDSconfig.xml.sample Interaction with 3rd party OLAP providers such as SAP,
MSAS and DB2OLAP
UDA ipfUDAclientconfig.xml.sample Runtime Queries
CRX ipfCRXclientconfig.xml.sample Report Expressions
DMB ipfDMBclientconfig.xml See notes
FM ipfFMclientconfig.xml.sample Framework Manager
XQE ipfXQEclientconfig.xml.sample Dynamic Query Mode issues
HTS ipfHTSclientconfig.xml.sample Human Task Service issues
MOB ipfMOBclientconfig.xml.sample Cognos Mobile issues

Examine Audit logging and IPF logging © Copyright IBM Corporation 2016

For CQE troubleshooting using the ipfCQEclientconfig.xml.sample file:

• Trace logging records the input received by CQE (such as governor settings),
warnings, and detailed information about input query translation to CQE internal
logical and physical query trees.
• Performance logging records the time spent in CQE functions.
• Audit logging records all CQE query service API calls.
For DMB (Dynamic Molap Builder) troubleshooting using the ipfDMBclientconfig.xml file:
• Audit data: Audit.RTUsage.DAM.DMB records information about Public API
function call (names and parameters): the XML model definition, the data
streams, and the request to build the cube.
• Trace data: Trace.DAM.DMB records information about the Exceptions thrown in
DMB, policy implementation, and specific failures.
• Performance data: Perf.DAM.DMB records information about the time spent to
build the cube (time spent in DMB and PPDS).

© Copyright IBM Corp. 2010, 2016 5-52

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 5 Examine Audit logging and IPF logging

Describe SDS logging

• ipfSDSclientconfig controls logging of several services.
• To turn on trace logging for the Agent Service in
ipfSDSclientconfig.xml:
 Search for <level value="warn">
 Change <level value="warn"> to <level value="debug">

<category name="Trace.ASV" class="com.cognos.indications.LogTypedLogger">

<level value="warn"/>
<appender-ref ref="clientFlatFile"/>
</category>

Examine Audit logging and IPF logging © Copyright IBM Corporation 2016

Describe SDS logging

The slide provides an example of turning on trace logging for the Agent service.

© Copyright IBM Corp. 2010, 2016 5-53

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 5 Examine Audit logging and IPF logging

Most commonly used IPF traces

• CM
• AAA
• UDA / MDDS
• CQE
• PERF
• DISP
• RSVP

Examine Audit logging and IPF logging © Copyright IBM Corporation 2016

Most commonly used IPF traces

These are the most common IPF traces that are used on a regular basis.

© Copyright IBM Corp. 2010, 2016 5-54

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 5 Examine Audit logging and IPF logging

Unit summary
• Describe installation logs and configuration logs
• Explore audit logging
• Explore IPF logging

Examine Audit logging and IPF logging © Copyright IBM Corporation 2016

Unit summary

© Copyright IBM Corp. 2010, 2016 5-55

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 5 Examine Audit logging and IPF logging

Exercise 2
Configure IPF logging

Examine Audit logging and IPF logging © Copyright IBM Corporation 2016

Exercise 2: Configure IPF logging

© Copyright IBM Corp. 2010, 2016 5-56

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 5 Examine Audit logging and IPF logging

Exercise 2:
Configure IPF logging

You need to configure log files to get additional logging information for Cognos 11
components. These log files are useful in getting additional information for specific
Cognos 11 Components. Specifically, you will implement IPF logging on the dispatcher
and Content Manager components. You will be working with the IBM Cognos Full
instance only, in this exercise.
To do this you will:
• Set the audit level of the dispatcher to Request
• Make a copy of ipfdispclientconfig.xml.sample and rename it to
ipfdispclientconfig.xml
• Open ipfdispclientconfig.xml in Internet Explorer, examine elements of the file,
and focus on the <appender> sections, noting the target file names and locations
• What is the difference between the <appender> sections named
fileWithFilter and clientFlatFile?
• Implement IPF logging on the dispatcher
• Stop services for the IBM Cognos Full:9315 instance
While this is not necessary to implement the logging, it will provide additional
content in the logs than if you made the change without restarting the service.
• Rename the file appropriately and start the services
• Stop services and examine the log file in Microsoft Excel
• Disable IPF logging on the dispatcher
• Repeat as above for the Content Manager using the
ipfCMclientconfig.xml.sample file
• Set the audit level of the dispatcher back to Minimal and then review the results of
the Content Manager logging
For more information about where to work and the exercise results, refer to the Tasks
and Results section that follows. If you need more information to complete a task, refer
to earlier demonstrations for detailed steps.

© Copyright IBM Corp. 2010, 2016 5-57

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 5 Examine Audit logging and IPF logging

Exercise 2:
Tasks and Results
At the beginning of this exercise, the IBM Cognos Full:9315 dispatcher is running; the
IBM Cognos DispCM:9320 dispatcher is not running. This is solely to reserve system
resources.
Task 1. Set audit logging for the dispatcher to Request.
• As admin\Education1, launch IBM Cognos Administration console, and then
on the Status tab, click System.
• In the Scorecard pane, click vclassbase, and then click
http://vclassbase:9315/p2pd.
• Click the Set properties icon on the Settings pane title bar.
• In the Category list, click Logging.
• Set the value for Audit logging level for the dispatcher to Request, and then
click OK.
• Close all browser windows.
Task 2. Open the ipfdispclientconfig.xml file and examine the
elements of the file.
When IPF logging is implemented on the ipfdispclientconfig.xml file, it can be used to
troubleshoot start-up problems, including services started by the dispatcher, load
balancing issues, and performance issues.
• In Windows Explorer, navigate to C:\Program
Files\IBM\cognos\analytics_full\configuration, copy
ipfdispclientconfig.xml.sample, and then paste to the same directory.
• Rename ipfdispclientconfig.xml - Copy.sample to ipfdispclientconfig.xml,
from the file properties, ensure that the Read-only attribute is not selected, and
then open the file in Internet Explorer (iexplore.exe).
If the Information Bar displays a message about running scripts, click the
Information Bar, click Allow Blocked Content, and then click Yes.

© Copyright IBM Corp. 2010, 2016 5-58

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 5 Examine Audit logging and IPF logging

• Locate the following section:

- <appender class="org.apache.log4j.RollingFileAppender"
name="fileWithFilter">
<!-- The setting for the File parameter below has been tested with
ReportNet while running under Tomcat.Because of their ‘current
working directory’, other application servers (e.g. WebLogic), may
require that an absolute path to the log file be specified. Ensure
the log directory is writable. -->
<param name="File" value="../logs/crnclientWarn.log"/>
<param name="MaxBackupIndex" value="1"/>
<param name="MaximumFileSize" value="10485760"/>
- <layout class="org.apache.log4j.PatternLayout">
<param name="ConversionPattern" value="%m%n"/>
</layout>
- <filter class="org.apache.log4j.varia.LevelRangeFilter">
<param name="LevelMin" value="WARN"/>
<param name="LevelMax" value="WARN"/>
</filter>
</appender>
This section is used to define a log file that includes a filter as defined by <param
name="LevelMin" value="WARN" /> and <param name="LevelMax"
value="WARN" />. As a result this file will only capture WARN messages if they
are generated.
• Locate the following section:
<appender class="org.apache.log4j.RollingFileAppender"
name="clientFlatFile" >
<param name="File" value="../logs/crnclient.log"/>
<param name="MaxBackupIndex" value="1"/>
<param name="MaximumFileSize" value="10485760"/>
- <layout class="org.apache.log4j.PatternLayout">
<param name="ConversionPattern" value="%m%n" />
</layout>
</appender>
This section is used to define a log file that is not filtered. As a result this file will
capture WARN messages and all lower messages, such as STOP and START, if
they are generated.
Notice that both sections include parameters for defining:
• a target file name and location for log output, for example:
• <param name="File" value="../logs/crnclient.log" />
• file properties, for example:
• <param name="MaxBackupIndex" value="1" /> - maximum number
of log files that will ever exist

© Copyright IBM Corp. 2010, 2016 5-59

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 5 Examine Audit logging and IPF logging

• <param name="MaximumFileSize" value="10485760" /> - maximum

size of the log file in KB
Note: With these property settings, when the file reaches its maximum
size, log data begins to be overwritten. If MaxBackupIndex value is
set to > 1, then once the maximum file size is reached additional log
files will be created as <name>.log.1, <name>.log.2, <name>.log.3
depending on the set value.
• Close Internet Explorer.
Task 3. Implement IPF logging on the dispatcher using
ipfdispclientconfig.xml.
• On the Taskbar, click Services, and then stop the IBM Cognos Full:9315
service.
While this is not necessary to implement the logging, it will provide additional
content in the logs than if you made the change without restarting the service.
• In Windows Explorer, rename ipfdispclientconfig.xml to ipfclientconfig.xml.
• Navigate to C:\Program Files\IBM\cognos\analytics_full\logs.
• Delete all files from the root of the logs folder, and then start the IBM Cognos
Full:9315 service.
Do not delete the XQE directory or its contents.
If a message displays, indicating that the service did not start in a timely fashion,
click OK to dismiss this message. Wait until this instance has fully started (you
may do a refresh of the display every two minutes) before proceeding to the next
step.

© Copyright IBM Corp. 2010, 2016 5-60

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 5 Examine Audit logging and IPF logging

• When the service has successfully started, navigate to C:\Program

Files\IBM\cognos\analytics_full\logs to identify the log files that are generated
as a result of the start operation, including the crnclient_xxxx.log files.
The results appear similar to those shown below:

• Stop the IBM Cognos Full:9315 service.

• Open the most recent crnclient_xxxx.log file with Microsoft Excel (the other
crnclient_xxxx.log file will be empty).
If an activation message appears for Microsoft Excel, dismiss the message, and
continue.
If the Text Import Wizard appears, click Finish to import the data using default
settings.
In Microsoft Excel, you may have to click the crnclient_xxxx tab to see the results
display.

© Copyright IBM Corp. 2010, 2016 5-61

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 5 Examine Audit logging and IPF logging

At this point the crnclient_xxxx.log file contains start up information only, as that is
the only operation you have performed. Notice that columns map to the indication
fields seen earlier in the content of this unit.
The results appear similar to the following:

• Close Microsoft Excel without saving changes.

• At C:\Program Files\ibm\cognos\analytics_full\configuration, delete the
ipfclientconfig.xml file.
Task 4. Open the ipfCMclientconfig.xml file and examine the
elements of the file.
• Copy ipfCMclientconfig.xml.sample and paste to the same directory.
• Rename ipfCMclientconfig.xml - Copy.sample to ipfCMclientconfig.xml, and
then open it in Internet Explorer.
Disregard the running scripts message if it appears in the browser, or allow the
blocked content.

© Copyright IBM Corp. 2010, 2016 5-62

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 5 Examine Audit logging and IPF logging

• Locate the following section:

<appender class="org.apache.log4j.RollingFileAppender"
name="cmFlatFile">
<!--__________________________________________________________________-->
<!-- The setting for the File attribute below has been tested with
ReportNet while running under Tomcat. -->
<!-- For other application servers (e.g. WebLogic), because of their
COG_ROOT setting, the below -->
<!-- file attribute may require that an absolute path to the log file be
specified. Ensure the log directory is writable. -->
<!-- For a distributed install on a single machine ensure only one
application writes to any given log file -->
<!--__________________________________________________________________-->
<param name="File" value="../logs/cm_trace.log"/>
<param name="MaxBackupIndex" value="1"/>
<param name="MaximumFileSize" value="10485760"/>
- <layout class="org.apache.log4j.PatternLayout">
<param name="ConversionPattern" value="%m%n"/>
</layout>
</appender>
Again, notice that this section includes parameters for defining a target file name
and location for log output, and file properties.
• Close Internet Explorer.
Task 5. Implement logging on the Content Manager using
ipfCMclientconfig.xml.
• Open the Services window and ensure that the IBM Cognos Full:9315 service
is not running (stop it if necessary).
• In Windows Explorer, rename ipfCMclientconfig.xml to ipfclientconfig.xml.
• Navigate to C:\Program Files\ibm\cognos\analytics_full\logs, and then delete
all files from the root of the logs folder.
Do not delete the XQE directory or its contents.
• Start the IBM Cognos Full:9315 service.

© Copyright IBM Corp. 2010, 2016 5-63

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 5 Examine Audit logging and IPF logging

• When the service has successfully started, navigate to C:\Program

Files\IBM\cognos\analytics_full\logs to identify the log files that are generated
as a result of the start operation, including the cm_trace_xxxx.log files.
The results appear similar to the following:

Task 6. Set audit logging for the dispatcher to Minimal and

review the cm_trace_xxxx.log file.
• As admin\Education1, launch IBM Cognos Administration console, and then
on the Status tab, click System.
• In the Scorecard pane, click vclassbase, and then click
http://vclassbase:9315/p2pd.
• Click the Set properties icon on the Settings pane title bar.
• In the Category list, click Logging.
• Set the value for Audit logging level for the dispatcher to Minimal, and then
click OK.
• Close all browser windows.

© Copyright IBM Corp. 2010, 2016 5-64

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 5 Examine Audit logging and IPF logging

• Stop the IBM Cognos Full:9315 service, and when it has stopped, open the
largest cm_trace_xxxx.log file in Microsoft Excel, and review the contents.
If an activation message appears for Microsoft Excel, dismiss the message, and
continue.
At this point the cm_trace_xxxx.log file contains start up information only, as that
is the only operation you have performed. Again, notice that columns map to the
indication fields seen earlier in this unit.
The results appear similar to those shown below:

Note: If you see messages regarding "runTimeState" is unknown, it could be due

to the dispatcher being too busy when starting, to be able to return a value.
• Close Microsoft Excel without saving.
• At C:\Program Files\ibm\cognos\analytics_full\configuration, delete the
ipfclientconfig.xml file.
• Close all open windows.

© Copyright IBM Corp. 2010, 2016 5-65

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 5 Examine Audit logging and IPF logging

© Copyright IBM Corp. 2010, 2016 5-66

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
Perform dye tracing

Perform dye tracing

IBM Cognos Analytics 11.0

© Copyright IBM Corporation 2016

Course materials may not be reproduced in whole or in part without the written permission of IBM.
 U n i t 6 P e r f o r m d ye t r a c i n g

© Copyright IBM Corp. 2010, 2016 6-2

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 6 P e r f o r m d ye t r a c i n g

Unit objectives
• Identify dye tracing requirements
• Perform dye tracing

Perform dye tracing © Copyright IBM Corporation 2016

Unit objectives

© Copyright IBM Corp. 2010, 2016 6-3

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 6 P e r f o r m d ye t r a c i n g

What is dye tracing?

• Allows tracing of actions by a single user or a set of users
• Implements special filter to be leveraged in Indication Processing
Facility (IPF) appenders
• Enabled through Java Management Extensions (JMX) and IPF
configuration
• Enabled/disabled at run-time only

Perform dye tracing © Copyright IBM Corporation 2016

What is dye tracing?

By dye tracing the actions of defined users, the actions of other users will be filtered out
in the trace. This is useful to focus on specific users, as previously all actions of all
users would be trapped in a dye trace, producing large quantities of data to review. Dye
tracing is available to all IPF (Indication Processing Facility) based logging, and can
filter all categories, and any type of indication. You could use this method, for example,
if someone is having a login problem, as this could trace their efforts, and by defining
the user, you can focus on the user(s) being traced.
Dye tracing is based on a user's CAMID. You can get the CAMID from a user's
Properties page in IBM Cognos Analytics, using the Search path property, to add to the
JMX dialog box. You can add more than one CAMID; the CAMID(s) act as parameters
to the IPF filter.
Dye tracing is to be enabled or disabled at run-time only. JMX parts reset if IBM Cognos
Analytics is shut down or restarted, as there is no persistence in the JMX. The CAMIDs
to dye trace will need to be re-entered, but the IPF files will have maintained their
information and require no further modification.

© Copyright IBM Corp. 2010, 2016 6-4

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 6 P e r f o r m d ye t r a c i n g

What are the requirements of JMX connectivity?

• Dye tracing requires JMX port and credentials
• CAMID of a user must be added to a JMX dialog
• Can use JConsole as tool to work with JMX properties

Perform dye tracing © Copyright IBM Corporation 2016

What are the requirements of JMX connectivity?

Dye tracing is enabled via Java Management Extensions (JMX). This requires the JMX
connectivity to be enabled in IBM Cognos Analytics and to have access to a JMX
console to actually work with the JMX properties. To enable JMX connectivity for dye
tracing, modify the external JMX port and JMX credential properties in IBM Cognos
Configuration.
CAMIDs are entered into the JMX property enableDyeTrace.

© Copyright IBM Corp. 2010, 2016 6-5

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 6 P e r f o r m d ye t r a c i n g

Add an IPF filter

• A filter can be added to any appender in IPF file

<appender name="ipfLocalFile" class="org.apache.log4j.RollingFileAppender">

<param name="File" value="../logs/AAAclient.log"/>
<param name="MaxBackupIndex" value="10"/>
<param name="MaximumFileSize" value="10485760"/>
<layout class="org.apache.log4j.PatternLayout">
<param name="ConversionPattern" value="%m%n"/>
</layout>
<filter class="com.cognos.indications.LogIPFDyeTraceFilter"/>
</appender>

Perform dye tracing © Copyright IBM Corporation 2016

Add an IPF filter

Dye tracing is implemented such that a <filter> is available for reference in IPF based
logging. This <filter> will exclude any IPF indication which does not originate from a
dyed user so that the remaining output contains dyed indications only.
Adding a new filter to any appender in an IPF file will filter indications from user
sessions that were not specified in the JMX dialog box. A <filter> element which is
referenced within an <appender> is used to define where to write the indication stream.
Any category making reference to that <appender> element will consequently provide a
superset of indications which the <appender> element might or might not dump to the
specified target, depending on the filter.
The filter in the slide example adds a dye tracing filter to the AAA trace
(ipfaaaclientconfig.xml).

© Copyright IBM Corp. 2010, 2016 6-6

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 6 P e r f o r m d ye t r a c i n g

Unit summary
• Identify dye tracing requirements
• Perform dye tracing

Perform dye tracing © Copyright IBM Corporation 2016

Unit summary

© Copyright IBM Corp. 2010, 2016 6-7

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 6 P e r f o r m d ye t r a c i n g

Exercise 1
Perform dye tracing

Perform dye tracing © Copyright IBM Corporation 2016

Exercise 1: Perform dye tracing

© Copyright IBM Corp. 2010, 2016 6-8

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 6 P e r f o r m d ye t r a c i n g

Exercise 1: Perform dye tracing

Dye tracing allows for the filtering of any IPF based logging to a defined set of users. To
achieve this, dye tracing leverages fields in the CAM cookie in IBM Cognos Analytics.
Once dye tracing is enabled, a special log4j <filter> can be added to any given IPF
<appender> to filter on only the dyed user's actions from the log stream. Any IPF based
logging in IBM Cognos Analytics can leverage the dye tracing functionality. log4j is a
Java-based logging utility.
You will enable user specific logging for IPF (dye tracing). To do this you will:
• Enable JMX connectivity:
• IBM Cognos Configuration: External JMX port 9700, and External JMX
credentials admin/Education1
• Gather the dyed log stream and write it to a log file:
• Change AAAclient.log to dyetrace_output.log
• Preceding the </appender> tag, add a filter:
<filter class="com.cognos.indications.LogIPFDyeTraceFilter"/>
• Change the <appender-ref> property as follows:
<appender-ref ref="DyeTraceOutput"/>
• Use IBM Cognos Administration to find the CAMIDs for users to dye trace: Frank
Bretton and Donald Chow
• Stop the IBM Cognos service, delete the log files, and then start the IBM
Cognos service (this will create an initially empty dyetrace_output.log file)
• Activate dye tracing using JConsole
(C:\Program Files (x86)\Java\jdk1.5.0_04\bin\jconsole.exe)
• Add the CAMIDs using the enableDyeTrace option
• Log on to IBM Cognos Analytics as a dyed user, and then as a non-dyed user
(Branka Hirsch, hirschb), repeating the same navigation tasks each time
• Optionally, log on as another dyed user, chowd, repeating the same navigation
tasks as the other users
• Stop the IBM Cognos Analytics Full: 9315 service, and investigate the results of
the trace by reviewing the log output file
• Start the IBM Cognos Analytics Full: 9315 service, for the next unit's exercise
For more information about where to work and the exercise results, refer to the Tasks
and Results section that follows.

© Copyright IBM Corp. 2010, 2016 6-9

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 6 P e r f o r m d ye t r a c i n g

Notes:
• Dye tracing is enabled via Java Management Extensions (JMX). This requires the
JMX connectivity to be enabled in IBM Cognos Analytics and to have access to a
JMX console to actually work with the JMXproperties. The Java Developer's Kit
(JDK) contains a JMX console called JConsole. As IBM Cognos Analytics comes
bundled with a JRE only, to get JConsole a JDK has to be installed. This is only
for the JConsole tool. If you have other JMX tools you may use those, however
this exercise will use JConsole. JConsole can run on any computer and is not
dependent on any IBM Cognos Analytics components. In the classroom
environment for this course, a JDK installed with Apache was used, jdk1.5.0_04.

© Copyright IBM Corp. 2010, 2016 6-10

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 6 P e r f o r m d ye t r a c i n g

Exercise 1:
Tasks and Results
At the beginning of this exercise, all dispatchers are stopped.
Task 1. Enable JMX connectivity for IBM Cognos Analytics.
• Launch the IBM Cognos Analytics Full instance of IBM Cognos
Configuration, and ensure that the IBM Cognos Full service is stopped.
• In the Explorer pane, click Environment.
You will configure the JMX properties for External JMX port and External JMX
credential.
If your environment is a distributed install, you will have to enable JMX
connectivity on each instance of the application tier. This environment is a
distributed install, however you will use only one instance in this exercise, so you
only have to enable JMX connectivity on this active instance.
• In the External JMX port property, type the available port number 9700, and
then press Enter.
• In the External JMX credential property, click Edit, type the admin/Education1
credentials, and then click OK.

• In IBM Cognos Configuration, on the toolbar click Save configuration, close

the message box when the process has finished, and then on the toolbar, click
Start.
• When all services have started, close the message, and then close IBM Cognos
Configuration.

© Copyright IBM Corp. 2010, 2016 6-11

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 6 P e r f o r m d ye t r a c i n g

Task 2. Gather the dyed log stream and write it to a log file.
An easy method of getting a dyed IPF based log file is to add the new <filter> to the
<appender> used in the pre-created IPF configurations. For example, consider the
ipfAAAclientconfig.xml.sample file which would be used to create an AAA trace to
troubleshoot authentication and security issues. It contains an <appender> which is
referenced by all the defined categories called "ipfLocalFile". This <appender> will write
to a file named AAAclient.log.
To add dye tracing to that file, simply add the <filter> to that <appender> and save the
file. This will create a dye tracing version of the AAA trace. The method you will use
here is to activate your IPF based logging by renaming the component specific IPF
trace, adding the <category> element, and adding dye tracing support by editing the
ipfclientconfig.xml file to add a new appender.
• In Windows Explorer, navigate to C:\Program
Files\IBM\cognos\analytics_full\configuration, make a copy of
ipfaaaclientconfig.xml.sample, paste it in the same location, and then rename
this new file as ipfclientconfig.xml.
• From the Taskbar, launch Eclipse. If the Workspace Launcher dialog box
appears, select the Use this as the default and do not ask again check box,
and then click OK. If the Usage Data Upload dialog box appears, select the Turn
UDC feature off button, and then click Finish. When Eclipse opens, close the
Welcome tab (if it is open).
• From the File menu, click Open File, navigate to C:\Program
Files\IBM\cognos\analytics_full\configuration, and then open
ipfclientconfig.xml.
• Maximize the Eclipse window, and then maximize the ipfclientconfig.xml tab.

© Copyright IBM Corp. 2010, 2016 6-12

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 6 P e r f o r m d ye t r a c i n g

• At the bottom of the pane click the Source tab, and then from the Edit menu, do
a Find/Replace for <appender name="ipfLocalFile".
The section appears similar to the following:
<appender name="ipfLocalFile"
class="org.apache.log4j.RollingFileAppender">
<!-- The setting for the file parameter below has been tested with
IBM Cognos 8 while running under Tomcat.Because of their 'current
working directory', other application servers (e.g. WebLogic), may
require that an absolute path to the log file be specified. Ensure
the log directory is writable.
-->
<param name="File" value="../logs/AAAclient.log"/>
<param name="MaxBackupIndex" value="10"/>
<param name="MaximumFileSize" value="10485760"/>
<layout class="org.apache.log4j.PatternLayout">
<param name="ConversionPattern" value="%m%n"/>
</layout>
</appender>
• Change AAAclient.log to dyetrace_output.log.
• Preceding the </appender> tag, add the following code:
<filter class="com.cognos.indications.LogIPFDyeTraceFilter"/>
A section of the result appears as follows:

• Do a Find for Audit.RTUsage.CAM.AAA and locate the following section:

<category name="Audit.RTUsage.CAM.AAA"
class="com.cognos.indications.LogTypedLogger" additivity="true">
<!-- Configurable levels: debug, error, off -->
<level value="debug"/>
<appender-ref ref="ipfLocalFile"/>
</category>
• Change the <level value> property in this section from debug to "error".
The results appear as follows:

© Copyright IBM Corp. 2010, 2016 6-13

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 6 P e r f o r m d ye t r a c i n g

• Change the <level value> property for the other categories to "off".
The results appear as follows:

By changing the logging levels, your dyetrace_output.log file will only store
messages related to logons, logoffs, expired logons, and failed logons.
• Save the file, and then close Eclipse. If necessary, select the Always exit
without prompt check box, and then click OK.
Dyed output will go to the file specified for the ipfLocalFile <appender>.

© Copyright IBM Corp. 2010, 2016 6-14

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 6 P e r f o r m d ye t r a c i n g

Task 3. Find the CAMIDs for the users that you want to dye
trace.
Dye tracing can be enabled for a defined set of users. This set is defined by the search
path for a user object in the Content Store in the form of a CAMID. As administrator,
you will use IBM Cognos Administration to obtain the CAMID for the users that you
want to trace.
• Launch Internet Explorer, go to http://vclassbase:88/ibmcognos/bi/, and then
log on as admin/Education1.
• From the Side panel, launch Manage/Administration console, and then click
the Security tab.
The users you want to trace are in the LDAP namespace.
• Click LDAP, and then click People.
• Navigate through the list to find Frank Bretton.
• In the Actions column for the Frank Bretton (brettonf) entry, click Set
properties, and then on the General tab, click View the search path, ID and
URL.
The CAMID information is displayed in the Search path box. The results appear
similar to the following:

• Copy the Search path contents, launch Notepad, and then paste the contents
into a text document.
• In IBM Cognos Administration, close the View the search path, ID and URL
dialog box, close the Set properties page, and then repeat the steps for Donald
Chow, to include him in your set of users to trace.
• In IBM Cognos Administration, close the View the search path, ID and URL
dialog box, close the Set properties page, and then click Log Off.
Close the browser window but leave Notepad open.

© Copyright IBM Corp. 2010, 2016 6-15

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 6 P e r f o r m d ye t r a c i n g

• From the Taskbar, launch Services, and stop the IBM Cognos Full:9315
service. When the service has fully stopped, in Windows Explorer, delete the
files from the root of the ..\logs directory, and then take note of the time.
..\ is the root of the IBM Cognos Analytics Full installation.
Do not delete the XQE directory or its contents.
• Start the IBM Cognos Full:9315 service.
If using the Services dialog to start IBM Cognos Full:9315 service, and a
message appears stating that it could not be started in a timely fashion, click OK,
and then click the Refresh button in two-minute intervals until you can see that
the service has started successfully.
Starting the IBM Cognos Full:9315 service will create the initially empty
dyetrace_output.log file.
Task 4. Activate dye tracing using JConsole.
• In Windows Explorer, navigate to C:\Program
Files (x86)\Java\jdk1.5.0_04\bin, and then double-click jconsole.exe to launch
JConsole.
Close any messages that appears regarding the color scheme being changed to
Windows 7 basic.
If you stop the IBM Cognos Analytics service, remember that JConsole is not
persistent, and to activate the dye tracing again, you will have to invoke another
JConsole session and re-enter the user(s) CAMID information for tracing.
• Click the Advanced tab.
You will use a connection string in the JMX URL field in the following format:
service:jmx:rmi://CM_Server/jndi/rmi://Monitoring_Server:<JMXport>/ proxyserver
CM_Server is the server name running Content Manager (vclassbase) and
Monitoring_Server is the server name running a JMX-enabled Dispatcher, which
in this environment is vclassbase.

© Copyright IBM Corp. 2010, 2016 6-16

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 6 P e r f o r m d ye t r a c i n g

• Populate the fields as follows:

• JMX URL: service:jmx:rmi://vclassbase/jndi/rmi://vclassbase:9700/
proxyserver
• User Name: admin
• Password: Education1

• Click Connect.
It may take a few moments for the contents in the Tree pane to appear.
• In the Tree pane, navigate to
com.cognos\"http://vclassbase:9315/p2pd"\Metrics, and then in the pane on
the right, click the Operations tab.
Several operations are displayed. You can add a single user to the set of dye
traced users, remove a single user from this set, or reset the whole set which will
disable dye tracing for all users.

© Copyright IBM Corp. 2010, 2016 6-17

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 6 P e r f o r m d ye t r a c i n g

• Copy the search path (CAMID) line for Frank Bretton that you pasted in Notepad,
paste it into the p1 text box for enableDyeTrace, replacing the current contents.
Ensure that you remove all text from the p1 text box and replace it with the
CAMID. The results appear similar to the following:

• Click enableDyeTrace.
• In the Info dialog box, click OK to close the message that the method was
successfully invoked.
• Click the Attributes tab, click Refresh, and then review the DyeTracedUsers
property to ensure that the CAMID information has been added.
The results appear similar to the following:

© Copyright IBM Corp. 2010, 2016 6-18

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 6 P e r f o r m d ye t r a c i n g

• Click the Operations tab, and then repeat the steps for the CAMID information
for Donald Chow.
• On the Attributes tab, click Refresh, and then double-click the DyeTracedUsers
property value to review the set of users to trace.
The results appear similar to the following:

You have defined the users that will be dye traced.

Leave JConsole open.
Task 5. Log on as a non-dyed user, and then as a dyed user.
• In Internet Explorer, go to http://vclassbase:88/ibmcognos/bi/, and then log
on as brettonf\Education1.
Frank Bretton is a dyed user.
• Navigate to Team content\Samples_DQ\Models\GO Sales (query).
• On the Application bar, click Frank Bretton, and then click My preferences.
• Click Frank Bretton, and then click Sign Out.
• Make note the time, and wait for 2 minutes to pass.
• Repeat the steps, logging on as a non-dyed user (hirschb/Education1).
Optionally, you can repeat the steps by logging on as another dyed user:
chowd/Education1.

© Copyright IBM Corp. 2010, 2016 6-19

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 U n i t 6 P e r f o r m d ye t r a c i n g

Task 6. Investigate the results of the trace.

• In Windows Explorer, disable the dye tracing by deleting the C:\Program
Files\IBM\cognos\analytics_full\configuration\ipfclientconfig.xml file.
• In the Services window, stop the IBM Cognos Analytics Full:9315 service.
Wait for the service to stop, before proceeding to the next step.
• Open Eclipse, and then close the ipfclientconfig.xml tab (if necessary).
• In Eclipse, open the most recent C:\Program
Files\IBM\cognos\analytics_full\logs\dyetrace_output_xxxx.log file that was
created during the trace (the other dyetrace_output_xxxx.log files will be empty).
The results appear similar to the following:

You could also open this file in another tool, such as Microsoft Excel.
Question: What entries do you see for each user? What entries are missing for
the non-dyed user? (Hint: Use the times you recorded to look in the log files.)
Answer: Only dye traced users are getting filtered.
Consider a large company with users logging in or out at all times; this could
generate large log files to review. Dye tracing is a great way to filter the results.
What you trace depends on the problem(s) they are having.
• Close the dyetrace_output_xxxx.log tab, and then close Eclipse.
• Close the Jconsole: Connect to Agent dialog box, and then close the J2SE 5.0
Monitoring & Management Console window.
• In the Services window, start the IBM Cognos Analytics Full:9315 service, and
then close all open windows without saving.

© Copyright IBM Corp. 2010, 2016 6-20

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
Explore Dynamic Query Mode

Explore Dynamic Query Mode

IBM Cognos Analytics 11.0

© Copyright IBM Corporation 2016

Course materials may not be reproduced in whole or in part without the written permission of IBM.
 Unit 7 Explore Dynamic Query Mode

© Copyright IBM Corp. 2010, 2016 7-2

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 7 Explore Dynamic Query Mode

Unit objectives
• Perform Dynamic Query Mode (DQM) logging
• Analyze queries using IBM Cognos Dynamic Query Analyzer (DQA)

Explore Dynamic Query Mode © Copyright IBM Corporation 2016

Unit objectives

© Copyright IBM Corp. 2010, 2016 7-3

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 7 Explore Dynamic Query Mode

Available Dynamic Query Mode logging

• XQE log files
• IPF logging
• QFS logging
• BAPI tracing (for SAP BW)
• QueryService logging

Explore Dynamic Query Mode © Copyright IBM Corporation 2016

Available Dynamic Query Mode logging

Usually, DQM logging would be done under the guidance of customer support.
A general starting point for troubleshooting errors or connectivity issues is to review
XQELog files.
IPF logging is used mainly to enable XQE audit logging.
QFS logging is used for tracing performance and communication between XQE and the
BIBus.
BAPI tracing for SAP BW is enabled in XQE.diagnosticlogging.xml.
QueryService logging is useful for troubleshooting report issues.

© Copyright IBM Corp. 2010, 2016 7-4

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 7 Explore Dynamic Query Mode

Describe XQE log files (1 of 2)

• Located in ..\logs\XQE by default
 ..\ refers to the product install directory.
• Log files generated by default
 xqelog-<date>-<timestamp>.xml
 queriesNotPlanned
 usage
 requestDumps

Explore Dynamic Query Mode © Copyright IBM Corporation 2016

Describe XQE log files

The xqelog files are at the root of the XQE directory and are date and time stamped.
These are a good starting point for DQM issues. Log files are not cleaned up
automatically, and will need to be removed manually or through some batch process
implemented outside of IBM Cognos 11.
You can change the default XQE log output location in the xqe.config.xml file under the
XQEConfiguration\General section. Uncomment <!--logsFolder value="../../logs"/--> and
specify the location in the value attribute. This can be helpful in a distributed
environment, to define a central log location.
queriesNotPlanned is DQM information output for queries that could not be planned for
one reason or another. For example, these logs may be generated if the IBM Cognos
data source was missing for a report. The report spec query or queries cannot be
planned in these cases. Another time you will see these logs generate is when a report
is run and you see an XQE-PLN-0000 error. These logs can indicate when DQM
reports are failing.

© Copyright IBM Corp. 2010, 2016 7-5

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 7 Explore Dynamic Query Mode

DQM statistics are tracked in the usage log. These logs are generated when the IBM
Cognos Analytics server is stopped.
requestDumps are used to analyze data output for requests. This can be useful in
troubleshooting data integrity issues between IBM Cognos 11 releases. For example,
report data from release to release may return the same data differently. This logging
would only be enabled under the guidance of customer support.

© Copyright IBM Corp. 2010, 2016 7-6

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 7 Explore Dynamic Query Mode

Describe XQE log files (2 of 2)

• Start point for any errors or DQM issues
• Contains IPF logging
• XQE logging can be configured in xqe.diagnosticlogging.xml located in
..\configuration
 Can increase logging detail to the xqelog XML files in the
Diagnostics\Components section
 Can enable or disable various XQE logging
• Must restart IBM Cognos service for changes to take effect

Explore Dynamic Query Mode © Copyright IBM Corporation 2016

When dealing with any DQM errors or issues, such as service or connectivity issues,
the xqelog-000000-0000000000.xml log files can provide information to help guide you
on where to focus your attention. For example, it may indicate an issue with the
MetadataService component of DQM. You can set the MetadataService eventGroup
item under the Diagnostics\Components section to trace, which will write more details
about that component in the xqelog-000000-0000000000.xml log files. If there is no
level attribute for a component, the default behavior is none (no logging).
In the xqe.diagnosticlogging.xml file, you can also enable and disable specific log files.
For example, you can disable queriesNotPlanned or enable queriesPlanned. You can
also turn off xqelog-000000-0000000000.xml logging by changing <diagnostics
enabled="true" appender="file" level="error"> to <diagnostics enabled="false"
appender="file" level="error">.

© Copyright IBM Corp. 2010, 2016 7-7

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 7 Explore Dynamic Query Mode

IPF logging for DQM

• Enabled by renaming ipfXQEclientconfig.xml.sample to
ipfclientconfig.xml in ..\configuration.
• Change is picked up after approximately 30 seconds.
• For XQE, typically would be used to enable IPF audit logging because
all IPF information is already written to the xqelog XML files.

Explore Dynamic Query Mode © Copyright IBM Corporation 2016

IPF logging for DQM

The same concept about IPF logging applies for the DQM component except that the
ipfXQEclientconfig.xml logging was created for conformance with other components.
This version of IPF logging is written to the xqelog-000000-0000000000.xml files
(mentioned earlier). Enabling IPF logging in the DQM component would be possible,
but redundant.

© Copyright IBM Corp. 2010, 2016 7-8

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 7 Explore Dynamic Query Mode

Describe QFS logging for DQM

• Configured in qfs_config.xml in ..\configuration
• Troubleshoot communication and performance between BIBus (C++)
and DQM (Java)
• Parameters of interest under the XQEQueryProvider section
 TraceLogLevel (communication)
− generates xqe prefixed log files in ..\logs
 PerfLogLevel (performance)
− generates xqePerf.csv file in ..\logs

Explore Dynamic Query Mode © Copyright IBM Corporation 2016

Describe QFS logging for DQM

For TraceLogLevel, the xqe log file name will be xqeTrace.log when setting the value to
1 or 2. If set to 3 or higher, you will see an xqeTrace.log file and an
XQERequest_00000000.log file. Value setting information is provided in this file.
Logging values for <parameter name="TraceLogLevel" value="0"/> are 0 Disable trace
logging, 1 Service level trace logging, 2 Session level trace logging, 3 Request level
trace logging, 4 Operation level trace logging, and 5 Detail trace logging.
The PerfLogLevel trace produces the xqePerf.csv file in the logs folder. This file
indicates the object, the operation, a begin and end timestamp for each operation, and
a column to show the time difference between the two.
There are other settings for tweaking performance and functionality also in this file, but
use these under customer support guidance only. qfs_changes are supposed to be
picked up automatically after approximately 30 seconds, but you may have to refresh
the service.

© Copyright IBM Corp. 2010, 2016 7-9

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 7 Explore Dynamic Query Mode

Enable DQM BAPI trace for SAP BW

• Configured in xqe.diagnosticlogging.xml in ..\configuration
• Change
<eventGroup name="DataQuery“/>
to
<eventGroup name="DataQuery“ level=“info”/>
• Information written to XQElog XML files

Explore Dynamic Query Mode © Copyright IBM Corporation 2016

Enable DQM BAPI trace for SAP BW

Add the level="info" comment in xqe.diagnosticlogging.xml, and then stop and start the
Query Service on the Dispatcher where the file change was made, to pick up the
changed configuration.

© Copyright IBM Corp. 2010, 2016 7-10

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 7 Explore Dynamic Query Mode

What is IBM Cognos DQA?

• IBM Cognos Dynamic Query Analyzer
• Ships with IBM Cognos 11
• Focuses on profiled runtree logs
• If report failed in planning you can open the last stage of planning log

Explore Dynamic Query Mode © Copyright IBM Corporation 2016

What is IBM Cognos DQA?

IBM Cognos Dynamic Query Analyzer (DQA) is a utility that provides a graphical user
interface for the execution tree logs (runtreeLog.xml) that are produced by Dynamic
Query Mode queries.
You can enable global execution trace logging for all DQM reports through the IBM
Cognos Administration console, or you can use IBM Cognos DQA to run individual
reports, which will automatically generate an execution trace for just that report, and can
be immediately analyzed in IBM Cognos DQA. For more information, refer to the IBM
Cognos Dynamic Query Analyzer User Guide 11.0.

© Copyright IBM Corp. 2010, 2016 7-11

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 7 Explore Dynamic Query Mode

What can you do with IBM Cognos DQA?

• Debug reports
• Run and display reports
• Read logs locally or remotely
• Display properties for each individual node
• Display MDX and SQL and copy the syntax
• Display performance times

Explore Dynamic Query Mode © Copyright IBM Corporation 2016

What can you do with IBM Cognos DQA?

IBM Cognos DQA allows a report administrator to easily identify the individual pieces of
a Dynamic Query Mode query. This overview helps to simplify the troubleshooting of
Dynamic Query Mode query performance.

© Copyright IBM Corp. 2010, 2016 7-12

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 7 Explore Dynamic Query Mode

Review the IBM Cognos DQA Graph legend

Node Description
An operation that occurred when the report was run.

An attribute of an operation, such as the data being processed. By default, most of these nodes are suppressed
in the graph. (To display all navigate to Window\ Preferences, and select Visualization\Node filtering.)

A collapsed node. To display the hidden nodes, double-click the node, or right-click it and click Show Subtree.

A node with hidden children due to the Node filtering settings. (To display hidden nodes, right-click the node
and click Expand Filtered.)

The node that is currently selected. The properties of this node are displayed in the Properties view. Click a
node to select it.

This node has subqueries that can be opened in another graph. (To display subquery graphs, right-click the
node and click Open sub queries. Some subqueries do not have an associated node in the parent trace and can
be opened using this option.)

The vertical bar represents timing information for the node. The color red represents the time for the report
spent in the node. The color yellow represents the proportion of time spent in the children of the node. The
color gray represents the time spent outside the node and its children. If the node is selected, the times are
also displayed in the Properties view.

Explore Dynamic Query Mode © Copyright IBM Corporation 2016

Review the IBM Cognos DQA Graph legend

When you open query log files in IBM Cognos DQA, you can view and analyze the data
in a number of ways.
The graph that is displayed when a query log file is opened shows a series of linked
nodes. Each node represents an operation that occurred when the report was run or
represents an attribute of an operation (such as the data being processed). The
meaning of the different node representations is defined in the table on the slide.

© Copyright IBM Corp. 2010, 2016 7-13

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 7 Explore Dynamic Query Mode

Explore IBM Cognos DQA views

Explore Dynamic Query Mode © Copyright IBM Corporation 2016

Explore IBM Cognos DQA views

The Summary view tab provides information about the active graph. There are four
sections on this tab:
• Summary section: displays the name, package, and timestamp of the query. It
also indicates whether the data source type is relational, OLAP, or DMR
(Dimensionally Modeled Relational).
• Timing section: displays timing information, the working times and waiting times
for each node that has timing information attached to it, in descending time order.
If you click a node, the corresponding node in the graph is selected. Timing
information for a query is not displayed if all the timing information is contained in
subqueries.
• Analysis section: displays information if the query planning trace option is
enabled.
• Node Shapes and Colors section: provides the meaning of node shapes and
colors.

© Copyright IBM Corp. 2010, 2016 7-14

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 7 Explore Dynamic Query Mode

The Query view tab shows the MDX or SQL query used in this report.
You can link MDX commands in the Query view with nodes in the graph by using the

Link MDX to graph icon. If you select an MDX command in the Query view and
click the Link MDX to graph icon, the nodes in the graph where the MDX commands
are executed are selected.
If the query is a SQL query, you can run the report again by clicking the Execute Sql

query icon.
The Properties view tab displays the properties for the currently selected graph node.
The Navigation view tab displays the graph as a tree structure. To open the Navigation
view for the active graph, click File\Show in Navigation. You can have multiple
Navigation views open, one for each graph. To navigate quickly between a Navigation

view and the corresponding graph, click the Link with editor icon. Clicking an item
in the Navigation view selects the corresponding node in the graph, and vice versa.

© Copyright IBM Corp. 2010, 2016 7-15

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 7 Explore Dynamic Query Mode

Explore Aggregate Advisor

• In IBM Cognos Dynamic Query Analyzer, Aggregate Advisor is used
with dynamic cubes
• Can use default logging settings
• Optimize aggregates
• Resolve performance issues

Explore Dynamic Query Mode © Copyright IBM Corporation 2016

Explore Aggregate Advisor

In IBM Cognos Dynamic Query Analyzer, you can launch the Aggregate Advisor, to
analyze dynamic cubes and suggest aggregates that, when implemented, will improve
cube performance. While tweaking a model is required when using in-database
aggregates, for in-memory aggregates the Aggregate Advisor allows performance
problems to be resolved without re-authoring or re-modeling.
Default logging is sufficient to enable logs for use by the Aggregate Advisor, as
Aggregate Advisor can analyze the underlying model in a dynamic cube data source
and recommend which aggregates to create. Aggregate Advisor runs on the query
service and can reference a workload log file. Administrators should be aware that to
make recommendations based on workload logs, the workload log file must be enabled
on the dynamic cube.

© Copyright IBM Corp. 2010, 2016 7-16

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 7 Explore Dynamic Query Mode

When enabled, the workload log file captures the information that represents user
workload usage such as running reports or performing interactive analysis. This log file
allows Aggregate Advisor to suggest aggregates (in-database or in-memory) that
correspond directly to the reports referenced in the log file.
Consider running Aggregate Advisor if non-trivial changes are made to the model, if
there are significant data changes, if query performance is not meeting expectations, or
if workload characteristics change significantly.
For more information on using the Aggregate Advisor, refer to the IBM Cognos
Dynamic Query Analyzer User Guide 11.0, in the section Getting started with Cognos
IBM Cognos Dynamic Query Analyzer: Optimize dynamic cube performance with
Aggregate Advisor.

© Copyright IBM Corp. 2010, 2016 7-17

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 7 Explore Dynamic Query Mode

Unit summary
• Perform Dynamic Query Mode (DQM) logging
• Analyze queries using IBM Cognos Dynamic Query Analyzer (DQA)

Explore Dynamic Query Mode © Copyright IBM Corporation 2016

Unit summary

© Copyright IBM Corp. 2010, 2016 7-18

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 7 Explore Dynamic Query Mode

Exercise 1
Enable DQM, publish a package, and review the logs created

Explore Dynamic Query Mode © Copyright IBM Corporation 2016

Exercise 1: Enable DQM, publish a package, and review the logs created

© Copyright IBM Corp. 2010, 2016 7-19

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 7 Explore Dynamic Query Mode

Exercise 1:
Enable DQM, publish a package, and review the logs created

In this exercise, you will configure a relational data source for Dynamic Query Mode,
publish a package in DQM, enable global trace logging, and review the logs that are
created. When you are done, you will disable global trace logging.
To do this you will:
• Ensure that the query service is enabled in IBM Cognos Configuration.
• Create a project named DB2 DQM Model.
• Add a connection to IBM DB2, enabling Dynamic Query Mode using
admin/Education1 credentials.
• Create the following data source connection using admin\Education1 credentials,
and test for compatible mode and dynamic query mode:
• Name: GOSALESDW(DB2)
• Connection type: IBM DB2
• Database name: GS_DB
• JDBC connection: enabled
• Server name: VCLASSBASE
• Port number: 50000
• For the GOSALESDW(DB2) data source, import the following tables:
GO_TIME_DIM, SLS_PRODUCT_DIM, SLS_SALES_FACT, and then test the
GO_TIME_DIM definition.
• Publish a package named GOSALESDW(DB2).
• In IBM Cognos Administration, ensure that the data source connection for
GOSALESDW(DB2) is running in both modes (DQM and Compatible) on the
dispatcher.

© Copyright IBM Corp. 2010, 2016 7-20

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 7 Explore Dynamic Query Mode

• In IBM Cognos Administration, select the query execution trace check box to
enable the service.
• Create, save, and run a simple report based on the GOSALESDW(DB2)
package.
• Review the logs generated by DQM at C:\Program Files\IBM\cognos\
analytics_full\logs\XQE.
• In IBM Cognos Administration, deselect the query execution trace check box to
disable the service.
• Close all open windows.
If necessary, modify the <reportPath></reportPath> tags in the manifest.xml file
to refer to the full path of the report.
For more information about where to work and the exercise results, refer to the Tasks
and Results section that follows.

© Copyright IBM Corp. 2010, 2016 7-21

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 7 Explore Dynamic Query Mode

Exercise 1:
Tasks and Results
At the beginning of this exercise, the IBM Cognos Full:9315 dispatcher is running.
Task 1. Ensure the Dynamic Query Mode service is enabled.
• From the Start menu, navigate to All Programs\IBM Cognos Analytics Full,
and then click IBM Cognos Configuration.
• In the Explorer pane, click IBM Cognos services, and then ensure Query
service enabled? is set to True.
If the value was set to False, change it to True, save the configuration, and then
restart the IBM Cognos service.
• Close IBM Cognos Configuration, selecting No, if prompted to save.
Task 2. Create a Dynamic Query Mode-enabled project and
connection to IBM DB2.
The following instructions use the sample Sample Outdoors Warehouse IBM DB2
database called GS_DB to allow you to create a relational data source connection.
For an IBM DB2 data source, the IBM Cognos Framework Manager instance requires
no additional software if all of your Framework Manager projects use the Dynamic
Query Mode. If any of your projects use the Compatible Query Mode, however, an IBM
DB2 client must be installed and configured on the computer hosting IBM Cognos
Analytics Framework Manager. This has been configured in the environment for this
course.
Although you may already be familiar with creating a Dynamic Query Mode-enabled
project, this exercise will be looking deeper into the process and the results.
• From the Start menu, navigate to All Programs\IBM Cognos Framework
Manager, and then click IBM Cognos Framework Manager.
• Click Create a new project, in the Project name box, type DB2 DQM Model,
and ensure that the Use Dynamic Query Mode check box is selected.
• Notice the path of the project location, and then click OK.
• Click OK if a message is displayed to create the directory, and then login as
admin/Education1.
• In the Select Language box, ensure that English is selected, and then click OK.
• On the Select Metadata Source page, ensure that Data Sources is selected,
click Next, and then click New to create a new data source connection.

© Copyright IBM Corp. 2010, 2016 7-22

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 7 Explore Dynamic Query Mode

• In the New Data Source wizard, click Next, in the Name box, type
GOSALESDW(DB2), and then click Next.
• Under Type, click IBM DB2.
Notice the Configure JDBC connection check box. Ensure that this box is
selected, so that information can be provided to connect through the JDBC driver
which is required for Dynamic Query Mode.

• Click Next.
In the next steps, the information provided is based on how the IBM DB2 clients
on the computer hosting Framework Manager and the IBM Cognos Analytics
servers were configured and how security is implemented for IBM DB2.
Connection information and sign on information should be provided by the
database administrator.
• In the DB2 database name box, type GS_DB, and then in the Signon\Signons
section, select the Password check box.
• In the User ID box, type GOSALESDW, and then in the Password and Confirm
password boxes, type Education1.

© Copyright IBM Corp. 2010, 2016 7-23

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 7 Explore Dynamic Query Mode

• Click Test the connection, and then click Test.

Notice that the Query Mode is Compatible. This means that Dynamic Query
Mode has not been configured for this data source at this point.

• On the View the results page click Close, and then on the Test the connection
page click Close.
• On the Specify the IBM DB2 connection string page, click Next.
You will now configure the JDBC connection information.
• In the Server name box, type VCLASSBASE (the name of the server hosting the
database), in the Port number box, type 50000 (the port number of the
database), and then in the Database name box, type GS_DB.
• In the Testing section click Test the connection, and then click Test.
Notice that the Query Mode is Dynamic.

• On the View the results page click Close, on the Test the connection page
click Close, click Finish, and then in the Finish dialog box, click Close.
The new GOSALESDW(DB2) data source that appears in the list is configured to
query using either query mode.

You will import metadata and test query subjects for this data source.
• Select GOSALESDW(DB2) in the list of data sources, click Next, expand
GOSALESDW, expand Tables, and then select the following tables:
• GO_TIME_DIM
• SLS_PRODUCT_DIM
• SLS_SALES_FACT
• Click Next, click Import, and then click Finish.

© Copyright IBM Corp. 2010, 2016 7-24

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 7 Explore Dynamic Query Mode

• In the Project Viewer, expand GOSALESDW(DB2).

The query subjects appear as child objects as follows.

• Double-click GO_TIME_DIM to open its definition, and then click the Test tab.
If the Query Mode property of the project is set to Dynamic when testing a query
subject, the test query will run in Dynamic Query Mode. If the Query Mode
property is set to Compatible, however, there is an option to use the Dynamic
Query Mode on the Test tab in the lower left corner, provided that the query
subject is for a data source supported by the Dynamic Query Mode. In this case,
the property for this project was set to Dynamic Query Mode, and therefore you
do not see this check box option.
• At the lower right, click Test Sample.
Framework Manager sends the test query through the IBM Cognos 11 gateway
to one of the IBM Cognos Analytics servers, which, in turn, queries the reporting
database. The data retrieved by the test query appears in the Test results pane.
A section of the result appears as follows:

• Click OK to close the Query Subject Definition window.

© Copyright IBM Corp. 2010, 2016 7-25

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 7 Explore Dynamic Query Mode

You should test all your model objects against the Dynamic Query Mode to
ensure that SQL generation is as expected for your requirements. If you are
building an OLAP over Relational model, this includes foundation objects such as
Data Source and Model Query Subjects as well as Regular and Measure
Dimensions. OLAP over Relational model replaces the term DMR model, for
DQM.
When you have finished building the model, you can create and publish a
package that uses the Dynamic Query Mode.
Task 3. Create and publish a package that uses the dynamic
query mode, and then verify the package properties.
• In the Project Viewer, right-click Packages, click Create, and then click
Package.
• In the Name box, type GOSALESDW(DB2), click Next, and then click Finish.
• At the prompt to open the Publish Package Wizard, click Yes.
• Change the Folder location in the Content Store to the root of Team Content
(if necessary).
• In the Publish Wizard clear the Enable model versioning check box, click
Next, and then on the Add Security page click Next.
On the Publish Wizard - Options page, if the Query Mode property of the project
is set to Compatible and if the package contained supported DQM data sources,
then the Use Dynamic Query Mode check box option would be displayed. You
have already defined the property of this project as Dynamic Query Mode, so this
option does not appear.
• Click Publish, and then click Finish.
The package is now available in IBM Cognos Analytics and will use the Dynamic
Query Mode for reports written against this package. In IBM Cognos Analytics,
the query mode used by the package can be verified in the package properties.
• Close Framework Manager, saving your changes.
• Launch Internet Explorer, go to http://vclassbase:88/ibmcognos/bi/, and then
log on as admin/Education1.
• Click Team content, beside GOSALESDW(DB2), click the ellipsis, and then click
Properties.

© Copyright IBM Corp. 2010, 2016 7-26

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 7 Explore Dynamic Query Mode

• Expand Advanced.
Notice that the Query Mode is Dynamic.

Task 4. In IBM Cognos Administration, enable the Query

execution trace to generate XQE log files.
In this task you will enable global tracing. Be aware that in a busy production
environment, enabling global tracing will result in all Dynamic Query reports being
traced as they are executed, which may have an impact on the system
performance. In the next exercise, you will generate log files on a report by report
basis, a strategy which would be better for a busy production environment.
• Launch Administration console, and then click the Configuration tab.
On the Configuration tab, there are four locations pertaining to the Dynamic
Query Service:
• Data Source Connections for configuring data sources including supported
Dynamic Query Mode data sources and dynamic cubes
• Content Administration for scheduling Query service administration tasks
• Dispatchers and Services for configuring the QueryService service
• Query Service Caching to immediately perform cache tasks
• On the Configuration tab\Data Source Connections pane, in the Actions
column for the GOSALESDW(DB2) data source connection, click More.

• Click View connections, in the Actions column click Test the connection ,
and then click Test.
There are two query modes listed for this dispatcher.

• Click Close, and then on the Test the connection page click Close.

© Copyright IBM Corp. 2010, 2016 7-27

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 7 Explore Dynamic Query Mode

• In the left pane, click the Dispatchers and Services link, and then click
http://vclassbase:9315/p2pd.
• Click the Next Page button, and notice that the QueryService appears in the list.

• In the Actions column for the QueryService, click Set properties, on the
Settings tab, in the Value column, select the Enable query execution trace
check box.
The trace configuration change will be picked up automatically within 15 seconds.
Enabling the query execution trace will write information such as the native MDX
to a run tree log in the ..\logs\XQE directory. Profiler information is also written to
capture execution and waiting time metrics for query constructs.
• In the Value column, notice the Enable query planning trace check box.
Enabling the query planning trace setting will write information related to the
transformation of the query to the plan tree log within the ..\logs\XQE directory.
This trace is useful when attempting to determine what decisions were made by
the Dynamic Query Mode to build the execution plan, however resultant log files
are large and may impact overall query performance. Use only for reports that fail
before the profile is complete.
Do not enable the query planning trace in this exercise.
• Click OK, and then wait 15 seconds before proceeding.

© Copyright IBM Corp. 2010, 2016 7-28

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 7 Explore Dynamic Query Mode

Task 5. Create and run a simple report based on a DQM data

source.
• Click the Welcome browser tab.
• On the Side panel, click New, and then click Report.
• Click Blank, and then click OK.
• Click Add report data, click GOSALESDW(DB2), and then click Open.

• On the Side panel, click Toolbox , and then drag a List to the report area.
• Click OK to accept the defaults.

• On the Side panel, click Data , and then populate the list with the following
items from the package:
• GO_TIME_DIM: DAY_DATE
• SLS_PRODUCT_DIM: PRODUCT_KEY
• SLS_SALES_FACT: QUANTITY
You could use any items from the package for your report; the specific content of
the items selected above is not important to this exercise. You can drag and drop
items in the list, or double-click items on the Source tab to add them to the list.
• Save the report in Team content/GOSALESDW(DB2) as DQM Report.

• Click Run options , and then click Run HTML.

A section of the report appears similar to the following:

• Close all open windows.

© Copyright IBM Corp. 2010, 2016 7-29

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 7 Explore Dynamic Query Mode

Task 6. Review the logs generated by DQM.

• In Windows Explorer, navigate to C:\Program
Files\IBM\cognos\analytics_full\logs\XQE.
This is where the QueryService logs are located. Notice that there is a folder
named <date>_<timestamp>_<report name> that was generated for the report
that you ran.

• Double-click the DQM+Report folder to open it.

The following files are available:
• manifest.xml
• profilingLog-0.xml
• runtreeLog.xml
Some report executions require executing sub-queries. Sub-queries execution
trace is stored under a separate directory named subqueries, within the main
report directory, and contains the same logging elements as the main report,
runtreeLog.xml and profilingLog-#.xml.
If you had enabled the planning trace, you would also see many
planningLog_pass_###.xml files.

© Copyright IBM Corp. 2010, 2016 7-30

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 7 Explore Dynamic Query Mode

• Open the manifest.xml, profilingLog-0.xml, and runtreeLog.xml files in

Internet Explorer to familiarize yourself with the information that has been
captured.
The manifest.xml file appears similar to the following:

• If the <reportPath></reportPath> tags contain a value of UNKNOWN, open the

manifest.xml file in Notepad, modify the value within the tags to appear as
follows, and then save and close the file:
<reportPath>/content/package[@name='GOSALESDW(DB2)']/
report[@name='DQM Report']</reportPath>
Task 7. Disable the query execution trace.
• Launch Internet Explorer, and then go to http://vclassbase:88/ibmcognos/bi/.
• Log on as admin/Education1, launch Administration console, and then click
the Configuration tab.
• In the left pane, click the Dispatchers and Services link, and then click
http://vclassbase:9315/p2pd.
• Click the Next Page button, in the Actions column for the QueryService, click
Set properties, on the Settings tab, in the Value column, clear the Enable
query execution trace check box.
The trace configuration change will be picked up automatically within 15
seconds.
• Click OK, and then close all browser windows.

© Copyright IBM Corp. 2010, 2016 7-31

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 7 Explore Dynamic Query Mode

Exercise 2
Use IBM Cognos Dynamic Query Analyzer to analyze a query

Explore Dynamic Query Mode © Copyright IBM Corporation 2016

Exercise 2: Use IBM Cognos Dynamic Query Analyzer to analyze a query

© Copyright IBM Corp. 2010, 2016 7-32

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 7 Explore Dynamic Query Mode

Exercise 2:
Use IBM Cognos Dynamic Query Analyzer to analyze a query

IBM Cognos Dynamic Query Analyzer (DQA) is a tool that provides graphical
representations for the query logs produced by Dynamic Query mode queries. This
exercise will introduce you to using IBM Cognos Dynamic Query Analyzer to analyze
results of the logs generated by the queries.
It is assumed that you have generated log files for use with IBM Cognos Dynamic
Query Analyzer, as described in Exercise 1. Please complete Exercise 1 before
proceeding with this exercise. This will help you become familiar with analyzing log files
in IBM Dynamic Query Analyzer, before you assess differences in report variations.
In this exercise scenario, with no global tracing enabled, you will run a report directly in
IBM Cognos Dynamic Query Analyzer, which will generate log files that you can
immediately analyze. This method of generating log files will have less of an impact on
the production environment than the global tracing method.
To do this exercise you will:
• Launch IBM Cognos DQA. If you encounter any "null pointer" errors, close and
reopen IBM Cognos DQA. If you encounter any login-related messages, dismiss
them. Review the settings in Window\Preferences to familiarize yourself with the
configuration of the environment. If necessary, modify the settings to reference
the correct IBM Cognos server and the logs directory URL. After you have
validated the settings, close and reopen DQA (logging on if prompted).
• In IBM Cognos DQA, refresh the content store display (if necessary), and explore
the GOSALESDW(DB2)\DQM Report\DQM Report (<Date>, <Time>)\ Profile 0
log. Refer to the DQA Graph Legend page in this unit, as you review the objects
in the graph, to assist in your interpretation of the graph.
• In a browser session, log on to the portal at http://vclassbase:88/ibmcognos/bi/,
with admin/Education1 credentials.

© Copyright IBM Corp. 2010, 2016 7-33

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 7 Explore Dynamic Query Mode

• Create a crosstab report with the Team content\Samples_DQ\Models\GO Data

Warehouse (analysis) package, using the Sales and Marketing (analysis)\Sales
source (Measures: Sales fact\Quantity, Rows: Products dimension\Products
hierarchy\Product level, Columns: Retailers dimension\Retailers
hierarchy\Retailer name level, and Order method dimension\Order method
hierarchy\Order method type level, nested under <#Retailer name#>). Apply full
suppression to rows and columns. Save the report as Crosstab with Full
Suppression.
• In the same report, change the suppression to nulls only, for rows and columns,
and save the report as Crosstab with Null Suppression.
• In the same report, remove the suppression from the rows and columns, apply
suppression within the query, and save the report as Crosstab with Null
Suppression in query.
• Run one of the three reports, clearing the cache before and after it has run.
Repeat this for the other two reports.
• In IBM Cognos DQA, review the Profile 0 logs generated by each of the three
report executions. Explore the runtree graph, XML node information, Properties of
the nodes, and timings. Compare results of the three report variations.
• Close IBM Cognos Dynamic Query Analyzer, log out from IBM Cognos
Administration, and then close the web browser.
• On the Taskbar, launch Services, and then stop the IBM Cognos 11 Full:9315
service.
You have compared three different variations of a report, using IBM Cognos Dynamic
Query Analyzer, and can use the results to ensure that the most efficient report is
available for users. Which report is the most efficient, based on your findings?
For more information about where to work and the exercise results, refer to the Tasks
and Results section that follows.

© Copyright IBM Corp. 2010, 2016 7-34

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 7 Explore Dynamic Query Mode

Exercise 2:
Tasks and Results
At the beginning of this exercise, the IBM Cognos Full:9315 dispatcher is running, and
log files are available in the ..\logs\XQE directory.
Task 1. Start IBM Cognos Dynamic Query Analyzer and review
the configuration.
• From the Start menu, navigate to
All Programs\IBM Cognos Dynamic Query Analyzer, and then click IBM
Cognos Dynamic Query Analyzer.
If you receive any "null pointer" errors (either standalone or at the top of what
appears to be a login dialog box), dismiss the errors and then close and reopen
IBM Cognos Dynamic Query Analyzer before proceeding.
• If you receive any other login-related errors, dismiss them and leave IBM Cognos
Dynamic Query Analyzer open.
• From the Window menu, click Preferences, and then in the left pane, click
Cognos Server.
This property has the settings for the host and port of the IBM Cognos server
which contains the reports to be analyzed. This has been configured by the
administrator who set up the environment.

© Copyright IBM Corp. 2010, 2016 7-35

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 7 Explore Dynamic Query Mode

• On the left, click Logs.

The Logs directory URL points to a virtual directory (XQElogs) on the Web server,
which references the XQE directory where the log files are saved on the server.
This property has been configured by the administrator who set up the
environment.

• Click OK to close the Preferences box.

• To ensure that you are in the correct view for this exerise, from the Window
menu, click Show View, click Navigation\Content Store, and then click OK.
Dismiss any error messages that may appear, and then close and reopen DQA. If
you are prompted to log on at this point, specify the LDAP namespace, a user ID
of admin, and a password of Education1. Also specify that you want to save the
selected namespace, user ID, and password.
The results appear similar to the following:

© Copyright IBM Corp. 2010, 2016 7-36

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 7 Explore Dynamic Query Mode

Task 2. Review the results of a report that was run, in IBM

Cognos Dynamic Query Analyzer.
• On the Content Store tab, if necessary, click the Refresh button, expand the
GOSALESDW(DB2) entry (click the entry, then click > to the left of the entry), and
then expand the DQM Report\DQM Report (<Date>, <Time>) entries.
A section of the result appears as follows:

• Double-click the Profile 0 entry, and then in the right pane, click the Summary tab.
The analysis will load, and the runtree log is displayed in a graphical view.
The results in the Summary tab appear similar to the following:

© Copyright IBM Corp. 2010, 2016 7-37

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 7 Explore Dynamic Query Mode

The results in the middle pane appear similar to the following:

• Maximize the window, and adjust the width of the Summary tab layout to let you
to see the information.
• On the Summary tab, expand the Node Shapes and Colors section, to assist
you in interpreting the results.
• Review the Timing section, and note the total time in node children and total time
in node color annotations, and summary of working times and wait times.
• To assist in the interpretation of the graph, refer to the DQA Graph Legend page
earlier in the content of this unit
Nodes can be SQL execution nodes, MDX execution nodes, local processing
nodes, decoration nodes, and many more. Results flow from the bottom of the
run tree (leaf nodes) to the top (XTree node) where the result is represented in
RSAPI (Resultset API) format and can be sent to the report service for rendering.
• Select the XTree node object in the graph.
• Review the properties by clicking the Properties tab, and then select the other
objects, one by one, to familiarize yourself with the properties and the information
that is displayed for each one.
Notice the XColumn objects, and compare the timing results of each column.
• Close IBM Cognos Dynamic Query Analyzer, and any other open windows.

© Copyright IBM Corp. 2010, 2016 7-38

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 7 Explore Dynamic Query Mode

Task 3. Create report variations.

You want to create reports with variations, so that you can compare the results in
IBM Cognos Dynamic Query Analyzer. To do this, you will create three variations
of a report. Typically, a report would be created and run, and then the log files
would be analyzed to determine if efficiencies could be found. Then, the updated
report would be run and the log files analyzed to determine the difference in
timing. In the interest of time you will create three reports, save them, run them to
generate the log files, and then in the next task, you will open the log files, and
compare results of all three.
• Launch Internet Explorer, go to http://vclassbase:88/ibmcognos/bi/, and then
log on as admin/Education1.

• Click Team content, and then click Switch Views .

• Click New folder , replace the name New Folder with Suppression
Reports, and then press Enter.
You will save the reports to this public folder, rather than a private folder, so that
you can access them from the Content Store pane in IBM Cognos Dynamic
Query Analyzer. You will proceed to open the package to use in your reports.
• On the Side panel, click New, and then click Report.
• Click Blank, and then click OK.
• Click Add report data, navigate to Team content\Samples_ DQ\Models\GO
Data Warehouse (analysis), and then click Open.
• On the Side panel, click Toolbox, drag a Crosstab to the report area, and then
click OK to accept the defaults.
• On the Side panel, click Data, expand Sales and Marketing (analysis), and then
expand Sales.
You will build a report from items in this namespace.

© Copyright IBM Corp. 2010, 2016 7-39

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 7 Explore Dynamic Query Mode

• Populate the crosstab by dragging the following source items to the crosstab in
the report layout:
• Measures drop zone: Sales fact\Quantity
• Rows drop zone: Products dimension\Products hierarchy\Product level
• Columns drop zone:
• Retailers dimension\Retailers hierarchy\Retailer name level
• Order method dimension\Order method hierarchy\Order method type
level, nested under <#Retailer name#>
The crosstab appears as follows:

• On the on-demand toolbar, click the Suppress arrow, and then click
Suppression options.
• In the Suppression section, click Rows and columns, in the Suppress the
following section, ensure that all check boxes are selected, and then click OK.
• On the Application bar, click Save/Save As, name the report Crosstab with
Full Suppression, and then save the report in Team content\Suppression
Reports.
What if the author was to decide that it is not full suppression that was required,
but merely suppression of null (missing) values? You will make the changes to
the report and save the new variation to analyze later.
• Click the crosstab's Container Selector to select the crosstab, on the toolbar,
click the Suppress arrow, and then click Suppression Options.
• In the Suppress the following section, ensure that only the Missing values
check box is selected, and then click OK.
• On the Application bar, click Save/Save As, name the report Crosstab with
Null Suppression, and then save the report in Team content\Suppression
Reports.
What if the author was to decide that suppression of null (missing) values could
be run in the query directly? You will make the changes to the report and save
the new variation to analyze later.
• Click the crosstab's Container Selector to select the crosstab, on the toolbar,
click the Suppress arrow, and then click No Suppression.

© Copyright IBM Corp. 2010, 2016 7-40

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 7 Explore Dynamic Query Mode

• On the Side panel, click Navigate , and then click Query explorer .
• Click Query1.
• From the Data Items pane, drag Quantity to the Detail Filters pane.
• In the Detail Filter Expression pane, in the Expression Definition pane, click
the cursor at the end of the expression, type is not null, and then click
Validate .
The [Quantity] is not null expression has no errors.
• Click OK.
• On the Application bar, click Save/Save As, name the report Crosstab with
Null Suppression in Query, and then save the report in Team
content\Suppression Reports.
• Close all browser windows.
Task 4. Run the reports in IBM Cognos Dynamic Query
Analyzer to generate log files for analysis.
• Launch IBM Cognos Dynamic Query Analyzer, if prompted log in as
admin/Education1, and then from the File menu, click Close All Results, if it is
available, to ensure that all previous results are closed.
If you encounter any NullPointerException errors, close IBM Cognos Dynamic
Query Analyzer and reopen it.
• Click the Content tab, click OK to accept the Login settings (if necessary), and
then expand the Suppression Reports folder to see the reports that you
created.
• Double-click the Crosstab with Full Suppression report, click OK to close the
Login to Cognos Server message, and then log in to the portal as
admin/Education1.
Before you run the first report, you want to clear the query service cache.
• Launch Internet Explorer, go to http://vclassbase:88/ibmcognos/bi/, and then
log on as admin/Education1.
• In Internet Explorer, launch IBM Cognos Analytics, log in as
admin/Education1, and then launch Administration console.
• On the Configuration tab\Query Service Caching pane, in the Server
Group(s) column, select the Group 64 check box, and then click Clear cache.
• When the cache has succeeded in clearing, click Close.

© Copyright IBM Corp. 2010, 2016 7-41

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 7 Explore Dynamic Query Mode

• Switch to the IBM Cognos Query Analyzer window, in the Content Store tab,
right-click the Crosstab with Full Suppression entry, and then click Run
Report.
The report executes, and displays the results on the report tab in the middle.
• In the Open Logs box, click No, as you will open the log later.
You want to clear the cache before running a different report, to ensure that
results are not skewed by cached information.
• Return to the browser window, where Admin Person is logged into IBM Cognos
Administration, and repeat the previous steps to clear the Query Service
cache.
• Switch to the IBM Cognos Dynamic Query Analyzer window, and repeat the
previous steps to run the Crosstab with Null Suppression report and clear the
query service cache.
• Switch to IBM Cognos Dynamic Query Analyzer, and repeat the previous steps
to run the Crosstab with Null Suppression in Query report and clear the query
service cache. It may take a while for this report to finish running.
By running the reports in IBM Cognos Dynamic Query Analyzer, even though
query execution is not enabled in your environment, logs have been generated,
for which you can analyze results.
Task 5. Review the logs from different report variations.
• In IBM Cognos Dynamic Query Analyzer, from the File menu, click Close All
Results.
• From the Window menu, click Analyze Logs, from the File menu, click Open
log, and then click From URL.
You can use this option if a virtual directory has been configured for the XQE
folder. In this environment, all of the dynamic query logs are stored here.
• Click the Crosstab with Full Suppression (<Date>, <Time>) entry, click the > at
the left of the entry to expand the list, and then in the expanded list, select the
Profile 0 check box.
You only want to load the Profile 0 file for comparison analysis at this time. Other
files that you may see in the log files are Fetch Cell Values and LoadLevels.
• Expand the Crosstab with Null Suppression (<Date>, <Time>) entry, and then
in the expanded list, select the Profile 0 check box.
• Expand the Crosstab with Null Suppression in Query (<Date>, <Time>) entry,
in the expanded list, select the Profile 0 check box, and then click OK.

© Copyright IBM Corp. 2010, 2016 7-42

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 7 Explore Dynamic Query Mode

• Click the Crosstab with Full Suppression (<Date>, <Time>) tab, to review the
results.
• From the Window menu, click Show View, and then expand Graph Details.
• Click XML Node, and then click OK.
As you explore each node, you can refer to this tab to view the XML associated
with it.
• In the XML Node tab, click in the blank pane, and then in the Crosstab with Full
Suppression pane, select the node objects, one by one, to familiarize yourself
with the properties and the information that is displayed for each one.
To assist in your interpretation of the graph. refer to the DQA Graph Legend page
earlier in the content of this unit.

• For expandable nodes, double-click the node or click the icon to expand and
explore more nodes and properties in the runtree.
In this runtree, the MDX query (green nodes) are sent to an MDX data source for
execution. The results returned will go through some decoration nodes
(decoration is an internal process that allows the mode to distinguish between
different parts of a query result), then a node that will flatten the result (MDX
results are multidimensional by nature) and finally another node will process the
flattened result.
The XMDXSelect node is the node which will display the pieces of the actual
MDX query used to satisfy the report request. The scale icon beside node is used
as a visual representation of the performance of the node.

© Copyright IBM Corp. 2010, 2016 7-43

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 7 Explore Dynamic Query Mode

• Click the XMdxSelect node to display the properties.

A section of the result appears similar to the following:

The properties pane of this node reveals the wait time spent in the node and the
wait time in the node and children.
Your result times may be different, depending on what is happening in your
environment. Compare each of the results of your findings against each other, in
your analysis in this exercise.
• Click the XV5Suppress node near the top of the tree, and observe the
properties.

The XV5Suppress node is evoked by the application of the Suppress\Rows and

Columns on the report.

© Copyright IBM Corp. 2010, 2016 7-44

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 7 Explore Dynamic Query Mode

• View the contents of the XML Node tab, while the XV5Suppress node is
selected.
Results appear similar to the following:

Notice the total elapsed time for the node and its children (totalElapsedTime), as
well as the elapsed time spent in the node itself (ownElapsedTime).
Notice the code for the suppression, and how all suppression values are true.
Based on the fact that there are two EdgeNum entries and nulls, divByZero and
overflow are all set to true, the properties confirm that a user applied zero, divide
by zero, overflow and null suppression on both the rows and columns.
At this point, it would be time to ask the report author whether or not they actually
need the divByZero, zero and overflow suppression, or whether or not they just
wanted to suppress nulls. Another good question to ask would be whether
suppression was actually needed on both the rows and columns.
The report author could come back with the statement that only null suppression
is required on both columns and rows. You have made this change to the report
and saved it as Crosstab with Null Suppression (<Date>, <Time>) on the same
package, and you ran the report to generate log files.
• In IBM Cognos Dynamic Query Analyzer, click the Crosstab with Null
Suppression in Query (<Date>, <Time>) tab, and review the objects in the
runtree.
• In the Graph tab, notice that there is no XV5Suppress node, due to visual
suppression being removed from the report, and running the suppression in the
query.

© Copyright IBM Corp. 2010, 2016 7-45

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 7 Explore Dynamic Query Mode

• On the Summary tab, notice the Timing section.

The results appear similar to the following:

• In IBM Cognos Dynamic Query Analyzer, click the Crosstab with Null
Suppression (<Date>, <Time>) tab, and review the Timing section results.
The results appear similar to the following:

© Copyright IBM Corp. 2010, 2016 7-46

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 7 Explore Dynamic Query Mode

• Compare the results with the timing results for the initial report, Crosstab with
Full Suppression (<Date>, <Time>).
The results appear similar to the following:

To identify the most efficient report for users, you have used IBM Cognos
Dynamic Query Analyzer to compare three different variations of the report.
• Close IBM Cognos Dynamic Query Analyzer, log out from IBM Cognos
Administration, and then close the web browser.
• On the Taskbar, launch Services, and then stop the IBM Cognos 11 Full:9315
service.

© Copyright IBM Corp. 2010, 2016 7-47

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 7 Explore Dynamic Query Mode

© Copyright IBM Corp. 2010, 2016 7-48

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
Explore component logging

Explore component logging

IBM Cognos Analytics 11.0

© Copyright IBM Corporation 2016

Course materials may not be reproduced in whole or in part without the written permission of IBM.
 Unit 8 Explore component logging

© Copyright IBM Corp. 2010, 2016 8-2

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 8 Explore component logging

Unit objectives
• Explore component logging for Gateway, Dispatcher, Report Server,
and Universal Data Access layer

Explore component logging © Copyright IBM Corporation 2016

Unit objectives

© Copyright IBM Corp. 2010, 2016 8-3

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 8 Explore component logging

Report Server (RSVP) trace

• For RSVP errors, use RSVP trace
 Trace SOAP requests sent to RSVP
 Trace data sent and received over BIBusTKServerMain socket
 Command and response documents associated with all Query Framework
requests generated by RSVP
 Enable recordings
 Trace print commands and statuses

Explore component logging © Copyright IBM Corporation 2016

Report Server (RSVP) trace

This is for your information. You would only use this if you were asked to do so by
customer support.
Traces are usually done in combination with other traces, and interpreting only one
trace file is merely one part of the whole story. When troubleshooting, customer support
would typically review more than one trace.

© Copyright IBM Corp. 2010, 2016 8-4

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 8 Explore component logging

BIBus trace
• Capture HTTP and socket requests sent to and from the
BIBusTKServerMain process
• Activate through environment variables or a configuration file
• Log to a file or console

Explore component logging © Copyright IBM Corporation 2016

BIBus trace
This is for your information. You would only use this if you were asked to do so by
customer support.

© Copyright IBM Corp. 2010, 2016 8-5

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 8 Explore component logging

Trace the Dispatcher

• Trace the Dispatcher: trace start-up problems and inter-component
communication
• Add elements

Explore component logging © Copyright IBM Corporation 2016

Trace the Dispatcher

Tracing the dispatcher is useful for determining what is happening between a
dispatcher and the other IBM Cognos services. The resulting files can be used to
troubleshoot general, performance, affinity and load balancing issues.
Historically, the dispatcher was once known as pogo. If you see a configuration file that
contains pogo, it is related to the dispatcher.
This is for your information. You would only use this if you were asked to do so by
customer support.

© Copyright IBM Corp. 2010, 2016 8-6

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 8 Explore component logging

Explore Query Framework logging

• Primary purpose of the Query Framework logging file is to configure
various OLAP providers
• Most of the OLAP providers have the following logging capabilities
 Dump incoming execute/validate requests as XML files
 Dump processing MDX statements into a log file
 Dump incoming metadata requests into a log file
 Output processing MDX statements into a debug window

Explore component logging © Copyright IBM Corporation 2016

Explore Query Framework logging

Query Framework logging can track information sent between components involved in
processing OLAP requests.

© Copyright IBM Corp. 2010, 2016 8-7

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 8 Explore component logging

Describe the Dispatcher Command Console

• Activate
 Enable Allow service to interact
with desktop functionality of the
IBM Cognos 11 Windows service

Explore component logging © Copyright IBM Corporation 2016

Describe the Dispatcher Command Console

This console is only available on a Windows OS with a registered IBM
Cognos Analytics service. You can use startup.bat if in a development or test
environment, as a quick way to start IBM Cognos Analytics in a command window; do
not use this method in a production environment.
You can use this to capture startup calls to troubleshoot service initialization issues.

© Copyright IBM Corp. 2010, 2016 8-8

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 8 Explore component logging

Gateway trace
• Diagnose problems with single sign-on and secure sockets, standby
dispatcher mechanism, and password encryption
• Activate
 In ..\cgi-bin\ directory, rename cognoscgi.conf.sample to cognoscgi.conf
 Add code to end of file
gw<type>LoggingConfig=<file_name>.log 5 GWSiMTLogger 1
• Output: ..\logs\<file_name>.log

Explore component logging © Copyright IBM Corporation 2016

Gateway trace
A gateway is an extension of a Web server program that transfers information from the
Web server to another server. Gateways are often CGI programs, but may follow other
standards such as Internet Server Application Program Interface (ISAPI), and Apache
Modules (apache_mod).
An example of a cognoscgi.conf file (remove # to uncomment a line):
# optional overrides; defaults are shown, uncomment and edit as required
#dispatcher_host=localhost
#dispatcher_port=9300
#dispatcher_Encryption=enabled
#SystemRecoverableIterationLimit=50
gwISAPILoggingConfig=gwisapi.log 5 GWSiMTLogger 1
Valid <type> entries include gwCGILoggingConfig for CGI, gwISAPILoggingConfig for
ISAPI, and gwModLoggingConfig for apache_mod.

© Copyright IBM Corp. 2010, 2016 8-9

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 8 Explore component logging

Demonstration 1
Perform a Gateway trace

Explore component logging © Copyright IBM Corporation 2016

Demonstration 1: Perform a Gateway trace

© Copyright IBM Corp. 2010, 2016 8-10

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 8 Explore component logging

Demonstration 1:
Perform a Gateway trace
Purpose:
You want to become familiar with the information available in a gateway trace.
To do this, you will invoke a trace and review the output.
At the beginning of this demonstration, no dispatcher is running.
Ensure that the following services are running:
• Apache Directory Server - default
• DB2-DB2COPY1 - DB2
• DB2DAS - DB2DAS00
• World Wide Web Publishing Service

Task 1. Allow IIS 7 write permission to the logs directory.

In this environment, the IIS 7 Web server user (IUSR) requires permission to write in
the logs directory. Before proceeding with the trace, you will enable this permission.
1. In Windows Explorer, navigate to C:\Program
Files\IBM\cognos\analytics_full, right-click the logs directory, and then click
Properties.
2. On the Security tab, to change permissions, click Edit.
3. Click Add.
4. In the Enter the object names to select (examples) pane, type IUSR, and
then click Check Names.
If the user is found, it will appear with an underscore in the pane.
5. Click OK, and then in the Group or user names pane, click IUSR.
6. In the Permissions for IUSR pane, scroll to the Write permission, and in the
Allow column, select the Write check box.
7. Click Apply, and then click OK to close the Permissions for logs box.
8. Click OK to close the logs Properties box, and then close Windows Explorer.

© Copyright IBM Corp. 2010, 2016 8-11

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 8 Explore component logging

Task 2. Enable the gateway trace.

1. On the Taskbar, click Services, ensure that the IBM Cognos Full:9315 service
has been stopped, and then close the Services window.
2. In Windows Explorer, navigate to C:\Program
Files\IBM\cognos\analytics_full\cgi-bin, and then copy and paste
cognoscgi.conf.sample to the same directory.
3. Rename cognoscgi.conf - Copy.sample to cognoscgi.conf, and then open
cognoscgi.conf in Eclipse.
4. Modify the code as follows:
• dispatcher_host=vclassbase
• dispatcher_port=9315
• dispatcher_Encryption=enabled
• SystemRecoverableIterationLimit=50
• gwCGILoggingConfig=gwcgi.log 5 GWSiMTLogger 1
This will direct the logging of the gateway to a log file called gwcgi.log. Do not
add a path to the filename. The result of the modified section of text appears as
follows:

5. Save the file and then close Eclipse.

6. Start the IBM Cognos Full:9315 service, clearing any messages of the service
not starting in a timely fashion, and refreshing the status every 2 minutes until it
has successfully started.
Task 3. Log in and run a report.
1. Launch Internet Explorer, go to http://vclassbase:88/ibmcognos/cgi-
bin/cognos.cgi?b_action=xts.run&m=portal/main.xts&m_redirect=/ibmcog
nos/bi/, and then log in as admin/Education1.
The path here is different because you are accessing the gateway directly.
2. Navigate to Team content\Samples_DQ\Models\GO Sales (query)\Report
Studio Report Samples, and then run the Horizontal Pagination_DQ report.
3. Navigate through all pages of the report, and then close the browser window.

© Copyright IBM Corp. 2010, 2016 8-12

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 8 Explore component logging

Task 4. Observe the results of the trace.

1. Open C:\Program Files\IBM\cognos\analytics_full\logs\gwcgi.log in
Eclipse.
If a file is open in the middle pane (for example, cognoscgi.conf), close the tab
first.
You will see results similar to the following:

2. Scroll through the file to see the information that is captured in this trace.
Items to look for include SOAP messages, HTML code, and elapsed time (scroll
to the bottom of the file).
3. When you have finished reviewing the file, close the gwcgi.log tab, and then
close Eclipse.
Task 5. Disable the trace.
1. From the System Tray, click Services window, stop the IBM Cognos
Full:9315 service.
2. In Windows Explorer, navigate to C:\Program
Files\IBM\cognos\analytics_full\cgi-bin, and delete cognoscgi.conf.
Leave the IBM Cognos Full:9315 service stopped for the next exercise.
Results:
You invoked a CGI gateway trace and reviewed the information available in
the output.

© Copyright IBM Corp. 2010, 2016 8-13

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 8 Explore component logging

Why use a UDA trace?

• Capture SQL sent to native API for purposes of executing SQL through
UDATest.exe
• Analyze performance issues
• Diagnose reporting database connection issues

Explore component logging © Copyright IBM Corporation 2016

Why use a UDA trace?

The Universal Data Access (UDA) layer is the component used for the processing of
SQL queries to relational data sources.
UDATest is a utility which ships with IBM Cognos Analytics. The purpose of the utility is
to allow users to execute the SQL generated by UDA, which has been previously
captured in a UDA trace, directly against a third party RDBMS. The output generated by
UDATest from the SQL execution will show attaching to the 3rd party RDBMS API, the
preparation of the SQL, the actual SQL, and will display the data returned.

© Copyright IBM Corp. 2010, 2016 8-14

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 8 Explore component logging

It is important to understand that UDATest does not fix issues. Its purpose is to verify if
the SQL sent to the RDBMS will execute successfully.
The following are some possible use cases for UDATest. Keep in mind that in some of
these examples, the SQL generated was identical or ran successfully. UDATest did not
help resolve the issue, but rather proved the SQL sent to the RDBMS could execute
successfully and therefore helped the administrator determine that the actual issue may
be elsewhere:
• Report runs against one DB vendor and fails against another. For example, you
create a report against SQL Server, the report validates and runs as expected,
then you create a similar report against a DB2 data source and the report fails
with a UDA error. Run UDATest against both vendors RDBMS and compare the
output to see where the process is failing and how the SQL differs.
• SQL Performance with Virtual View Manager versus directly against the vendor:
Running a report which uses a Composite data source runs in x minutes.
Running the same SQL, directly against Oracle takes x + minutes. Run UDATest,
with output logging enabled, against both and compare to see what the
differences are in the SQL.
• Upgrade: Comparing SQL generated in different versions of IBM Cognos
Analytics or IBM Cognos BI: Running a report against an earlier version of IBM
Cognos runs successfully, running the same report after upgrading to
IBM Cognos Analytics fails with an error. Run UDATest to see the differences in
the SQL being generated.
• Intermittent Report Failures: Every day a summary report is sent out. Since
upgrading report returns incorrect data usually once or twice a week. This is not
due to a database issue because if you re-run the report again you will get the
correct answer. Run UDATest a number of times in sequence, waiting a couple of
seconds between each launch of UDATest.
See good results for run#2, run# 3, run#4 and run# 5: uda_2.log, uda_3.log,
uda_4.log, uda_5.log. See bad results for run# 1, run #6 and run# 7: uda_1.log,
uda_7.log and uda_7.log. Compare the logs to see the differences.

© Copyright IBM Corp. 2010, 2016 8-15

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 8 Explore component logging

Describe methods to enable UDA traces

Method Pros Cons

Server Environment set any EVs requires IBM Cognos
Variables logs until EVs are unset service restart

Session Environment set any EVs variables only good for

Variables no IBM Cognos restart session
required
Use captures performance will probably want to use
ipfUDAClientConfig.xml categories other IPF files at the
no IBM Cognos restart same time and merging
required IPF files takes care and
consideration

Explore component logging © Copyright IBM Corporation 2016

Describe methods to enable UDA traces

There are several methods to enable UDA traces. The method you choose depends on
your circumstances for enabling the UDA trace, your comfort level with the method and
what flexibility you require for the tracing.
Before enabling UDA tracing:
• check the IBM Cognos Analytics Version 11.0.0 Troubleshooting Guide and the
Readme file for common UDA issues
• search the IBM technical support portal (https://www-947.ibm.com
/support/entry/portal/support) for the UDA error message and see if any are
similar to the issue that is being encountered
• search the IBM Cognos Proven Practice document library
(http://www.ibm.com/developerworks/analytics/practices.html) for potential
solutions

© Copyright IBM Corp. 2010, 2016 8-16

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 8 Explore component logging

Enable UDA tracing:

• To capture the SQL sent to the native API for the purposes of executing that SQL
through .bin/UDATest.exe, thereby taking the rest of the Cognos services and
components out of the picture.
• To help in analyzing performance issues. If you have encountered a performance
issue where the actual slow points of performance have not been isolated across
components you may want to enable UDA logging. Be aware that you will
probably need to capture traces from other components to establish a timeline of
activity across all components.
• The key place where the timeline becomes important is establishing where
components are waiting for their consumers (either other Cognos components or
3rd Party APIs) to re-invoke them, etc. Looking at a single component trace on its
own can mask that delay.
• The cogserver.log does not provide enough granularity to pinpoint where the
performance hit is taking place.

© Copyright IBM Corp. 2010, 2016 8-17

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 8 Explore component logging

Explore UDA trace and environment variables

• Activate with server environment variables
 TRACE_FILE=<trace_file_location>/<filename>.xml
 TRACE_ALL_THREADS=Y
 TRACE_LAYER_DMD_SQLAPIRW = 0x0002

Explore component logging © Copyright IBM Corporation 2016

Explore UDA trace and environment variables

When using TRACE_FILE=<trace_file_location>/<filename>.xml, if you are a Visual
Studio user, if this is set to a value of ::DEBUGWIN, the output will be directed to Visual
Studio.
TRACE_ALL_THREADS=Y will catch tracing from all threads.
TRACE_LAYER_DMD_SQLAPIRW = 0x0002 performs SQL API tracing.
There are other environment variables that are organized into trace layers with 32 trace
categories within each layer. These environment variables apply to IBM Cognos only
and will not affect any other processes.
For the settings in the environment variables to take effect, the IBM Cognos Analytics
service will have to be re-started, as setting environment variables is a function of the
operating system. In Windows, open My Computer, click View system information, click
the Advanced tab, click the Environment Variables button. For UNIX/Linux, environment
variables are usually set in shell scripts.

© Copyright IBM Corp. 2010, 2016 8-18

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 8 Explore component logging

Describe common trace layers and categories

Trace Layer Category

TRACE_LAYER_COMMON=0x0004 Trace low level initialization

TRACE_LAYER_COMMON=0x0008 Trace loading/unloading of shared libraries
TRACE_LAYER_DMD_SQLAPIRW = 0x0002 SQL API tracing
TRACE_LAYER_GENERIC=0x0400 Trace sort statistics
TRACE_FORMAT=bare Removes trace file formatting such as the XML tags

Explore component logging © Copyright IBM Corporation 2016

Describe common trace layers and categories

The most common traces are displayed above.

© Copyright IBM Corp. 2010, 2016 8-19

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 8 Explore component logging

Example of a UDA trace

• TRACE_FILE = x:\<path>\<name>.api
• TRACE_LAYER_DMD_SQLAPIRW = 0x0002
• TRACE_ALL_THREADS=Y

Explore component logging © Copyright IBM Corporation 2016

Example of a UDA trace

The trace file can be located in any place that is accessible by the IBM Cognos 11
server and can be named at your discretion. The file extension does not matter; it could
be .xml, .log, .txt, and so on. UDATest picks up .api by default, but you can point to the
trace file using Show all files.
The IBM Cognos Service has to be restarted for the trace to be enabled.
The example shows the setting of System Environment variables for UDA trace on a
Windows server. Customer support frequently uses UDA traces for troubleshooting.

© Copyright IBM Corp. 2010, 2016 8-20

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 8 Explore component logging

Activate UDA trace with session variables

• Stop IBM Cognos service
• Modify ..\bin\startup.bat, add code below @echo off
• Save and run startup.bat file to start IBM
Cognos 11

@ echo off
set TRACE_FILE = <drive letter>:\<path>\<name>.api
set TRACE_LAYER_DMD_SQLAPIRW = 0x0002
set TRACE_ALL_THREADS=Y
@ echo off
Example set TRACE_FILE = C:\UDATrace.txt
set TRACE_LAYER_DMD_SQLAPIRW = 0x0002
set TRACE_ALL_THREADS=Y
Explore component logging © Copyright IBM Corporation 2016

Activate UDA trace with session variables

This technique really only applies to Windows platforms and is only applicable in
development or test environments since startup.bat should not be used in a production
environments.
In the example shown, press Ctrl+C to stop.

© Copyright IBM Corp. 2010, 2016 8-21

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 8 Explore component logging

Activate UDA trace with IPF file

• Rename ..\configuration\ipfUDAclientconfig.xml.sample to
ipfclientconfig.xml
• Output to ..\logs directory:
 UDA_Trace.log
 UDA_Perf.log
 UDA_RTUsage.log

Explore component logging © Copyright IBM Corporation 2016

Activate UDA trace with IPF file

Tracing will take effect within 30 seconds.
A UDA trace can be useful to determine how long processing is taking with the
database.

© Copyright IBM Corp. 2010, 2016 8-22

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 8 Explore component logging

Example UDA output

<?xml version="1.0"?><UDATrace version="UDA-AW-ML-8.500-WIP-31860-0(Production)" build="31860" patch="0"

Date="2015/03/11 11:06“><TraceEvent Layer="8" Category="2" ThreadId="00000C84"
Timestamp="1469"><SQLAPI><![CDATA[initialize e1 for "en" metadata callback m1,ThreadId="00000C84"
Timestamp="1469"><SQLAPI><![CDATA[initialize e1 for "en" metadata callback m1,
sql99datatypes;]]></SQLAPI></TraceEvent><TraceEvent Layer="8" Category="2" ThreadId="00000C84"
Timestamp="1469"><SQLAPI Id="e1"><![CDATA[multidbattachdirect d10001 dblogicname "CQE_DB" in e1(dblogicname "SQL-
Environment" "" QS );]]></SQLAPI></TraceEvent><TraceEvent Layer="8" Category="2" ThreadId="00000C84"
Timestamp="1469"><SQLAPI Id="e1"><![CDATA[show features d10001 passive;]]></SQLAPI></TraceEvent><TraceEvent
Layer="8" Category="2" ThreadId="00000C84" Timestamp="1469"><SQLAPI Id="e1"><![CDATA[start t10001 for d10001
read;]]></SQLAPI></TraceEvent><TraceEvent Layer="8" Category="2" ThreadId="00000C84" Timestamp="1469"><SQLAPI
Id="e1"><![CDATA[prepare r10001 from"Select * from [gosales].PRODUCT_LINE" in t10001 tag sql, enable
nagging;]]></SQLAPI></TraceEvent><TraceEvent Layer="8" Category="2" ThreadId="00000C84" Timestamp="1469"><SQLAPI
Id="e1"><![CDATA[show tagged sql for r10001;]]></SQLAPI></TraceEvent><TraceEvent Layer="8" Category="2"
ThreadId="00000C84" Timestamp="1469"><SQLAPI Id="e1"><![CDATA[release request
r10001;]]></SQLAPI></TraceEvent><TraceEvent Layer="8" Category="2" ThreadId="00000C84"
Timestamp="1531"><SQLAPI><![CDATA[initialize e2 for "en" metadata callback m2,
sql99datatypes;]]></SQLAPI></TraceEvent><TraceEvent Layer="8" Category="2" ThreadId="00000C84"
Timestamp="1531"><SQLAPI Id="e2"><!["CQE_DB" in e2(dblogicname "great_outdoors_sales"
"DBInfo_Type=MS;Provider=SQLOLEDB;User ID=sa;Password=********;Data Source=localhost\\ SQL2005;Provider_String=Initial
Catalog=gosales;@COLSEQ=" OL );]]></ SQLAPI></TraceEvent><TraceEvent Layer="8" Category="2" ThreadId="00000C84"
Timestamp="1672"><SQLAPI Id="e2"><![CDATA[get attribute max name length context dbname "great_outdoors_sales" for
database d20001 ;]]></SQLAPI></TraceEvent><TraceEvent Layer="8" Category="2" ThreadId="00000C84"
Timestamp="1672"><SQLAPI Id="e2"><![CDATA[show features d20001 case sensitive;]]></SQLAPI></TraceEvent><TraceEvent
Layer="8" Category="2" ThreadId="00000C84" Timestamp="1672"><SQLAPI Id="e2"><![CDATA[show features d20001 case
sensitive;]]></SQLAPI></TraceEvent><TraceEvent Layer="8" Category="2" ThreadId="00000C84" Timestamp="1672"><SQLAPI
Id="e1"><![CDATA[prepare r10002 from"select PRODUCT_LINE.PRODUCT_LINE_CODE

Explore component logging © Copyright IBM Corporation 2016

Example UDA output

The slide includes a snippet of UDA output. The items in red bold are the connect
string, SQL and bulkfetch. Timings are in milliseconds. The second timing in red bold
(Timestamp="1531") is the connection to the 3rd party data source vendors API. The
line (Timestamp="1672") is the first response back from that call. Therefore you can
determine that at least part of 1.5 seconds of this request was the time it took to attach
and get a response back.
By finding the timestamp in the log file, looking at the response, and looking at the
timestamp, you can determine timings to help troubleshoot. For example, how long did
it take to log in? This trace may help you to identify where the time is being spent,
including in connection of third party database vendor applications.
This type of code will be displayed in Exercise 1: Explore UDA Trace and UDATest.
To describe a scenario that might result in the listed UDA output, consider a report that
took 8 seconds to run. Through a UDA trace you were able to determine that 5 seconds
are taken up by this attach time. The issue in this case was a bug in a third party vendor
driver which was taking too long to encrypt the information. A bug was logged with the
vendor and eventually the report execution time was reduced by 3 seconds. The
connection time will never be zero as all vendors require some time to process this
information.

© Copyright IBM Corp. 2010, 2016 8-23

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 8 Explore component logging

What is UDATest?
• Utility in IBM Cognos 11 at ..\bin\udatest.exe or ..\bin64\udatest.exe
• Users can execute SQL generated by UDA directly against a third
party data source
• UDATest verifies if the SQL sent to the RDBMS will execute
successfully

Explore component logging © Copyright IBM Corporation 2016

What is UDATest?
It is important to understand that UDATest does not fix issues. Over the next few pages,
some possible use cases for UDATest are presented.

© Copyright IBM Corp. 2010, 2016 8-24

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 8 Explore component logging

UDATest scenario 1
• Report runs against one DB vendor and fails against another
 You create a report against SQL Server, the report validates and runs as
expected
 You create a similar report against a DB2 data source and the report fails
with a UDA error
 Run UDATest against each vendor RDBMS and compare output to see
where process is failing and how the SQL differs

Explore component logging © Copyright IBM Corporation 2016

UDATest scenario 1

© Copyright IBM Corp. 2010, 2016 8-25

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 8 Explore component logging

UDATest scenario 2
• SQL Performance with Composite/VVM vs. directly against the vendor
 A report which uses a Composite/VVM data source runs in x minutes
 Running the same SQL, directly against Oracle takes x + minutes
 Run UDATest, with output logging enabled, against both, and compare
differences in the SQL

Explore component logging © Copyright IBM Corporation 2016

UDATest scenario 2

© Copyright IBM Corp. 2010, 2016 8-26

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 8 Explore component logging

UDATest scenario 3
• Compare SQL generated on different operating systems
 Report performance on AIX going through DataDirect ODBC driver to MS
SQL Server is unacceptable
 Database administrators see multiple cursors on AIX
 Running on Windows, the cursors are not sent to the database and
performance is acceptable
 Run UDATest against both, and review the SQL generated and the output it
produced

Explore component logging © Copyright IBM Corporation 2016

UDATest scenario 3

© Copyright IBM Corp. 2010, 2016 8-27

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 8 Explore component logging

UDATest scenario 4
• Compare SQL generated in different versions of IBM Cognos Analytics
 Running a report against IBM Cognos BI 8.4.1 runs successfully
 Running the same report after upgrading to IBM Cognos BI 10.2.2 fails with
an error
 Report still fails with an error when upgraded to IBM Cognos 11.0.0
 Run UDATest to see the differences in the SQL being generated

Explore component logging © Copyright IBM Corporation 2016

UDATest scenario 4

© Copyright IBM Corp. 2010, 2016 8-28

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 8 Explore component logging

UDATest scenario 5
• Specific version of IBM Cognos
 Running a report in IBM Cognos BI 8.4.1 runs successfully
 Same report fails with an error in IBM Cognos BI 10.2.2
 Same report runs successfully in IBM Cognos 11.0.0
 Probably not a database issue
 Run UDATest and compare the resulting SQL to look for differences

Explore component logging © Copyright IBM Corporation 2016

UDATest scenario 5

© Copyright IBM Corp. 2010, 2016 8-29

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 8 Explore component logging

UDATest scenario 6
• Intermittent report failures
 Each day a summary report is sent out
 Since upgrading, the report returns incorrect data usually once or twice a
week
 Not due to a database issue because if you re-run the report again you will
get the correct data
 Run UDATest a number of times in sequence, waiting a couple of seconds
between each launch of UDATest
− See good results for run #2, run #3, run #4 and run #5: uda_2.log, uda_3.log,
uda_4.log, uda_5.log.
− See bad results for run #1, run #6 and run #7: uda_1.log, uda_7.log and
uda_7.log.
 Compare the logs to see the differences

Explore component logging © Copyright IBM Corporation 2016

UDATest scenario 6
Be aware that UDA is not used with the QueryService which processes the 64-bit
ReportServer service. The scenario presented here assumes that you are running a
report against the 32-bit ReportServer service. For 64-bit ReportServer traces of
queries, use the Dynamic Query Analyzer utility.

© Copyright IBM Corp. 2010, 2016 8-30

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 8 Explore component logging

Exercise 1
Explore UDA Trace and UDATest (optional)

Explore component logging © Copyright IBM Corporation 2016

Exercise 1: Explore UDA Trace and UDATest (optional)

© Copyright IBM Corp. 2010, 2016 8-31

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 8 Explore component logging

Exercise 1:
Explore UDA Trace and UDATest (optional)

UDA is not used with the QueryService which processes the 64-bit ReportServer
service. In this exercise, you will run a report against the 32-bit ReportServer service.
For 64-bit ReportServer traces of queries, use the Dynamic Query Analyzer utility.
You are an administrator testing a report in IBM Cognos Analytics - Reporting, and
want to know if the query submitted in IBM Cognos returns the correct information from
the database. You need to extract the native SQL and query execution plan of
Relational Query Planner (RQP). The native SQL then can be tested in the database
vendor's native query tool. You will use the UDATest utility to accomplish this.
UDATest is used to isolate the database information. You will perform a trace to get this
information.
You will:
• Ensure that the IBM Cognos Full:9315 service and the IBM Cognos
DispCM:9320 service are stopped.
• Enable SQL comments in CQEconfig.xml making it easier to identify the query
and the user running it. The log file created will be tested using the udatest.exe
and the native query will be executed in the native client query tool.
• Set Universal Data Access (UDA) environment variables (on both Dispatchers) to
enable the creation of the log files when a query is executed.
• Create a report (using admin/Education1 credentials) that will be used to run UDA
trace.
• Modify the uda_trace.log file and save as .api file.

© Copyright IBM Corp. 2010, 2016 8-32

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 8 Explore component logging

• Run udatest.exe to examine the .api file from the Cognos 11 bin folder.
• Copy the native SQL from the .api file and test its performance in IBM Data
Studio.
• Reset all configurations back to their original state
Keep in mind, that in a real troubleshooting scenario, it is best to run multiple traces
(UDA, BIBus, Dispatcher) to get a better understanding of the causes of the issues.
For more information about where to work and the exercise results, refer to the Tasks
and Results section that follows. If you need more information to complete a task, refer
to earlier demonstrations for detailed steps.

© Copyright IBM Corp. 2010, 2016 8-33

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 8 Explore component logging

Exercise 1:
Tasks and Results
At the beginning of this exercise, no dispatcher is running.
Task 1. Enable SQL comments in the UDA trace and native
SQL.
• In the Services window, ensure the IBM Cognos Full:9315 service and the IBM
Cognos DispCM:9320 service are stopped.
• In Windows Explorer, navigate to C:\Program
Files\IBM\cognos\analytics_full\configuration, and then copy and paste
CQEConfig.xml.sample to the same directory.
• Rename to CQEConfig.xml - Copy.sample to CQEConfig.xml, and then open
CQEConfig.xml in Eclipse.
• Locate the following section:
<section name="QueryEngine">
…
</section>
• Uncomment the following four lines of code in this section by deleting the !--
characters:
<!-- entry name="GenerateCommentInNativeSQL" value="1"-->

<!-- entry name="GenerateCommentInCognosSQL" value="1"-->

<!-- entry name="NativeCommentMacro" value="#'user=' +

$account.defaultName + ' report-Path=' + $reportPath + ' queryName='
+ $queryName + 'REMOTE_ADDR=' + $REMOTE_ADDR + ' SERVER_NAME='
+$SERVER_NAME + ' requestID=' + $requestID#"/-->

<!-- entry name="CognosCommentMacro"value="#'user=' +

$account.defaultName + ' report-Path=' + $reportPath + ' queryName='
+ $queryName + 'REMOTE_ADDR=' + $REMOTE_ADDR + ' SERVER_NAME='
+$SERVER_NAME + ' requestID=' + $requestID#"/-->
You can also copy the contents of C:\Training\B6019\08-
Explore_Component_Logging\Unit8_Exercise_1_Task1.txt into CQEconfig.xml,
replacing these lines of code.
• Save the file, and then close Eclipse.

© Copyright IBM Corp. 2010, 2016 8-34

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 8 Explore component logging

Task 2. Set environment variables to enable UDA tracing.

• In Windows Explorer, create a folder named Temp at the root of C:\.
• Navigate to C:\Program Files\IBM\cognos\analytics_full\bin64, right-click
startup.bat, and then click Properties.
• Ensure that the Read-only check box is clear, and then click OK.
• Right-click startup.bat, and then click Edit.
• Preceding the setlocal line, add the following lines of code:
set TRACE_LAYER_DMD_SQLAPIRW=0x0002
set TRACE_FILE=C:\Temp\uda_trace.log
The results appear as follows:

This trace will contain all SQL statements sent to the UDA layer. In addition it will
have the timings of how long each statement took to execute. The trace file will
be written to uda_trace.log.
• Save and then close the file.
• Repeat the preceding steps for the C:\Program
Files\IBM\cognos\analytics_DispCM\bin64\startup.bat file.
Task 3. Create a report that will be used to run the UDA trace.
• Double-click C:\Program Files\IBM\cognos\analytics_full\bin64\startup.bat to
start the IBM Cognos Analytics Full instance with the new CQEconfig.xml and
environment variable settings.
If a Windows Security Alert box appears with a message related to Windows
Firewall, select only the Private networks, such as my home or work network
check box, and then click Allow access.

© Copyright IBM Corp. 2010, 2016 8-35

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 8 Explore component logging

You should not use startup.bat to start IBM Cognos Analytics in a production
environment, but you are doing testing in a non-production environment for this
exercise.
Allow a few minutes for the services to start.
• When The dispatcher is ready to process requests message appears in the
command window, repeat with the C:\Program
Files\IBM\cognos\analytics_DispCM\bin64\startup.bat file to start the IBM
Cognos Analytics DispCM instance.
UDA is not used with the QueryService which processes the 64-bit ReportServer
service. You will be running a report against the 32-bit ReportServer service, and
in this environment, that is on the DispCM server. Therefore you must start both
instances to execute the trace. For 64-bit ReportServer traces of queries, use the
Dynamic Query Analyzer utility.
• Launch Internet Explorer, go to http://vclassbase:88/ibmcognos/bi/, and then
log in as admin/Education1.
• Click New, and then click Report.
• Click Blank, and then click OK.
• Click Add report data, navigate to
Team content\Legacy_Samples\Samples\Models\GO Sales (query), and then
click Open.
• From the Toolbox panel, drag a List to the report area, and then click OK to
accept the defaults.
• From the Data panel, populate the list report with the following items from the
Sales (query) namespace:
• Products: Product line, Product type
• Sales: Product cost
• In the report layout, click the <Product line> column, and then on the
On-demand toolbar click Group / Ungroup .

• Select the list object using its Container selector , and then on the
Application bar, click Show properties .
• In the DATA section of the Properties panel, change the Rows Per Page to 25.

© Copyright IBM Corp. 2010, 2016 8-36

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 8 Explore component logging

• Save the report as UDA Test in the

Team content\Legacy_Samples\Samples\Models\GO Sales (query) package.
Ensure that the report is saved to a location that is accessible to all, and is not
saved to a private location, like My Folders.
• On the Application bar, click the down arrow beside UDA Test, and then click
Remove.
• On the Sidebar panel, navigate to the Team content\Legacy
Samples\Samples\Models\GO Sales (query) package, and then click UDA
Test to run the report.
Count the number of rows of data that are returned in the report.
The results appear similar to the following:

• After the report opens, leave the browser open.

© Copyright IBM Corp. 2010, 2016 8-37

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 8 Explore component logging

Task 4. Modify the uda_trace.log file and save as an .api file.

• In Windows Explorer, navigate to C:\Temp, to identify the presence of the
uda_trace.<PID #>.log file.
If there is more than one log file, it is because the trace was enabled on both
dispatchers. You will want to open the file with the most recent timestamp, and
which has some content in it. Likely the other file will be 0 KB in size and will be
blank.
• Open the uda_trace.<PID #>.log file in Eclipse and find ********.
This line will contain the connection string information to the database. The eight
asterisks represent the connection password to the database.
• Change ******** to Education1, and then close the Find/Replace box.
• Press Ctrl+Home to return to the beginning of the file, find the second instance of
multidbattach, and then copy the following text from the file to the clipboard:
multidbattachdirect d20001 dblogicname "CQE_DB" in e2(dblogicname
"great_outdoors_sales"
"DSN=GS_DB;UID=GOSALES;PWD=Education1;@ASYNC=0@0/0@COLSEQ=IBM_JD_CNX
_STR:^User ID:^?Password:;LOCAL;JD-
D2;URL=jdbc:db2://VCLASSBASE:50000/GS_DB;DRIVER_NAME=com.ibm.db2.jcc
.DB2Driver" D2 );
• In Windows Explorer, navigate to C:\Training\B6019\08-
Explore_Component_Logging, and then open Unit8_Exercise1_Task4.txt in
Notepad.
This file will serve as a template to create a query for UDATest that will return the
native SQL and the execution plan.
• Delete the following text:
<<INSERT MULTIDBATTACHDIRECT STATEMENT HERE>>;
• Paste the contents of the clipboard.
• Locate the following section:
get attribute max name length context dbname "<<INSERT DATA
SOURCE NAME HERE>>" for database d20001 ;

© Copyright IBM Corp. 2010, 2016 8-38

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 8 Explore component logging

• Replace <<INSERT DATA SOURCE NAME HERE>> with

great_outdoors_sales.
This line appears as follows:
get attribute max name length context dbname "great_outdoors_sales"
for database d20001 ;
• In Eclipse, in the uda_trace.<PID #>.log file, find with, and then search for the
semicolon at the end of the SQL statement.
• Copy all the text from the with clause to the end of the SQL including the avoid
zero division and ; (semicolon), to the clipboard.
• In the Unit8_Exercise1_Task4.txt file, delete the following text:
<<INSERT SQL STATEMENT HERE>>

© Copyright IBM Corp. 2010, 2016 8-39

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 8 Explore component logging

• Paste the contents of the clipboard.

In this example, the two features for which you want to get information are:
• show native sql for r20001; (this will generate the native SQL)
• show execution plan for r20001; (this will show the execution plan for
RQP)
The results appear as follows:

© Copyright IBM Corp. 2010, 2016 8-40

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 8 Explore component logging

• In Notepad, from the File menu, click Save As, and then in the Save in list,
navigate to C:\Program Files\IBM\cognos\analytics_full\bin64.
• In the File name box, type Test.api, in the Save as type list, click All Files (*.*),
in the Encoding list, click ANSI, and then click Save.
You may wonder why another format, other than ANSI is not used here. UDA is a
low level component; and this format has been traditionally used. As an
experiment, you could try to use different encoding types (UTF-8, Unicode) and
determine if alternate types work with UDA. Do this only after you have
successfully completed this exercise, and if you have the time to do this.
• Close Notepad without saving changes.
• In Eclipse, close the uda_trace.<PID #>.log tab without saving changes, and
then close Eclipse.

© Copyright IBM Corp. 2010, 2016 8-41

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 8 Explore component logging

Task 5. Run udatest.exe and test the native SQL.

• Navigate to C:\Program Files\IBM\cognos\analytics_full\bin64 and then
double-click udatest.exe.
• From the I/O Control menu, click Read from, and then open Test.api.
The UDATest utility executes the Test.api file and produces a log file. In this case,
test.log will be created in the bin folder. The results in the UDATest utility indicate
that 21 rows were selected.
The results appear as follows:

• In the C:\Program Files\IBM\cognos\analytics_full\bin64 folder open the

TEST.log file in Eclipse.
The log file contains the original query, the native SQL, the execution plan and
the data that is returned from the query.

© Copyright IBM Corp. 2010, 2016 8-42

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 8 Explore component logging

• Find native SQL.

This section of the file contains the native SQL that is sent to the database.
Notice that most of the code appears on one line (displayed below with word
wrap).

SQL> show native sql for r20001;

Native SQL statements ( 1 ) :

with "PRODUCT_NAME_LOOKUP7" as (select
"PRODUCT_NAME_LOOKUP"."PRODUCT_NUMBER" "PRODUCT_NUMBER"
, "PRODUCT_NAME_LOOKUP"."PRODUCT_NAME" "PRODUCT_NAME" ,
"PRODUCT_NAME_LOOKUP"."PRODUCT_DESCRIPTION"
"PRODUCT_DESCRIPTION" from
"GOSALES"."PRODUCT_NAME_LOOKUP" "PRODUCT_NAME_LOOKUP"
where "PRODUCT_NAME_LOOKUP"."PRODUCT_LANGUAGE" = 'EN'),
"Products" as (select "PRODUCT_LINE"."PRODUCT_LINE_EN"
"Product_line" , "PRODUCT_TYPE"."PRODUCT_TYPE_EN"
"Product_type" , "PRODUCT6"."PRODUCT_NUMBER"
"Product_number" from "GOSALES"."PRODUCT_LINE"
"PRODUCT_LINE", "GOSALES"."PRODUCT_TYPE" "PRODUCT_TYPE",
"GOSALES"."PRODUCT" "PRODUCT6", "PRODUCT_NAME_LOOKUP7",
"GOSALES"."PRODUCT_SIZE_LOOKUP" "PRODUCT_SIZE_LOOKUP",
"GOSALES"."PRODUCT_BRAND" "PRODUCT_BRAND",
"GOSALES"."PRODUCT_COLOR_LOOKUP" "PRODUCT_COLOR_LOOKUP"
where "PRODUCT_LINE"."PRODUCT_LINE_CODE" =
"PRODUCT_TYPE"."PRODUCT_LINE_CODE" and
"PRODUCT_TYPE"."PRODUCT_TYPE_CODE" =
"PRODUCT6"."PRODUCT_TYPE_CODE" and
"PRODUCT6"."PRODUCT_NUMBER" =
"PRODUCT_NAME_LOOKUP7"."PRODUCT_NUMBER" and
"PRODUCT_COLOR_LOOKUP"."PRODUCT_COLOR_CODE" =
"PRODUCT6"."PRODUCT_COLOR_CODE" and
"PRODUCT_SIZE_LOOKUP"."PRODUCT_SIZE_CODE" =
"PRODUCT6"."PRODUCT_SIZE_CODE" and
"PRODUCT_BRAND"."PRODUCT_BRAND_CODE" =
"PRODUCT6"."PRODUCT_BRAND_CODE"), "Sales" as (select
"ORDER_DETAILS"."PRODUCT_NUMBER" "Product_number" ,
"ORDER_DETAILS"."QUANTITY" * "ORDER_DETAILS"."UNIT_COST"
"Product_cost" from "GOSALES"."ORDER_DETAILS"
"ORDER_DETAILS", "GOSALES"."ORDER_HEADER" "ORDER_HEADER"
where "ORDER_HEADER"."ORDER_NUMBER" =

© Copyright IBM Corp. 2010, 2016 8-43

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 8 Explore component logging

"ORDER_DETAILS"."ORDER_NUMBER") select "T0"."C0"

"Product_line" , "T0"."C1" "Product_type" , "T0"."C2"
"Product_cost" , sum("T0"."C2") over ()
"Summary_Product_cost_" , sum("T0"."C2") over (partition
by "T0"."C0") "Summary_Product_cost_5" from (select
"Products"."Product_line" "C0" ,
"Products"."Product_type" "C1" ,
sum("Sales"."Product_cost") "C2" from "Products",
"Sales" where "Products"."Product_number" =
"Sales"."Product_number" group by
"Products"."Product_line", "Products"."Product_type")
"T0" order by "Product_line" asc FOR FETCH ONLY
• Copy the SQL from with to the end of asc to the clipboard.
The following is selected:
with "PRODUCT_NAME_LOOKUP7" as (select
"PRODUCT_NAME_LOOKUP"."PRODUCT_NUMBER" "PRODUCT_NUMBER" ,
"PRODUCT_NAME_LOOKUP"."PRODUCT_NAME" "PRODUCT_NAME" ,
"PRODUCT_NAME_LOOKUP"."PRODUCT_DESCRIPTION"
"PRODUCT_DESCRIPTION" from
"GOSALES"."PRODUCT_NAME_LOOKUP" "PRODUCT_NAME_LOOKUP"
where "PRODUCT_NAME_LOOKUP"."PRODUCT_LANGUAGE" = 'EN'),
"Products" as (select "PRODUCT_LINE"."PRODUCT_LINE_EN"
"Product_line" , "PRODUCT_TYPE"."PRODUCT_TYPE_EN"
"Product_type" , "PRODUCT6"."PRODUCT_NUMBER"
"Product_number" from "GOSALES"."PRODUCT_LINE"
"PRODUCT_LINE", "GOSALES"."PRODUCT_TYPE" "PRODUCT_TYPE",
"GOSALES"."PRODUCT" "PRODUCT6", "PRODUCT_NAME_LOOKUP7",
"GOSALES"."PRODUCT_SIZE_LOOKUP" "PRODUCT_SIZE_LOOKUP",
"GOSALES"."PRODUCT_BRAND" "PRODUCT_BRAND",
"GOSALES"."PRODUCT_COLOR_LOOKUP" "PRODUCT_COLOR_LOOKUP"
where "PRODUCT_LINE"."PRODUCT_LINE_CODE" =
"PRODUCT_TYPE"."PRODUCT_LINE_CODE" and
"PRODUCT_TYPE"."PRODUCT_TYPE_CODE" =
"PRODUCT6"."PRODUCT_TYPE_CODE" and
"PRODUCT6"."PRODUCT_NUMBER" =
"PRODUCT_NAME_LOOKUP7"."PRODUCT_NUMBER" and
"PRODUCT_COLOR_LOOKUP"."PRODUCT_COLOR_CODE" =
"PRODUCT6"."PRODUCT_COLOR_CODE" and
"PRODUCT_SIZE_LOOKUP"."PRODUCT_SIZE_CODE" =
"PRODUCT6"."PRODUCT_SIZE_CODE" and
"PRODUCT_BRAND"."PRODUCT_BRAND_CODE" =

© Copyright IBM Corp. 2010, 2016 8-44

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 8 Explore component logging

"PRODUCT6"."PRODUCT_BRAND_CODE"), "Sales" as (select

"ORDER_DETAILS"."PRODUCT_NUMBER" "Product_number" ,
"ORDER_DETAILS"."QUANTITY" * "ORDER_DETAILS"."UNIT_COST"
"Product_cost" from "GOSALES"."ORDER_DETAILS"
"ORDER_DETAILS", "GOSALES"."ORDER_HEADER" "ORDER_HEADER"
where "ORDER_HEADER"."ORDER_NUMBER" =
"ORDER_DETAILS"."ORDER_NUMBER") select "T0"."C0"
"Product_line" , "T0"."C1" "Product_type" , "T0"."C2"
"Product_cost" , sum("T0"."C2") over ()
"Summary_Product_cost_" , sum("T0"."C2") over (partition
by "T0"."C0") "Summary_Product_cost_5" from (select
"Products"."Product_line" "C0" ,
"Products"."Product_type" "C1" ,
sum("Sales"."Product_cost") "C2" from "Products",
"Sales" where "Products"."Product_number" =
"Sales"."Product_number" group by
"Products"."Product_line", "Products"."Product_type")
"T0" order by "Product_line" asc FOR FETCH ONLY
• From the Start menu, navigate to All Programs\IBM Data Studio, and then click
Data Studio 4.1.0.0 Client.
You need to submit this query to the vendor database vendor query tool for the
specific database you are referencing; in your environment, the database is DB2.
• In the Administration Explorer pane on the left side, expand localhost and
DB2.

• Click New SQL Script .

• Click the No Connection link, click GS_DB, and then click Finish.
Once you have connected to a database as an authorized user, you can then
issue SQL statements or DB2 commands against that database.
If you are prompted to enter a password, type Education1 in the Password box,
select the Save password check box, and then click OK.
• Paste the clipboard contents into the middle pane, click OK to close the
Statement Terminator box, and then click Run SQL .

© Copyright IBM Corp. 2010, 2016 8-45

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 8 Explore component logging

The query runs and the Result1 tab in the bottom right corner displays the output
of 21 rows.
The results appear as follows:

You have checked the performance of the query at the database level, to see if
the same values are returned as those seen in the report in IBM Cognos
Analytics. In both environments, 21 rows were returned.
• Return to the TEST.log file in Eclipse, and locate the execution plan section.
• Examine the fetch, prepare, execution and CPU times by locating the following
section.
<operator CPUTime="0.000000" elapsedTime="0.000000" nRows="0"
operatorType="dbScan" rowSize="480" totalCPUTime="0.000000"
totalElapsedTime="0.000000">
In this scenario, the execution time of the query was minimal, and there were no
issues. This exercise provides you with a method to get this information; there is
nothing to troubleshoot here, but you were able to confirm that the SQL results
returned were the same in the IBM Cognos query as they were in the direct SQL
query against the database.

© Copyright IBM Corp. 2010, 2016 8-46

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 8 Explore component logging

This is an example of a low level development trace. You could also test the SQL
going through Cognos SQL, as opposed to the native SQL. Does it take longer to
execute?
If you do comparisons with earlier versions of IBM Cognos, the SQL may not be
the same. This does not necessarily indicate an issue.
Task 6. Restore the settings and files to their original state.
• Close all open windows without saving.
• In Windows Explorer, navigate to C:\Program
Files\IBM\cognos\analytics_full\bin64, and then delete TEST.log and Test.api.
• Edit startup.bat for both dispatcher installations (C:\Program
Files\IBM\cognos\analytics_full\bin64 and C:\Program
Files\IBM\cognos\analytics_DispCM\bin64) to remove the setting of the
environment variables.
The result appears as follows:

• Navigate to C:\Program Files\IBM\cognos\analytics_full\configuration, and

delete CQEconfig.xml.
• Close all open applications.
Leave the IBM Cognos Full:9315 service and the IBM Cognos DispCM:9320
service stopped for the next exercise.

© Copyright IBM Corp. 2010, 2016 8-47

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 8 Explore component logging

What is Perf.QFS?
• Purpose:
 Use to determine report running time allocation
• Description:
 Captures data within query framework (QFW) code
 Captures gesture and action times from IBM Cognos Analytics

Explore component logging © Copyright IBM Corporation 2016

What is Perf.QFS?
If your report is slow, use Perf.QFS to determine where time is being spent when
running a report. There may be external factors involved such as database loads,
network latency, overloaded servers, and so on, but this will isolate the IBM Cognos
Analytics components involved.
Perf.QFS provides a method to capture data within the QFW code, and is independent
of the product or test tool that consumes the QFW code.
Perf.QFS allows gesture or action times from IBM Cognos Analytics to be captured,
rather than only the overall request run timing as in QFWTest.

© Copyright IBM Corp. 2010, 2016 8-48

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 8 Explore component logging

Activate Perf.QFS
• Activate:
 Modify ipfPERFclientconfig.xml.sample and save as ipfclientconfig.xml

<category name="Perf.QFS" class="com.cognos.indications.LogTypedLogger">

<level value=“debug"/>
<appender-ref ref="clientFlatFile"/>
</category>

Explore component logging © Copyright IBM Corporation 2016

Activate Perf.QFS
To setup Perf.QFS, edit the ipfPERFclientconfig.xml.sample file, in the section below
the string <!-- QFS -->.

© Copyright IBM Corp. 2010, 2016 8-49

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 8 Explore component logging

Describe Perf.QFS output

• Output:
 ..\logs directory in a file prefixed with performance
 Information by report and component

<RP n="Add Color" rN="0" st="2015-03-24T08:56:38.977" et="2015-03-

24T09:15:56.609" status="SUCCESS">
<RC><![CDATA[;/content/package[@name='GO
Sales(Query)']/folder[@name='Documentation Report
Samples']/report[@name='Add Color'];asynchRun_Request;]]></RC>
<RS et="6586">
<C n="MDOperationProvider" et="227"></C>
<C n="RelationalQueryProvider" et="317"></C>
<C n="CoordinationPlanner" et="5522"></C>

Explore component logging © Copyright IBM Corporation 2016

Describe Perf.QFS output

The information in the file will be presented by report and then by component.
The XML file can be analyzed as is, or it can be transformed into something more
readable by applying a transformation to the XML output, such as perf.xslt, which will be
used in the exercise on this topic.
The meaning of the XML elements are described at the top of the output file. The file
may not be written immediately, as it depends on the flushing of master dataset. In
most cases, running more than one report or running the same report twice will result in
the file being created in the ..\logs directory.
perf.xslt will identify the areas that took more than 15 seconds in red; you can change
the 15 seconds setting by editing perf.xslt. The code for perf.xslt has been provided for
your reference at the end of this unit, if you are interested in using such a file in your
own environment.

© Copyright IBM Corp. 2010, 2016 8-50

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 8 Explore component logging

Exercise 2
Perform Perf.QFS logging

Explore component logging © Copyright IBM Corporation 2016

Exercise 2: Perform Perf.QFS logging

© Copyright IBM Corp. 2010, 2016 8-51

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 8 Explore component logging

Exercise 2:
Perform Perf.QFS logging

You need to identify the architectural components that are used to process a run report
request and how much time spent in each component. This will help you with
troubleshooting issues should they occur.
You will:
• Assign the IIS 7 IUSR user to have Write permission to the logs directory for the
analytics_DispCM instance.
• Set the logging level to info for Perf.QFS logging in the ipfclientconfig.xml file for
the analytics_DispCM instance.
• Using admin/Education1 credentials, create and save a list report and a crosstab
report in IBM Cognos Analytics - Reporting, and then execute each report twice.
• Stop the services and open the perf.xml file and briefly examine the contents.
You can modify the xml file to use the perf.xslt stylesheet at
C:\Training\B6019\08-Explore_Component_ Logging\.
• Compare the components that each report used and compare the results with
the IBM Cognos 11.0 Architecture diagram. Why is there an
OlapQueryProvider as a component for the cross tab report?
• What component is the crosstab report spending most of its time in? Why?
• What component function is the most time spent in? Why?

For more information about where to work and the exercise results, refer to the Tasks
and Results section that follows. If you need more information to complete a task, refer
to earlier demonstrations for detailed steps.

© Copyright IBM Corp. 2010, 2016 8-52

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 8 Explore component logging

Exercise 2:
Tasks and Results
At the beginning of this exercise, no dispatcher is running.
Task 1. Allow IIS 7 write permission to the logs directory.
In this environment, the Web server user (IUSR) requires permission to write in the
..\logs directory. Before proceeding with the trace, you will enable this permission for the
Analytics_DispCM instance. You may be familiar with this process, as it has been done
earlier, for the Analytics_full Dispatcher instance.
• In Windows Explorer, navigate to C:\Program
Files\IBM\cognos\analytics_DispCM, right-click the logs directory, and then
click Properties.
• On the Security tab, to change permissions, click Edit.
• Click Add.
• In the Enter the object names to select (examples) pane, type IUSR, and then
click Check Names.
If the user is found, it will appear with an underscore in the pane.
• Click OK, and then in the Group or user names pane, click IUSR.
• In the Permissions for IUSR pane, scroll to the Write permission, and in the
Allow column, select the Write check box.
• Click Apply, and then click OK to close the Permissions for logs box.
• Click OK to close the logs Properties box, and then close Windows Explorer.

© Copyright IBM Corp. 2010, 2016 8-53

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 8 Explore component logging

Task 2. Set the logging level to INFO for Perf.QFS logging in

the ipfclientconfig.xml file.
• From the Taskbar, launch Services, and then ensure that the IBM Cognos
DispCM:9320 service is stopped.
• Ensure that the following services are started:
• Apache Directory Server - default
• DB2-DB2COPY1 - DB2
• DB2DAS - DB2DAS00
• World Wide Web Publishing Service
• Start the IBM Cognos Full:9315 service.
• In Windows Explorer, navigate to C:\Program
Files\IBM\cognos\analytics_DispCM\configuration and copy
ipfPERFclientconfig.xml.sample to the same directory.
The DispCM instance is the instance in the server groups that runs the 32-bit
ReportServer service queries. The Full instance is the instance in the server
groups that runs the 64-bit ReportServer service queries, and therefore does not
require this type of tracing.
• Rename ipfPERFclientconfig.xml - Copy.sample to ipfclientconfig.xml, and
then open this ipfclientconfig.xml file in Eclipse.
Ensure that you do not keep PERF in the filename when you rename the file.
If necessary, close any open tabs in the middle pane before opening the
ipfclientconfig.xml file.
• Maximize the ipfclientconfig.xml tab, and then on the Source tab, locate the
following section:
<!--category name="Perf.QFS" class="com.cognos.indications.
LogTypedLogger">
<level value="info"/>
</category-->
Do not use the level value="warn" section.

© Copyright IBM Corp. 2010, 2016 8-54

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 8 Explore component logging

• Replace this section with the following:

<category name="Perf.QFS" class="com.cognos.indications.
LogTypedLogger">
<level value="debug"/>
<appender-ref ref="clientFlatFile"/>
</category>
Hint: You can copy and paste the text from C:\Training\B6019\08-
Explore_Component_Logging\Unit8_Exercise2_Task1.txt.
You have uncommented the section, by removing the !, the --, and have modified
the setting of info to debug, and added an appender-ref setting.
The results appear as follows:

• Save the file, close the ipfclientconfig.xml tab, and then close Eclipse.
Task 3. Create a list report and a crosstab report in IBM
Cognos Analytics - Reporting and then execute the
reports.
If the UI becomes unresponsive, you may need to refresh the browser before
continuing.
• Navigate to C:\Program Files\IBM\cognos\analytics_DispCM\logs, and then
delete the files at the root of this folder.
If prompted, skip any files still in use.
Do not delete the XQE folder if there is one.
• Switch to the Services window, start the IBM Cognos DispCM:9320 service,
and wait for it to fully start before proceeding to the next step.
• Launch Internet Explorer, go to http://vclassbase:88/ibmcognos/bi/, and then
log in as admin/Education1.

© Copyright IBM Corp. 2010, 2016 8-55

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 8 Explore component logging

• Create a new Blank report using the Team content\Legacy_Samples\

Samples\Models\GO Sales (query) package, and then drag a List to the report
area.
• Populate the list object from the Sales (query) namespace with the following
items:
• Products: Product line, Product type
• Sales: Product cost

• Do not run the report at this time, but save the report as perf.qfs_list in the GO
Sales (query) folder.
• Create a new Blank report using the Team content\Legacy_Samples\
Samples\Models\GO Sales (query) package, and then drag a Crosstab to the
report area.
• Populate the list object from the Sales (query) namespace with the following
items:
• Columns: Time: Year
• Rows: Order method: Order method type
• Measures: Sales: Quantity

• Do not run the report at this time, but save the report as perf.qfs_crosstab in the
GO Sales (query) folder.
• On the Application bar, click the down arrow beside perf.qfs_crosstab, and
then beside perf.qfs_list, click Remove.
• Beside perf.qfs_crosstab, click Remove.

© Copyright IBM Corp. 2010, 2016 8-56

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 8 Explore component logging

• Navigate to Team content\Legacy_Samples\Samples\Models\

GO Sales (query), and then click perf.qfs_list to run the report as HTML.
• On the Application bar, click the down arrow beside perf.qfs_list, and then click
Remove.
• Run the same report again, and then on the Application bar, click the down
arrow beside perf.qfs_list, and then click Remove.
• Repeat to run the perf.qfs_crosstab report two times, and then close the
browser window.
What do you notice about the run times after the first execution of the report?
Task 4. Modify the Performance_<datetimestamp>.xml file so
that its contents can be examined in a stylesheet.
• In Windows Explorer, navigate to C:\Program
Files\IBM\cognos\analytics_DispCM\logs to identify the presence of the
Performance_<datetimestamp>.xml file(s).
• Stop the IBM Cognos DispCM:9320 service and the IBM Cognos Full:9315
service, and then open the most recent Performance_<datetimestamp>.xml file
in Eclipse.
At the top of the Performance_<datetimestamp>.xml file you will find some
descriptions of the elements (for example, CF=Component Function), and their
attributes (for example, nc=NumCalls, rN=RunNumber, and so forth).
• Add the following as the second line:
<?xml-stylesheet type="text/xsl" href="C:\Training\B6019\08-
Explore_Component_Logging\perf.xslt"?>
The perf.xslt code has been provided at the end of this exercise.
• Add the following as the last line (if necessary), </PerformanceData>.
• From the File menu, click Save As, navigate to C:\Training\B6019\08-
Explore_Component_Logging.
• In the Save as type list, click *.*, in the File name box, type perf.xml, and then
click Save.

© Copyright IBM Corp. 2010, 2016 8-57

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 8 Explore component logging

• Close the perf.xml tab, and then close Eclipse.

• In Windows Explorer, navigate to C:\Training\B6019\08-Explore_
Component_Logging, and then open perf.xml in Internet Explorer.
The result appears similar to the following, note that you may have to scroll
through the results to see the perf.qfs_list and perf.qfs_crosstab outputs:

The file opens based on the formatting used in the perf.xlst file. This makes the
file easier to read.
The numbers shown in the right column such as Request Summary are in
milliseconds. Numbers in parentheses shown in the left column represent the
number of calls. These values come directly from the original, unformatted
Performance_<datetimestamp>.xml log file. You can refer to
Performance_<datetimestamp>.xml to understand the values being presented.
Near the top of this file is an explanation of the abbreviations for results.

© Copyright IBM Corp. 2010, 2016 8-58

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 8 Explore component logging

• Review the information in the file, and answer the following:

• Compare the components that each report used. Are there any
differences?
• Identify the components that spent the most time processing the request.
• Compare the components used with the
Cognos Analytics 11.0.1 Archtecture_diagram.jpg file located at
C:\Training\B6019\01-Intro_and_SOA.
• Why is there an OlapQueryProvider as a component for the crosstab
report?
• Close Internet Explorer, and then delete perf.xml from C:\Training\B6019\08-
Explore_Component_Logging.
• In Windows Explorer, delete the files at the root of C:\Program
Files\IBM\cognos\analytics_DispCM\logs.
If prompted, skip any files still in use.
• Delete ipfclientconfig.xml from C:\Program
Files\IBM\cognos\analytics_DispCM\configuration.
• Start the IBM Cognos Full:9315 service, and then start the IBM Cognos
DispCM:9320 service.
• Close all open windows.

© Copyright IBM Corp. 2010, 2016 8-59

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 8 Explore component logging

Additional information for exercise: perf.xslt code

<?xml version="1.0" encoding="UTF-8"?>
<!-- Copyright (C) 2007 Cognos Incorporated. All Rights Reserved. Cognos (R) is a trademark of Cognos
Incorporated. -->
<!-- Cognos and the Cognos logo are trademarks of Cognos Incorporated. -->
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<xsl:output method="html" encoding="UTF-8"/>
<xsl:variable name="result" select="/PerformanceData"/>
<!--Match document root-->
<xsl:template match="/">
<html>
<head>
<title>Performance</title>
<meta http-equiv="pragma" content="no-cache"/>
<meta http-equiv="cache" content="0"/>
</head>
<body bgcolor="#ffffff">
<font size="5" face="arial">Performance Information</font>
<!--Match all elements under 'PerformanceData' -->
<xsl:apply-templates select="$result/RP"/>
</body>
</html>
</xsl:template>
<!--Execute this block for every matching File element-->
<xsl:template match="RP">
<table border="1" cellpadding="10">
<!--Output Name attribute from element File-->
<tr>
<td bgcolor="#8EB6F0" colspan="4">
<font size="4" face="arial">
<b>Report: </b>
</font>
<xsl:value-of select="@n"/>
</td>
</tr>
<tr>
<td bgcolor="#E3E9F3">
<font size="2" face="arial">
<b>Execution Start Time</b>
</font>
</td>
<td bgcolor="#E3E9F3">
<xsl:value-of select="@st"/>
</td>
</tr>
<tr>
<td bgcolor="#E3E9F3">
<font size="2" face="arial">
<b>Execution End Time</b>
</font>
</td>
<td bgcolor="#E3E9F3">
<xsl:value-of select="@et"/>
</td>
</tr>
<tr>
<td bgcolor="#E3E9F3">
<font size="2" face="arial">
<b>Status</b>
</font>
</td>
<td bgcolor="#E3E9F3">
<xsl:value-of select="@status"/>
</td>
</tr>
<!--Match all Customer elements under the RS element-->
<xsl:apply-templates select="RS"/>
<xsl:apply-templates select="RQ"/>
</table>
</xsl:template>
<!--Execute this block for every matching RS element-->
<xsl:template match="RS">

© Copyright IBM Corp. 2010, 2016 8-60

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 8 Explore component logging

<tr>
<td bgcolor="#BFD2E2">
<font size="3" face="arial">
<b>Request Summary </b>
</font>
</td>
<td bgcolor="#BFD2E2">
<xsl:value-of select="@et"/>
</td>
</tr>
<xsl:apply-templates select="C"/>
</xsl:template>
<xsl:template match="RQ">
<tr>
<td bgcolor="#BFD2E2">
<font size="3" face="arial">
<b>Request Query: </b>
<xsl:value-of select="@n"/>
</font>
</td>
<td bgcolor="#BFD2E2">
<xsl:value-of select="@et"/>
</td>
</tr>
<xsl:apply-templates select="C"/>
</xsl:template>
<xsl:template match="C">
<tr>
<td bgcolor="#E3E9F3">
<font size="2" face="arial">
<xsl:value-of select="@n"/>
</font>
</td>
<td bgcolor="#E3E9F3">
<!--Highlight name when elapse time exceeds n milliseconds'-->
<xsl:if test="@et > 15000">
<xsl:attribute name="bgcolor">#FF0000</xsl:attribute>
</xsl:if>
<font size="2" face="arial">
<xsl:value-of select="@et"/>
</font>
</td>
</tr>
<xsl:apply-templates select="CF"/>
</xsl:template>
<xsl:template match="CF">
<tr>
<td bgcolor="#E3E9F3">
<font size="2" face="arial">
&#160;&#160;&#160;&#160;
<xsl:value-of select="@n"/>
( <xsl:value-of select="@nc"/> )
</font>
</td>
<td bgcolor="#E3E9F3">
<!--Highlight name when elapse time exceeds n milliseconds'-->
<xsl:if test="@et > 15000">
<xsl:attribute name="bgcolor">#FF0000</xsl:attribute>
</xsl:if>
<font size="2" face="arial">
<xsl:value-of select="@et"/>
</font>
</td>
</tr>
</xsl:template>
</xsl:stylesheet>

© Copyright IBM Corp. 2010, 2016 8-61

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 8 Explore component logging

Unit summary
• Explore component logging for Gateway, Dispatcher, Report Server,
and Universal Data Access layer

Explore component logging © Copyright IBM Corporation 2016

Unit summary

© Copyright IBM Corp. 2010, 2016 8-62

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
Examine additional tools and special task logging

Examine additional tools and

special task logging

IBM Cognos Analytics 11.0

© Copyright IBM Corporation 2016

Course materials may not be reproduced in whole or in part without the written permission of IBM.
 Unit 9 Examine additional tools and special task logging

© Copyright IBM Corp. 2010, 2016 9-2

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 9 Examine additional tools and special task logging

Unit objectives
• Explore diagnostic tools and utilities for special task logging

Examine additional tools and special task logging © Copyright IBM Corporation 2016

Unit objectives
Note: In this unit, ..\ references point to the install location of IBM Cognos Analytics.
For example: ..\bin can be found at C:\Program Files\ibm\cognos\analytics_full,
the install path of the IBM Cognos Analytics server product.

© Copyright IBM Corp. 2010, 2016 9-3

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 9 Examine additional tools and special task logging

IBM Cognos Analytics Content Manager Browser Tool

• Diagnostic name: IBMCognosBI_CMBrowser
• Diagnostic description: reports detailed information of objects
• Download from the IBM Support Portal:
 http://www-01.ibm.com/support/docview.wss?uid=swg24021211

Examine additional tools and special task logging © Copyright IBM Corporation 2016

IBM Cognos Analytics Content Manager Browser Tool

The IBM Cognos Analytics Content Manager Browser Tool (CMBrowser) is a graphical
user interface that displays detailed information for all objects in the Content Store.
For each object within the Content Store database, which is managed through Content
Manager, the user can review the properties and their respective value settings. You
can use this to verify that what you think should be in the database is in fact, in the
database.
Note: For the Windows-based tools presented in this unit, you could use a Windows
shell or emulator in a non-Windows environment.

© Copyright IBM Corp. 2010, 2016 9-4

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 9 Examine additional tools and special task logging

IBM Cognos Analytics Content Manager Size Tool

• Diagnostic name: IBMCognosBI_CMSize
• Diagnostic description:
 Reports size and count of objects in Content Store
 Returns the search path of the objects
• Download from the IBM Support Portal:
 http://www-01.ibm.com/support/docview.wss?uid=swg24021252

Examine additional tools and special task logging © Copyright IBM Corporation 2016

IBM Cognos Analytics Content Manager Size Tool

The IBM Cognos Analytics Content Manager Size Tool (CMSize) is a Windows-based
utility that reports the size and count of all objects in the Content Store database.
Within the specified search scope and type of objects, it returns the count, approximate
size, and search path of the objects. This can be useful to find Content Store objects
that can take up a lot of space, such as report outputs and report versions.

© Copyright IBM Corp. 2010, 2016 9-5

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 9 Examine additional tools and special task logging

IBM Cognos Framework Manager Tool

• Diagnostic name: IBMCognosBI_FrameMgr
• Diagnostic description: retrieves system and product information about
Framework Manager
• Download from the IBM Support Portal:
 https://www-304.ibm.com/support/docview.wss?uid=swg24020971

Examine additional tools and special task logging © Copyright IBM Corporation 2016

IBM Cognos Framework Manager Tool

The Framework Manager Windows-based diagnostic tool will retrieve system and
product information about Framework Manager, and will highlight potential issues with
Framework Manager models, such as ambiguous joins, list of facts, multiple valid joins,
and recursive joins. These are common modeling traps that the modeler might want to
consider resolving.

© Copyright IBM Corp. 2010, 2016 9-6

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 9 Examine additional tools and special task logging

IBM Cognos Analytics Content Store Information Tool

• Diagnostic name: IBMCognosBI_ContentStore
• Diagnostic description: use to retrieve Content Store database
information
• Download from the IBM Support Portal:
 https://www-304.ibm.com/support/docview.wss?rs=0&uid=swg24020678

Examine additional tools and special task logging © Copyright IBM Corporation 2016

IBM Cognos Analytics Content Store Information Tool

This diagnostic is executed when you are troubleshooting problems with getting
Content Store tables created in IBM Cognos Analytics. It will retrieve Content Store
database information, database connection URL, driver name and version, and
database name and version.
The output results are displayed in 2 forms:
• a text file named IBMCognosBI_ContentStore_<date>_<time>.txt
• an XML file named IBMCognosBI_ContentStore_<date>_<time>.xml

© Copyright IBM Corp. 2010, 2016 9-7

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 9 Examine additional tools and special task logging

System Overview Diagnostic Tool

• Diagnostic name: IBM_SystemOverview
• Diagnostic description: gathers environment and system information
• Download from the IBM Support Portal:
 https://www-304.ibm.com/support/docview.wss?rs=0&uid=swg24020682

Examine additional tools and special task logging © Copyright IBM Corporation 2016

System Overview Diagnostic Tool

The graphical user interface (GUI) IBM_SystemOverview allows the user to select the
categories to report on.
Using this tool allows you to:
• compare your system values from two different environments
• quickly gather system information
• check information about local drives

© Copyright IBM Corp. 2010, 2016 9-8

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 9 Examine additional tools and special task logging

It is recommended to run the utility from the .bat file, which enables you to see the
progress in the command window. You can also double-click the .jar file, which runs in
the background without displaying progress, but will display the result window when the
diagnostic process has completed.
The following list provides a summary of the information collected: local drives and
system information, Microsoft network adapter configuration, Computer name,
Operating system version, user and system environment, Java information, Microsoft
Internet Explorer properties and security settings, Microsoft Internet Explorer trusted
sites, Processes, Microsoft Data Access (MDAC) version, network status/statistics,
Microsoft .NET Framework, Add/Remove Programs, Microsoft Windows hot fixes,
ODBC versions.
This diagnostic runs the reg.exe utility; if it is not installed, the diagnostic will not run.

© Copyright IBM Corp. 2010, 2016 9-9

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 9 Examine additional tools and special task logging

Demonstration 1
Explore diagnostic tools

Examine additional tools and special task logging © Copyright IBM Corporation 2016

Demonstration 1: Explore diagnostic tools

© Copyright IBM Corp. 2010, 2016 9-10

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 9 Examine additional tools and special task logging

Demonstration 1:
Explore diagnostic tools
At the beginning of this demonstration, the IBM Cognos Full:9315 dispatcher and the
IBM Cognos DispCM:9320 dispatcher are running.
Purpose:
You are the administrator and want to use diagnostic tools to gather
information about your IBM Cognos Analytics environment.

Task 1. Configure the system path variable for Java home

and bin directories.
Prior to running a diagnostic, the PATH system variable should include the
Java\bin path.
1. From the Start menu, right-click Computer, and then click Properties.
2. In the left pane, click Advanced system settings, click the Advanced tab, and
then click Environment Variables.
3. Scroll through the System variables list, click the Path variable, and then click
Edit.
4. At the end of the current path, type a semi-colon, and then type the Java\bin
path.
In this case, you will be referencing the folder that was included with the full
install of IBM Cognos Analytics.
You have added the following items to your PATH system variable:
;C:\Program Files\IBM\cognos\analytics_full\bin64\jre\bin
5. Click OK to close the following dialog boxes: Edit System Variable, Environment
Variables, System Properties.
6. Close the Control Panel Home dialog box.
Task 2. Use the IBM Cognos Analytics Content Manager
Browser tool to report detailed information of objects.
For each object within the Content Store database, the IBM Cognos Analytics
Content Manager Browser tool will allow the user to review the object properties
and their respective values.
1. In Windows Explorer, navigate to C:\Training\B6019\diagnostictools, open
the IBMCognosBI_CMBrowser_64 folder, and then double-click
IBMCognosBI_CMBrowser.exe.
If prompted, log on as admin/Education1.
2. If you receive a security warning, click Run to run the software.

© Copyright IBM Corp. 2010, 2016 9-11

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 9 Examine additional tools and special task logging

3. If you receive a message indicating that the Content Manager could not be
reached, click OK to dismiss it.

4. On the toolbar, click Test Content Manager Connection .

5. If necessary, modify the URL to http://vclassbase:9315/p2pd/servlet.
6. Click Save, and then click Test.
The results display the Content Manager build, the time it was started, current
time, and the state, which is currently running.

7. Click OK to close the Test Content Manager Connection dialog box.

8. On the toolbar, click Log on to Content Manager , populate the fields with
the following information, and then click Login:
• Content Manager URL: http://vclassbase:9315/p2pd/servlet
• Namespace: LDAP_Dev_ID
• User name: admin
• Password: Education1

© Copyright IBM Corp. 2010, 2016 9-12

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 9 Examine additional tools and special task logging

9. On the toolbar at the top right, click Refresh the complete browse tree , to
see the objects appear in the tree.
The top level objects in Content Manager are displayed in the left pane of the
CMBrowser tab.

You can expand each item to view its child objects.

10. From the Window menu, click Preferences.
Here you can configure your environment settings for Content Manager URL
that will be used by CMBrowser. Your environment could have more than one
Content Manager. Do not change the Soap Action and BI Bus Namespace
fields.
11. Click Cancel to close the Preferences dialog box.
In the CMBrowser toolbar, you can toggle between retrieving a small set of
properties and all properties, refresh the browse tree, search for objects, and
access Help.

12. Click Search Tool , and then in the Select scope section, click Portal.
13. In the Enter search string(* retrieves all objects) box, type *, click Search,
and then click Yes to close the message about all objects being returned.
The results include pages, pagelets, portlets, and other portal objects. This will
help you determine a count of portlet objects in your environment. You can use
this tool to count and list other object types also.
If the search returns no results, check that you have no spaces in the search
string.
14. Scroll through the results to review them, and then click Exit to close the
Search Tool window. and then
15. In the IBM Cognos Analytics Content Manager Browser Tool window, from
the File menu, click Exit.

© Copyright IBM Corp. 2010, 2016 9-13

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 9 Examine additional tools and special task logging

Task 3. Use the IBM Cognos Framework Manager tool to

retrieve information about models.
This diagnostic tool will retrieve system and product information about
Framework Manager, and will highlight potential issues with Framework
Manager models, such as ambiguous joins, list of facts, multiple valid joins, and
recursive joins.
1. In Windows Explorer, navigate to the directory with the diagnostic tools, open
the IBMCognosBI_FrameMgr folder, and then double-click
execute_IBMCognosBI_FrameMgr.bat.
Ensure that the Java bin path was added to the PATH system variable in
Task 2.
The first time the diagnostic is executed a file called properties is created. This
file holds a true or false value for a list of variables that can be chosen from the
check boxes. You can open the file and modify the values as needed, or from
this dialog box, click Current Settings Saved if you make changes to the default
settings.
The IBM Cognos BI Framework Manager Information Request dialog box is
displayed.
2. In the Diagnostic Categories section, click Unselect All, and then select the
Content Store Info and the Ambiguous Join Info check boxes.
3. In the IBM Cognos BI Install Path section, click Browse, navigate to
C:\Program Files\IBM\cognos\analytics_full, and then click Open.
4. In the Content Store Connection section, enter the admin/Education1
credentials.
5. In the Model Filepath section, browse to where the dynamic query sample
models were installed, C:\Program
Files (x86)\IBM\cognos\c10\webcontent\samples\models\
great_outdoors_sales, click model.xml, and then click Open.
6. Click OK to run the diagnostic.
The DIAGNOSTICS RESULTS TREE window is displayed in the background,
and in the active dialog box in the foreground you are prompted to select the
results tree, results file, log file, or go to the results directory. Notice that the
results file location is displayed in the message along with the filename.
7. If necessary, click View Results Tree.
8. In the tree, click Ambiguous Joins, and use the PgUp and PgDn keyboard
buttons to scroll through the results, resizing the window if necessary.

© Copyright IBM Corp. 2010, 2016 9-14

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 9 Examine additional tools and special task logging

9. Click the DIAGNOSTIC TOOLS dialog box to view an alternate option, and
when you have finished your review, close any windows opened by the tool,
and then in the DIAGNOSTIC TOOLS dialog box, click Exit.
Task 4. Use the IBM Cognos Analytics Content Store
Information tool to retrieve information about the
Content Store database.
This diagnostic tool is executed when you are troubleshooting problems with
getting Content Store tables created in IBM Cognos Analytics. It will retrieve
Content Store database information, database connection URL, driver name
and version, and database name and version.
1. In Windows Explorer, navigate to the directory with the diagnostic tools, open
the IBMCognosBI_ContentStore folder, and then double-click
execute_IBMCognosBI_ContentStore.bat.
2. In the IBM Cognos Analytics Information Request dialog box, click Browse,
navigate to C:\Program Files\IBM\cognos\analytics_full, and then click
Open.
3. Login as admin/Education1, and then click OK.
In the DIAGNOSTIC TOOLS dialog box, you have the options to view the text
results, XML results, or log file, or go to the results directory.
4. Click View TEXT Results File, scroll through the results, and then close the
window.
5. Click Go To Results Directory.
Windows Explorer is directed to the path of the output result files. The output
results are displayed in 2 forms:
• a text file called IBMCognosBI_ContentStore_<date>_<time>.txt
• an XML file called IBMCognosBI_ContentStore_<date>_<time>.xml
The log file is also saved at this location.
6. Double-click the IBMCognosBI_ContentStore_<date>_<time>.txt file, review
the results, and then close the file.
7. Close the results directory window, and then click Exit to close the
DIAGNOSTIC TOOLS dialog box.

© Copyright IBM Corp. 2010, 2016 9-15

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 9 Examine additional tools and special task logging

Task 5. Use the System Overview diagnostic tool to gather

environment and system information.
The graphical user interface (GUI) IBM_SystemOverview allows the user to
select the categories to report on.
1. In Windows Explorer, navigate to the directory with the diagnostic tools, open
the IBM_SystemOverview folder, and then double-click
execute_IBM_SystemOverview.bat.
The IBM System Overview Information Request dialog box allows you to
customize multiple categories on which to report.

© Copyright IBM Corp. 2010, 2016 9-16

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 9 Examine additional tools and special task logging

2. Click OK to run the diagnostic with the default options.

When the execution is complete (it will take a few moments), the IBM SYSTEM
OVERVIEW DIAGNOSTIC Results window is displayed, with a tab for each of
the categories selected at the execution.
3. Click each tab, to see the information results.
In the DIAGNOSTIC TOOLS dialog box, notice that you can select a tabbed
view, and that you can also view the text results and XML results, or you can go
to the results directory.
4. Click Exit to close the diagnostic tool.
Results:
As the administrator, you used diagnostic tools to gather information about
your IBM Cognos Analytics environment.

© Copyright IBM Corp. 2010, 2016 9-17

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 9 Examine additional tools and special task logging

IBM Cognos Log Viewer utility

• Utility name: logviewV2
• Utility description: allows filtering of a log file
• Location of utility: ..\bin and ..\bin64

Examine additional tools and special task logging © Copyright IBM Corporation 2016

IBM Cognos Log Viewer utility

This utility presents a formatted view of log files that you may find easier to read
compared to looking at log files in a text editor. You can use this utility to review IPF log
files.
With IBM Cognos Log Viewer, you can filter the log file to reduce the amount of data
being viewed, and focus on specific messages.

© Copyright IBM Corp. 2010, 2016 9-18

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 9 Examine additional tools and special task logging

Describe cm_tester
• Utility name: cm_tester.htm
• Utility description: manipulate Content Manager objects with SOAP
requests
• Location of utility: ..\webapps\p2pd

Examine additional tools and special task logging © Copyright IBM Corporation 2016

Describe cm_tester
CMTools requires Java, whereas cm_tester.htm uses a lot of JavaScript and runs
within a browser, such as Internet Explorer or Firefox.

© Copyright IBM Corp. 2010, 2016 9-19

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 9 Examine additional tools and special task logging

CMTools utility
• Utility name: CMTools
• Utility description: provides advanced cm monitoring and update
capabilities
• Location of utility: ..\bin64\utilities\cm\CMTools

Examine additional tools and special task logging © Copyright IBM Corporation 2016

CMTools utility
This utility provides advanced Content Manager monitoring and update capabilities.
The CMTools utility includes the functionality of CMBrowser, CMSize, and
cm_tester.htm (CMTester).

© Copyright IBM Corp. 2010, 2016 9-20

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 9 Examine additional tools and special task logging

Demonstration 2
Explore the IBM Cognos Log Viewer and CMTools utilities

Examine additional tools and special task logging © Copyright IBM Corporation 2016

Demonstration 2: Explore the IBM Cognos Log Viewer and CMTools utilities

© Copyright IBM Corp. 2010, 2016 9-21

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 9 Examine additional tools and special task logging

Demonstration 2:
Explore the IBM Cognos Log Viewer and CMTools utilities
At the beginning of this demonstration, the IBM Cognos Full:9315 dispatcher and the
IBM Cognos DispCM:9320 dispatcher are running.
Purpose:
Log files can be difficult to read, due to the amount of information and limited
formatting if viewing with a text viewer. You will use IBM Cognos Log Viewer
to filter the logs, and then launch CMTools to explore some of the
functionality available for advanced Content Manager monitoring.

Task 1. Use logviewV2.exe to filter log files for easier reading.

1. In Windows Explorer, navigate to C:\Program
Files\IBM\cognos\analytics_full\bin, and then double-click logviewV2.exe.
The IBM Cognos Log Viewer launches, and displays a tab that lets you drag
and drop IPF log files onto it.
2. In IBM Cognos Log Viewer, from the File menu, click Load Cognos Log
File(s).
This is an easy way to quickly navigate to where the Cognos log files are stored.
Also available from the File menu, you can load files with filters that you have
already created.
3. Click cogserver.log, and then click Open.
If prompted with a warning about messages other than audit messages being
dropped, click OK.
4. Click the cogserver.log tab, and then maximize the window.
Notice that the information is presented in columns, with a reference ID for each
row.

There are summary buttons on the toolbar that you can use.

5. Click Summarize errors .

If there are errors, they are listed with counts of each, and information is
displayed about the last occurrence and the message text that was displayed.
You can generate a filter from each of the summary views provided, by clicking
the Generate Filter button. If there were no errors, the summary will display a
blank window.
6. Click OK to close the Error Summary dialog box, and then click Summarize

messages .

© Copyright IBM Corp. 2010, 2016 9-22

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 9 Examine additional tools and special task logging

7. Review the information, click OK to close the dialog box, and then scroll through
the log file.
Rows may be highlighted in yellow or highlighted in dark red. This is a quick
visual identifier, which is not usually available when looking at log files in a text
editor. The color highlights are based on Rulesets that have been configured.
To change the colors, right-click in the rows area, and then select LogPanel
Color Filter. You can easily customize the foreground and background colors of
specific rules.
There are many lines of information in this log file, so you want to apply a filter,
to focus on items requiring attention.
8. In the Refine focus on box, type STATUS == 'Warning'. You do not need to
press Enter.
Syntax is important in this field as you type a value. If there are no Warning
entries, you may want to filter on a different status, such as 'Info'.
The items are filtered to match this status of Warning, letting you focus on much
less data.
9. Right-click anywhere in the Status column body, and then click Clear 'refine
focus' field to display all results.
10. Scroll to a row with Info listed in the Status column, in the Status column, right-
click the Info status, and then click Set 'refine focus' field.
If there are no Info entries, you may want to filter on a different status. This is
another way to populate the Refine focus on field, without typing the syntax, to
filter your results. Using the methods presented here, you can efficiently focus
on specific items to assist when troubleshooting.
If there were no Info messages in your log, use a different status row for the
next step.
11. Click a row displayed with the Info status to select it, and then expand the lower
pane as needed for a different presentation of the information.
The last line lists other information that can be helpful to you, in a more readable
format than the tabular view.
12. Close IBM Cognos Log Viewer.
Task 2. Use CMTools for advanced Content Manager
monitoring.
1. In Windows Explorer, navigate to C:\Program
Files\IBM\cognos\analytics_full\bin\utilities\cm\CMTools, and then double-
click CMTools.exe.
2. Click OK to close the Problem Occurred dialog box.
3. On the toolbar, click Test CM Connection.

© Copyright IBM Corp. 2010, 2016 9-23

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 9 Examine additional tools and special task logging

4. In the CM URL box, ensure that http://vclassbase:9315/p2pd/servlet is

displayed, click Test, and then click OK.
5. In the Logon dialog box, login as admin/Education1, and then click OK.
Within this utility, you can access other CM tools.
6. From the Window menu, click Show View, and then click Content Tree if this
view is not already visible.

7. On the Content Tree toolbar, click Rebuilds the entire browse tree to
refresh the display.
8. From the Window menu, click Show View, and then click Other.
9. In the Cognos folder, click CMSize, and then click OK.
A new tab appears in the CMTools window. The functionality of the CMSize
tool, that you reviewed earlier in this unit, is available through CMTools.
10. On the CMSize tab, change Scope to Other, and then replace /content/* with
the following:
/content/folder[@name='Samples_DQ']/folder[@name='Models']/*
11. In the Max Objects box, type 10.
12. Change Classes from output to model, and then click Send.
You may need to resize the window to see all options on the CMSize tab, such
as the Send button.
13. Click Yes to the message about executing an intensive query.
A section of the result appears similar to the following:

© Copyright IBM Corp. 2010, 2016 9-24

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 9 Examine additional tools and special task logging

The count and size of the models found in the Samples_DQ folder in the
Models subfolder of the Content Store are displayed. Notice that the Count
column is empty at the folder level.
14. In the list of results, expand GO Sales (query), and observe the size of the
model.
Notice that you can export the findings to a .CSV or .XML file (Export button on
the toolbar), which would be helpful to compare to later results, if you monitor
the changes in the size of your Content Store over time.
15. Change Classes from model to specs, and then in the Max Objects box,
type 10 (if necessary).
16. Click Send, click Yes to the intensive query message, and review the children
of GO Sales (query).
You have changed the class of objects that you want to review. Instead of one
model, there is information displayed regarding reports, queries, report version,
and analysis.
You will now explore the Content Tree in CMTools.
17. From the Window menu, click Show View, and then click Content Tree (if
necessary).
18. In the Content Tree pane, expand Configuration.
Notice the two dispatchers in the environment are displayed.
19. Expand http://vclassbase:9315/p2pd to review the children, and then double-
click any item to display its properties.
The results appear similar to the following:

20. Explore the Help file for more detail on each of the options and the tool itself.
21. When you have finished reviewing the tool, from the File menu, click Exit.
Results:
Using IBM Cognos Log Viewer, you were able to use formatting and filters to
focus on information and warnings that can be helpful when troubleshooting
issues. You then launched CMTools, and explored some of the functionality
available in the utility, for advanced Content Manager monitoring.

© Copyright IBM Corp. 2010, 2016 9-25

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 9 Examine additional tools and special task logging

Drill Through Assistant (1 of 2)

• Purpose:
 Debug drill through definitions
• Description:
 Displays values selected by the user for passing to the target report
 Displays the parameter names mapped in the
drill-through definition

Examine additional tools and special task logging © Copyright IBM Corporation 2016

Drill Through Assistant

Use the Drill Through Assistant to debug functionality for drill through definitions. The
values selected by the user when invoking the drill-through action will be displayed, for
you to review as what is available for passing to the target report. This utility also
displays the name of the parameter that was mapped in the drill-through definition, and
the values that the source is attempting to pass to that parameter.
This feature is available by default to System Administrators. To activate the Drill
Through Assistant for other users, in IBM Cognos Administration, on the Security tab, in
the Capabilities section, add users to the member list for Drill Through Assistant.

© Copyright IBM Corp. 2010, 2016 9-26

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 9 Examine additional tools and special task logging

Drill Through Assistant (2 of 2)

Examine additional tools and special task logging © Copyright IBM Corporation 2016

When the Drill Through Assistant capability is enabled, the Go to window will have
additional options available to the user. This information can assist you when
troubleshooting drill through issues.
For more information about the Drill Through Assistant see the Administration and
Security guide.
This topic is also covered in the IBM Cognos Analytics Administration (v11.0) course,
which is a prerequisite to this course.

© Copyright IBM Corp. 2010, 2016 9-27

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 9 Examine additional tools and special task logging

Use diagnostic URL commands

• Get Dispatcher version
• Determine if Content Manager is running
• Determine if a Dispatcher is alive
• View installed components
• Memory utilization
• Environment
• Get load balancing statistics
• Pin requests for load balanced services to a specific Dispatcher
• Determine if the Certificate Server is responding
• XML parser information

Examine additional tools and special task logging © Copyright IBM Corporation 2016

Use diagnostic URL commands

There are a variety of URL diagnostic commands available, to assist you when
troubleshooting issues. Refer to the product for others than those listed here.
Refer to the Exercise titled Examine URLs Available for Troubleshooting for specific
examples of available commands.

© Copyright IBM Corp. 2010, 2016 9-28

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 9 Examine additional tools and special task logging

Analyze logs with I.C.E.T.E.A.

• I.C.E.T.E.A.: IBM Cognos Exploration Tool for Event Analysis
• Logs (individual files or entire directories) are loaded into an in-memory
database.
• Logs can be associated to specific "cases" and have several pre-
canned queries (hourly activity, hourly errors, process lifecycles, and
so forth).
• Logs can be filtered on-demand and have full drill-through capability
into underlying errors which then allow for further filtering.

Examine additional tools and special task logging © Copyright IBM Corporation 2016

Analyze logs with I.C.E.T.E.A

I.C.E.T.E.A. (IBM Cognos Exploration Tool for Event Analysis) is a log analysis tool
which allows for interactive examination, filtering, and correlation of log entries from
single or multiple log files which are imported and indexed into a database.
I.C.E.T.E.A. is similar to the logviewV2.exe tool, but is considerably more powerful. It is
not installed with IBM Cognos Analytics. You can download it from IBM
developerWorks at the following link:
https://www.ibm.com/developerworks/community/groups/service/html/
communityview?communityUuid=0ad1d51b-4366-4735-a999-3522a4cba6cd.

© Copyright IBM Corp. 2010, 2016 9-29

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 9 Examine additional tools and special task logging

Demonstration 3
Analyze logs with I.C.E.T.E.A.

Examine additional tools and special task logging © Copyright IBM Corporation 2016

Demonstration 3: Analyze logs with I.C.E.T.E.A.

© Copyright IBM Corp. 2010, 2016 9-30

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 9 Examine additional tools and special task logging

Demonstration 3:
Analyze logs with I.C.E.T.E.A.

Purpose:
To get a better understanding of what is going on in your environment, you
will use the I.C.E.T.E.A. utility to analyze the logs that have been generated.
You will first launch I.C.E.T.E.A. and import the logs. You will then drill
through on error messages to see more detail. Next you will filter on errors
using query filters. Lastly you will examine the pre-made queries that come
with the tool.

Task 1. Launch I.C.E.T.E.A. and import logs.

1. In the C:\Training\B6019\diagnostictools folder, double-click the ICETEA
subfolder, and then double-click icetea.exe.
2. Click Run if you get a security warning.
3. If necessary, accept the license agreement, and then close the Welcome tab.
4. On the toolbar of the Case Navigator pane in the top left corner, click Import
Logs .
5. In the Validating database connectivity dialog box, click Details to see the
progress of connecting, and wait for the Import Data Files dialog box to
display.
6. In the Selected Files area, click Add Directories, navigate to C:\Program
Files\IBM\cognos\analytics_DispCM\logs, and then click OK.
7. Clear the Constrain Logs To A Certain Time Window check box.

© Copyright IBM Corp. 2010, 2016 9-31

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 9 Examine additional tools and special task logging

8. Ensure all checkboxes are selected under Parse These Types of Logs.
A section of the result appears similar to the following:

9. Click Next, and then on the Filter Log Entry Columns page, click Next.
10. Type additional notes about the case (if you want), and then click Finish.
The log parsing window displays (this may take a few moments).
11. In the Additional Information Required window, click OK.
This message appears due to missing timing information in some log files.
12. In the Case Navigator pane in the top left corner, expand the date object, and
then double-click the logs directory which was imported.
The Case Summary pane on the right side is populated with information about
the case.
Task 2. Drill through on error messages.
1. In the Error Summary Count section, right-click an error message, and then
click Drill Through On <error>.
Notice that to the right side of the vertical scroll bar there are thin blue horizontal
marks . These represent the occurrences of the errors in the logs.
2. Click a blue mark to jump to that point of the log file (you may need to scroll
slightly up or down to get to the error row which will be highlighted in blue).

© Copyright IBM Corp. 2010, 2016 9-32

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 9 Examine additional tools and special task logging

Task 3. Filter errors using query filters.

1. Expand Query Filters at the top of the workspace tab.
2. Expand the Error Code list, and then select CAF_WRN-0010.
3. Click Execute This Tab.
The result set is now filtered down to only rows containing the selected error
code.
In the COMPONENT column, notice the value for the error message logged is
caf.
4. Expand Query Filters at the top of the workspace tab.
5. In the Error Code list, click the top blank entry to clear it, in the Component list,
click caf, and then click Execute This Tab.
The results appear similar to the following:

The result set is now filtered down to only rows containing the selected
component. This may be quite a large result set.
6. Close the workspace tab.

© Copyright IBM Corp. 2010, 2016 9-33

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 9 Examine additional tools and special task logging

Task 4. Explore the pre-made queries.

1. In the Queries pane on the bottom left side, expand Case Summary\System
Runtime Information\Error Pattern.
2. Right-click Hourly Error Pattern, and then click Run Query.
A message may appear with requirements to turn on basic level logging of the
study component and ensure that there are cogserver.log or pogo logs.
When these requirements are met, the result set will display the frequency with
which errors occurred on an hour-by-hour basis. This result set can be filtered
using the same steps outlined in Task 3. The results appear similar to the
following:

Additional queries can be created and saved within this section of I.C.E.T.E.A.
by right-clicking a folder and selecting New Query.
3. Close all open windows.
Results:
To get a better understanding of what is going on in your environment, you
used the I.C.E.T.E.A. utility to analyze the logs that have been generated. You
first launched I.C.E.T.E.A. and imported the logs. You then drilled through on
error messages to see more detail. Next you filtered on errors using query
filters. Lastly you examined the pre-made queries that come with the tool.

© Copyright IBM Corp. 2010, 2016 9-34

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 9 Examine additional tools and special task logging

Unit summary
• Explore diagnostic tools and utilities for special task logging

Examine additional tools and special task logging © Copyright IBM Corporation 2016

Unit summary

© Copyright IBM Corp. 2010, 2016 9-35

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 9 Examine additional tools and special task logging

Exercise 1
Examine URLs available for troubleshooting

Examine additional tools and special task logging © Copyright IBM Corporation 2016

Exercise 1: Examine URLs available for troubleshooting

© Copyright IBM Corp. 2010, 2016 9-36

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 9 Examine additional tools and special task logging

Exercise 1:
Examine URLs available for troubleshooting

As the administrator, you want to use URL commands to assist in troubleshooting your
company's IBM Cognos Analytics environment. You will review some URL commands,
to become familiar with the tools available. Before beginning this exercise, ensure that
both Dispatchers are running.
Within a browser window, explore the following commands and review their purpose: If
you are prompted to log in, use admin/Education1 credentials.
• Get Dispatcher version: http://vclassbase:9315/p2pd/servlet/gc
• Get Dispatcher version: http://vclassbase:9320/p2pd/servlet/gc
• Determine if Content Manager is running:
http://vclassbase:9315/p2pd/servlet
• Determine if Dispatcher ("pogo") is alive:
http://vclassbase:9315/p2pd/servlet/dispatch?b_action=/dbg
• Memory utilization:
http://vclassbase:9315/p2pd/servlet/dispatch?b_action=/diagnostics
• Get load balancing statistics. Can also use this to verify the configuration of an
install:
http://vclassbase:9315/p2pd/servlet/dispatch/p2plbDiag
• Pin requests for load balanced services to a specific Dispatcher (need to be
logged in first):
http://vclassbase:9315/p2pd/servlet/dispatch/pin
You could use this to force select services to one dispatcher, to free up
resources for another.
• See if the Certificate Server is responding:
http://vclassbase:9315/p2pd/servlet/dispatch/autoCAService
• XML Parser Information:
http://vclassbase:9315/p2pd/servlet/dispatch/xts.diag
For more information about where to work and the exercise results, refer to the Tasks
and Results section that follows. If you need more information to complete a task, refer
to earlier demonstrations for detailed steps.

© Copyright IBM Corp. 2010, 2016 9-37

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 9 Examine additional tools and special task logging

Exercise 1:
Tasks and Results
At the beginning of this exercise, the IBM Cognos Full:9315 dispatcher and the IBM
Cognos DispCM:9320 dispatcher are running.
Task 1. Explore Useful URL commands.
• Launch Internet Explorer.
• Launch Windows Explorer, navigate to C:\Training\B6019\09-Examine_
Additional_Tools_and_Special_Task_Logging, and then open
UsefulURLS.txt in Notepad.
• From the UsefulURLS.txt file, copy the first URL command, to get the Dispatcher
version, http://vclassbase:9315/p2pd/servlet/gc, switch to Internet Explorer,
paste the URL command in the Address box, and then press Enter.
The version of the dispatcher is displayed, and the state is ready. There is
another instance of a dispatcher in your environment. You can easily redirect the
URL command to the second dispatcher.

• In the Address box of Internet Explorer, change 9315 to 9320 and then press
Enter.
• Repeat for the next URL command http://vclassbase:9315/p2pd/servlet.

© Copyright IBM Corp. 2010, 2016 9-38

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 9 Examine additional tools and special task logging

• For each of the remaining URL commands in the text file, repeat to view the
results. If you are prompted to log in, log in with admin/Education1 credentials.
Some of the results appear as follows:
• http://vclassbase:9315/p2pd/servlet/dispatch?b_action=/diagnostics

• http://vclassbase:9315/p2pd/servlet/dispatch/p2plbDiag

• http://vclassbase:9315/p2pd/servlet/dispatch/xts.diag

© Copyright IBM Corp. 2010, 2016 9-39

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Unit 9 Examine additional tools and special task logging

If you encounter Firewall Security Rejection for any of the URLs, it may be due to
the current environment setup. One possible solution is within IBM Cognos
Configuration, set all of the URI settings to fully qualified URI's; an example of
Gateway URI: http://machine-name.domain-name.com:88/ibmcognos/cgi-
bin/cognos.cgi. The classroom environment is not on a domain, but you are
encouraged to try this in your environment if you are on a domain and encounter
this issue.
Question: For the Content Manager URL, do you see any differences between
the states of each?
Answer: One is Running, the other is Running as standby.

© Copyright IBM Corp. 2010, 2016 9-40

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 IBM Training

© Copyright IBM Corporation 2016. All Rights Reserved.