IBM Support

MustGather: Enabling diagnostic tracing and checking connectivity for troubleshooting e-mail in ClearQuest

Technote (FAQ)


Question

What information and diagnostic trace logging can be gathered for troubleshooting e-mail related issues in IBM Rational ClearQuest in both Microsoft Windows and UNIX-based environments?

Answer

Click on the category to view more information.

Basic Troubleshooting Information


Diagnostic Tracing instructions for Microsoft Windows Environments
Windows Registry keys can be set to enable the tracing and gathering of diagnostic information for troubleshooting problems on the native ClearQuest client and ClearQuest web.

You can create a .reg file to set up these keys. Copy the following lines for your ClearQuest product into a text editor and save the file with a ".reg" extension. This file can then be run to enable diagnostic tracing.

Note: The ClearQuest client, Mail Reader, and Web services need to be restarted after the registry settings have been set.

Once diagnostic tracing is enabled, perform the actions to reproduce the issue you are experiencing. Review the log file for output that indicates the source of the problem.

Code for .reg file for the ClearQuest Windows and Eclipse clients
Windows Registry Editor Version 5.00

[HKEY_CURRENT_USER\Software\Rational Software\ClearQuest\Diagnostic]
"Trace"="API;DB_CONNECT=2;DB_MISC;EMAIL;EMAIL_VB;HOOKS=2;MAILREAD;PERL;THROW;SQL=2;VBASIC"
"Report"="MESSAGE_INFO=0X70B;DIAG_FLAGS=-1"

"EmailSendVB"="ODS"
"Output"="C:\\cq_diagnotics.log"

Code for .reg file for the ClearQuest Web Server or ClearQuest Mail Reader* on Windows platforms
REGEDIT4

[HKEY_USERS\.DEFAULT\Software\Rational Software\ClearQuest\Diagnostic]
"Trace"="API;DB_CONNECT=2;DB_MISC;EMAIL;EMAIL_VB;HOOKS=2;MAILREAD;PERL;THROW;SQL=2;VBASIC"
"Report"="MESSAGE_INFO=0X70B;DIAG_FLAGS=-1"

"EmailSendVB"="ODS"
"Output"="C:\\cq_diagnotics.log"

Note: HKEY_USERS\.DEFAULT is only appropriate when the IBM WebSphere Application Server (WAS) profile service is running as "Local System" account.

If the WAS profile service is not running as "Local System" account, then the user "must" log onto the machine "as" the user that is running the web service, and add the key to the following location
[HKEY_CURRENT_USER\Software\Rational Software\ClearQuest\Diagnostic]

Make sure you disable the trace values when diagnostics are complete. Failure to do so can have a negative impact on system performance, and cause large text files to be created.

Code for .reg file to disable tracing for the ClearQuest Windows and Eclipse clients
Windows Registry Editor Version 5.00

[HKEY_CURRENT_USER\Software\Rational Software\ClearQuest\Diagnostic]
"Trace"=""
"Report"=
""
"Output"=""

"EmailSendVB"=""

Code for .reg file to disable tracing for the ClearQuest Windows Server or ClearQuest Mail Reader*
REGEDIT4

[HKEY_USERS\.DEFAULT\Software\Rational Software\ClearQuest\Diagnostic]
"Trace"=""
"Report"=
""
"Output"=""

"EmailSendVB"=""

* Note: If the Mail Reader service is running as a user account instead of Local System, you must log into Windows as that user and use the same registry keys as the ClearQuest Windows and Eclipse clients.


Diagnostic Tracing instructions for UNIX and Linux Environments
The following is instructions on how to enable e-mail diagnostic tracing on UNIX-based platforms. Note that Visual Basic-based trace values are not used, as BASIC scripts are not executed in UNIX-based environments.

Note: Make sure users disable the trace values when diagnostics are complete. Failure to do so can have a negative impact on system performance, and cause large text files to be created.

Enabling e-mail diagnostic tracing on ClearQuest UNIX-based workstations running the native UNIX or RCP Eclipse clients:

ClearQuest UNIX client tracing is dependent upon a series of environment variables. Create these environment variables for e-mail diagnostic tracing.

The following commands assume that users are working in the c-shell (csh):

setenv CQ_DIAG_TRACE "API;DB_CONNECT=2;DB_MISC;EMAIL;HOOKS=2;PERL;THROW;SQL=2"  
setenv CQ_DIAG_REPORT "MESSAGE_INFO=0x070B;DIAG_FLAGS=-1"
setenv CQ_DIAG_OUTPUT "/export/home/username/cq_diagnostics.log"

When diagnostic tracing is completed, turning off tracing by running the following commands from a system prompt:

unsetenv CQ_DIAG_TRACE
unsetenv CQ_DIAG_OUTPUT


The following statements would be used for the bash shell:

export CQ_DIAG_TRACE="API;DB_CONNECT=2;DB_MISC;EMAIL;HOOKS=2;PERL;THROW;SQL=2"  
export CQ_DIAG_REPORT="MESSAGE_INFO=0x070B;DIAG_FLAGS=-1"
export CQ_DIAG_OUTPUT="/export/home/username/cq_diagnostics.log"

unset CQ_DIAG_TRACE
unset CQ_DIAG_OUTPUT



Enable e-mail diagnostic tracing on ClearQuest Web 2003 UNIX-based servers running the Request Manager:

  1. On the server, modify the file start_cqrm.sh, which is found in the /opt/rational/clearquest/cqweb/cqserver directory. Note: If install directory is different than indicated, modifications will need to be made to accommodate your install directory. Un-comment these lines, or add them if they do not already exist.

    CQ_DIAG_TRACE="API;DB_CONNECT=2;DB_MISC;EMAIL;HOOKS=2;PERL;THROW;SQL=2"

    CQ_DIAG_REPORT="MESSAGE_INFO=0x070B;DIAG_FLAGS=-1"    CQ_DIAG_OUTPUT="/opt/rational/clearquest/cqweb/cqserver/logs/cq_diagnostics.log"
    export CQ_DIAG_TRACE
    export CQ_DIAG_REPORT
    export CQ_DIAG_OUTPUT
  2. Restart the web services.
  3. Reproduce the problem you are troubleshooting.
  4. Save file cq_diagnostics.log found in directory indicated above.
  5. Comment out these lines in start_cqrm.sh to turn off the diagnostics.
  6. Restart the web services.


Enabling e-mail diagnostic tracing on ClearQuest Web 7.0.x UNIX-based servers
  1. On the server, modify the file start_cqreg.sh, which is found in the /opt/rational/clearquest/cqweb/cqregsvr directory. Note: If install directory is different than indicated, modifications will need to be made to accommodate your install directory. Un-comment these lines, or add them if they do not already exist.

    CQ_DIAG_TRACE="API;DB_CONNECT=2;DB_MISC;EMAIL;HOOKS=2;PERL;THROW;SQL=2"
    CQ_DIAG_REPORT="MESSAGE_INFO=0x070B;DIAG_FLAGS=-1"
    CQ_DIAG_OUTPUT="
    /opt/rational/clearquest/cqweb/cqregsvr/logs/cq_diagnostics.log"
    export CQ_DIAG_TRACE
    export CQ_DIAG_REPORT
    export CQ_DIAG_OUTPUT
  2. Restart the web services.
  3. Reproduce the problem you are troubleshooting.
  4. Save file cq_diagnostics.log found in directory indicated above.
  5. Comment out these lines in start_cqreg.sh to turn off the diagnostics.
  6. Restart the web services.

Enabling e-mail diagnostic tracing on ClearQuest Web 7.1.x UNIX-based servers
  1. On the server, modify the file cqrpc.sh, which is found in the /opt/RationalSDLC/common/CM/bin directory. Note: If install directory is different than indicated, modifications will need to be made to accommodate your install directory. Un-comment these lines, or add them if they do not already exist.

    CQ_DIAG_TRACE="API;DB_CONNECT=2;DB_MISC;EMAIL;HOOKS=2;PERL;THROW;SQL=2"

    CQ_DIAG_REPORT="MESSAGE_INFO=0x070B;DIAG_FLAGS=-1"    CQ_DIAG_OUTPUT="/opt/RationalSDLC/common/CM/profiles/cmprofile/logs/cq_diagnostics.log"
    export CQ_DIAG_TRACE
    export CQ_DIAG_REPORT
    export CQ_DIAG_OUTPUT
  2. Restart the web services.
  3. Reproduce the problem you are troubleshooting.
  4. Save file cq_diagnostics.log found in directory indicated above.
  5. Comment out these lines in cqrpc.sh to turn off the diagnostics.
  6. Restart the web services.

Parameters and values used for tracing

Trace:
A semi-colon separated list of what we want to trace. For example:

"DB_CONNECT;EMAIL;MAILREAD;SQL"


Possible values for trace:

Parameter Type Comment
DB_CONNECT (Numeric) DB connection information 1:general info 2:show connection handle
DB_MISC (Numeric) Returns the output values returned by sql statements
EMAIL (Boolean) Email delivery
EMAIL_VB (Boolean) Email activity in VB (Windows-Only)
HOOKS (Boolean) General hook execution
MAILREAD (Boolean) Mailreader (Windows-Only)
PERL (Numeric) Perl engine. 1: general activity; 2: include script source
SQL (Numeric) All SQL statements. 1:general info 2:show connection handle that is executing sql
THROW (Boolean) Throwing PaMsgExceptions and PdExceptions and others
VBASIC (Boolean) Visual Basic Engine (Windows-Only)

Report:
A semi-colon separated list of what we want to report. For example:

"MESSAGE_INFO=0X401;PREFIX=CQDiagnostics"


Possible values for report:

Parameter Type Comment
DIAG_FLAGS (Numeric) Report state of the diagnostic mechanism at startup.
This is a mask value:
0x001 for behavior flags
0x002 for report flags
0x004 for trace flags
0x010 for all diagnostic environment variables
PREFIX (String) Set extra prefix for Report and PutLine. The string will appear in front of standard "[CQ]" prefix, and is useful to accommodate other filters.
MESSAGE_INFO (Numeric) Add additional information to each message prefix (after "CQ" inside the square brackets).
This is a mask value:
0x0001: message number
0x0002:
0x0100: time (in sortable format)
0x0200: date (in sortable format)
0x0400: seconds since initial debug message (secs)
0x0800: seconds since previous debug message (ticks)
0x1000: add label for each item in prefix
MESSAGE_LIMIT (Numeric) Set the message number at which to take the breakpoint path. For example MESSAGE_LIMIT=10000000 will limit the size of the output file to 10MB in size. This flag is useful when troubleshooting server related issues that may generate lots of output.
OUTPUT_LIMIT (Numeric) Set the message number at which to take the breakpoint path. For example OUTPUT_LIMIT=10000000 will limit the size of the output file to 10000000 message lines. This flag is useful when troubleshooting server related issues that may generate lots of output.

REGISTRY EDITS:

This solution contains information about modifying the system registry. Before making any modifications to the Microsoft Registry Editor, it is strongly recommended that you make a backup of the existing registry. For more information describing how to back up the registry, refer to Microsoft Knowledge Base article 256986


Related information

A simplified Chinese translation is available

Document information

More support for: Rational ClearQuest
E-Mail Configuration and Setup

Software version: 7.0, 7.0.1, 7.1, 7.1.1, 7.1.2, 2003.06.16

Operating system(s): AIX, HP-UX, Linux, Solaris, Windows

Reference #: 1231445

Modified date: 18 June 2009


Translate this page: