eClient Customization, Part 8: eClient troubleshooting and debugging

This article provides troubleshooting and debugging tips for IBM® DB2® Information Integrator for Content and IBM DB2 Content Manager eClient.

Share:

Guang Xu (xuguang@cn.ibm.com), Software Engineer, IBM Content Manager Development, IBM

Author Photo: Xu GuangXu Guang works as a Content Manager eClient developer in IBM China Software Development Lab (CSDL).



Wei-Dong Zhu, Project Leader, IBM

Wei-Dong (Jackie) Zhu is a Project Leader in Content Management for the International Technical Support Organization at the Almaden Research Center in San Jose, Calif. She has more than 10 years of software development experience in document search systems, image workflow processing, and digital media distribution. She holds a Master of Science degree in Computer Science from the University of Southern California.



Mike Grasselt (grasselt@de.ibm.com), Technical Lead, IBM

Mike Grasselt is a senior software engineer who has worked for IBM since 1997. Currently, he leads an Information Platform and Solutions development team focusing on solutions integrating Master Data Management and SAP. In earlier roles, he integrated text analysis technology with content management and was an author of the IBM Redbooks publication "eClient 101 Customization and Integration." He has presented university lectures on software development for IBM mainframe servers. He developed an SQL extension for the Business Processes Execution Language (BPEL) and published several papers on data-aware business processes and web services. He was responsible for the service-oriented architecture (SOA) alignment of InfoSphere Information Server to allow integration with WebSphere Portal, WebSphere Process Server, and InfoSphere Master Data Management Server. In addition to his technical responsibilities, he is a mentor in the IBM technical community.



Alan Mayer, I/T Architect, IBM

Alan Mayer is an I/T Architect in IBM Global Services in U.S. He has 10 years of experience implementing Content Manager for various clients. His areas of expertise include application development and document imaging.



Lijing Zhang, Software Engineer, IBM

Lijing Zhang is a software engineer for IBM. He has worked for IBM since 2001 in the Content Management field. His areas of expertise include Content Manager, Information Integrator for Content, and VideoCharger. He is a co-author of the "Content Manager V8 Certification Study Guide."



23 October 2008

The material in this article was originally published as part of an IBM Redbooks® publication, eClient 101 Customization and Integration. It has been updated to include details for eClient, Version 8, Release 3, Fixpack 8.

Isolating problems

Content Manager eClient is a complex application. You have to install and configure many products before you are able to launch the logon window. For this scenario, the following products have been installed and configured:

  • WebSphere® Application Server
  • IBM HTTP Server
  • IBM DB2 Information Integrator for Content
  • IBM DB2 Content Manager eClient

In such a complex environment, it is extremely important to isolate the problem while you are doing troubleshooting. For example, if you have problems in the Web server but you are troubleshooting in the WebSphere Application Server, the problem will never be resolved. Before you can fix a problem, you have to identify which product or products cause the problem.


Trace eClient

This section shows you an eClient trace file. To modify the eClient trace level, you need to edit the cmblogconfig.properties file.

  1. Open cmblogconfig.properties located in ${IBMCMROOT}/cmgmt/connector using a text editor.

    Tip: Make a backup of cmblogconfig.properties before you make any modifications.

  2. Modify the value of parameter DKeClientLogLevel to DEBUG. The default log priority setting is DKeClientLogLevel=ERROR. The priorities are shown in Table 1.
Table 1. Trace log level
NameDescription
DISABLEDisables logging.
FATALProvides information that the problem encountered unrecoverable errors and must cease operating immediately. Stopping the problem is done separately, not from the logging facility.
ERRORProvides information that the program encountered recoverable or unrecoverable errors, but is able to continue operating.
INFOProvides significant event messages, such as a successful log on.
TRACEUsed to output additional diagnostic information, such as program state changes, function parameter information, and function return value information.
DEBUGUsed to output information for debugging errors.

The Content Manager eClient is built with the java API. In most circumstances, problems with the eClient can be attributed to problems connecting to the library server or problems accessing the Resource Manager.

To create the log file, the following example goes through a login process and deliberately supplies the wrong password information:

  1. Stop the eClient_Server application server (Server1 in version 8.4).
  2. Delete every file in the C:\\Program Files\\IBM\\db2cmv8\\log\\eclient directory.
  3. Start the eClient_Server application server.
  4. Open a Web browser and enter the URL http://localhost/eclient/IDMInit to display the eClient logon window.
  5. Enter the username icmadmin and the password: password to log on. Note that the password is incorrect.
  6. A message window pops up and indicates that an incorrect user ID, password, or server name has been entered.
  7. Open the eClient log file, which in this case is C:\Program Files\IBM\db2cmv8\log\eclient\eClientTrace.txt. You should see the content of the sample log file shown in Example 1:
    Example 1. eClient log file eClientTrace.log
    [LOC]: com.ibm.mm.beans.util.CMBTraceLog:error
    [MSG]: icmadmin  icmnlsdb  com.ibm.idm.servlets.IDMConnection.connect  
    com.ibm.mm.beans.CMBConnectFailedException: 
    DGL0394A: Error in : DKDatastoreICM.connect; [SERVER = icmnlsdb, USERID = icmadmin]; 
    ICM7172: The password provided is invalid for this user ID, or it is NULL. 
    (STATE) : [LS RC = 7172, LS reasonCode = 9]

Note that <hostname>.dklog.log file is also available in the C:\Program Files\IBM\db2cmv8\log\connectors directory. The <hostname>.dklog.log file is discussed in the next section.


Trace the Information Integrator for Content Java API

eClient is built on top of the Information Integrator Java APIs. The logging and tracing mechanism in Information Integrator also provides valuable information while you troubleshoot problems in eClient.

When you run an application that is written in the Information Integrator for Content Java API -- in this case, it is eClient -- the Information Integrator for Contentlog file <hostname>.dklog.log resides in the current working directory. For eClient, the working directory is defined by the WorkingDir parameter in the cmblogconfig.properties file, as discussed in the Trace eClient section. By default, it is C:\Program Files\IBM\db2cmv8\log\connectors.

Configure the log manager

The Information Integrator for Content Java API has two log managers: the default and LOG4J. You can configure and use only one of them at a time. The same configuration file, cmblogconfig.properties, is used to control which log manager type is used and how to configure them. By default, the file resides in the C:\Program Files\IBM\db2cmv8\cmgmt\connectors directory. This section discusses how to configure the default log manager.

There are eight sections in the cmblogconfig.properties file:

SECTION 0 -- Global settings

This section specifies the key(s) used to control the internal behavior of the logging facility, regardless which log manager (default log manager or log4J) you are using.

Table 2. Values for parameter MAX_EXCEPTION_COUNT
ValueDiscription
ONSet this key to ON to limit the maximum number of exceptions per message ID sent to the logger. The maximum number is 5.
OFFSet this key to OFF to not limit the maximum number of exceptions per message ID sent to the logger.

SECTION 1 -- Log manager factory setting

The key DKLogManagerFactory specifies which log manager facility is to be used.

Table 3. Values for parameter DKLogManagerFactory
ValueDiscription
com.ibm.mm.sdk.logtool.DKLogManagerFactory_defaultSetting to use the default log manager.
com.ibm.mm.sdk.logtool.DKLogManagerFactory_Log4JSetting to use the log4j log manager.

SECTION 2 -- Set up your default log manager

When you start more than one Java Virtual Machine (JVM), the log priority setting has only local impact.

The parameter DKLogPriorit specifies the Log Priority. Its values are defined in Table 4. By default, it is set to ERROR.

Table 4. Values for parameter DKLogPriorit
ValueDiscription
DISABLEDisables logging
FATALLogs FATAL messages
ERRORLogs FATAL + ERROR messages
PERFLogs FATAL + ERROR + PERFORMANCE messages
INFOLogs FATAL + ERROR + PERFORMANCE + INFO messages
TRACE_NATIVE_APILogs FATAL + ERROR + PERFORMANCE + INFO + TRACE_NATIVE_API messages
TRACE_ENTRY_EXITLogs FATAL + ERROR + PERFORMANCE + INFO + TRACE_NATIVE_API + TRACE_ENTRY_EXIT messages
TRACELogs FATAL + ERROR + PERFORMANCE + INFO + TRACE_NATIVE_API + TRACE_ENTRY_EXIT + TRACE messages
DEBUGLogs FATAL + ERROR + PERFORMANCE + INFO + TRACE_NATIVE_API + TRACE_ENTRY_EXIT + TRACE + DEBUG messages

SECTION 3 -- Log output destination setting

The key DKLogOutputSetting specifies the log output destination. The key allows only one destination. By default, it is set to 1.

Table 5. Values for parameter DKLogOutputSetting
ValueDiscription
1Logs to a file
2Logs to Standard Error
3Logs to Standard console

DKLogOutputFileName and DKLogOutputFileSize. The parameter DKLogOutputFileName specifies the log file name to be used. The default name is dklog.log. The parameter DKLogOutputFileSize specifies the log file size limit before the log file is rolled over to a backup copy. The log file size is in MB. The default log file size is 5 MB. If the log file size is set to 0, the log file will keep being appended and never get to be rolled over. The rolled-over backup file name is constructed by appending the suffix .sav to the log output file name.

Sample log file

Use the same scenario as generating the eClient log file from the last section. You will find that there is also such an error message in dklog.log file when you input the incorrect password to log onto eClient.

Example 2. DKLOG file -- eidy.dklog.log
[EXC]: 09/04/2008 GMT @ (9.181.142.166); com.ibm.mm.sdk.common.DKLogonFailure 
# com.ibm.mm.sdk.logtool.DKLogManager_Log4J
[USR]: xuguang (C:\Documents and Settings\jianglijun) @ 
C:\Program Files\IBM\WebSphere\AppServer\profiles\default
[THD]: WebContainer : 1 ( 64f0b080 )
[THG]: main = { Deferred Alarm Manager, Non-Deferred Alarm Manager, 
Approximate Time Keeping Thread, Thread-5, Thread-6, Alarm : 0, Alarm : 1,
LT=0:P=194266:O=0:port=4793, DCS Plugin Delivery Thread, LT=1:P=194266:O=0:port=2811, 
ServerSocket[addr=0.0.0.0/0.0.0.0,port=0,localport=8882],
PoolScavenger0, LocalNotificationServiceDispatcher : 2, Thread-13, 
Thread-14, Thread-15, Inbound Read Selector.1, Inbound Write Selector.1, 
Shared TCPChannel NonBlocking Accept Thread, 
Thread-20, HAManager.thread.pool : 0, Thread-21, Inbound Read Selector.1, 
WebContainer : 0, WebContainer : 1, WebContainer : 2, Inbound Write Selector.1, 
NotificationServiceDispatcher : 6, HAManager.thread.pool : 1, }
[LOC]: com.ibm.mm.sdk.server.DKDatastoreICM:logon
[MSG]: DGL0394A: Error in : DKDatastoreICM.connect; 
[SERVER = icmnlsdb, USERID = icmadmin]; 
ICM7172: The password provided is invalid for this user ID, or it is NULL. 
(STATE) : [LS RC = 7172, LS reasonCode = 9]
    at com.ibm.mm.sdk.server.DKDatastoreICM.logon(DKDatastoreICM.java:3875)
    at com.ibm.mm.sdk.server.DKDatastoreICM.connect(DKDatastoreICM.java:3429)
    at com.ibm.mm.beans.CMBConnection.connect(CMBConnection.java:1700)
    at com.ibm.idm.servlets.IDMConnection.connect(IDMConnection.java:588)
    at com.ibm.idm.servlets.IDMConnection.doGet(IDMConnection.java:1414)
    at com.ibm.idm.servlets.IDMConnection.doPost(IDMConnection.java:1502)
    at javax.servlet.http.HttpServlet.service(HttpServlet.java:763)
    at javax.servlet.http.HttpServlet.service(HttpServlet.java:856)
    at com.ibm.ws.webcontainer.servlet.ServletWrapper.service(ServletWrapper.java:1212)
    at com.ibm.ws.webcontainer.WebContainer.handleRequest(WebContainer.java:1657)
    at com.ibm.ws.webcontainer.channel.WCChannelLink.ready(WCChannelLink.java:77)
    at com.ibm.ws.tcp.channel.impl.WorkQueueManager.attemptIO(WorkQueueManager.java:601)
    at com.ibm.ws.tcp.channel.impl.WorkQueueManager.workerRun(WorkQueueManager.java:934)
    at com.ibm.ws.tcp.channel.impl.WorkQueueManager$Worker.run(WorkQueueManager.java:1021)
    at com.ibm.ws.util.ThreadPool$Worker.run(ThreadPool.java:1332)

Additional trace information

Since eClient is a WebSphere Application Server, you can obtain additional information through the WebSphere logging mechanism. By default, the WebSphere log files for eClient are in the C:\Program Files\IBM\WebSphere\AppServer\profiles\default\logs\eClient_Server directory.

If you have problems displaying the eClient logon window, it is possible that the Web server has problems or has not even started. In this case, the Web server log files and Web server plug-in log files may present tips for you to identify the problem. By default, these log files reside in both the C:\Program Files\IBM HTTP Server\logs and C:\Program Files\IBM\WebSphere\AppServer\logs directories. In the C:\Program Files\IBM\WebSphere\AppServer\profiles\default\logs directory, pay special attention to the activity.txt, and in the C:\Program Files\IBM\WebSphere\Plugins\logs\webserver1 directory, pay special attention to http_plugin.txt files.


Debug your application

In addition to tracing, you can debug your applications using programming and external third-party tools.

Debug Java code using stdout

One way of debugging your Java source code, whether it is in a custom servlet, a custom Java file, or Java code in a JSP, is by writing messages to the stdout file using the System.out.println() method. For example:

Example 3. Debugging Java code
String myVariable = "test";
System.out.println("The value of test is '" + myVariable + "'");

The output from this code goes to the stdout file.

If you use IBM Rational® Software Development Platform, the stdout output goes to the console that can be viewed in the IBM Rational Software Development Platform Web perspective.

If you are running in the standard eClient, the location of the stdout file is controlled by WebSphere. The default location is C:\Program Files\IBM\db2cmv8\log\eclient\eClient_Server_stdout.log.

To check or change the location of stdout, run the WebSphere Administrative Console. Be sure to stop your IBM Rational Software Development Platform test environment and start the WebSphere server1 service before trying to run the standard WebSphere Administrative Console. They cannot be run at the same time. When the Administrative Console is up, select Troubleshooting > Logs and Trace > eClient_Server. You can modify the location of stdout from that window.

Debug JavaScript code

Because JavaScript runs in a Web browser, you cannot use System.out.println() to debug as you would for Java code in your JSP. The following are two methods of debugging JavaScript:

  1. Use the alert() statement

    In most cases, adding alert() calls in the JavaScript code embedded in your JSP files is adequate for debugging. The alert() statement displays a message box containing the text that you pass into the function. You can place these messages in the JavaScript contained in the JSP to trace the execution path and display the values of variables.

  2. Use the JavaScript debugging facilities of your browser

    Microsoft Internet Explorer has a facility for debugging JavaScript code built into it, as does Netscape Navigator. "Debugging client-side scripts" or "JavaScript debugger" can be used for JavaScript debug.


Conclusion

Part 8 of this series guided you through how to troubleshoot an eClient application and II4C when you meet error messages during the run time. It also showed you the debugging method on both Java code and JavaScript. By analysing the log files, you can determine cause of the problem. It also included instruction on how to configure the parameters in the cmblogconfig.properties file.

Resources

Learn

Get products and technologies

  • Build your next development project with IBM trial software, available for download directly from developerWorks.
  • Download IBM product evaluation versions and get your hands on application development tools and middleware products from DB2, Lotus®, Rational, Tivoli®, and WebSphere.

Discuss

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 Information management on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Information Management
ArticleID=347067
ArticleTitle=eClient Customization, Part 8: eClient troubleshooting and debugging
publish-date=10232008