This document is intended to provide a troubleshooting methodology which incorporates publicly available utilities to diagnose and resolve an issue identified within a specific use case. The use case will be presented as a scenario where an IBM Cognos Support Analyst is working with a client to diagnose and solve a particular issue.
The utilities mentioned in this document can be found at http://www.ibm.com/software/data/support/cognos_sdk.html
Although the troubleshooting approach outlined is not IBM Cognos BI version specific, some of the diagnostic utilities used are. The version of the utility to be downloaded will be specific to the IBM Cognos BI version that is experiencing the issue.
Use Case Description
A client calls IBM Cognos support and indicates one of their IBM Cognos BI servers in a multi-server environment will not start. The client is fairly sure that all the server environments are the same and adhere to the IBM Cognos supported environments listing on the support site.
Gathering Information for this Use Case
The support analyst requests the component lists from each of the servers and sees that the IBM Cognos BI software versions for all servers match. The support analyst asks the client about the operating systems used in the environments and what application servers are being used. The client indicates all servers are running a Microsoft Windows Server 2008 operating system and that they are using the Tomcat servlet container shipped with the product.
The support analyst then requests that the client download and run the IBM Cognos BI Diagnostic tool. This tool is located at the following URL, http://www.ibm.com/support/docview.wss?uid=swg24020669
The diagnostic tool is run on the IBM Cognos BI server that does not start and again on one of the servers that does start. The client then sends the resulting log files captured by the diagnostic tool to the support analyst for review.
Indicating Considerations and Precautions
The support analyst reviews the output files from the diagnostic tool (IBMCognosBI_CognosInfo_<date><time>.txt) from each server and notices that the server that does work does not have the JAVA_HOME environment variable set.
The support analyst informs the client that the JAVA_HOME environment variable on the problem server is pointing to a version of Java not supported by the version of IBM Cognos BI being used. When no JAVA_HOME environment variable is supplied, Tomcat will default to the Java shipped with the IBM Cognos BI product, which explains why the other servers work.
The support analyst offers a few suggestions on how to remedy the situation.
- The client can remove the JAVA_HOME environment variable on the problem IBM Cognos BI server or point it to a supported version of Java.
- The client can also edit the bootstrap_win34.xml or bootstrap_win64.xml file (depending on whether a 32 bit or 64 bit version of IBM Cognos BI is installed) and hard code a path to a supported version of Java. These bootstrap XML files are located in the <cognos_install>/bin directory and are referenced by the cogbootstrapservice.exe for start up parameters when starting the IBM Cognos BI service on a Windows machine.
Resolving the Issue
In this case, the client did not want to remove or change the JAVA_HOME environment variable in their Windows environment as they have other software running on that server requiring the setting. The client opts to change their bootstrap_win32.xml file and changes the line that reads,
<path quoteAsParam="true">C:\Progra~1\IBM\cognos\c10 \bin\jre\6.0\bin\java.exe</path>
The bolded sections highlight the changed element in the XML.
The client’s IBM Cognos BI server now starts without issue.