CQCC Source Code documentation


Tue Apr 9 11:33:22 2002

Dave Schlegel August 28, 2001 - ClearCase 5.0 GA release

1. Introduction

The Base Clearcase/ClearQuest Perl integration is provided in source code form because that is how Perl works. This allows customers an opportunity to make local source code changes to the integration to customize its behavior but it can also complicate product support for both Rational and your site. It is hoped that source code changes will not be needed at your site but if you feel they are absolutely necessary, your personnel need to accept responsibility for the local changes and work within Rational Support guidelines.

Source code documentation is provided to facilitate and guide any changes you feel are essential; following recommended practices will make it easier to work within our guidelines.

1.1. Rational Support Policy

Rational Support supports the new integration as provided and local configuration changes made using the parameters in the configuration file (config.pl).

For the 5.0 release, Rational will support both the new Perl integration and the existing Windows GUI integration based on Visual Basic. The Perl integration provided on UNIX with earlier releases (cqcc_trigger) will no longer be supported.

Rational does NOT support source code changes to the integration even though it is provided in source code form as Perl scripts; internal source code documentation is provided to enable local sites to make judicious changes if needed but Rational Customer Support can not and will not support local changes of this sort.

1.2. Source Code documentation files

For available documentation on the source code see the CQCC Source Code document contained in the source code documentation archive (cqcc_doc.tar.gz).

To open this archive run "gunzip" on the .gz file, then use Winzip(Windows) or tar (UNIX) to extract files from the archive. See the CQCC_Source.html file in that archive for an introduction to the available materials.

Each Perl class source file includes internal documentation on the class and its methods as POD (Plain Old Documentation) comments. These are then extracted and formatted as HTML files included in the source code documentation archive.

Also each Perl class file has embedded leader tags that allow it to be "folded" up in Emacs outline mode. If you use this editor, you can activate this feature by add the following command to your .emacs file then using M-x outline-mode to be able to view the file by folding it up to see only the method header lines: (setq outline-regexp `"#:+\\|:+")

2. Architecture overview

The CQCC integration is written as a series of interrelated object classes to provide modularity, extensibility, and reusability. Developers not familiar with using object oriented practices in Perl are referred to the the PERLTOOT topic (Tom's Object Oriented Tutorial for Perl) in the standard Perl documentation.

The overall class architecture is described in a separate document, CQCCarchitecture.doc, which provides a summary of each class and UML diagrams documenting the class and its methods in Rational Rose. See that document for more information on how the different classes work together.

2.1. TriggerCQCC class

If you want to look at the source code, start initially with config.pl which sets the local parameters then starts the trigger by calling into TriggerCQCC::TriggerMain.

Most of the "application" behavior is in the TriggerCQCC class, i.e. what happens on a checkout or checkin. This class instantiates a ClearCase interface object (CCase or CCPerlAPI) and a ClearQuest interface object (CQPerlAPI or CQWeb) and communicates with them to perform an operation. Support classes such as IOBase provide user interaction support. Class methods provide the main menu (MenuDisplay), interactive dialogs (Dialog_nnn), and specific actions (Action_Commit, etc) to carry out the work of the trigger.

There should be very little reason to wander into the source code for the ClearCase or ClearQuest classes. The methods they provide offer generic operation support. CCase::PostCommand("cmd") will send any cleartool command to the current Clearcase connection and return the results. The ClearQuest classes provide broad access to perform queries and modify record entities through their basic methods. Try to work within the existing class paradigm.

Support: Rational Support can not provide support for sites that wish to customize their own source code beyond changes to the config.pl file. Sites that do choose to modify the source code are strongly encouraged to modify the code by subclassing the target code and using the subclass instead of directly modifying the original Rational code. This approach will facilitate returning to a known baseline during problem diagnosis

3. Making local changes

3.1. Subclassing

It is very important for continuing Rational Support for this integration that you avoid making direct inline changes to the supported classes if at all possible. Subclassing allows your source code to "override" the support behavior in selective ways without modifying the original code directly.

For example to modify the behavior of TriggerCQCC, make a copy of the sample subclass file, "MyTrigger.pm" and rename it to the name you want for your class, i.e. "TriggerCompany.pm" where Company is the name of your company. Then copy the methods you want to override into the subclass file and make just the minimal changes you need there instead of in the original TriggerCQCC file. Then in your config file (config.pl) tell the trigger to use your subclass instead of TriggerCQCC.

Now if you find problems using your version of the trigger, commenting out this one line will return you to using the supported integration so you can better determine where the problem lies. This will make it much easier to import later Rational source code changes without overwriting your local source code.

3.2. Debugging

The trigger is started through the cqcc_launch startup script and this is the point you need to enable the debugger if you need to perform interactive debugging. Set CQCC_LAUNCH_DEBUG=2 to enable the debugger when the trigger script starts up.

Breakpoints are a basic debugger tool for stopping at preselected points in the source code during execution. Note that CCPerl does not appear to support breakpoints but CQPerl does - use CQPerl during most debugging if possible. The class names all begin with the name of their home directory, CQCC, so it is essential to include this prefix when setting breakpoints, i.e. "b CQCC::TriggerCQCC::Action_Commit."

Some classes are not loaded unless they are needed - CQPerlAPI, CQWeb, etc. This means you can't set breakpoints when the trigger first starts up. Set a breakpoint in the operation method you are working with (for example, "b CQCC::TriggerCQCC::Op_checkout") then step through the first few statements until the components you need to work with have been initialized. Then you can set the remaining breakpoints as needed. Alternatively you can (temporarily) you can force an early load of the target package by using a "use" statement in the config.pl file, i.e. "use CQCC::CQPerlAPI;" will preload the CQPerlAPI class and allow you to set breakpoints.

3.3. Message Catalog Translations

The Message Catalog class (MsgCat_English.pm) isolates all user visible messages and menu lines facilitating translations or site changes. Translations of this catalog should be done by following these steps:
  1. Make a copy of this file, naming it MsgCat_<language>.pm where <language> is the name of the target language.
  2. Inside the copy, replace all instances of MsgCat_English with MsgCat_<language>.
  3. In the copy, edit each &AddMsg call to change only the third parameter. The %s markers indicate where the arguments (second paramater list) will be placed. Do not change the order of these. Do NOT add double-quotes (") within the body of the messages.
  4. Test the translation printout as follows:
  5. Modify the config file (CQCC/config.pl) to use the new translation:


Generated by jfo2html from notes/source.otl on Tue Apr 9 11:33:22 2002