SUMMARY: V2 Base ClearCase/ClearQuest Integration FAQ TROUBLESHOOTING TIPS: 1. Introduction The new Perl-based Base Clearcase/ClearQuest integration (V2) provides a number of improvements over the existing Perl UNIX trigger. It also provides a viable alternative to the existing Visual Basic Windows trigger, to customer sites that require extensive customization or features that are in the new integration. The new integration also brings with it some complicated issues that need to be understood to provide effective support for it. * Platform context: On UNIX, the new integration provides more functionality than the current implementation so the V1 integration is being deprecated. On Windows, the initial lack of a GUI interface made V2 less attractive; with the new GUI available in the 2002B patch this should become less of an issue, though there are some feature differences. * Multiple ClearQuest APIs: Support for ClearQuest access using either CQWeb or CQPerl APIs provides more functionality for both platforms but may cause confusion in initial customer setup. * Integration source code: Perl programs are provided in source code form and we will provide additional internal source documentation on request through support. But support needs to avoid getting drawn into customer changes to source code. Internal comments encourage any local source code changes to be made by subclassing the official release. If problems are reported to support, this will make it easier to drop back to the supported release. * Object oriented Perl: Some administrators may be a little overwhelmed by object-oriented Perl programming - for more information they should see "Tom's Object-Oriented Tutorial for Perl (perltoot)", available with most Perl distributions or at www.perldoc.com. * Performance: Performance will continue to be an issue with the new integration in some sites and circumstances; ClearQuest login will be one culprit. Built in analysis should help pin down where the time is going but we may not have immediate solutions. 2. Frequently Asked Questions 2.1. General 1. Where do administrators go to configure the integration ? * /lib/perl5/CQCCTrigger/CQCC/config.pl is the commented configuration file and the README in the same folder will provide a more extensive description of some its options as well as release notes. 2. Is the V2 integration available for ClearCase 4.2 ? * Yes it is available for ClearCase 4.2 in the 2002A patch. Both CC 4.2 and CC 5.0 will provide a GUI interface in the 2002B patch. 3. Is there some way to change an association after the file is checked in ? * Use the "edit" operation. "cqcc_launch -op edit" will prompt you for a vob name and extended pathname to the file that you want to change then it will bring up the menu or GUI as if you were checking in the file. Because the V1 and V2 integrations store associations the same way, this operation can be used against the V1 integration as well. Note: The edit is subject to the RESTRICTIONS query defined for your site and may prevent you from making new associations with closed or completed defects. 2.2. How to tell which version is running: 1. How can I distinguish V1 (old) from V2 (new) ? * (Windows) V1 provides an extensive GUI including buttons for New Record and Build Query * (UNIX) V1 Perl provides a typein window only with * doing query, ? showing help, 0 aborting, etc. * (Both) V2 Perl will either present a text or clearprompt menu including Database and Record Type options. When available, the new GUI provides buttons for Refresh, Type in IDs, Database and Record Type but not for New Record. 2. How can support identify different versions of V2 ? * Patches: Each class file that makes up the integration has a version tag at the beginning of the file ("sub Version { return '2.0';}). The initial release was labeled as version 2.0, and the updated GUI release 1is labeled as 2.1. 2.3. Confirming ClearQuest access outside the integration 1. How can I verify a CQWeb connection is working ? * Pre-test: Use a web browser to log into http:/// where is the name of the CQWeb server host and is the main entry page, usually "CQWeb". A ClearQuest login page should appear; if it doesn't check the configuration of your CQWeb server. * Configure the server information: Set the environment variables, CQCC_SERVER (server) and CQCC_SERVERROOT (serverroot) or the same variables set in the config.pl file. 2. How can I verify that the CQPerlAPI connection is working ? (if ClearQuest is installed, this is the default) * Setup: * (Windows) Use the ClearQuest Maintenance tool to set the current database repository or create a new connection. * (UNIX) Use environment variables if needed for non-standard repository locations; defaults should usually work. * Test: Run ClearQuest and it should show the entry to the current repository, showing databases and confirming logins. 2.4. Installation 1. How do I confirm ClearQuest is ready for the integration ? * Test: Look at a sample entity record in the target database - should show ClearCase tab in output display, otherwise not installed. If you fail to do this you will get an error message saying the cc_change_set entity was not found. 2. Does the Clearcase VOB have triggers enabled (use config tool) ? * Test: Use the ClearQuest integration config tool to see which triggers are installed on a particular VOB (the executable names are different enough that the tool can recognize V1 vs V2). 3. Does the Clearcase VOB have triggers enabled (using cleartool) ? * Test: cleartool describe trtype:cq_co_trigger (after cd to view/vob, etc) * (error): Nothing is installed * cqtrigger_coci.exe: V1 VB/GUI trigger is installed * cq_trigger: V1 UNIX Perl trigger is installed * cqcc_launch: (may have .bat) V2 Perl trigger is installed 4. Is there some way to install the triggers on a UNIX platform without using the Windows CQConfig tool ? * We currently only support UNIX installations using CQConfig which provides customization and reliability. It is possible to do this on UNIX if needed. * On Windows, use cqconfig (CC Admin/Integrations/ClearQuest etc) to configure the triggers for a dummy vob the way you want them. * Using cleartool, type "lstype -kind trtype" to see the current triggers and "describe trtype:" to see the details on each. You may see differences in the -element call, added branch restrictions, etc. * write a bat file that will apply the same triggers and the hltype to the UNIX vobs. Depending on the options you have selected it should look something like this: * (Note if hltype:CrmRequest already exists you don't need to change it) * mkhltype -shared -c "ClearQuest Integration" CrmRequest * rmtype -rmall trtype:cq_co_trigger@\ * rmtype -rmall trtype:cq_ci_trigger@\ * rmtype -rmall trtype:cq_unco_trigger@\ * rmtype -rmall trtype:cq_postci_trigger@\ * mktrtype -element -all -preop checkin -execwin "cqcc_launch.bat CQCC\config.pl -entitydef defect " -execunix "cqcc_launch CQCC/config.pl -entitydef defect " -c "ClearQuest Integration" cq_ci_trigger@\ * mktrtype -element -all -postop checkin -execwin "cqcc_launch.bat CQCC\config.pl -postop -entitydef defect " -execunix "cqcc_launch CQCC/config.pl -postop -entitydef defect " -c "ClearQuest Integration" cq_postci_trigger@\ * mktrtype -element -all -postop checkout -execwin "cqcc_launch.bat CQCC\config.pl -postop -entitydef defect " -execunix "cqcc_launch CQCC/config.pl -postop -entitydef defect " -c "ClearQuest Integration" cq_co_trigger@\ * mktrtype -element -all -preop uncheckout -execwin "cqcc_launch.bat CQCC\config.pl -entitydef defect " -execunix "cqcc_launch CQCC/config.pl -entitydef defect " -c "ClearQuest Integration" cq_unco_trigger@\ 2.5. Configuration confirmation 1. Why can't I see my database or record types on the menu lists ? * The config.pl file is set to SAMPL:Defect by default and must be changed to identify which databases and record types are association enabled. * Test: Look at config.pl for following: * CQCC_DATABASE_ENTITY_LIST: (Database: entity list) pairs describing which databases can have associations and which entities are supported for each. The names are case sensitive, so make sure they match the actual names you are using. 2. What Database access is expected by the integration ? * If ClearQuest is NOT installed on client, it will use ccperl and the CQWeb interface, looking for CQCC_SERVER and CQCC_SERVERROOT to be set as environment or configuration variables. * Else if ClearQuest IS installed on client it will use cqperl and the CQPerlAPI interface, looking for same database ClearQuest Maintenance tool is pointing us at (Windows) or same database XClearQuest attaches to on UNIX * UNLESS the CQCC_CQWEB_ONLY is turned on as configuration parameter then it will use cqperl and CQWeb access as above. 3. How do I handle multiple schema repositories ("database sets") ? * If you get a list of schema repositories when you attempt to connect you need to tell the configuration file which database set to use through the CQCC_DATABASE_SET and the CQCC_WEB_DATABASE_SET parameters. 2.6. Common errors 1. Why doesn't the GUI show up ? * The V2 GUI depends on a number of factors to enable it to be used: * The right version of the V2 trigger has to be installed providing the IOPerlTK.pm and related packages (2002B patch and beyond). * The client must have ClearQuest (2002.05.00) installed in order to get access to the Perl/TK package that provides the widgets. The trigger has to use cqperl (version 5.6 or above). * The config.pl file has to permit using the GUI (CQCC_GUI_ENABLE is not set to off) 2. The GUI Browse button (or the menu QUERYNAME option) only shows "local" queries and not the queries defined in the ClearQuest workspace. * CQWeb - the workspace queries are not accessible through the CQWeb API so only local queries will be shown. * CQPerlAPI - the CQCC_QUERY_ENABLE config parameter is disabled by default; see the details in config.pl. 3. After I hit "OK", I get a fatal error message about "object that does not exist ... cc_change_set". * You are trying to make associations to a record type that does not have the ClearCase schema package applied to it. See Installation Confirmation section above. 4. In UNIX, I have ClearQuest client installed and the CQWeb interface isn't working * The cqperl executable with UNIX ClearQuest doesn't support sockets needed by the CQWeb interface. You must use the ccperl that comes with ClearCase instead. Setting the environment variable "CQCC_LAUNCH_CCPERL" to 1 will force the integration to only use ccperl to work around the problem. NOTE: This will disable being able to use the V2 GUI since it only works with cqperl. 2.7. Debugging aids Note: These debugging variables are available in the initial release of V2 but were only documented in the later GUI based release in the config.pl file. 1. Where does debugging information go, particularly when using ClearCase Explorer ? * config.pl:CQCC_LOG_OUTPUT=v (Easiest way to grab session prompts and error log) * OFF: no log file * OVERWRITE: overwrite %TMPDIR%\cqcc_output.log on each trigger invocation, including checkin post operation trigger. * APPEND: append to current cqcc_output.log file as above. Best used only for diagnosis, otherwise log file will eventually grow too large. 2. How are debugging messages turned on or off ? * Using environment variables. On UNIX, "setenv CQCC_DEBUG n" and on Windows, "set CQCC_DEBUG=n" where n is one of the following: * 0: default/off * 1: basic debugging statements * 2: more detailed, including all global parameter settings * Note: On Windows command prompt, "set CQCC_DEBUG=2", etc will work. But if using ClearCase Explorer, you must make changes in System/Environment tab for them to affect new processes. Restart ClearCase Explorer after changing variables. 3. How can performance problems be isolated at a local site ? * Using environment variables: On UNIX, "setenv CQCC_TIMER n" and on Windows, "set CQCC_TIMER=n" where n is one of the following: * 0: default/off * 1: timing report for fundamental operations at end of log Expect to spend a chunk of time loading the CQPerlAPI package and logging into the ClearQuest database. 2.8. Information caching 1. Where is user information cached between trigger sessions ? * The V2 integration does not use any registry values but stores several information files in the user's home directory or user profile area. * Windows: %USERPROFILE% is usually c:\winnt\profiles\\Applications Data\ Rational\cqcc. * UNIX: Files are stored in the user's home directory (~username). 2. What user information is saved between trigger sessions ? * %USERPROFILE%\.cqparams (ClearQuest login information) * %USERPROFILE%\cqcc_cache (cached state information between trigger invocations) Consists of parameter name=value pairs in plain text * %TMPDIR%\cqcc_output.log - output log for most recent trigger invocation. same information is displayed in cleartool command line mode but most is not seen in ClearCase Explorer/ClearPrompt mode 2.9. Local customization 1. What changes does Rational support at local sites ? * Rational supports config.pl changes only (see the "Rational Support Policy" section) 2. Where is there more information on the source code ? * See cqcc_doc.tar.gz (see attachments) for README, architectural overview and class documentation files. 3. How can Support validate that the local site is running supported source code rather than their own customized version ? * CQCC_DEBUG=2 will show class names. If the local site is subclassing their local changes as recommended, you will see different classnames in the parameter listing (nnnInterface=class). Rational Customer Service Policies and Information: http://www.rational.com/support/info.jsp