IBM Cognos Proven Practices: IBM Cognos Express 9.5 Troubleshooting

Nature of Document: Troubleshooting; Product(s): IBM Cognos Express 9.5; Area of Interest: Infrastructure

Introduction

Purpose

This document is aimed to provide understanding on what IBM Cognos Express is, how it works and where to find troubleshooting information.

Applicability

This document applies to the IBM Cognos Express 9.5 release. All references to IBM Cognos Express in this document refer to this release only.


What is IBM Cognos Express

IBM Cognos Express is the BI/PM solution targeted towards mid-market businesses that allows the business end-user to report, plan and analyse in a self-service manner. The suite is easy to install/use and requires minimal IT support.

The main philosophy behind IBM Cognos Express is simplicity, make it easy for the end-user to install and enable them to start analysing immediately. This has been accomplished by providing all necessary software modules in one simple package and by accelerating the installation and configuration process.

IBM Cognos Express is modularly built to enable the business to start anywhere and to add to their infrastructure as they grow. IBM Cognos Express includes the following modules:

  • Express Manager
    A very simple and easy interface for both installing and configuring the IBM Cognos Express products.
  • Express Xcelerator
    Built upon IBM Cognos TM1 technology to bring planning and Excel-based analysis capabilities to the end-user.
  • Express Reporter
    Comprised of IBM Cognos Framework Manager, Report Studio and Query Studio to provide self-service reporting and ad hoc query capabilities.
  • Express Advisor
    Built upon IBM Cognos Executive Viewer to provide intuitive modelling and real-time analytical capabilities.
  • Express Planner
    Based upon IBM Cognos TM1 Contributor which provides centralized planning and allows users to make template-driven plan contributions on a continuous basis.

IBM Cognos Express Architecture

IBM Cognos Express is logically divided into 3 tiers as shown in the diagram below. On the left side we have the client components that make up the Presentation Tier, all applications that can be installed on or run from the end user's machine and communicate with the IBM Cognos Express server components that make up the Application Tier in the middle section of the diagram. Finally, on the right side of the diagram we have the Data Tier where the business data and IBM Cognos content repositories reside.

The modular composition of IBM Cognos Express is demonstrated in the following image and table by assigning each installable module its own colour.

Table 1: IBM Cognos Express product module per colour
ModuleColour
Express CoreBlue
Express XceleratorGreen
Express AdvisorBrown
Express ReporterRed
Express PlannerGray
Figure 1: High-level map of IBM Cognos Express modules
Figure 1: High-level map of IBM Cognos Express modules

In both the table and image above, each installable IBM Cognos Express product module and the high level overview of which components the product module makes available is represented by a colour.

The first module that needs to be mentioned in the Application Tier is the Express Core module as depicted in blue. This module contains all components that are available once the IBM Cognos Express installation procedure has finished successfully. These components include:

  • The Informix Dynamic Server (IDS) instance
  • The IBM Cognos Analytic Server (ICAS)
  • Express Manager
  • A dispatcher
  • The Content Manager

The dispatcher, Content Manager and Express Manager are all Java servlets that are deployed in the built-in Tomcat Java Application Server. The dispatcher is the IBM Cognos Express default entry point that is responsible for dispatching the incoming requests to the appropriate services according to their type. The Content Manager on the other hand is the component responsible for the management and storage of IBM Cognos Express content in the Content Store. In addition to the above Application Tier components it also makes the Data Advisor and Architect modelling tools available for download in the Presentation Tier.

Once the Express Core is up and running, the rest of the IBM Cognos Express modules can be downloaded and installed through the easy-to-use Express Manager Console (Express Manager's graphical user interface) as depicted in the Presentation Tier.

Alongside the Content Store, the database used and managed by the Content Manager to store all IBM Cognos Express content, an additional IBM Cognos Content Database has been added to the Informix instance. The Express Store, which is managed by Express Manager, contains the information about the managed data sources and users. The IBM Cognos Content Manager also uses the Express Store as its authentication database for the built-in Cognos Express security namespace.

The second module, represented in red, is Express Reporter. Adding this module will enable you to use Report Studio and Query Studio (located in the Presentation Tier), and makes the IBM Cognos Framework Manager modelling tool available for download. In addition to this it also adds the Report Service components which are responsible for accessing the business data, to the IBM Cognos Express dispatcher.

Installing the Express Xcelerator module, listed in green, allows you to utilise the Xcelerator Web features and makes the Xcelerator Excel client tool available for download. These Presentation Tier components utilise the ICAS server components to access the data that is to be analysed and/or entered.

The brown coloured module Express Advisor adds the Advisor web client to the software download page in the Presentation Tier and adds the Advisor server component EVServer to the Application Tier which enables Advisor to create analysis views based of ICAS cubes.

Last but not least there is the newly added Express Planner module represented in gray which adds and deploys the Planner server component as a servlet into the Tomcat Application Server in the Application Tier. This also makes the Express Planner Administration and Express Planner Contributor tools, located in the Presentation Tier, available for download.


Initial Installation

The first part of the installation process for IBM Cognos Express 9.5 will start after having been provided the following mandatory information:

  • Installation destination folder.
  • Password for the IBM Cognos Express Administrator user. This user account is used to access IBM Cognos Express Manager.
  • Password for the icognosexpress Windows user account. This user account is used to connect to the IDS repository

In this phase all necessary files are copied to the installation destination folder (referred to as <cx_install_root> throughout this document) and the user accounts are created. In the case of the icognosexpress Windows user account, the process will try to make sure the password for this account never expires as this could result in IBM Cognos Express startup failure if the account password expires. A message will be recorded in the log file named IBM_Cognos_Express_InstallLog.log should the installer be unable to remove the password expiration.

During this procedure several log files get created that allow you to obtain more detail in case something did not finish successfully. Here are a few examples of log files which are located in the folder <cx_install_root>\logs\express. This folder will be referred to as the “product specific log folder” throughout this document.

  • IBM_Cognos_Express_InstallLog.log
    This log file contains detailed information such as the configuration parameters used during installation and the creation of the IBM Cognos Express directory structure.
  • ids_install.log and ids.log
    These files provide you with success or failure messages obtained from the Informix installation.
  • database_creation.log
    As the filename suggests this file contains the status messages for the creation of the Content Store and Express Store.

Once all files are in place and the IBM Informix databases have been created, the end user is prompted in an Internet browser to finish the second phase of the installation process. During this phase the Express Manager, Authentication, Data Access and ICAS modules are installed and configured. In addition to that, the Data Advisor and Architect client tools are also made available for download.

Once IBM Cognos Express is up and running, the product specific logs can be found in the same folder. We’ll go into more detail about the contents of the entire folder later on when discussing the individual IBM Cognos Express modules.


IBM Cognos Express Manager

Overview

IBM Cognos Express Manager is a simple and easy to use interface for installing and configuring IBM Cognos Express modules. This Java servlet acts as an configuration interface to make configuration tasks easier.

Installation

The installation of IBM Cognos Express modules and its progress can be viewed in the Event Messages pane in Express Manager. This log window also contains entries and error messages encountered during the creation of managed data sources and users.

A more detailed diagnostic is the ExpressDiagnostic.xml file located in the product specific log folder. This file mainly contains the full stack traces of errors that have occurred while installing modules as well as informational messages that were recorded on startup.

Although this file already contains detailed information its verbosity can still be increased. The amount of information captured is controlled by the CX.prop file located in the <cx_root_install>\bin folder. Verbosity is increased by simply adding a the line LoggingLevel=ALL to the bottom of this file as depicted below.

Figure 2: Example of the CX.prop configuration file showing LoggingLevel set to ALL
Figure 2: Example of the CX.prop configuration file showing LoggingLevel set to ALL

In addition to controlling logging levels, the CX.prop file also serves as a configuration file for module installations. As shown above, the file contains the DiscoveryPath variable which is used by Express Manager to find the software components for a specific Express Module.

Note: In the case of an “SDK-ERR-0034: Unable to find Module ID: <Express Module>” or “SDK-ERR-0001: Discovery Path <path> not found” error, you would check this file for the DiscoveryPath and verify the location is valid.

The express\ folder

The express\ folder, located under the <cx_install_root>, contains several files and locations that you need to be aware of and can aid you in troubleshooting a problem:

  • modules\
    This folder contains all low level modules that are available in IBM Cognos Express. Each module has its own folder which contains status information, where it has been installed from and when.
  • models\
    This folder contains the IBM Cognos Framework Manager models generated by the script player when creating a managed data source in the Express Manager console.
  • track\download\
    This folder contains information about which user downloaded which piece of client software and whether the download succeeded or not.
  • queue\
    This folder holds the queuing state of all modules to be installed over an IBM Cognos Express service restart.
  • vers\ce_runtime-inst.ver
    This file holds the build number of the currently installed IBM Cognos Express instance.
  • properties\systemproperties.xml
    This file contains general Express Manager and product module configuration settings. Although editing this file is not supported and could lead to unexpected behaviour it does enable you to change the location where the IBM Cognos Express backups are stored.

Managed data sources

Express Manager also allows you to easily create packages to relational data or IBM Cognos TM1 cubes.

Once all database information is entered, Express Manager will attempt to verify the validity using the program ./bin/udaxtest.exe. This is an internal driver program that uses similar logic to access reporting databases as IBM Express Reporter does. Once the data is verified and submitted, (1) Express Manager will send a request to the IBM Cognos Express dispatcher to create an IBM Cognos data source connection for further use in reporting. Once this data source has been successfully saved in the content store, (2) Express Manager will launch the BMTScriptPlayer application to execute a script that (3) retrieves the metadata by directly connecting to the data source. Once the metadata has been received the script will (4) create the model/package and publish this out to IBM Cognos Connection via the dispatcher for you to report from.

Figure 3: The flow for creating a managed data source
Figure 3: The flow for creating a managed data source

Authentication

By default IBM Cognos Express comes with two security namespaces enabled. The built-in Cognos namespace and the CognosExpress Custom Java Authentication Provider. In addition to these default namespaces, an optional Active Directory namespace can also be activated.

  • Cognos
    This is the bult-in namespace containing a set of predefined roles used for mapping users from any other supported namespace to specific pieces of functionality. Users cannot be created in this namespace and as a result it is not available for authentication.
  • CognosExpress
    This namespace, a Custom Java Authentication Provider (CJAP) created with the IBM Cognos Java SDK, is the default form of authentication in IBM Cognos Express. It is managed in IBM Cognos Express Manager and its objects (users) are stored in the express store. Whenever an authentication event occurs the CAM, a component located within the content manager which is responsible for security, will query this express store via the CJAP.
    This namespace does not support Single Sign-on (SSO).
  • Active Directory
    Additionally an optional Active Directory namespace can also be enabled to integrate IBM Cognos Express into the corporate security infrastruture. Single Sign-On (SSO) into the IBM Cognos Express environment can only be achieved using this namespace as it is the only one that supports Kerberos SSO.

Java Diagnostics

Retrieving low level diagnostic information on the Tomcat Java instance was made easier in the IBM Cognos Express 9.5 release with the addition of the “Diagnostics Interface”. This page can be found by entering the following URI into your browser window after having logged in as the IBM Cognos Express Administrator:
http://<express_server>:<express_port>/cognos_express/manager/diagnostics.html

Figure 4: The IBM Cognos Express Diagnostics page
Figure 4: The IBM Cognos Express Diagnostics page

As can be seen in the image above, the web page is just a collection of buttons that allows you to dump the following information to a file located in the <cx_install_root>/bin folder on request of your escalation source. The buttons are labelled as follows:

  • Java Dump (javacore.<timestamp>.txt)
    Contains information on Java Memory Manager, locks, thread and stack trace, classes and classloader
  • Heap Dump (heapdump.<timestamp>.phd)
    This is a dump of all objects on the Java heap being used by the running Java
  • Java System Dump (core.<timestamp>.dmp)
    A complete process image (memory dump) of the running JVM
  • Java Trace Snap (Snap.<timestamp>.trc)
    Contains JVM startup information and a list of active threads

These files are usually required to investigate performance and memory issues relating to the Java components (eg. Express Manager, Planner Service, etc).

Cognos Configuration

Although IBM Cognos Express is to be configured solely through IBM Cognos Express Manager, the IBM Cognos Configuration tool is also shipped with the product. Due to the nature of how IBM Cognos Express integrates the different product modules, the IBM Cognos Configuration tool should only be used to adjust Cognos Application Firewall (CAF) settings and the Java heap size configuration. Modifying anything else using IBM Cognos Configuration should be considered unsupported.


IBM Cognos Analytic Server (ICAS)

Server Component logs

As of IBM Cognos Express 9.5, part of the Xcelerator module has been moved (and re-branded) to the IBM Cognos Express core. To be more specific, the Xcelerator Server has been moved and re-branded to IBM Cognos Analytic Server (ICAS).

  • IBM Cognos Analytic Server Admin Service
    Keeps track of all ICAS servers running on a network
  • IBM Cognos Analytic Server – CXMD
    Loads cubes, dimensions and system information found in database directory into memory on startup, handles the cube security and maintains a log of changes

By default, logging information for these components will be saved in the default product specific logs folder as the following files:

  • tm1server.log
    The IBM Cognos TM1 Server message log
  • tm1s<timestamp>.log
    The IBM Cognos TM1 Server transaction log
  • TM1Process_xx_xx.log
    The IBM Cognos TM1 process error log

These log files are also viewable through the Xcelerator Architect Client tool under the Server menu item.

When ICAS starts, the server registers itself with the ICAS Admin Server that is running on a specified administration host. The ICAS Admin Server maintains the Server name, IP address, Protocol and Port number for each available ICAS instance. This information is supplied by the ICAS instance when the server registers itself on the ICAS Admin Server.

Xcelerator clients then reference the ICAS Admin Server to determine which ICAS servers are available on the network. In case of IBM Cognos Express that would be the local ICAS instance.

The ICAS Admin Server must be running before the ICAS server can start. If you have specified an administration host in the Tm1s.cfg file, the server will attempt to connect to an ICAS Admin Server on that host. The ICAS server will fail to come up if it is unable to connect to the ICAS Admin Server for any reason. If you have not specified an administration host, the ICAS server attempts to connect to an ICAS Admin Server on the local machine.

Client component logs

The installation logs for the clients are available in the <client_install_root>\logs folder.

Communication between the client components and the IBM Cognos Express dispatcher uses the Integration Toolkit API. Logging this toolkit is controlled by the C8ITK.ini configuration file which is located in the <client_install_root>\configuration folder. By modifying the LogInfo, LogTrace, Diagnose and LogHTTP variables to a non-zero value, you can enable those specific log levels along with the location of the log files.

Apart from the files in the <client_install_root>, the Xcelerator Client also installs its IBM Cognos TM1 Server configuration file in:

  • %USERPROFILE%\Application Data\Applix\TM1\tm1p.ini (Windows 2003)
  • %APPDATA%\Applix\TM1\tm1p.ini (Windows 2008)

This file is a good place to start if the client has problems reading the IBM Cognos TM1 SSL certificates or contacting the TM1 Server.


IBM Cognos Express Advisor

Server component logs

The Express Advisor features and functionality make use of 2 main server components, the dataAdvisorService and the Advisor Server.

The Advisor Server component (EVServer.exe), started as the “IBM Cognos Express Advisor” Windows service, is responsible for serving the Advisor Web Client with all the data it needs in order to display views. This server has two main log files that can aid in finding a root cause for problems with Express Advisor, the first being the installation log and the second being the operations log. Both of these files are stored in the product specific logs folder <cx_install_root>\logs\express\.

  • AdvisorInstall.log - the installation log
  • Advisor.<YYMMDD>.log - the operations log

The verbosity and scope of the operational logs are controlled by the EVServer.exe.config file located in the <cx_install_root>\bin folder. For the IBM Cognos Express 64-bit edition, this file can be found in <cx_install_root>\bin64. For more information on how to control the level and scope of the logging please refer to Appendix A.

The second server component, which is part of the Express Core and available to use after the initial installation, is the dataAdvisorService which runs as a plugin to the IBM Cognos Express dispatcher. This service is responsible for retrieving business data, creating Xcelerator cubes using the Xcelerator TI API, creating packages and much more.

The logging facility used for this component is IPF and can be enabled using the instructions listed in Appendix B. There is no need to restart any service as the change will be picked up within 30 seconds. The service will start logging information into the following files stored in the <cx_install_root>\logs\express folder:

  • daTrace.log
    Generic trace log
  • daSVTrace.log
    dataAdvisorService trace log
  • daCPITrace.log
    DataAdvisorBIBusPlugin trace log (contains information surrounding cube builds)
  • daCPIControllerTrace.log
    Plugin status messages

Client component logs

The installation of the Data Advisor client can be verified in the <client_install_root>\logs folder. There you can find the log files left behind by the install program.

Troubleshooting “Analyze”

In order to troubleshoot any analyze problems, we need to be familiar with its high level workflow first. Below you can find an overview showing how data flows once the Analyze button has been clicked in different scenarios.

Relational Model

As of IBM Cognos Express 9.5, Data Advisor is able to model and publish relational models based on metadata retrieved from a database via an ODBC connection. The option to model relationally is chosen when first creating the Analysis Definition (an XML document describing the data source metadata) and can be changed to Dimensional and back at any time.

When the newly created Analysis Definition has been given a name, Data Advisor will prompt the modeller to select any ODBC connection that is available on the machine where Data Advisor installed. Once confirmed the tool will import the metadata via the ODBC connection and make it available for the modeller to work with.

When the required modelling steps have been completed and the Create Model button is clicked, Data Advisor will construct a Framework Manager model based upon the Analysis Definition you just created and will forward this along with the data source information to the dataAdvisorService via the dispatcher. The dataAdvisorService will then create a data source connection (prefixed with CXA_) and expose the package in IBM Cognos Connection. If this completes successfully, the dispatcher will notify Data Advisor that the package can be opened in Query Studio. Note that in order for Query Studio to successfully open this package, an ODBC data source identical to the one used on the the Data Advisor machine needs to exist on the IBM Cognos Express server machine.

Figure 5: The flow for publishing a relational model in Data Advisor
Figure 5: The flow for publishing a relational model in Data Advisor

Dimensional Model – Server Based

When the newly created Analysis Definition has been given a name, Data Advisor will prompt the modeller to select any ODBC connection that is available on the machine where Data Advisor installed. Once confirmed the tool will import the metadata via the ODBC connection and make it available for the modeller to work with.

In short, when the Create Cube button is clicked, Data Advisor pushes its Analysis Definition and data source connection information to the dataAdvisorService which in turn retrieves the business data via an existing ODBC connection into flat files. The data in those files is then pulled into an ICAS Cube using scripts that handle the movement and transformation of data (Turbo Integrator scripts). If this has succeeded, the package and default Analysis (a type of report specification for the Advisor Web Client) are published to IBM Cognos Connection for consumption. The dispatcher then notifies Data Advisor that the package can be opened in Advisor.

Figure 6: Analysing a server based dimensional model in Data Advisor
Figure 6: Analysing a server based dimensional model in Data Advisor

Dimensional Model – Client Based

The process for analysing a dimensional model via the Client Based option is very similar to the process described for the Server Based option. The only difference is that all business data is retrieved via the ODBC connection on the client side (rather than on the server side) and sent to the dataAdvisorServer via the dispatcher along with the Analysis Definition. There the data is unpacked by means of a Turbo Integrator script and pulled into a ICAS cube.

The benefit of analysing this way is that the ODBC connection doesn't need to be set up on the server side hence less administrative work.

Figure 7: Analysing a client based dimensional model in Data Advisor
Figure 7: Analysing a client based dimensional model in Data Advisor

Advisor – Dimensional Model

Once published, the package retrieved via the dispatcher and view layout information (either Local or Remote) can be loaded into the Advisor Web Client. This client then communicates with the Advisor Server to obtain the data (and view information) from the previously created ICAS cube.

Note: This only applies for dimensional packages. In case of relational packages Express Reporter is used rather than Express Advisor.

Figure 8: Opening IBM Cognos Express Advisor Web
Figure 8: Opening IBM Cognos Express Advisor Web

Advisor Pre-load

The Advisor Server component can be configured to pre-load cubes on startup in order to improve data access times within the Advisor Web Client and reduce network traffic. This however means that the Express Advisor Windows service will take longer to start.

Selecting the cubes to pre-load is done via Express Manager by clicking the Configure button on the Advisor module tab. Once the required cubes are selected, the changes are written to the file EVServer.exe.preload.config located in the <cx_install_root>\bin folder to be read by the Advisor Service at startup.

Pre-load settings can also be confirmed by using the following URI:
http://<cx_server>:<cx_port>/p2pd/servlet/dispatch/EVService?ui.action=getconfiguration


IBM Cognos Express Xcelerator

Server component logs

With the addition of the ICAS component to the Express Core, the Express Xcelerator module now consists of the following two components:

  • IBM Cognos Express Web – This is a Microsoft .NET web application that allows you to create web forms for analyzing large amounts of complex data with self-service, read-write and what-if modeling capabilities.
  • IBM Cognos Express Xcelerator Excel Service – This is a Windows service which handles IBM Cognos Xcelerator Web requests for converting Excel files into XML format.

When a user opens a websheet, they trigger the IIS web server running Xcelerator Web to invoke the Excel Service and pass to it the file name and location of the Excel XLS file underlying the websheet. That will start an Excel session in batch mode/background which will render/convert the Excel XLS file into an XML file (it will open the XLS file and save it as XML file).

A timestamped copy of both the XLS file and the XML file will be saved in the Xcelerator Web directory <cx_install_root>/Xcelerator/TM1WebEx/Excelsheet and the websheet control file as <cx_install_root>/Xcelerator/TM1WebEx/Excelsheet/ExcelReport.bin.

The web server will pick up the XML file and render/convert it into an HTML page, which will then be forwarded to and displayed by the Xcelerator Web Client.

Hint: If errors occur during this process, then simulating this behaviour manually in Microsoft Excel might help in determining a root cause (e.g. file corruption). Simply open the websheet XLS file in Excel and save this as “XML Spreadsheet 2003 (*.xml)” to simulate the “Excel to XML” process.

Logging for the Xcelerator Excel Service can be enabled/changed by modifying the <cx_install_root>\Xcelerator\bin\TM1ExcelService.exe.config file. For more information on how to enable this log see Appendix C. This steps outlined there will enable the logging at DEBUG level and store the messages in the <cx_install_root>\Xcelerator\bin. For the 64-bit edition, the location of these files will be <cx_install_root>\Xcelerator\bin64.

Appendix D outlines the steps needed to enable more detailed information for the Xcelerator Web component that is being recorded in the <cx_install_root>\Xcelerator\TM1Web\log folder.

Client component logs

See “Client components logs” in the section titled “IBM Cognos Analytics Server” for more information on the client software logging.


IBM Cognos Express Planner

Server component logs

The centralized planning capability that is brought into IBM Cognos Express by installing the Planner module is realized by relying on the following two server components:

  • IBM Cognos Analytics Server (ICAS)
  • IBM Cognos Planner Service

Logging for the ICAS component has already been discussed earlier in the document so in this chapter we will focus on the IBM Cognos Planner Service.

The IBM Cognos Planner Service on its own is another application (similar to parts of IBM Cognos Express reporter) that is deployed to the built-in Apache Tomcat application server instance. The application itself is a collection of Java Server Pages (JSP) and Java servlets that are responsible for the user interface and the application logic. The service is accessible through the Apache Tomcat application server on the following URL:
http://<cx_server>:<cx_port>/pmpsvc/

Installing the Planner module from within the IBM Cognos Express Manager does not generate any additional log files though. The actions performed during the installation (copying of the application files) can be tracked in the ExpressDiagnostics.xml file that was covered in the section titled “IBM Cognos Express Manager”.

By default, error logging for the IBM Cognos Planner Service is enabled and will log error events in the file <cx_install_root>/webapps/pmpsvc/WEB-INF/logs/pmpsvc.log. The amount of information logged to this file is controlled as shown below by the log4j.properties file located in the <cx_install_root>/webapps/pmpsvc/WEB-INF/configuration folder. Be aware that increasing the logging level (as described in Appendix E) will generate a huge amount of information and shouldn't be left on indefinitely.

Client component logs

The very first time you access IBM Cognos Express Planner no applications exist since the IBM Cognos Express Planner Administration client still needs to be installed. To do this you need to click the Design an Application button which will prompt you to install the IBM Cognos Rich Client Framework (CognosRCP). Once this is installed and the browser is restarted, another click on the Design an Application button will launch this framework in order to attempt to download and install the IBM Cognos Express Planner Administration client.

These client components are installed into the following folders depending on which operating system is in use:

  • %USERPROFILE%\Application Data\CognosRCP (Windows 2003)
  • %APPDATA%\CognosRCP (Windows 2008)

Steps to extract more information from these client components are described in Appendix F.


The IBM Cognos Express Repository

Overview

IBM Cognos Express uses a pre-configured, scaled down instance of Informix Dynamic Server (IDS) as its Content Repository. IDS delivers exceptional reliability, scalability, ease of administration, online transaction processing (OLTP) performance, and a complete range of application development options.

This database server will contain the Content Store, Express Manager Store and can also be used to deploy the Express Samples into. The samples should only be deployed in this instance as a proof of concept though as mixing reporting and content stores on the same database server could lead to performance degradation at peak times. In addition to the possible performance degradation it is also important to note that deploying business data to the embedded IDS violates the license agreement.

Configuration and logging points

As mentioned above, the IDS instance shipped with IBM Cognos Express is scaled down and pre-configured in line with the Express philosophy – simplicity. The installer will copy all required binaries and configuration files to the <cx_install_root>/ids and <cx_install_root>/ids_cs folders.

Once the IBM Cognos Express installation procedure has finished, the IDS instance will have been registered as the Informix IDS - cm_ids_svr_custom Windows service. No additional configuration changes are required to be able to make use of the database server.

On service startup, the IDS instance will read in the configuration file from the %ONCONFIG% environment variable. This variable is set by the installer to a value of <cx_install_root>/ids/etc/ONCONFIG.cm_ids_svr_custom.

The two main IDS log files can be found in the <cx_install_root>/ids folder:

  • cm_ids_svr_custom.log
    This message log contains status messages and diagnostic messages relating to the IDS instance. In a vanilla IDS installation, this file is named online.log by default. The contents of this file can also be viewed using the onstat utility.
  • concm_ids_svr_custom.log
    This console log contains status and diagnostic messages. In a vanilla IDS installation, this file is named console.log by default

The actual database files can be found in the <cx_install_root>/ids_cs folder.

IDS tools and commands

Below you'll find a list of tools and commands that you might find useful in case you are retrieving troubleshooting information for IDS problems.

Note: Before attempting to run any of the tools/commands listed below make sure you have set up the environment variables as per your environment. For your convenience the <cx_install_root>/ids/cm_ids_svr_custom.cmd batch script does just that.

The first tool to mention would be dbaccess, located in the <cx_install_root>/ids/bin folder. This tool provides command line access to the databases on the IDS instance. You can use this tool by just executing dbaccess.exe and following the console UI.

Figure 9: The console UI for the dbaccess tool
Figure 9: The console UI for the dbaccess tool

This console only allows for keyboard interaction so it might feel a bit cumbersome. An additional feature of dbaccess is that it can also be scripted. Using pipes (|) and redirects (< or >), you can feed the tool your SQL queries in batch mode.

Here some additional examples how the above information can be extracted using pipes and redirects:

echo connect to 'express';select * from 'icognosexpress'.expressusers | dbaccess
echo connect to 'express';select * from 
 'icognosexpress'.expressusers | dbaccess > users.txt 
echo connect to 'express' user 'icognosexpress';select * from expressusers | dbaccess
Figure 10: Feeding SQL statements from the command prompt into the dbaccess tool using a pipe
Figure 10: Feeding SQL statements from the command prompt into the dbaccess tool using a pipe

The second utility worth mentioning is onstat which can be found in <cx_install_root>/ids/bin/onstat.exe. onstat reads shared memory structures and provides statistics about the database server at the time that the specific commands execute. This particular tool is useful for debugging IDS and collecting environment information relating to the database instance.

  • onstat -g dis
    Prints a list of database servers and their status, and information about each database server.
  • onstat -g sql [<SessionID>]
    Prints SQL information by session id. If session id is omitted, a one-line summary for each session prints.
  • onstat -g all
    Prints all multithreading information.
  • onstat -a or onstat -cuskbtdlp
    Collects configuration, user activity, locks, buffers, tablespaces, DB space, logging info, profile statistics.
  • onstat -m
    Display the last 20 lines of the system message log (even in offline mode).

HINT: To redirect the output to a file, append “> filename” to the onstat command. For example, onstat -a > onstatinfo.txt.

The options listed above are just a small extract of information that might be needed in order to collect problem related information using onstat. For a complete reference please see the onstat reference guide.


Appendix A: Advisor Server logging

The log provider for the Advisor Server component is enabled and configured through the EVServer.exe.config file under the <cx_install_root>\bin folder. For the IBM Cognos Express 64-bit edition, this file can be found in <cx_install_root>\bin64.

To increase the logging level you can open up this file and modify the logLevel attribute in the <logProviders> section to match example below:

<logProviders>
	…
	<logLevelTable>
		<logLevels>
			<logLevel logLevel="Trace" category="*" component="*"/>
		</logLevels>
	</logLevelTable>
	…
</logProviders>

This will set the level for all categories/components to Trace and store its information in the Express specific logs folder. A list of known categories, components and log levels can be found in the table below.

logLevelcategorycomponent
SevereGeneralSecurityProviders.CAM
ErrorSessionServer
WarningSecurityDefault Command
InfoConfigurationLogProviders.XML
VerboseInternalErrorTM1
TraceUnsupportedTypeMDX
DebugParameterValidationContentStoreAccess
SOAPResponse
SOAPRequest
SOAPFaultResponse

Once the changes are saved, a restart of the IBM Cognos Express Advisor service is required for the changes to take effect.


Appendix B: DataAdvisorService logging

The logging infrastructure implemented in the DataAdvisorService component uses the Indication Processing Facility (IPF) which is based on the log4j framework.

To enable more detailed information to be logged to file you simply find the ipfDAclientconfig.xml.sample file in the <cx_install_root>/configuration folder and rename it to ipfclientconfig.xml.

There is no need to restart any service as the change will be picked up within 30 seconds. The service will start logging information into the following files stored in the <cx_install_root>\logs\express folder:

  • daTrace.log
    Generic trace log
  • daSVTrace.log
    DataAdvisorServicetrace log
  • daCPITrace.log
    DataAdvisorBIBusPlugin trace log (contains information surrounding cube builds)
  • daCPIControllerTrace.log
    Plugin status messages

Appendix C: Xcelerator Excel Service logging

The logging for the Xcelerator Excel Service is configured by default and is intended for every-day use. To increase the verbosity of the logging information, open up the TM1ExcelService.exe.config file in the <cx_install_root>\Xcelerator\bin folder and modify it to resemble the snippet below:

...
<root>
	<level value="DEBUG" />
	<appender-ref ref="LogFileAppender" />
</root>
<appender name="LogFileAppender" type="log4net.Appender.RollingFileAppender">
	<file value="tm1excelservice.log" />
	<appendToFile value="true" />
	<datePattern value="yyyyMMdd" />
	<rollingStyle value="Date" />
	<filter type="log4net.Filter.LevelRangeFilter">
		<acceptOnMatch value="true" />
		<levelMin value="DEBUG" />
		<levelMax value="FATAL" />
	</filter>
...
</appender>
...

Once the changes are saved, a restart of the IBM Cognos Express Xcelerator Excel service is required for the changes to take effect.


Appendix D: Xcelerator Web logging

The configuration for Xcelerator Web logging is stored in a logging properties section of the <cx_install_root>\Xcelerator\TM1Web\Web.config file. You can edit the properties in this file to adjust the logging message level as demonstrated below:

...
<root>
	<level value="DEBUG" />
	<appender-ref ref="LogFileAppender" />
</root>
<appender name="LogFileAppender" type="log4net.Appender.RollingFileAppender">
	<file value="log\tm1web.log" />
	<appendToFile value="true" />
	<datePattern value="yyyyMMdd" />
	<rollingStyle value="Date" />
	...
</appender>
...

Once the changes are saved, a restart of IBM Cognos Express Xcelerator Web is not required for the changes to take effect. The changes will be automatically picked up within 60 seconds.


Appendix E: Planner Service logging

Increasing the amount of operational information and function calls logged in the <cx_install_root>/webapps/pmpsvc/WEB-INF/logs folder is done as follows:

  1. Open the <cx_install_root>/webapps/pmpsvc/WEB-INF/configuration/log4j.properties file.
  2. Make a backup in case you need to revert the changes easily.
  3. Find the following lines:
       log4j.logger.com.ibm.cognos=ERROR
       log4j.logger.com.cognos=ERROR
       log4j.logger.com.cognos.org=ERROR
  4. Increase the logging level as follows:
       log4j.logger.com.ibm.cognos=INFO
       log4j.logger.com.cognos=INFO
       log4j.logger.com.cognos.org=INFO
  5. Save the changes.

If you are more interested in tracing the performance of this server component you can remove some comment tags (#) as shown below. This will create two additional log files in the <cx_install_root>/webapps/pmpsvc/WEB-INF/logs folder that are dedicated to performance metrics.

  1. Open the <cx_install_root>/webapps/pmpsvc/WEB-INF/configuration/log4j.properties file.
  2. Make a backup in case you need to revert the changes easily.
  3. Find the following lines:
       #log4j.rootlogger=ERROR, PerfConsole, perfText, perfXML
       #log4j.logger.com.ibm.cognos.perf=DEBUG
  4. Enable the performance trace by removing the comment tags as follows:
       log4j.rootlogger=ERROR, PerfConsole, perfText, perfXML
       log4j.logger.com.ibm.cognos.perf=DEBUG
  5. Save the changes. It is not necessary for the IBM Cognos Express Planner service to be restarted for the changes to take effect. The changes will be automatically picked up within 60 seconds.

Appendix F: Planner Client logging

To enable tracing for the Planner Adminstration tool follow the steps as demonstrated below.

  1. Open the %APPDATA%\CognosRCP\rcp\defaultLog.properties file and make a backup.
  2. Find the following lines:
       #log4j.rootLogger=ERROR, appAppender
       #log4j.logger.com.cognos=ALL
       #log4j.logger.com.ibm.cognos=ALL
  3. Enable tracing by removing the comment tags as follows:
       log4j.rootLogger=ERROR, appAppender
       log4j.logger.com.cognos=ALL
       log4j.logger.com.ibm.cognos=ALL
  4. Save the changes and restart the Planner Administration tool.

Verbose information will be logged in the %APPDATA%\CognosRCP\logs\ModellingADT_8.4.1 folder.

By default, events are logged in XML format which might make it more difficult to read. To log the information in a more human readable format make the following adjustments:

  1. Open the %APPDATA%\CognosRCP\rcp\defaultLog.properties file.
  2. Find the following line at the end of the file:
      log4j.appender.appAppender.layout=org.apache.log4j.xml.XMLLayout
  3. Modify this line so it resembles the following:
      log4j.appender.appAppender.layout=org.apache.log4j.PatternLayout
      log4j.appender.appAppender.layout.ConversationPattern=%d [%t] %-5p (%x) %c - %m%n
  4. Save the changes and restart the Planner Administration tool.

Potential issues with the IBM Cognos Rich Client Framework can be traced and logged by editing the cognosrcp.ini file, located in the %APPDATA%\CognosRCP\rcp folder, as follow

  1. Open the cognosrcp.ini file and make a backup.
  2. Find the following two lines at the bottom of the file:
       ;log=log.txt
       log.level=none
  3. Modify the logging entries to resemble the following:
       log=c:\log.txt
       log.level=debug
  4. Save the changes and restart the Planner Administration tool.

Appendix G: The IBM Cognos Express 9.5 cheat sheet

For the port numbers below, the “x” should be replaced with the range chosen during the initial installation. For example, 19400-19409.

Express Manager
Windows ServiceIBM Cognos Express
Port numberExpress Manager19x00
Version<cx_install_root>/express/vers/ce_runtime-inst.ver
Express Reporter
Windows ServiceIBM Cognos Express
Port numberExpress Dispatcher19x00
IPF Log Port19x02
Tomcat Shutdown Port19x03
Client SoftwareFramework Manager (Thick)
Report Studio (Thin)
Query Studio (Thin)
Express Planner
Windows ServiceIBM Cognos Express
Port numberPlanner Service19x00
Client SoftwarePlanner Administration
Planner Contributor (Thin)
Express Xcelerator
Windows ServiceIBM Cognos Analytic Server Admin Service
IBM Cognos Analytic Server - CXMD
IBM Cognos Express Xcelerator Excel Service
Port numberICAS Server Port19x06
ICAS Server Client Message Port19x07
Client SoftwareArchitect (Thick)
Perspectives for MS Excel (Thick)
Xcelerator Web (Thin)
Express Advisor
Windows ServiceIBM Cognos Express Advisor
Port numberAdvisor Port - used by clients19x08
Advisor Internal Port19x09
Client SoftwareData Advisor (Thick)
Advisor Web Client (Thin)
Express Repository
Windows ServiceInformix IDS Message Service
Informix IDS - cm_ids_svr_custom
Port numberInformix SQLI Port19x04
Informix DRDA Port19x05

Appendix H: Useful Links

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Big data and analytics on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Business analytics, Information Management
ArticleID=784332
ArticleTitle=IBM Cognos Proven Practices: IBM Cognos Express 9.5 Troubleshooting
publish-date=01112012