CQCC Source Code documentation
Dave Schlegel August 28, 2001 - ClearCase 5.0 GA release
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.
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.
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 `"#:+\\|:+")
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.
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
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.
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.