Ccint Ddts

CLEARCASE CLEAR DDTS
INTEGRATION
Release 4.0 and later
Windows/UNIX Edition
800-013104-000
ClearCase Clear DDTS Integration
Document Number 800-013104-000 December 1999
Rational Software Corporation 20 Maguire Road Lexington, Massachusetts 02421
IMPORTANT NOTICE
Copyright Notice
Copyright © 1992, 1999 Rational Software Corporation. All rights reserved.
Copyright 1989, 1991 The Regents of the University of California
Copyright 1984–1991 by Raima Corporation
Copyright 1992 Purdue Research Foundation, West Lafayette, Indiana 47907
Trademarks
Rational, the Rational logo, Atria, ClearCase, ClearCase MultiSite, ClearCase Attache, Clear DDTS,
ClearQuest, ClearGuide, PureCoverage, Purify, Quantify, Rational Rose, and SoDA are trademarks or
registered trademarks of Rational Software Corporation in the United States and in other countries. All other
names are used for identification purposes only and are trademarks or registered trademarks of their
respective companies.
Microsoft, MS, ActiveX, BackOffice, Developer Studio, Visual Basic, Visual C++, Visual InterDev, Visual J++,
Visual Studio, Win32, Windows, and Windows NT are trademarks or registered trademarks of Microsoft
Corporation.
Sun, Solaris, and Java are trademarks or registered trademarks of Sun Microsystems, Inc.
Oracle and Oracle7 are trademarks or registered trademarks of Oracle Corporation.
Sybase and SQL Anywhere are trademarks or registered trademarks of Sybase Corporation.
U.S. Government Rights
Use, duplication, or disclosure by the U.S. Government is subject to restrictions set forth in the applicable
Rational License Agreement and in DFARS 227.7202-1(a) and 227.7202-3(a) (1995),
DFARS 252.227-7013(c)(1)(ii) (Oct 1988), FAR 12.212(a) 1995, FAR 52.227-19, or FAR 52.227-14, as applicable.
Patent
U.S. Patent Nos. 5,574,898 and 5,649,200 and 5,675,802. Additional patents pending.
Warranty Disclaimer
This document and its associated software may be used as stated in the underlying license agreement, and,
except as explicitly stated otherwise in such license agreement, Rational Software Corporation expressly
disclaims all other warranties, express or implied, with respect to the media and software product and its
documentation, including without limitation, the warranties of merchantability or fitness for a particular
purpose or arising from a course of dealing, usage or trade practice.
Technical Acknowledgments
This software and documentation is based in part on BSD Networking Software Release 2, licensed from the
Regents of the University of California. We acknowledge the role of the Computer Systems Research Group
and the Electrical Engineering and Computer Sciences Department of the University of California at Berkeley
and the Other Contributors in its development.
This software and documentation is based in part on software written by Victor A. Abell while at Purdue
University. We acknowledge his role in its development.
/vobs/doc/ccase/integrat/ddts/ddtsTTL.fm — November 15, 1999 3:28 pm

Contents
Preface ........................................................................................................................................xi
About This Manual ...........................................................................................xi
ClearCase Documentation Roadmap ............................................................xii
Typographical Conventions ......................................................................... xiii
Technical Support .......................................................................................... xiv
1. Installing the ClearCase ClearDDTS Integration ......................................................... 1

1.1 Overview of the Installation Process............................................................... 1
1.2 Checking Disk Space Availability.................................................................... 2
1.3 Installing the Integration on UNIX.................................................................. 2
1.4 Installing the Integration on a Windows NT System.................................... 2
1.5 Setting Up the Environment for Your Site and Users................................... 3
Windows NT ClearCase/CRM Integration ................................................... 5
Setting Up the Environment for Attache Users ............................................. 6
PATH Variables for the Windows NT Helper........................................ 7
PATH Variables for the UNIX Helper ..................................................... 7
1.6 Preparing VOBs for Use by the Integration ................................................... 8
1.7 Configuring ClearDDTS Projects to Use ClearCase...................................... 9
1.8 Preparing User Environments for the Integration ........................................ 9
Setting up an Alternate Policy File .................................................................. 9
Reducing Interactions with the Integration ................................................. 10
1.9 Removing the ClearCase ClearDDTS Integration ....................................... 10
2. Overview of the Integration............................................................................................. 11

2.1 Extending ClearCase’s checkout/checkin Model ....................................... 11
Command-Line and Graphical Interfaces .................................................... 13
2.2 Using xddts’ Configuration Management Menu ........................................ 14
2.3 vob_prep Modifies ClearCase Databases ..................................................... 15
Integrating New VOBs .................................................................................... 15
2.4 Using ClearCase MultiSite with the Integration.......................................... 16
Contents iii
/vobs/doc/ccase/integrat/ddts/ddtsTOC.fm — November 15, 1999 3:34 pm

2.5 Reporting Capabilities .....................................................................................16
2.6 Configuration and Customization .................................................................17
Bug Tasks ...........................................................................................................17
3. ClearCase-to-ClearDDTS Communications ................................................................19

3.1 checkout Triggers .............................................................................................20
Pre-checkout Trigger........................................................................................20
Post-checkout Trigger ......................................................................................21
Failure Modes....................................................................................................22
3.2 checkin Triggers................................................................................................23
Pre-checkin Trigger ..........................................................................................23
Post-checkin Trigger.........................................................................................24
Changing the Defect Identifier .......................................................................25
Failure Modes....................................................................................................25
3.3 uncheckout Triggers.........................................................................................26
Pre-uncheckout Trigger ...................................................................................26
Post-uncheckout Triggers................................................................................26
Failure Modes....................................................................................................27
4. Using the ClearCase ClearDDTS Integration from Windows NT ...........................29

4.1 Using the Integration from Visual C++.........................................................29
4.2 Using the Integration from the Windows Explorer.....................................31
5. Using the ClearCase ClearDDTS Integration from the Command Line ...............33
5.1 Typical Bugfixing Session ...............................................................................33
5.2 Working on Multiple Bugs at the Same Time ..............................................36
5.3 Setting Up a Bug Task......................................................................................37
5.4 Cancelling Work In Progress ..........................................................................38
5.5 Bypassing the Integration................................................................................39
5.6 Suppressing Interactions at checkout/checkin ............................................39
Specifying Defect Identifiers at checkout Only............................................39
Specifying Defect Identifiers at checkin Only ..............................................40
5.7 Recovering from ClearDDTS Update Failures.............................................40
iv ClearCase ClearDDTS Integration

6. Reporting Commands....................................................................................................... 43
6.1 The find_fixes Command................................................................................ 43
6.2 The find_wip Command ................................................................................. 45
6.3 Generating Reports with ClearCase Commands......................................... 46
Using Attribute Queries .................................................................................. 46
Using Configuration Records......................................................................... 46
6.4 Putting it All Together with ClearDDTS ...................................................... 47
A. The Policy File and Environment Variables ............................................................... 49

A.1 Changing the Original Policy File.................................................................. 49
A.2 Creating and Using Additional Policy Files................................................. 49
Creating a New Policy File ............................................................................. 50
A.3 Policy File Variables......................................................................................... 51
A.4 Environment Variables.................................................................................... 53
Contents v

vi ClearCase ClearDDTS Integration

Figures
Figure 1 Setting Key Policy Variables for the Windows NT Integration ......................6
Figure 2 Updating ClearCase and ClearDDTS Databases ............................................ 12
Figure 3 ClearCase Interfaces to the UNIX ClearCase ClearDDTS Integration.........13
Figure 4 One ClearCase Interface to the Windows NT ClearDDTS Integration........14
Figure 5 xddts Configuration Management Submenu .................................................. 15
Figure 6 Examining a CM Events Enclosure ................................................................... 16
Figure 7 Checkout Trigger Mechanism............................................................................ 22
Figure 8 Check-in Mechanism........................................................................................... 25
Figure 9 Checking out a File using Developer Studio and the Integration ................30
Figure 10 Checking the Status of a Defect ......................................................................... 34
Figure 11 Rechecking the Status of a Defect after Several Fixes..................................... 36
Figure 12 Typical Mail Message to ClearDDTS Administrator...................................... 41
Figure 13 Complex Version Tree with FIXES Attributes................................................. 44
Figures vii
/vobs/doc/ccase/integrat/ddts/ddtsLOF.fm — November 15, 1999 3:34 pm

viii ClearCase ClearDDTS Integration
/vobs/doc/ccase/integrat/ddts/ddtsLOF.fm — November 15, 1999 3:34 pm

Tables
Table 1 Trigger Types ....................................................................................................... 19

Table 2 Attribute Types for Versions.............................................................................. 20
Table 3 Policy File Variables ............................................................................................ 51
Table 4 Environment Variables ....................................................................................... 53
Tables ix
/vobs/doc/ccase/integrat/ddts/ddtsLOT.fm — November 15, 1999 3:34 pm

x ClearCase ClearDDTS Integration
/vobs/doc/ccase/integrat/ddts/ddtsLOT.fm — November 15, 1999 3:34 pm

Preface
This document describes the Integration of ClearCase configuration management system with
the Clear DDTS defect tracking system. The integration lets you associate ClearCase VOB
element versions with Clear DDTS requests. This version of the Integration provides remote
integration, which supports users who run ClearCase on systems that do not support Clear
DDTS. This Integration also supports users who employ Attache to access ClearCase VOBS.
About This Manual
This manual is for users of the ClearCase Clear DDTS Integration and for administrators who are
responsible for tasks such as installing the software and using or demonstrating its facilities.
Preface xi
ClearCase Documentation Roadmap
Project
Development Management
Developing Managing
Software with Projects with
ClearCase ClearCase
Orientation
Introduction to
ClearCase
ClearCase and
MultiSite Release
Notes ClearCase Build
ClearCase Administration Management
Tutorials
Administering ClearCase
ClearCase OMAKE Manual
(Windows)
ClearCase
Product Family Building
Installation Notes Software with
ClearCase
ClearCase
MultiSite Manual
More Information
ClearCase Reference
Manual
ClearCase Quick
Reference Guide
ClearCase Online Help
clearcase.rational.com
xii ClearCase ClearDDTS Integration

Typographical Conventions
This manual uses the following typographical conventions:
➤ ccase-home-dir represents the directory into which the ClearCase Product Family has been
installed. By default, this directory is /usr/atria on UNIX and
C:\Program Files\Rational\ClearCase on Windows.
➤ attache-home-dir represents the directory into which ClearCase Attache has been installed.
By default, this directory is C:\Program Files\Rational\Attache, except on Windows 3.x,
where it is C:\RATIONAL\ATTACHE.
➤ Bold is used for names the user can enter; for example, all command names, file names, and
branch names.
➤ Italic is used for variables, document titles, glossary terms, and emphasis.
➤ A monospaced font is used for examples. Where user input needs to be distinguished
from program output, bold is used for user input.
➤ Nonprinting characters are in small caps and appear as follows: <EOF>, <NL>.
➤ Key names and key combinations are capitalized and appear as follows: F1, SHIFT,
CTRL+G.
➤ [] Brackets enclose optional items in format and syntax descriptions.
➤ {} Braces enclose a list from which you must choose an item in format and syntax
descriptions.
➤ | A vertical bar separates items in a list of choices.
➤ ... In a syntax description, an ellipsis indicates you can repeat the preceding item or line
one or more times. Otherwise, it can indicate omitted information.
NOTE: In certain contexts, ClearCase recognizes “...” within a pathname as a wildcard, similar
to “*” or “?”. See the wildcards_ccase reference page for more information.
➤ If a command or option name has a short form, a “medial dot” ( ⋅ ) character indicates the
shortest legal abbreviation. For example:
lsc·heckout
Preface xiii
This means that you can truncate the command name to lsc or any of its intermediate
spellings (lsch, lsche, lschec, and so on).
Technical Support
If you have any problems with the software or documentation, please contact Rational Technical
Support via telephone, fax, or electronic mail as described below. For information regarding
support hours, languages spoken, or other support information, click the Technical Support link
on the Rational Web site at www.rational.com.
Your Location Telephone Facsimile Electronic Mail
North America 800-433-5444 408-863-4194 support@rational.com

toll free or Cupertino, CA
408-863-4000 781-676-2460
Cupertino, CA Lexington, MA
Europe, Middle +31-(0)20-4546-200 +31-(0)20-4546-201 support@europe.rational.com

East, and Africa Netherlands Netherlands
Asia Pacific 61-2-9419-0111 61-2-9419-0123 support@apac.rational.com

Australia Australia
xiv ClearCase ClearDDTS Integration

1 Installing the ClearCase ClearDDTS
Integration
1
This document describes Release 4.0 of the ClearCase® ClearDDTS Integration (the Integration),
which integrates the ClearCase configuration management system with the ClearDDTS defect
tracking system. This Integration is a layered product that requires both ClearDDTS and
ClearCase.
The Integration lets you associate ClearCase VOB element versions with ClearDDTS requests.
ClearCase users execute standard version-control commands (checkout, checkin, uncheckout).
These commands cause software triggers to execute trigger scripts in remote shells on ClearDDTS
host or hosts, providing ClearCase event history information and pathnames to VOB elements
that have been modified to address ClearDDTS requests.
Because the Integration is configurable using the file policy_vars.sh, the exact nature of user
interaction with the Integration varies. In general, however, when users execute a cleartool
checkout, they are prompted for the bug numbers of the requests they intend to address. When
they execute a cleartool checkin of their versions, ClearCase may prompt for additional
information.
This version of the Integration provides remote integration, supporting users who run ClearCase
on systems such as Windows NT that do not support ClearDDTS.
1.1 Overview of the Installation Process

ClearCase runs on both UNIX and Windows NT systems. ClearDDTS runs only on UNIX
systems. The ClearCase ClearDDTS Integration allows you to use ClearDDTS with ClearCase
1 - Installing the ClearCase ClearDDTS Integration 1

from either UNIX or Windows NT (including by means of Attache). Using the Integration from
Windows NT requires that the Integration also be installed on UNIX.
1.2 Checking Disk Space Availability

The Integration software has the following approximate disk space requirements:
➤ 800KB on the network-wide UNIX host for the release area
➤ 745KB for the installation directory, which will also be on a UNIX host
➤ 745KB on any Windows NT system to contain the software prior to installation
➤ 25KB additional space on Windows NT systems to contain the software after the
installation
1.3 Installing the Integration on UNIX

The ClearCase ClearDDTS Integration is installed on UNIX in the same way as ClearCase,
MultiSite, and other related products. Please see ClearCase Product Family Installation Notes for
instructions on installing all these products.
1.4 Installing the Integration on a Windows NT System

To install the remote Integration on a Windows NT system:
1. On a UNIX system, populate a release area as described in ClearCase Product Family

Installation Notes.
2. Create a directory on the Windows NT system, such as C:\cc_ddts_int, to contain the files
from Step #3.
3. Copy the files from the ClearDDTS release directory

release_area/architecture/bugtrack/nt_install on the UNIX system to the directory created in
Step #2 on the Windows NT system.
2 ClearCase ClearDDTS Integration

4. On the Windows NT system, run the setup.exe program you just copied. A dialog box will
appear, and it will take you through the following steps.
5. Supply a pathname for a directory to receive the installation on the Windows NT system.
The default is c:\Program Files\Rational\ClearCase. On Windows NT, this value is
automatically used to define the environment variable ATRAIAHOME
6. Let setup.exe install the trigger scripts in %ATRIAHOME%\bugtrack\install.
1.5 Setting Up the Environment for Your Site and Users

Once you have installed the Integration, you must take steps to see that your users’
environments are properly set up on both UNIX and Windows NT and that your site’s needs are
accommodated as reflected in the policy files.
Please see The Policy File and Environment Variables on page 49 for a full explanation of policy files
and environment variables.
1. Make sure the environment variable ATRIAHOME is defined. This is commonly defined as
/usr/atria on UNIX systems and as c:\Program Files\Rational\ClearCase on Windows NT
systems. ATRIAHOME is defined automatically on Windows NT and by default on UNIX
systems, but you should check because the usual directories are not necessarily those used
at your site.
2. Make sure the environment variable PATH includes $ATRIAHOME/bugtrack for every
UNIX system using the integration or %ATRIAHOME%\bugtrack for every Windows NT
system using the Integration as well as the host ClearDDTS system.
3. In each ClearCase user’s environment on systems that do not support ClearDDTS, which
includes all Windows NT systems, define the following environment variables:
➣ BUGTRACK_PROXY_HOST — specifies the host on which the trigger scripts are to execute.
This can be any valid hostname.
➣ BUGTRACK_PROXY_USER — specifies the username under which the scripts are to

execute. This can be any valid username.
When the ClearCase user executes a checkin, checkout, or uncheckout command, the
appropriate software trigger causes a trigger script to execute by means of a remote shell
command, rsh hostname –l username script. The bugtrack proxy variables for host and user

must be set on systems that don’t support ClearDDTS, because the variables specify how the
remote shell executes.
NOTE: On systems that do support ClearDDTS, you may define the proxy variables, but if
you do, they will cause an rsh to be executed, and this is generally not necessary. (However,
you may wish the scripts to execute using a different username, in which case you should
define the variables.)
4. Make sure that each user on the unsupported ClearDDTs platform has the ability of remote
shell access, that is, rsh access to the UNIX machine
Another environment variable is provided for platforms on which rsh is replaced by some
other command, such as remsh:
➣ BUGTRACK_RSH_COMMAND — Specifies the command to be used to execute shell

commands to the remote BUGTRACK_PROXY_HOST.
This command can (and probably should) include references to the other local policy
environment variables BUGTRACK_PROXY_HOST and BUGTRACK_PROXY_USER. The
default command is:
rsh $BUGTRACK_PROXY_HOST –l $BUGTRACK_PROXY_USER
NOTE:Please see Windows NT ClearCase/CRM Integration on page 5 for information about a

GUI applet that defines these variables on Windows NT.
NOTE: Please see Setting Up the Environment for Attache Users on page 6 for information about
defining these variables for Attache users.
5. On each ClearDDTS host that will run the integration, copy the policy files from their
installed locations to locations searched by the Integration. The files are initially installed in
a ddts directory, but the Integration looks for them in the bugtrack directory. (This is so you
can customize the files in bugtrack for your installation while retaining the originals in ddts
in case you want to customize further. If they remained in ddts, they’d be overwritten.)
To prepare the policy files for use by the integration:
a. Copy them from their installed locations to the $ATRIAHOME/bugtrack directory, for
example:
# cp $ATRIAHOME/ddts/policy_vars.sh $ATRIAHOME/bugtrack
# cp $ATRIAHOME/ddts/local_policy.pl $ATRIAHOME/bugtrack

b. Edit them so that the policy environment variables defined there are appropriate for
your site policies and system parameters. Please see The Policy File and Environment
Variables on page 49 for more information.
6. On the ClearCase host for the Integration:
a. Copy the local policy file from its installed location to the $ATRIAHOME/bugtrack
directory, for example:
# cp $ATRIAHOME/ddts/local_policy.pl $ATRIAHOME/bugtrack
b. Edit the policy file to define a directory to be used by the ClearCase scripts to keep
temporary files.
This is done by defining the local policy file variable CCTEMP. The default is /usr/tmp or
C:\TEMP. Please see The Policy File and Environment Variables on page 49 for more
information.
7. Run vob_prep over any VOBs that are to be integrated with ClearDDTS. (See Preparing VOBs
for Use by the Integration on page 8.)
Windows NT ClearCase/CRM Integration
The ClearCase/CRM Integration is a GUI applet for setting key policy variables for the
ClearCase ClearDDTS integration is available at My Computer➔Control Panel➔CRM
Integration.
Use it to set BUGTRACK_PROXY_HOST, BUGTRACK_PROXY_USER and BUGTRACK_RSH_COMMAND. as

discussed in Setting Up the Environment for Your Site and Users on page 3 and as described fully in
The Policy File and Environment Variables on page 49.
You can also provide the location of an alternate policy file, as described in Setting up an Alternate
Policy File on page 9.
Finally, this applet allows you to run vob_prep, which is described in Preparing VOBs for Use by
the Integration on page 8.

Figure 1 Setting Key Policy Variables for the Windows NT Integration
Setting Up the Environment for Attache Users
In order for the integration to work, the ws_helper requires certain environment variables set.
There are two methods for defining environment variables for the helper:
➤ Define the variables in a ws_startup script in ATRIAHOME. See the ws_helper reference page
for more information.
➤ Define the variables in an .attache.env file located in your home directory on the helper host
using entries of the form VARIABLE=value.
The environment variables are the same for both Windows NT and UNIX helpers, except for the
PATH statements:
BUGTRACK_PROXY_HOST= hostname
BUGTRACK_PROXY_USER=username
Another environment variable is provided for platforms on which rsh is replaced by some other
command, such as remsh:

➤ BUGTRACK_RSH_COMMAND — Specifies the command to be used to execute shell
commands to the remote BUGTRACK_PROXY_HOST.
This command can (and probably should) include references to the other local policy
environment variables BUGTRACK_PROXY_HOST and BUGTRACK_PROXY_USER. The default
command is:
rsh $BUGTRACK_PROXY_HOST –l $BUGTRACK_PROXY_USER
PATH Variables for the Windows NT Helper
Create the .attache.env file from the command line:
echo > .attache.env
Set the PATH environment variable as follows, replacing ccase-home-dir with the pathname of the
ClearCase installation directory:
PATH=%SystemRoot%\system32:ccase-home-dir\bin:ccase-home-dir\bugtrack
For example:
PATH=c:\winnt\system32:c:\atria\bin:c:\atria\bugtrack
PATH Variables for the UNIX Helper
Set your PATH environment variable as follows, replacing ccase-home-dir with the pathname of the
ClearCase installation directory:
PATH=ccase-home-dir/bin:ccase-home-dir/bugtrack:/bin
For example:
PATH=/usr/atria/bin:/usr/atria/bugtrack:/bin
NOTE: If your rsh command is not located in /bin (use which rsh to check), replace /bin with the
location of rsh.

1.6 Preparing VOBs for Use by the Integration
The vob_prep utility prepares VOBs for use with the Integration. You must be in a view when
you run vob_prep. Start vob_prep as follows, on UNIX and Windows NT, respectively:
# $ATRIAHOME/bugtrack/install/vob_prep vob-tag
> %ATRIAHOME %\bugtrack\install\vob_prep vob-tag
vob_prep accepts one or more VOB-tags.
On Windows NT systems, you can also use the ClearCase/CRM Integration applet, as described
in Windows NT ClearCase/CRM Integration on page 5.
The ClearCase ClearDDTS Integration either applies to all of the elements in a VOB or applies to
none. You cannot select individual elements or subtrees. If several VOBs reside on a host, you
can choose to have the Integration control some of them, and not others.
For example:
# $ATRIAHOME/bugtrack/install/vob_prep /vobs/proj
Installing types for ClearCase DDTs Integration into /vobs/proj.

----------------------------------------------------------------
Created trigger type "ddts_pre_co_trig".

Created trigger type "ddts_post_co_trig".
Created trigger type "ddts_pre_ci_trig".
Created trigger type "ddts_post_ci_trig".
Created trigger type "ddts_pre_unco_trig".
Created trigger type "ddts_post_unco_trig".
Created attribute type "WIP".
Created attribute type "FIXES".
vob_prep complete.

1.7 Configuring ClearDDTS Projects to Use ClearCase
For each existing ClearDDTS project you wish to integrate with ClearCase, use the ClearDDTS
command adminbug mprj to set clearcase as the project’s configuration management system.
You can also establish this setting when creating a new ClearDDTS project with adminbug aprj.
For details, see the ClearDDTS Administrator’s Guide.
1.8 Preparing User Environments for the Integration

To use the ClearCase ClearDDTS Integration, change your shell start-up file:
➤ Optionally add the ClearDDTS executables directory to the search path. See the search
paths discussion in the ClearDDTS Administrator’s Guide.
➤ Review the instructions in Setting Up the Environment for Your Site and Users on page 3 and
Preparing VOBs for Use by the Integration on page 8.
Setting up an Alternate Policy File
If you are using remote integration (executing the software trigger scripts on a remote host), you
may wish to use a policy file other than the standard one you copied into the bugtrack directory.
To do this, modify your shell start-up script to specify the pathname of the alternate file:
Environment Command
C shell setenv ALT_POLICY policy-file-pathname
Bourne shell ALT_POLICY=policy-file-pathname ; export ALT_POLICY
Windows NT set ALT_POLICY=policy-file-pathname
On Windows NT systems, you can also use the ClearCase/CRM Integration applet, as described
in Windows NT ClearCase/CRM Integration on page 5.

For information on policy files, see The Policy File and Environment Variables on page 49.
Reducing Interactions with the Integration
You can control how often the Integration prompts you to specify defect identifiers, either
specifying identifiers through environment variables, or bypassing the Integration altogether.
See Bypassing the Integration on page 39 and Suppressing Interactions at checkout/checkin on page 39.
1.9 Removing the ClearCase ClearDDTS Integration

To remove the ClearCase ClearDDTS Integration:
1. Use the vob_prep utility to remove trigger types from VOBs as follows, on UNIX and
Windows NT respectively:
# $ATRIAHOME/bugtrack/install/vob_prep –deinstall /vobs/proj1 (UNIX)
> %ATRIAHOME%\bugtrack\vob_prep –deinstall \projs (Windows NT)
2. Use the install_release script to remove the Integration from installation directories.
3. Remove the release area from the ClearCase network-wide release host. For example:
# rm –r release_area/ccase.ddts_v4.0
4. Remove the %ATRIAHOME%\bugtrack directory from Windows NT systems.

2 Overview of the Integration
2
ClearCase is a comprehensive software configuration management system. ClearCase
AttacheTM supports ClearCase on Windows platforms. ClearDDTS tracks and manages software
change requests. The ClearCase ClearDDTS Integration uses standard interfaces provided by the
ClearCase and ClearDDTS:
➤ ClearCase and Attache users execute standard version-control commands (checkout,

checkin, uncheckout). The integration uses ClearCase triggers associated with these
commands to communicate with ClearDDTS.
➤ ClearDDTS users invoke ClearCase version-control commands using the standard CM

(configuration management) pull-down menu from ClearDDTS. Users may examine
ClearCase-related information by opening enclosures attached to defect records.
This chapter assumes that you have a general familiarity with both ClearCase and ClearDDTS.
Specific areas for review include ClearCase meta-data and setting up projects in ClearDDTS. In
this document, references to ClearCase refer to Attache as well.
NOTE: In this chapter, the command-line examples are from UNIX, but the syntax is almost the
same on Windows NT. The only difference is that the UNIX examples the pathnames have
slashes (/). To make the examples correct for Windows NT, users must substitute backslashes (\)
in pathnames wherever there are slashes.
2.1 Extending ClearCase’s checkout/checkin Model

The checkout/checkin model is ClearCase’s standard mechanism for managing the growth of an
element’s version tree:
2 - Overview of the Integration 11

➤ checkout creates an editable copy of a file in your view
➤ checkin adds a new version to the element’s version tree
➤ uncheckout cancels the checkout of an element.
The ClearCase ClearDDTS Integration extends this model to include information relating to
defects (bugs). When checking out a file, you enter one or more defect identifiers. The check out
succeeds only if the identifiers match existing defect records in the ClearDDTS database.
Information about the check out is recorded in a ClearCase versioned object base, or VOB, in the
form of an event record and an attribute; it is recorded by ClearDDTS in the form of an entry in the
CM events enclosure of the defect record. (See Figure 2 and note that the entries written to the
CM events enclosure are also written to the History enclosure.)
Figure 2 Updating ClearCase and ClearDDTS Databases
ClearCase
versioned object ClearCase
Events
base (VOB)
WIP="HODts01209"
scripts provided with the
ClearCase ClearDDTS
integration extract
bug-related information
ClearCase commands from VOBs
update VOB database with
event records and attributes
at the same time,

ClearCase triggers update
ClearDDTS database with
transaction that appears in Defect Record
the defect’s enclosures
standard ClearDDTS
procedures perform
History CM Events
queries and produce
ClearDDTS
configuration
database
management activity
reports
When checking in a file, you enter one or more defect identifiers again. This begins the same
validation sequence that was performed before: the check in succeeds only if corresponding
ClearDDTS defect records exist. Both the VOB database and the ClearDDTS CM events enclosure
are updated to reflect the change in the file’s condition.

Not every checkin constitutes a fix, however. You can create checkpoint, or intermediate, versions
of a file during the course of bugfixing work. Only the final version is marked as fixing the bug,
not the intermediate versions. Similarly, you can mark intermediate versions as fixing some of the
bugs you originally associated with the file, but not others.
You can also cancel a checkout with the uncheckout command, removing information about the
checkout from the VOB database and updating the ClearDDTS CM events enclosure.
Command-Line and Graphical Interfaces
ClearCase includes both a command-line interface (cleartool) and graphical user interfaces
(xclearcase for UNIX and a several graphical user interfaces for Window NT). You can use any
of these interfaces with the integration. (Figure 3 shows the differences between command line
and GUI in a UNIX environment.)
Figure 3 ClearCase Interfaces to the UNIX ClearCase ClearDDTS Integration
command-line
interface
UNIX graphical
interface

Figure 4 One ClearCase Interface to the Windows NT ClearDDTS Integration
For more information on using the ClearCase ClearDDTS Integration on Windows NT systems,
please see Chapter 4, Using the ClearCase ClearDDTS Integration from Windows NT on page 29
2.2 Using xddts’ Configuration Management Menu

The xddts defect window, which displays summary information on an individual defect,
includes a CM (configuration management) submenu (Figure 5). Installing the integration on a
host causes the Check In, Check Out, and UnCheck Out selections on this submenu to invoke
the appropriate ClearCase commands. (See Configuring ClearDDTS Projects to Use ClearCase on
page 9.) The UnCheck In and Version Init selections are not used.

Figure 5 xddts Configuration Management Submenu
2.3 vob_prep Modifies ClearCase Databases

Integrating ClearCase with ClearDDTS involves making modifications to one or more ClearCase
VOBs. The vob_prep utility creates attribute types and trigger types in a VOB to support the
integration. As developers use the integration, attributes are attached to versions to track their
involvement in bugfixing work. Triggers invoke the procedures through which ClearCase
communicates with ClearDDTS.
No modifications are made in the ClearDDTS database. Standard ClearDDTS interfaces and data
structures are used by the Integration.
Integrating New VOBs
You can integrate new VOBs with ClearDDTS without reinstalling the Integration. The vob_prep
utility can be run at any time, on a new VOB or on an existing one.

2.4 Using ClearCase MultiSite with the Integration
The ClearCase ClearDDTS Integration is compatible with the ClearCase MultiSite product. The
integration must be installed separately at each site. Likewise, individual replicated VOBs must
be processed with vob_prep at each site.
NOTE: The Integration’s triggers are not propagated among replicas by the MultiSite syncreplica
command.
On the other hand, the integration’s attributes, WIP and FIXES, will be propagated to all of a
VOB’s replicas, even those at sites where the integration is not installed. Such attributes can be
modified at multiple sites, because the attribute types are always created as shared
(object-mastered) types.
2.5 Reporting Capabilities

ClearDDTS users can examine a CM events enclosure in the standard manner, by locating the
associated defect record and opening the enclosure (Figure 6).
Figure 6 Examining a CM Events Enclosure
ClearCase users can use scripts to track the involvement of elements and versions in bugfixing
activity:
➤ The find_wip script lists versions to which the WIP attribute (meaning work-in-progress) is
attached. For example:
% find_wip base.c
base.c@@/main/CHECKEDOUT "HODts45343"
base.c@@/main/ports/2 "HOSts10990"

➤ The find_fixes script lists every bug that a particular version of an element fixes, using
values of the FIXES attribute. For example:
% find_fixes base.c
HODts45343
XYZcd87878
NOTE: Each version’s FIXES attribute can list multiple bugs — unless this capability is
suppressed by setting the policy variable MULTIPLE_BUGS to false. In addition, a version
implicitly fixes a bug if it is a descendant of the version whose FIXES attribute explicitly
names that bug.
For details, see Chapter 6, Reporting Commands.
2.6 Configuration and Customization

The ClearCase ClearDDTS Integration enables enforcement of software maintenance policies
through its policy file (policy_vars.sh, by default). This file contains shell commands that set
environment variables used by the integration’s shell scripts, including the trigger action scripts.
For example, one policy variable controls whether you must supply a defect identifier when
checking out or checking in an element.
You can specify an alternate policy file by means of environment variables. This makes it easy for
different workgroups (or even individual users) to use different policies. For example, a
particular group might use an alternate policy file that specifies a different script for validating
defect identifiers.
For more information on the policy file, please see Appendix A, The Policy File and Environment
Variables.
Bug Tasks
On UNIX systems, the defect identifiers to be associated with a checkin, checkout, or

uncheckout can be specified in your environment, eliminating the need for prompting by a
trigger action script. This capability is packaged in the bug_task utility.
bug_task creates the following:

➤ a shell set to a particular view
➤ TASK_BUGNUM, an environment variable set to a particular list of defect identifiers
NOTE: Any setting of TASK_BUGNUM is overridden by settings for CI_BUGNUM and

CO_BUGNUM.
In this shell, you never need to enter defect identifiers; instead, the trigger action scripts
automatically use the TASK_BUGNUM value.
The bug_task utility is not available for Windows NT systems.

3 ClearCase-to-ClearDDTS
Communications
3
ClearCase triggers, Perl scripts, and a program named cm2ddts (a standard interface to
ClearDDTS) implement ClearCase-to-ClearDDTS communications.
The vob_prep utility creates a set of global element trigger types in a specified VOB database. This
has the effect of attaching triggers to all elements in that VOB.
Table 1 Trigger Types
Trigger Name Type and Action
ddts_pre_co_trig pre-checkout trigger; fires before any element in the VOB is checked
out
ddts_post_co_trig post-checkout trigger; fires after any element in the VOB is

successfully checked out
ddts_pre_ci_trig pre-checkin trigger; fires before any element in the VOB is checked in
ddts_post_ci_trig post-checkin trigger; fires after any element in the VOB is

successfully checked in
ddts_pre_unco_trig pre-uncheckout trigger; fires before a checkout of any element in the

VOB is cancelled
ddts_post_unco_trig post-uncheckout trigger; fires after a checkout of any element in the

VOB is successfully cancelled
3 - ClearCase-to-ClearDDTS Communications 19
Each trigger runs a Perl script. Using the standard ClearCase mechanism, the pre-operation
triggers cancel the ClearCase operation if you specify any invalid defect identifier.
The trigger action scripts manage attributes of type FIXES and WIP on versions of elements
involved in bugfixing work. Each attribute value is a character string that lists one or more
ClearDDTS defect identifiers.
Table 2 Attribute Types for Versions
Attribute Type Type and Action
FIXES A version’s FIXES attribute lists bugs that are fixed by that particular
version. For example, if version /main/r4.1_fix/12 of an element fixes
two bugs, that version gets a FIXES attribute with a value like
"PRJxx09458 PRJxy02272".
WIP A checked-out version’s WIP attribute lists bugs that will be fixed by
some successor version. A WIP attribute on a checked-in version
indicates that it is an intermediate checkpoint version — some
successor version will complete the fix.
To create checkpoint versions, you can have the integration propagate WIP attributes to one or
more intermediate versions. When you finally declare that a particular checkin fixes a bug, that
version gets a FIXES attribute with the defect identifier or identifiers. In addition, the WIP
attributes on all the checkpoint versions of that element are adjusted to remove the appropriate
defect identifiers. (If appropriate, the attributes are removed altogether.)
3.1 checkout Triggers

The checkout triggers enable you to attach a WIP attribute to the checked-out version of a file or
directory element, and to make a corresponding entry in one or more CM events enclosures. The
attribute’s value, a list of defect identifiers, is either read from your environment or prompted for.
Pre-checkout Trigger
The pre-checkout trigger ddts_pre_co_trig fires each time a checkout command is invoked on
an element in a VOB that has been processed with vob_prep.

On UNIX systems, you can check out elements through cleartool, xclearcase, or the Check Out
selection on the ClearDDTS CM menu.
On Windows NT systems, you can check out elements in many ways, including using the
Windows Explorer, the Visual C++ Integration, and Visual Basic Integration,.
The pre_co_trig trigger action script establishes a list of defect identifiers to be associated with
the checked-out version:
➤ If the CO_BUGNUM (higher precedence) or TASK_BUGNUM (lower precedence, available only

in UNIX) environment variable is set, its value is used. (See Bypassing the Integration on
page 39 and Suppressing Interactions at checkout/checkin on page 39.)
➤ Otherwise, the script prompts you to enter one or more identifiers. If the version being
checked out has a WIP attribute, the script offers the attribute value as the default. Entering
an asterisk (*) displays a list of all unresolved defect identifiers assigned to you.
If you don’t wish to associate any defect identifiers with the checked-out version, enter the
no-bugfix character string (by default, the single digit 0). This suppresses creation of the WIP
attribute by the post-operation trigger.
However the list of identifiers is established, the script then issues a bugval command to verify
the existence of the identifiers in the ClearDDTS database. If every such identifier exists, the
trigger action script exits with a success status, and the checkout proceeds.
Post-checkout Trigger
The post-checkout trigger ddts_post_co_trig attaches an attribute of type WIP to the

checked-out version, with the list of defect identifiers as its value (a character string). Then, it
invokes a cm2ddts command to update the CM events enclosures of the ClearDDTS defect
records.
Figure 7 illustrates how the checkout trigger action scripts function.
Figure 7 Checkout Trigger Mechanism
ClearDDTS
database Defect Report
CM Events
cleartool checkout foo.c
pre-operation trigger:
establishes list of defect identifiers
(for example, HODts0004)
bugval
Everything OK? check out succeeds!
cm2ddts
post-operation trigger:
attaches WIP attribute
and updates CM Events enclosure
ClearCase
Events
ClearCase WIP=HODts00004
VOB foo.c@@/main/CHECKEDOUT
database
Failure Modes
If any of the specified defect identifiers does not exist, the pre_co_trig script exits with a failure
status, and the checkout is cancelled. If the CM events enclosure cannot be created after a
successful checkout, the post_co_trig script sends mail to the user specified by
BUGTRACK_ADMIN, as defined in the policy file, explaining the problem and showing the failed
commands, which can be rerun subsequently. (For details, see section Recovering from ClearDDTS
Update Failures on page 40.)

3.2 checkin Triggers
The checkin triggers let you attach a FIXES attribute to a new version of a file or directory
element, and to make a corresponding entry in one or more CM events enclosures. The
attribute’s value, a list of defect identifiers, is either read from your environment or you are
prompted for it.
Typically, WIP attributes are also manipulated, to indicate that certain bugfix work is no longer
in progress.
Pre-checkin Trigger
The pre-checkin trigger fires each time checkin is invoked on an element.
On UNIX systems, you can check in elements through cleartool, xclearcase, or the Check Out
selection on the ClearDDTS CM menu.
On Windows NT systems, you can check in elements in many ways, including using the
Windows Explorer, Visual C++ Integration, or Visual Basic Integration.
The trigger action script establishes a list of defect identifiers to become the value of the FIXES
attribute on the checked-in version:
➤ If the CI_BUGNUM (higher precedence) or TASK_BUGNUM (lower precedence, available only

in UNIX) environment variable is set, its value is used. (See Bypassing the Integration on
page 39 and Suppressing Interactions at checkout/checkin on page 39.)
➤ Otherwise, the script prompts you to enter one or more identifiers. If the version being
checked in has a WIP attribute, the script offers the attribute value as the default. Entering
an asterisk (*) displays a list of all unresolved defect identifiers assigned to you.
A typical response is to accept the default by pressing <RETURN>. This means, “This version
fixes all the bugs I was working on.” Another typical response is to type some, but not all, of
the identifiers in the WIP value. This means, “This version fixes just some of the bugs I was
working on.” But the list can include any valid identifiers, even ones not in the checked-out
version’s WIP value.
Entering the no-bugfix character string (by default, the single digit 0) implements a
checkpoint: no FIXES attribute is created; the WIP attribute (if any) on the checked-out
version is carried forward to the newly checked-in version.
However the list of identifiers is established, the script issues a bugval command to verify the
existence of the identifier or identifiers in the ClearDDTS database. If every such identifier exists,
the script stores the list in a temporary file, for use by the post-operation trigger. It then exits with
a success status, allowing the checkin to proceed.
Post-checkin Trigger
The post-checkin trigger ddts_post_ci_trig invokes a script that attaches an attribute of type
FIXES to the checked-in version, and sometimes attaches a WIP attribute, as well:
➤ The list of identifiers retrieved from the temporary file becomes the value of the FIXES
attribute.
➤ If the checked-out version has a WIP value, the FIXES identifiers are removed from the
WIP value. If any identifiers still remain (that is, if you didn’t fix all the bugs), the shorter
list becomes the WIP value of the new version.
NOTE: The WIP values on the predecessors of the checked-out version are also adjusted by
removing the FIXES identifiers. This ensures that no version’s WIP value names a bug that
has already been fixed.
Then, the script invokes a cm2ddts command to update the CM events enclosure of the
ClearDDTS defect record.
Figure 8 illustrates how the checkin trigger action scripts function.

Figure 8 Check-in Mechanism
ClearDDTS
database Defect Report
cleartool checkin foo.c CM Events
pre-operation trigger: verifies that

checked-out version has WIP attribute
pre-operation trigger requests and bugval

verifies defect identifier
(for example, HODts0004)
cm2ddts
Everything OK? check in succeeds!
post-operation trigger replaces WIP

attribute with FIXES attribute
and updates CM Events enclosure
ClearCase
Events
ClearCase FIXES=HODts00004
VOB foo.c@@/main/3
database
Changing the Defect Identifier
The pre_ci_trig script does not require that the identifier you specify on checkin match the one
you specified on checkout (as recorded in the WIP attribute). If you change identifiers, the CM
events enclosure for one defect will have a checkout entry but no corresponding checkin entry.
Likewise, the CM events enclosure for the other defect will have a checkin entry but no
corresponding checkout entry.
Failure Modes
If the specified defect identifier does not exist, the pre_ci_trig script exits with a failure status,
and the checkin is cancelled. If the CM events enclosure cannot be created after a successful
checkin, the post_ci_trig script sends mail to the user specified by BUGTRACK_ADMIN, as defined
in the policy file, explaining the problem and showing the failed commands, which can be rerun
subsequently.
3.3 uncheckout Triggers

The uncheckout triggers update one or more CM events enclosures with uncheckout records.
Pre-uncheckout Trigger
The pre-uncheckout trigger ddts_pre_unco_trig fires each time an uncheckout command is

invoked on an element.
On UNIX systems, you can cancel the checkout of an element through cleartool, xclearcase, or
the UnCheck Out selection on the ClearDDTS CM menu.
On Windows NT systems, you can cancel the checkout of an element in many ways, including
using the Windows Explorer, Visual C++ Integration, Visual Basic Integration, or cleartool.
The trigger action script determines whether the version whose checkout is to be cancelled has
a WIP attribute. If so, it stores the value of the attribute — one or more defect identifiers — in a
temporary file, for use by the post-operation trigger script.
Post-uncheckout Triggers
The post-uncheckout trigger ddts_post_unco_trig fires after an uncheckout command has been
successfully executed on an element. The trigger action script uses the contents of the temporary
file to invoke a cm2ddts command, updating the CM Events enclosure of the ClearDDTS defect
record.
If the checked-out version did not have a WIP attribute, then both the pre- and post-uncheckout
triggers are essentially no-ops.
NOTE: Thereis no need for a trigger action script to remove a WIP attribute. The uncheckout
command itself deletes the attribute along with the checked-out version.

Failure Modes
If the CM events enclosure cannot be created after a successful uncheckout, the post_unco_trig
script sends mail to the user specified by BUGTRACK_ADMIN, as defined in the policy file,
explaining the problem and showing the failed commands, which can be rerun subsequently.
4 Using the ClearCase ClearDDTS
Integration from Windows NT
4
This chapter presents usage scenarios for the ClearCase ClearDDTS Integration on Windows NT.
Once you have the ClearCase ClearDDTS Integration on your ClearCase Windows NT host, you
can continue to interact with ClearCase as you normally would. You will be prompted at
appropriate times (checkin/checkout) for information regarding the bug you are working on. In
this chapter, there are examples using the Visual C++ and File Manager graphical interfaces on
a Windows NT system. For examples of command line use, see the next chapter.
In these scenarios, a problem has been assigned at least one ClearDDTS defect identifier, known
as a bug. The fix involves several source files, including test.c.
➤ In the first example, using the Visual C++ Developer Studio, one developer begins work on
test.c, periodically issuing checkin and checkout commands from the menu bar or
right-button popup menu.
➤ In the second example, developer uses the Windows NT File Manager to select files to
checkout, before using an editor on them, and uses the File Manager to check the file back
in using the checkin command.
4.1 Using the Integration from Visual C++

Periodically, a developer uses the ClearCase Visual C++ Integration to select a file for checkout
and later for checkin. When this happens:
➤ The ClearCase Visual C++ Integration allows ClearCase to respond to the

ClearCase➔Checkout command on the Windows NT system running ClearCase
4 - Using the ClearCase ClearDDTS Integration from Windows NT 29

➤ The ClearCase ClearDDTS Integration triggers the remote rsh shell on the UNIX
ClearDDTS host, and uses it to pass the bug number and comment to ClearDDTS
This activity involves the following steps:
1. The developer checks out test.c by highlighting the file in the Project View of the Visual C++
Developer Studio, and selecting the Tools➔Source Control ➔Checkout item from the menu
bar.
2. This action produces a sequence of two popup menus that ask for:
➣ a comment (this popup is not shown in Figure 9)
➣ the bug, that is, the ClearDDTS defect identifier (this popup is shown in Figure 9)
Figure 9 Checking out a File using Developer Studio and the Integration
The comment and bug number are remembered in the WIP attribute of the checked-out file
and used as default values for the checkin. If there is more than one bug number, they can

all be entered at the prompt as long as they are separated by a space, as in DRKen00002
DRKen00003.
3. The developer edits test.c and checks it back in by selecting Tools➔Source

Control➔Checkin from the menu bar. Again, the same sequence of popups asks for:
➣ a comment, which defaults to the one given at checkout
➣ the bug number, defaulting to the bug number given at checkout
4. The lower-left corner of the Visual C++ Developer Studio window shows whether the file is
being checked in or out. There is also a Source Control tab that shows the output from
checkout and checkin operations.
4.2 Using the Integration from the Windows Explorer

Periodically, another developer uses the Windows Explorer to select a file for checkout and later
for checkin. When this happens:
➤ the ClearCase Windows Explorer Integration allows ClearCase to respond to the File
Manager’s ClearCase➔Checkout command on the Windows NT system running
ClearCase
➤ the ClearCase ClearDDTS Integration triggers the remote rsh shell on the UNIX ClearDDTS
host, and uses it to pass the bug number and comment to ClearDDTS
This activity involves the following steps:
1. Check out test.c:
2. Use the Windows Explorer to navigate to and select the file you want to check out.
3. Click the right mouse button over the file to display its context menu.
4. From the context menu, select ClearCase➔Checkout.
5. ClearCase displays dialog boxes asking for:
➣ a comment
➣ a bug, that is, the ClearDDTS defect identifier (This is the same as shown in Checking out
a File using Developer Studio and the Integration on page 30.)
4 - Using the ClearCase ClearDDTS Integration from Windows NT 31

The comment and bug number are saved in the WIP attribute of the checked-out file and
used as default values for the checkin. If there is more than one bug number, enter them
separated by a space, as
DRKen00002 DRKen00003
6. Edit test.c, compile and run it, and check it back in by selecting ClearCase➔Checkin from
the file’s context menu. You will again be prompted for:
➣ a comment, which defaults to the one given at checkout
➣ the bug number, defaulting to the bug number given at checkout.

5 Using the ClearCase ClearDDTS
Integration from the Command Line
5
This chapter presents typical usage scenarios for the ClearCase ClearDDTS Integration using the
command line and cleartool. The examples are from UNIX, but they work the same way on
Windows NT systems if you choose to use the command line there. Keep in mind that pathnames
in the UNIX examples use slashes (/). If you wish to follow the examples in Windows NT, you
must substitute backslashes (\) for slashes in pathnames.
5.1 Typical Bugfixing Session

A problem has been assigned ClearDDTS defect identifier DRKen00003. The fix involves several
source files, including parse_base.h. Using ClearCase, a developer begins working on this
element. Periodically, a software support engineer monitors the bugfixing activity with
ClearDDTS. The comments and questions printed as system output come from the triggers
provided by the ClearDDTS Integration.
1. The developer checks out parse_base.h, and types in the defect identifier:
% cleartool checkout –nc parse_base.h

Enter bugs to fix in this version. (0 for none) DRKen00003
Created attribute “WIP” on (ClearCase update)
“/vobs/ctrack_test/parse_base.h@@/main/CHECKEDOUT”.
Checked out “parse_base.h” from version “/main/1”
2. After editing the file, she checkpoints it with checkin, entering the no-bugfix character
string:
5 - Using the ClearCase ClearDDTS Integration from the Command Line 33

% cleartool checkin –c "checkpoint" parse_base.h
Enter bugs fixed in this version. (0 for none) [DRKen00003] 0
Checked in “parse_base.h” version “/main/2”.
3. Using ClearDDTS, a support engineer checks ClearCase activity on defect DRKen00003. The
CM events enclosure (Figure 10) shows that parse_base.h has been checked out. The
checkpoint checkin performed in Step #2 is not reflected in the enclosure. (Any checkout or
checkin of any other elements associated with defect DRKen00003 will also appear in this
enclosure.)
Figure 10 Checking the Status of a Defect
4. The developer checks out parse_base.h again, to continue working on defect DRKen00003;
however, she does not need to type the defect identifier again, since it is offered as the
default:
% cleartool checkout –c "resume conditionalizing work" parse_base.h

Enter bugs to fix in this version. (0 for none) [DRKen00003]
Created attribute “WIP” on (Clearcase update)
“/vobs/ctrack_test/parse_base.h@@/main/CHECKEDOUT”.
Checked out “parse_base.h” from version “/main/2”.
5. Before getting to work, she uses the find_wip utility to see if parse_base.h is being edited to
fix any other bugs:

% find_wip parse_base.h
parse_base.h@@/main/5 "DRKen00003" (No activity since developer’s last check in)
parse_base.h@@/main/CHECKEDOUT "DRKen00003"
6. The developer repeats the checkout-then-checkpoint cycle (Step #1 and Step #2) a couple of
more times, creating more versions on the main branch of parse_base.h.
7. The support engineer checks the defect status again (Figure 7). Since ClearDDTS does not
maintain information on checkpoint checkins, the CM events enclosure show several
checkout entries, but no checkin entries.
8. The developer checks in parse_base.h, indicating that it fixes defect DRKen00003:
% cleartool checkin –c "conditionalized parameters" parse_base.h

Enter bugs fixed in this version. (0 for none) [DRKen00003]
Created attribute “FIXES” on “/vobs/ctrack_test/parse_base.h@@/main/3”.
Removed attribute “WIP” from “/vobs/ctrack_test/parse_base.h@@/main/3”.
Removed attribute “WIP” from “/vobs/ctrack_test/parse_base.h@@/main/2”.
Checked in “parse_base.h” version “/main/3”. (Databases were successfully updated)
9. The developer verifies that the bugfix was recorded in the VOB:
% find_fixes parse_base.h
DRKen00003

Figure 11 Rechecking the Status of a Defect after Several Fixes
last entry shows most recent checkin
5.2 Working on Multiple Bugs at the Same Time

This scenario is similar to the preceding one. In this case, the developer’s source file changes will
fix more than one bug: defects DRKen00003 and DRKen00002 both require a change to source file
parse_base.h.
1. The developer checks out parse_base.h, and types in the defect identifiers:
The developer can invoke Report➔Describe➔Object at this point (or, click the
magnifying-glass icon) to show the value of the WIP attribute.

2. The developer edits parse_base.h to fix one of the bugs, but not the other. When she checks
in the file, the trigger script offers both the defect identifiers; she edits the input field to
indicate DRKen00003 only.
3. Later, the developer checks out parse_base.h again, to fix the remaining bug. She accepts
DRKen00002 as the value for the WIP attribute to be attached to the checked-out version.
4. After editing parse_base.h to implement the bugfix, she performs a final checkin, accepting
the offer to make a FIXES attribute on the new version with DRKen00002 as its value.
5.3 Setting Up a Bug Task

NOTE: The bug_task utility is not supported on Windows NT.
A developer is assigned to work on defect XYZcd45990. The fix involves several files, so she
decides to set up a bug task to make the job easier. The project leader has instructed everyone to
make fixes in the bugfix view.
1. The developer runs the bug_task utility to establish task parameters and start the task:
% bug_task
What bug will you be working on? (0 for none) XYZcd45990
What view will you be using? [arb] bugfix
Starting task to fix bug "XYZcd45990" in view "bugfix".
Please exit shell when done.
2. She checks out the first of several files involved with the fix:
% cleartool checkout –nc main.c (No defect identifier required)

Created attribute "WIP" on "main.c@@/main/CHECKEDOUT"
Checked out "main.c" from version "/main/5".
3. She checks in the file when ready:

% cleartool checkin –c "fixed init error" main.c (Again, no defect identifier required)
Removed attribute "WIP" from "/src/salome/src/main.c@@/main/6".
Created attribute "FIXES" on "/src/salome/src/main.c@@/main/6".
Checked in "main.c" version "/main/6".
4. When all files have been checked in, she terminates the bug_task by exiting the process:
% exit
% cleartool pwv
Working directory view: arb
Set view: arb
5.4 Cancelling Work In Progress

A developer checks out a file with the wrong defect identifier, and cancels the checkout.
1. She performs the checkout, specifying defect XYZcd55590 by mistake:
% cleartool checkout –nc base.c

Enter bugs to fix in this version. (0 for none) XYZcd55590
Created attribute "WIP" on "base.c@@/main/CHECKEDOUT"
Checked out "base.c" from version "/main/1".
2. She checks the file’s status with find_wip, and realizes the mistake:
% find_wip base.c
base.c@@/main/CHECKEDOUT WIP XYZcd55590
3. She cancels the checkout, and checks the file’s status again:
% cleartool uncheckout –rm base.c

Checkout cancelled for "base.c". (Uncheckout record also written to DDTS events enclosure)
% find_wip base.c
There are no WIP attributes on this element.

5.5 Bypassing the Integration
A new project has started, and the development team wants to bypass the integration
mechanism altogether. (They will not be fixing bugs!) In the shell start-up file, each team member
sets the TASK_BUGNUM environment variable to 0 (the character string specified by the
BUG_NONE variable in the policy file — see Appendix A, The Policy File and Environment Variables):
C shell: setenv TASK_BUGNUM 0

Bourne shell: TASK_BUGNUM=0; export TASK_BUGNUM
Windows NT: set TASK_BUGNUM=0
In addition, the policy file variables BUGNUM_REQ_CO and BUGNUM_REQ_CI must both be set to
FALSE if the integration is to be bypassed.
NOTE: The value of TASK_BUGNUM may also be a bug number. Any setting of TASK_BUGNUM is
overridden by settings for CI_BUGNUM and CO_BUGNUM.
5.6 Suppressing Interactions at checkout/checkin

By default, a developer is prompted for defect identifiers both when checking out a file, and when
checking it back in. Setting up a bug task (as described in Setting Up a Bug Task on page 37)
suppresses both these interactions. This section describes alternative strategies.
Specifying Defect Identifiers at checkout Only
A developer wants to suppress the interaction at checkin — whatever defect identifiers were
specified at checkout should be used automatically. (More precisely, the value of the WIP
attribute on the checked-out version should automatically be used as the value of the FIXES
attribute on the newly-created version.)
To accomplish this, the developer sets her CI_BUGNUM environment variable to 00 (the character
string specified by the BUG_DEFAULT variable in the policy file — see Appendix A, The Policy File
and Environment Variables):
C shell setenv CI_BUGNUM 00
Bourne shell: CI_BUGNUM=00; export CI_BUGNUM
Windows NT: set CI_BUGNUM=00

NOTE: For this feature to work properly, the policy file variables BUGNUM_REQ_CO and
BUGNUM_REQ_CI must have the same value.
To further increase the level of automation, the developer can suppress the checkout interaction
by specifying one or more defect identifiers as the value of environment variable CO_BUGNUM,
which specifies the WIP value to be assigned to the checked-out version.
Specifying Defect Identifiers at checkin Only
Conversely, a developer might want to bypass the integration completely at checkout — only at
checkin would the integration require specification of one or more defect identifiers.
To accomplish this, the developer sets environment variable CO_BUGNUM to 0 (the character
string specified by the BUG_NONE variable in the policy file — see Appendix A, The Policy File and
Environment Variables). In addition, the BUGNUM_REQ_CO variable in the policy file must be set to
FALSE.
The BUGNUM_REQ_CI variable in the policy file should be set to TRUE. The developer can specify
defect identifiers at checkin either interactively, or by setting her CI_BUGNUM environment
variable appropriately.
5.7 Recovering from ClearDDTS Update Failures

If the ClearDDTS database cannot be updated during a ClearCase operation, ClearCase triggers
send mail to the user specified by $BUGTRACK_ADMIN (or, for Windows NT,
%BUGTRACK_ADMIN%), as defined in the policy file. The message explains the problem and
includes the cm2ddts command that failed.

Figure 12 Typical Mail Message to ClearDDTS Administrator
Administrator,
The operation "checkin" of the file "/src/salome/src/parser.c" failed to

be recorded in the bugtracking database.
"bill" was working on bug "DRKen00003".
The exact call that failed was:
-----------------------------------------------
cm2ddts DRKen00003 argon bill -checkin /src/salome/src/parser.c
-----------------------------------------------
This message sent automatically by the ClearCase/DDTs bugtracking

integration trigger.
You can recover the lost transaction (for example, a ClearCase checkin) by rerunning the
cm2ddts command manually. For example:
% cm2ddts DRKen00003 argon bill –checkin /tut_vobs/demo/parser.c

6 Reporting Commands
6
This chapter describes utilities for tracking the involvement of ClearCase elements and versions
in bugfixing activity.
6.1 The find_fixes Command

The find_fixes utility searches the version trees of one or more elements and reports defect
identifiers with FIXES attributes. A particular defect will be listed if:
➤ Your view’s version of the element implements the fix — the FIXES attribute is attached to
the currently-selected version
➤ An ancestor of your view’s version implements the fix — the FIXES attribute is attached to
a predecessor of the currently-selected version
➤ Your view’s version picks up the fix through a merge — the FIXES attribute is attached to
a version that was merged (directly or through an intermediate merge) into the
currently-selected version, or any of its ancestors
The command-line syntax of the find_fixes command is:
find_fixes [ –v·erbose ] [ –r·ecurse ] [–sin·ce date-time ]

[ –sincel abel label-type ] pname ...
–v·erbose
Lists individual versions, each followed by the defect or defects that it fixes. By default,
the only output is a sorted list of defect identifiers.
6 - Reporting Commands 43
–r·ecurse
For each pname argument that names a directory, searches the entire directory tree rooted
at that directory. By default, only versions of the directory element itself are searched.
–sin·ce date-time
Restricts the search to versions created at or after a particular time. (See the ClearCase
lshistory reference page for a complete description of the date-time argument.)
–sincelabel label-type
In each element, restricts the search to versions that are not ancestors of the version with
the specified version label. (The version to which the label is attached is not included.)
pname ...
One or more pathnames, each a file or directory element in a ClearCase VOB.
To understand the find_fixes algorithm, consider the version tree in Figure 13. Several versions
have the FIXES attribute — some on the main branch, others on subbranches.
Figure 13 Complex Version Tree with FIXES Attributes
main
branch
0
1 0
branch1
FIXES=XYZcd00875
0 2 1
branch2
1 3 2 0
branch3
FIXES=XYZcd09887 2 4 3 1
merge FIXES=XYZcd45091 XYZcd45093

FIXES=XYZcd87409 5 2
By default, find_fixes lists all the defects fixed by a version, including those fixed by the version’s
ancestors. For example, if the view selects version /main/5:

% find_fixes foo.c
XYZcd00875
XYZcd45091
XYZcd45093
XYZcd87409
The listing includes defects XYZcd45091 and XYZcd45093 because the fix in version
/main/branch3/2 was merged into an ancestor version of version main/5; it includes defect
XYZcd00875 because that bug was fixed in an ancestor of version main/5.
Similarly, find_fixes lists these defects for the most recent version on the branch2 branch:
% find_fixes foo.c@@/main/branch2/LATEST
XYZcd00875
XYZcd09887
The listing includes defect XYZcd09887 because the latest version on the branch2 branch fixes
that defect. It includes defect XYZcd00875 because that fix was made in an ancestor version.
When invoked with the –v option (for verbose), find_fixes produces a version-by-version
listing. For example:
% find_fixes –v foo.c@@/main/5
foo.c@@/main/5: XYZcd87409
6.2 The find_wip Command

The find_wip utility locates versions to which the WIP attribute is attached, instead of versions
with FIXES attributes. Thus, this command reports on versions that are currently involved in
bugfix work.
The command-line syntax of the find_wip command is:
find_wip [ –r·ecurse ] pname ...
–r·ecurse
For each pname argument that names a directory, searches the entire directory tree rooted
at that directory. By default, only versions of the directory element itself are searched.
pname ...
One or more pathnames, each of which specifies a file or directory element in a
ClearCase VOB.
For each element it processes, find_wip searches through the entire version tree, reporting all
versions to which a WIP attribute is attached.
6.3 Generating Reports with ClearCase Commands

This section suggests ways in which you can use cleartool, to produce reports on bugfixing
activity.
Using Attribute Queries
Since the integration uses ClearCase attributes, you can use standard ClearCase queries to
generate reports. For example, to find all versions of an element that have a FIXES attribute:
% cleartool find element-name –version 'attype(FIXES)' –print
To find all versions under the current directory with a FIXES attribute of ABCde01234:
% cleartool find . –version 'attr_sub(FIXES,==,"ABCde01234")' –print
See the ClearCase reference pages find and query_language for more information.
Using Configuration Records
The find_fixes command can search of an entire directory tree. Often, however, you may want to
search the versions that make up a particular product. You can use ClearCase configuration
records to do this:
% cleartool catcr –flat -element_only –short DO-pname | xargs find_fixes
This command generates a list of the version-extended pathnames of element versions that
contributed to DO-pname, and it uses the standard UNIX xargs(1) utility to feed that list to
find_fixes. You can still use the –verbose, –since, and –sincelabel options to find_fixes.

If every version that went into a previous software release is labeled RELEASE_1.0, a variant of
the above command finds the bugs fixed since that release in DO-pname:
% cleartool catcr –flat -element_only –short DO-pname \

| xargs find_fixes –sincelabel RELEASE_1.0
See the ClearCase reference page catcr for more information.
6.4 Putting it All Together with ClearDDTS

ClearDDTS provides several commands that produce reports from a list of defect identifiers on
standard input:
➤ cm.relnotes.sh
➤ dumpbug
➤ sortbug
➤ summarybug
These commands are documented in the ClearDDTS Administration Manual. You can combine
them with the find_fixes commands illustrated above. For example:
% cleartool catcr –flat –element_only –short DO-pname \

| xargs find_fixes –sincelabel RELEASE_1.0 \
| cm.relnotes.sh –f output-file
This command generates a set of release notes for DO-pname, describing the changes from
Release 1.0.
A The Policy File and Environment
Variables
A
This appendix describes how to set up one or more policy files, and it describes each of the
environment variables that can be set in a policy file or in the user’s environment.
A.1 Changing the Original Policy File

The original ClearCase ClearDDTS Integration policy file is located in ClearCase’s network-wide
release area:
/usr/release-area/ddts/policy_vars.sh
This file is shared, through a UNIX symbolic link to its parent directory, by all hosts where the
Integration is installed. Editing this file potentially affects all users of the integration. Therefore,
you must give careful consideration before making such changes.
To change the original policy file, copy it from the ddts directory into ccase-home-dir/bugtrack (for
UNIX systems) or ccase-home-dir\bugtrack (for Windows NT) and edit it there.
A.2 Creating and Using Additional Policy Files

The following code segment in the original policy file governs the use of additional policy files:
A - The Policy File and Environment Variables 49

## Comment out ... if you wish to disallow alternate Policy files.
##
## WARNING! The following code must not be in an alternate
## Policy File as recursion would take place!!
##
if [ -n "$ALT_POLICY" ] ; then
if [ ! -r "$ALT_POLICY" -o -d "$ALT_POLICY" ] ; then
echo "Could not read ALT_POLICY file: $ALT_POLICY"
echo "Set your ALT_POLICY correctly, or unset it."
exit 1
fi
. $ALT_POLICY
fi
All integration scripts read the original policy file; when the above code is reached, a script
switches to the alternate policy file whose pathname is the value of environment variable
ALT_POLICY (if the variable is set).
Creating a New Policy File
Follow these steps to create a new policy file:
1. Make a copy of the original policy file so that it is accessible to all prospective users.
2. Delete or comment out the alternate-policy-file code segment from the copy. As explained in
the comment lines (see the preceding section), this code must be executed only by the original
policy file.
3. Change the environment variable settings in the copy, being careful to maintain consistency
among settings you want all policy files to share.
4. Have users who will use this new, non-default policy file set their ALT_POLICY environment
variable to point to the file’s location. See Setting up an Alternate Policy File on page 9.

A.3 Policy File Variables
Table 3 lists the policy file variables that configure the ClearCase ClearDDTS Integration. The
table is divided into three parts: variables that help establish and enforce site policies; variables
that set miscellaneous system parameters; and the single variable in the local policy file.
Table 3 Policy File Variables (Part 1 of 3)
Variable Description Values
Policy Variables
BUGNUM_REQ_CO must a defect identifier be true, false (See BUG_NONE

provided on checkout? below)
default: false
BUGNUM_REQ_CI must a defect identifier be true, false (See BUG_NONE

provided on checkin? below)
default: false
BUG_DEFAULT suppress-checkin-interaction string; any character string

valid at checkin time only default: 00 (set CI_BUGNUM to this
value to suppress prompting for
defect identifiers at checkin time)
BUG_NONE no-bugfix string; valid at checkout any character string

time only if BUGNUM_REQ_CO is default: 0 (set TASK_BUGNUM to
false; valid at checkin time only this value to bypass Integration)
if BUGNUM_REQ_CI is false
BUGTRACK_ADMIN user to receive mail when update ClearDDTS Administrator’s

of ClearDDTS database fails UNIX login name, or any other
valid UNIX login name
default: root

Miscellaneous Variables
MKTYPE_COMMENT creation comment for meta-data any character string

types default: “Created for use with
bug tracking triggers.”
PRE_CI_TRIG ClearCase pre-operation and any valid ClearCase trigger name

POST_CI_TRIG post-operation trigger-type defaults: ddts_pre_ci_trig
PRE_CO_TRIG names for checkin, checkout, and ddts_post_ci_trig
POST_CO_TRIG uncheckout commands ddts_pre_co_trig
PRE_UNCO_TRIG ddts_post_co_trig
POST_UNCO_TRIG ddts_pre_unco_trig
ddts_post_unco_trig
WIP_NAME work-in-progress attribute type any valid ClearCase attribute

name
default: WIP
FIXES_NAME fixes-problem attribute type any valid ClearCase attribute

name
default: FIXES
MULTIPLE_BUGS controls whether the value of true, false

WIP_NAME and FIXES_NAME default: true
attributes can include more than
one defect identifier
Local Policy File Variables
CCTEMP defines a directory to be used by any appropriate directory for

the ClearCase scripts to keep temporary files, such as /tmp.
temporary files; set in default: /usr/tmp or C:\TEMP. If
$ccase-home-dir/ddts/local_policy. the default doesn’t exist, you must
pl edit CCTEMP in local_policy.pl.

BUGTRACK_RSH_C Specifies the command to be used In most cases, the default

OMMAND to execute shell commands to the command is appropriate. Some
remote BUGTRACK_PROXY_HOST. systems use remsh or other
This command can (and probably designations.
should) include references to the default: rsh
other local policy environment $BUGTRACK_PROXY_HOST -l
variables BUGTRACK_PROXY_HOST $BUGTRACK_PROXY_USER
and BUGTRACK_PROXY_USER.
BUGTRACK_GET_PO Specifies the command to get The default is usually correct.

LICY policy variable values from default:
BUGTRACK_PROXY_HOST. /usr/atria/bugtrack/getpolicy
A.4 Environment Variables

Table 4 lists the environment variables that need to be set in the user’s UNIX or Windows NT
environment.
Table 4 Environment Variables
BUGTRACK_PROXY_HOST the host on which the trigger scripts any valid hostname
are to execute
BUGTRACK_PROXY_USER the username under which the any valid username

scripts are to execute
PATH executable path of the ClearDDTS $ATRIAHOME/bugtrack or
host’s proxy user who is specified in %ATRIAHOME%\bugtrack
$BUGTRACK_PROXY_USER (or
%BUGTRACK_PROXY_USER%)


Ccint Ddts

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Ccint Ddts

Uploaded by

Copyright:

Available Formats

CLEARCASE CLEAR DDTS

/vobs/doc/ccase/integrat/ddts/ddtsTTL.fm — November 15, 1999 3:28 pm

1. Installing the ClearCase ClearDDTS Integration ......................................................... 1

2. Overview of the Integration............................................................................................. 11

/vobs/doc/ccase/integrat/ddts/ddtsTOC.fm — November 15, 1999 3:34 pm

3. ClearCase-to-ClearDDTS Communications ................................................................19

4. Using the ClearCase ClearDDTS Integration from Windows NT ...........................29

iv ClearCase ClearDDTS Integration

/vobs/doc/ccase/integrat/ddts/ddtsTOC.fm — November 15, 1999 3:34 pm

A. The Policy File and Environment Variables ............................................................... 49

/vobs/doc/ccase/integrat/ddts/ddtsTOC.fm — November 15, 1999 3:34 pm

/vobs/doc/ccase/integrat/ddts/ddtsTOC.fm — November 15, 1999 3:34 pm

/vobs/doc/ccase/integrat/ddts/ddtsLOF.fm — November 15, 1999 3:34 pm

/vobs/doc/ccase/integrat/ddts/ddtsLOF.fm — November 15, 1999 3:34 pm

Table 1 Trigger Types ....................................................................................................... 19

/vobs/doc/ccase/integrat/ddts/ddtsLOT.fm — November 15, 1999 3:34 pm

/vobs/doc/ccase/integrat/ddts/ddtsLOT.fm — November 15, 1999 3:34 pm

About This Manual

xii ClearCase ClearDDTS Integration

This manual uses the following typographical conventions:

➤ [] Brackets enclose optional items in format and syntax descriptions.

➤ | A vertical bar separates items in a list of choices.

Your Location Telephone Facsimile Electronic Mail

North America 800-433-5444 408-863-4194 support@rational.com

Europe, Middle +31-(0)20-4546-200 +31-(0)20-4546-201 support@europe.rational.com

Asia Pacific 61-2-9419-0111 61-2-9419-0123 support@apac.rational.com

xiv ClearCase ClearDDTS Integration

1.1 Overview of the Installation Process

1 - Installing the ClearCase ClearDDTS Integration 1

1.2 Checking Disk Space Availability

➤ 800KB on the network-wide UNIX host for the release area

➤ 745KB on any Windows NT system to contain the software prior to installation

1.3 Installing the Integration on UNIX

1.4 Installing the Integration on a Windows NT System

1. On a UNIX system, populate a release area as described in ClearCase Product Family

3. Copy the files from the ClearDDTS release directory

2 ClearCase ClearDDTS Integration

6. Let setup.exe install the trigger scripts in %ATRIAHOME%\bugtrack\install.

1.5 Setting Up the Environment for Your Site and Users

➣ BUGTRACK_PROXY_USER — specifies the username under which the scripts are to

1 - Installing the ClearCase ClearDDTS Integration 3

➣ BUGTRACK_RSH_COMMAND — Specifies the command to be used to execute shell

rsh $BUGTRACK_PROXY_HOST –l $BUGTRACK_PROXY_USER

NOTE:Please see Windows NT ClearCase/CRM Integration on page 5 for information about a

To prepare the policy files for use by the integration:

4 ClearCase ClearDDTS Integration

6. On the ClearCase host for the Integration:

Windows NT ClearCase/CRM Integration

Use it to set BUGTRACK_PROXY_HOST, BUGTRACK_PROXY_USER and BUGTRACK_RSH_COMMAND. as

1 - Installing the ClearCase ClearDDTS Integration 5

Setting Up the Environment for Attache Users

6 ClearCase ClearDDTS Integration

rsh $BUGTRACK_PROXY_HOST –l $BUGTRACK_PROXY_USER

PATH Variables for the Windows NT Helper

Create the .attache.env file from the command line:

echo > .attache.env

PATH Variables for the UNIX Helper

1 - Installing the ClearCase ClearDDTS Integration 7

> %ATRIAHOME %\bugtrack\install\vob_prep vob-tag

vob_prep accepts one or more VOB-tags.

Installing types for ClearCase DDTs Integration into /vobs/proj.

Created trigger type "ddts_pre_co_trig".

8 ClearCase ClearDDTS Integration