NOTE: These scripts have only been tested on Windows systems, and not on UNIX or heterogenous environments.
IBM Rational® ClearCase® is a Software Configuration Management (SCM) tool. ClearCase has been available for more than 10 years, and works on both the UNIX® and Windows® platforms, as well as heterogeneous environments. ClearCase has powerful command line interface and triggering functionalities, and can be easily customized to the needs of end users.
Unified Change Management (UCM) implements on top of ClearCase (and optionally IBM Rational ClearQuest), and provides a process workflow that dramatically simplifies parallel development.
Other SCM tools, such as Revision Control System or RCS, implement a feature called "keyword substitution," or "keyword expansion" as a way of identifying files that are added to source code over version control. These keywords are automatically updated during the checkout / checkin process. ClearCase does not implement this feature out of the box, and neither is it provided by UCM. The purpose of this document is to describe the necessary steps to install and use a new keyword substitution merge manager for ClearCase.
Example of such keywords are as follows:
Example of usage in a file called
/* $Author: ccadmin $ $Date: 2005-08-17 12:46:00 GMT $ $Header: @(#) \test_vob\test.c@@\main\1 2005-08-17 12:46:00 GMT ccadmin $ $Id: @(#) test.c@@\main\1 2005-08-17 12:46:00 GMT ccadmin $ $Name: test.c $ $Revision: \main\1 $ $Source: \test_vob\test.c $ */
ClearCase v2003.06.14 has been used in this document, as shown in the following output:
C:\>cleartool -ver ClearCase version 2003.06.00 (Fri Apr 18 13:06:18 2003) clearcase patch p2003.06.01 (Fri Sep 5 11:59:28 2003) clearcase patch p2003.06.12 (Fri Nov 7 11:59:28 2003) @(#) MVFS version 2003.06.10+ (Nov 12 2004 09:49:18) cleartool 2003.06.10+ (Mon Nov 15 21:06:24 2004) db_server 2003.06.10+ (Fri Nov 12 09:03:18 2004) VOB database schema version: 54 C:\>cleartool -verAll ClearCase version 2003.06.00 (Fri Apr 18 13:06:18 2003) clearcase patch p2003.06.01 (Fri Sep 5 11:59:28 2003) clearcase patch p2003.06.12 (Fri Nov 7 11:59:28 2003) @(#) MVFS version 2003.06.10+ (Nov 12 2004 09:49:18) cleartool 2003.06.10+ (Mon Nov 15 21:06:24 2004) libatriaadm 2003.06.10+ (Fri Nov 12 07:50:08 2004) libatriaccfs 2003.06.10 (Thu May 22 02:26:37 2003) libatriaclient_meters 2003.06.10+ (Fri Nov 12 08:12:29 2004) libatriacm 2003.06.10+ (Fri Nov 12 07:56:01 2004) libatriacmd 2003.06.10+ (Fri Nov 12 08:14:24 2004) libatriacmdsyn 2003.06.10+ (Fri Nov 12 08:15:37 2004) libatriacredmap 2003.06.10+ (Wed Jun 23 07:43:55 2004) libatriadbrpc 2003.06.10+ (Fri Nov 12 07:55:20 2004) libatriaks 2003.06.10+ (Fri Nov 12 07:47:23 2004) libatriamntrpc 2003.06.10+ (Fri Nov 12 08:16:22 2004) libatriamsadm 2003.06.10+ (Fri Nov 12 07:46:51 2004) libatriamvfs 2003.06.10 (Sat Apr 12 20:49:57 2003) libatriasplit 2003.06.10+ (Fri Nov 12 08:08:47 2004) libatriasum 2003.06.10+ (Tue Nov 2 08:03:34 2004) libatriasumcmd 2003.06.10+ (Fri Nov 12 08:11:08 2004) libatriatbs 2003.06.10+ (Fri Nov 12 07:48:58 2004) libatriatool 2003.06.10+ (Fri Nov 12 08:08:36 2004) libatriaview 2003.06.10+ (Fri Nov 12 08:08:02 2004) libatriavob 2003.06.10+ (Wed Dec 15 19:36:09 2004) libatriaxdr 2003.06.10+ (Fri Nov 12 07:50:32 2004) db_server 2003.06.10+ (Fri Nov 12 09:03:18 2004) VOB database schema version: 54
Special thanks go to:
- Stephen Gildea and David Kaelbling, first writers of the type manager
- Joerg Svensson (SVENSSON@de.ibm.com), who update the source code to make it work on ClearCase v2003.06
- ClearCase Team by Draeger (Germany), who requested this feature integrated into UCM
ClearCase has a type manager interface to implement ClearCase commands (such as, create version, merge, compare, etc.). This makes it easy to change some of the default behavior of ClearCase.
Here we are writing our own type manager, that is invoked over the
compare and merge operation in ClearCase. The type manager simply stores in some temporary place the version information, without the keyword substitution.
In addition to these instruction you will need the following files:
Table 1. List of merge manager files
|md.bat||Compilation script (debug mode)|
|manager.c||Source of the type manager|
|keyword_subst.pl||Trigger to use|
Compilation of the type manager (Windows)
- Copy all the files listed above to a directory called
- Edit the
md.batfile and the
m.batto adjust the path to the
vcvars32.bat(Microsoft Visual C++ compiler settings) and ClearCase installation directory paths
- Compile the
manager.exeprogram, by calling either
md.bat(debug mode). You should get a file created called
Copying the type manager
- Edit the
c.batfile to adjust the path to the ClearCase installation directory
Warning: You need to copy the new type manager to all the ClearCase clients and to the view server.
Modifying the map file
Edit the file
c:\Program Files\Rational\ClearCase\lib\mgrs\map, and add the following:
keyed_text_file_delta construct_version ..\..\bin\tfdmgr.exe keyed_text_file_delta create_branch ..\..\bin\tfdmgr.exe keyed_text_file_delta create_element ..\..\bin\tfdmgr.exe keyed_text_file_delta create_version ..\..\bin\tfdmgr.exe keyed_text_file_delta delete_branches_versions ..\..\bin\tfdmgr.exe keyed_text_file_delta compare ..\..\bin\ktfdcompare.exe keyed_text_file_delta xcompare ..\..\bin\ktfdcompare.exe keyed_text_file_delta merge ..\..\bin\ktfdcompare.exe keyed_text_file_delta xmerge ..\..\bin\ktfdcompare.exe keyed_text_file_delta annotate ..\..\bin\tfdmgr.exe keyed_text_file_delta get_cont_info ..\..\bin\tfdmgr.exe
keyword_subst.pl perl script to a common storage area for ClearCase triggers (for example, to a share on the server).
For each VOB that you want to use the new type manager, you need to create a new element type:
cleartool mkeltype -supertype text_file -manager keyed_text_file_delta -c "RCS keyword type" eltype:keyed_text_file@vob:<your-vob>
M:\test_view\test_vob>cleartool mkeltype -supertype text_file -manager keyed_text_file_delta -c "RCS keyword type" eltype:keyed_text_file@vob:\test_vob
Created element type "keyed_text_file"
Adjustment of elements
For each VOB that you want to use the new type manager, you need to create a new trigger type:
cleartool mktrtype -element -all -preop checkin -eltype keyed_text_file -execwin "ccperl \\<server>\<trigger_share>\keyword_subst.pl" KEYWORDSUBST
M:\test_view\test_vob>cleartool mktrtype -element -all -preop checkin -eltype keyed_text_file -execwin "ccperl \\titeuf\keyword\keyword_subst.pl" KEYWORDSUBST@\test_vob
Created trigger type "KEYWORDSUBST"
Adjustment of the element type
For all the elements that you want to use the new element type, enter:
cleartool chtype keyed_text_file <element_name>
M:\test_view\test_vob>cleartool chtype keyed_text_file test.txt
Change version manager and reconstruct all versions for "test.txt"? [no] yes
Changed type of element "test.txt" to "keyed_text_file"
Usage over compare
Over a compare, you should get the file diffs without any keyword substitution, as shown in Figure 1:
Figure 1. Comparing versions
Usage over merge (and deliver/rebase)
Over a merge (e.g. deliver and rebase), you should get the file diffs without any keyword substitution, as shown in Figure 2:
Figure 2. Merging versions
With this small utility, you can easily implement keyword substitution in ClearCase without any trouble, but it should be noted that:
- This has not been tested on UNIX
- The following RCS keywords are not supported: Log, Locker
- Line of source cannot be bigger then 8192 characters.
|Sample Perl scripts for this article||cc_merge_manager.zip||44KB|
- You may also be interested in Daniel Diebolt's developerWorks article about how to gather ClearCase and ClearQuest usage statistics: Dark License statistics usage tool.
- Read author Daniel Diebolt's developerWorks article about useful ClearCase triggers: IBM Rational ClearCase: The ten best triggers.
- Learn about some other useful scripts for ClearCase in author Daniel Diebolt's developerWorks article: ClearCase: The ten best scripts.
- Browse for books on these and other technical topics at the Safari bookstore.
- Software Configuration Management Strategies and IBM Rational ClearCase: A Practical Introduction (2nd edition, IBM Press 2005) by David Bellagio and Tom Milligan provides a comprehensive review of CM strategies and practices with a UCM focus. This second edition is the updated and expanded version of Brian White’s popular book.
Get products and technologies
- Find more resources for ClearCase users and administrators in the ClearCase area of the developerWorks Rational zone, including articles and whitepapers, plug-ins, scripts and triggers; and links to training, discussion forums, product documentation and support.
- To learn more about IBM Rational products, visit the developerWorks Rational zone. You'll find technical documentation, how-to articles, education, downloads, product information, and more.
- Find a user group in your area from the Rational Global User Group Community. Rational User Groups are independent, user-run organizations that provide an open forum to promote information exchange between customers and Rational staff.
- The ClearCase discussion forum on developerWorks is a great place to post questions and get answers about configuration management and UCM with IBM Rational ClearCase.