Base ClearCase FAQs

Base ClearCase designates ClearCase without UCM.
The first FAQ of Base ClearCase could be: do not use UCM, but as the rest of the answers, this is controversial. Do not assume consistency between the answers in this FAQ. Take it as a work in progress, a side-effect of which should be to spot differences of opinion—hoping no-one exercises censorship!

originally compiled by Christian Goetze.

[see other ClearCasePages on this CMWiki]

Questions

• 1.1 UNIX-ish and admin questions
  • 1.1.1 How to remove (specify) a file with a name beginning in "-"?
  • 1.1.2 setview in scripts doesn't work
  • 1.1.3 Get "Event not found." error when running the cleartool find command. (Frederick Sena <fsena@nortelnetworks.com>)
  • 1.1.4 When I try to unmount a vob, I get a "Device busy" error and the vob does not unmount. (Frederick Sena <fsena@nortelnetworks.com>)
  • 1.1.5 In which order should I upgrade my servers and clients?
  • 1.1.6 When shutting down Clearcase, I get "device busy"...
  • 1.1.7 How can I support more users with my limited set of licenses?
  • 1.1.8 What perl should I use?

• 1.2 Elements
  • 1.2.1 How to undo a mkelem if rmelem is disabled?
  • 1.2.2 How to undo an rmname?
  • 1.2.3 I do a findmerge or a checkout and see: "Not a VOB object", but I know that the file is a VOB object.
  • 1.2.4 How can I locate Hard Links?
  • 1.2.5 RCS Keyword expansion?
  • 1.2.6 How to perform mass checkouts?
  • 1.2.7 How to perform mass checkins?
  • 1.2.8 what is an evil twin?
  • 1.2.9 How can I see who changed what parts of a file and when?
  • 1.2.10 Uncheckout leaves a zero version on branch; is this bad?
  • 1.2.11 I can see a file on one branch, but I can't see it on another branch for the same directory. How can I get the file to appear on the other branch? (Frederick Sena <fsena@nortelnetworks.com>)
  • 1.2.12 When I do cleartool ls, it says "[eclipsed]". What does "eclipsed" mean? (Frederick Sena <fsena@nortelnetworks.com>)
  • 1.2.13 How to check in a file that hasn't change (or is empty) (Bygland, Brian <Brian.Bygland@PSS.Boeing.com>)
  • 1.2.14 How to see a file that your view / config spec can't see (Bygland, Brian <Brian.Bygland@PSS.Boeing.com>)
  • 1.2.15 What's the difference between %u and %[owner]p ? (Bygland, Brian <Brian.Bygland@PSS.Boeing.com>)
  • 1.2.16 If I mkelem of a Directory, which is a view private object, I get the "Cleartool Error:Can't create directory element because "directory" already exists." Help? (Stuttgart, Niko <NikoMahle@web.de>)

• 1.3 Queries
  • 1.3.1 How to see what changed between two labels?
  • 1.3.1a How to see what changed between two timestamps?
  • 1.3.2 how to determine the vob of an element?
  • 1.3.3 findmerge takes forever on a single element
  • 1.3.4 findmerge takes forever over a vob
  • 1.3.5 What was the last label type created in this vob?

• 1.4 Views & Config Specs
  • 1.4.1 Why do people put /main/0 at the end of a config spec?
  • 1.4.2 I see checkouts to a view that no longer exists; how do I get rid of them?
  • 1.4.3 How do I rename a view?
  • 1.4.4 How can I keep people from changing their config specs? (Evelyn Leeper <eleeper@lucent.com>)
  • 1.4.5 How can I keep people from creating views? (Evelyn Leeper <eleeper@lucent.com>)
  • 1.4.6 The message says: see view_log on server server-name. Where are the logfiles stored? (Frederick Sena <fsena@nortelnetworks.com>)
  • 1.4.7 How to I cleanup view private files from my view? (Frederick Sena <fsena@nortelnetworks.com>)
  • 1.4.8 How do I recover stranded view private files?
  • 1.4.9 How to I remove a view owned by some else, e.g: someone who left the company? (Frederick Sena <fsena@nortelnetworks.com>)
  • 1.4.10 Why do I get "Checked-out version is not selected by view." when I try to check out a file? (Frederick Sena <fsena@nortelnetworks.com>)
  • 1.4.11 Why do I get "permission denied" when I try to checkout a file in someone else's view? (Frederick Sena <fsena@nortelnetworks.com>)
  • 1.4.12 How to list all of the files in my view that have never been checked-in to the VOB (Bygland, Brian <Brian.Bygland@PSS.Boeing.com>)
  • 1.4.13 Why deal with the "linked storage area"?

• 1.5 Vobs
  • 1.5.1 what is the recommended vob size?
  • 1.5.2 How (and why) do I split vobs?
  • 1.5.3 Why do I have to lock vobs prior to backing them up?
  • 1.5.4 Why deal with storage pools?
  • 1.5.5 I see a hyperlink described as "? -> ?". How do I get rid of it?
  • 1.5.6 How do I rename a vob?
  • 1.5.7 What are adminvobs? (Sakib Bhola <SBhola@DERIVION.com>)
  • 1.5.8 What is in lost+found? (<ffarmer2@csc.com>)
  • 1.5.9 The VOB is Empty! Where did it go? How to Mount a VOB

• 1.6 Clearmake, DO's and Winkins
  • 1.6.1 How to list all of the Derived Objects stored within a ClearCase VOB in the current view? Bygland, Brian <Brian.Bygland@PSS.Boeing.com>
  • 1.6.2 How to remove derived objects? Bygland, Brian <Brian.Bygland@PSS.Boeing.com>

• 1.7 Process, Policies etc
  • 1.7.1 Commonly used triggers?
  • 1.7.2 How can I visualize the branching policy used at a site?
  • 1.7.3 Commonly used branching policies
  • 1.7.4 Subversion has the concept of atomic check-ins. Does clearcase have this capability?

Answers

1.1 UNIX-ish and admin questions

1.1.1 How to remove (specify) a file with a name beginning in "-"?

Say "./-filename".

1.1.3 Get "Event not found." error when running the cleartool find command. (Frederick Sena <fsena@nortelnetworks.com>)

For example:

 % ct find . -version "!version(/main/0)" -print

This is a csh'ism. The "!" is interpreted as an event reference, and this is done prior to resolving the quotes. Use "\!" as in:

 % ct find . -version "\!version(/main/0)" -print

1.1.4 When I try to unmount a vob, I get a "Device busy" error and the vob does not unmount. (Frederick Sena <fsena@nortelnetworks.com>)

Make sure no process has its working directory set to a path beginning with the vob's vob tag. One can use fuser(1) to determine which processes are using that file system.

More specifically, go to /view (view root of the ClearCase Unix Server) and type 'fuser -cu'. If there are entries, try 'fuser -ck' (as root).

It has been observed that this isn't enough in some cases. In extreme cases, only a reboot will clear out the locks. A classic one is when /data (where you find 'clearcase/vobstore') is a link to a remote file system. If that file system is removed (typically, during DRP - Disaster Recovery Plan -) whereas ClearCase server is still up... you can only reboot (the mvfs module will deny any attempt to unmount itself: device busy)

1.1.5 In which order should I upgrade my servers and clients?

Servers first, clients later. Always refer to the release notes for details on any particular upgrade.

1.1.6 When shutting down Clearcase, I get "device busy"...

See 1.1.4.

1.1.7 How can I support more users with my limited set of licenses?

First, start by monitoring your license usage over the day. There are some nice packages that allow you to do this, For example Ed Finch's ClGraph.

The next thing is to reduce the license timeout to the minimum allowed: 30 minutes. Do this by adding a line saying: -timeout 30 into your /var/adm/atria/license.db file. You may also want to give a list of priority users by adding lines saying: -user userid.

If you still run out of licenses (and you can't afford to buy more), you can ask people to say clearlicense -release, but keep in mind you can only do this a limited number of times per day (approx. twice the number of licenses).

Touching the /var/adm/atria/license.db file releases all licenses at once, but again this can only be done 12 times per day. I use a crontab script similar to the one below, touching the file at a frequency that roughly matches my usage pattern:

5 9,10,11,1,2,3,4,5,6 * * * /bin/touch /var/adm/atria/license.db

Yet another way to reduce license usage is to encourage developers to use snapshot views and ensure that your change process knows how to deal with snapshot views, as there are a couple of pitfalls. Developers usually need little encouragement, as they will gladly sacrifice dynamic views for faster build performance, especially on NT systems.

1.2 Elements

1.2.1 How to undo a mkelem if rmelem is disabled?

Most sites disable the rmelem command, therefore you cannot undo a mkelem directly. Instead, you should use the rmname (rm for short) command.

Suppose, for example, you accidentally created the subdir element as a file element instead of a directory element. Use this procedure to correct the problem:

% ct mkelem subdir   <== error!
Created element "subdir" (type "compressed_file").
Checked out "subdir" from version "/main/0".

% ct ci -identical -nc subdir
Checked in "subdir".

% ct rm subdir
cleartool: Warning: Object "subdir" no longer referenced.
cleartool: Warning: Moving object to vob lost+found directory as "subdir.9e881d0d390711d5b3ee000180a933fe".
Removed "subdir".

% ct mkdir subdir
Created directory element "subdir".
Checked out "subdir" from version "/main/0".

%

The checkin is mainly for cosmetic reasons and to avoid confusion if this procedure is used in a snapshot view. In the end, the element isn't removed but just relocated into the trash bin. The ClearCase administrator will empty out the trash once in a while.

This procedure will not work as described if you don't notice the error immediatly and check in the containing directory. If you later check out the directory and remove the element, you will notice that it doesn't get relocated into lost+found, since the previous version of the directory still has a reference to that element. If you then attempt to create a directory element with the same name, the evil twin trigger will get in your way. You can fool the trigger, though, by first creating a directory element with a different name and then renaming it using the ct mv command, assuming the evil twin trigger fires only on mkelem, not lnname.

1.2.2 How to undo an rmname?

The important thing to remember is that renames, additions and removals of elements from a directory are all harmless and recoverable, so don't panic!

It helps to visualize additions, removals and renames as editing the containing directory. It's very much like adding, removing or changing lines in a file, and the recovery procedures are similar.

The easiest thing to do is to simply cancel the checkout of the directory. This will restore the previous version of the directory, and the removed elements will reappear, as if by magic:

% ct co -nc .
Checked out "." from version "/main/234".

% ct rm file  <=== OOOPS!!
Removed "file".

% ct unco .
Checkout cancelled for ".".

% ls file
file

%

If you don't notice the error immediately and have already checked in your directory, you can take advantage of the evil twin trigger and allow it to help you. Simply attempt to re-mkelem the deleted element and follow the instructions:

% ct co -nc .
Checked out "." from version "/main/234".

% ct mkelem file
ERROR:  An element named "file" already exists in
        in some other version of ".":

Instead of creating a new element, you probably want to
create a hard link to the existing element, like so:

cleartool ln .@@/main/LATEST/file .

% ct ln .@@/main/LATEST/file .
Link created: "./file".

%

In general, directories don't contain elements but contain named links to elements. Removing an element doesn't destroy the element, it just removes the link. It is therefore almost trivial to resurrect a removed element.

One consequence is that removing directories and removing files are really the same operation, and the recovery procedure is identical. In particular, if you accidentally removed a whole tree, you only need to recreate the link to the topmost directory of that tree.

1.2.3 I do a findmerge or a checkout and see: "Not a VOB object", but I know that the file is a VOB object.

You are probably dealing with an eclipsed file. Run "cleartool ls" on the file, and if you see "[eclipsed]", simply rename the file out of the way using a plain ordinary "mv" and retry the operation.

The most common way this happens is when developers copy files from other views. Don't do that. Merge the containing directories instead.

1.2.4 How can I locate Hard Links?

A more precise formulation would be: "How do I locate elements that are linked into two or more different directory elements?". There is no really good method to do this except by exhaustive search, for example by using this technique:

Run this command:

 % find . -print | record_inodes

where record_inodes is this little perl script:

#!/bin/perl

%links = ();  # hash indexed by inodes containing an array of
              # directory locations

%twice = ();  # hash indexed by those inodes referenced by two
              # or more directories
while (<>) {
  chomp;
  next if $_ eq '.';           # skip top level
  next if -l $_;               # skip over symlinks

  ($dir = $_) =~ s,/[^/]*$,,;  # determine directory of element

  # get inode of version 0, if it exists. If not, use
  # just stat the file itself. This way, this script can
  # be used outside of clearcase too.
  $zero_version = $_.'@@/main/0';
  ($dev, $inode) = (-e $zero_version
                    ? stat($zero_version)
                    : stat($_));

  if (exists($links{$inode})) {
    # register new location and register inode as "interesting"
    push(@{$links{$inode}}, $_);
    $twice{$inode}++;
  } else {
    # initialize array of locations
    $links{$inode} = [ $_ ];
  }
}

if (%twice) {
  print "------------------------------------------------------------\n";
  for $inode (keys(%twice)) {
    print(map("  $_\n", @{$links{$inode}}));
    print "------------------------------------------------------------\n";
  }
} else {
  print "No element linked to multiple directories found.\n";
}

1.2.5 RCS Keyword expansion?

This is probably the single most often asked question. The simple answer is that ClearCase doesn't support RCS keyword expansion, mainly for one reason: it would break merges.

Since two different versions would always have a different RCS keyword expansion at the same location within the file, any merge between those two versions would invariably cause a conflict that couldn't be resolved automatically.

In general, "inband info" (i.e. storing information about an object within an object) is a bad idea, since care must be taken not to confuse any random string with the actual metadata. A vivid demonstration of the danger can be found when attempting to check into RCS files that explain how RCS keywords work.

Instead of storing metadata within the data, one should take advantage of ClearCase's extensive metadata types (attributes, hyperlinks, comments etc...).

The obvious follow-up question then is: "How do I access the metadata when I can't connect to ClearCase?" There are really two cases here:

• Version info on the production system;
• Version info in an offline development source tree, for example a disconnected snapshot view.

The correct solution to the first case is to insert the RCS keywords at build or packaging time. There are tools to insert keywords into binaries, for example the contributed package T0039 (ccwhat).

The second case is the best argument for implementing RCS keywords, and if it's truely important to your environment, read on...

There are ways to make RCS keywords work within ClearCase, but they are by no means trivial. The best method so far is to use the contributed package T0027, which contains both a trigger and a type manager. The trigger does the actual work of substituting RCS keywords, and the type manager avoids the merge conflicts by interposing itself between the file and the real type manager, removing all RCS keywords.

Note that even with this solution, your branching strategy should be set up to deal with the case described in the diagram on the right. Assume that the blue developer delivers a change (1) of some file into the red delivery branch. He then never touches that file again. The green developer then makes another change and delivers it (2). The blue developer, having done changes in some other files wants to sync up and executes a findmerge from the red branch, which will cause green's change to be merged over as a copy merge (3). Now, the blue developer wants to deliver his other changes, but since the merge in (3) caused the RCS keywords to change, findmerge will think that blue modified the file even though he didn't and cause (4) to happen, which is somewhat bewildering.

The reason this happens is because the findmerge algorithm has a case where the actual file content is compared. Unfortunately, findmerge does not use the type manager's compare function, but something hard coded and will think the files are different even though the only difference is in the keywords.

There are two possible workarounds:

• delete or rename the development branches after delivery. This is a good thing to do in general, since it will keep the version tree looking clean, especially if the development branch name is to be re-used for the next change;
• have the RCS keywords pre-checkin trigger look for a merge hyperlink, test if the merge was a copy merge and if yes, don't modify the keywords.

1.2.6 How to perform mass checkouts?

On UNIX:

 % cleartool find path -print | awk '{print "co -nc \""$0"\""}' | cleartool

Most often, this is done in the context of upgrading third party software or doing some other form of mass checkin. Recently, Rational came up with clearfsimport, a tool that will apparently do the right thing. Stay tuned...

See also 1.2.12

1.2.9 How can I see who changed what parts of a file and when?

Look up the "cleartool annotate" command.

1.2.10 Uncheckout leaves a zero version on branch; is this bad?

I consider it a nuisance. One common development strategy is for every developer to create their own development branch by using a view with a config spec similar to this one:

element * CHECKEDOUT
element * .../mybranch/LATEST
element * BASELINE -mkbranch mybranch
element * /main/0 -mkbranch mybranch

Note that whenever a developer starts working on some file he hasn't touched, a branch gets created at that point. As work progresses, more and more elements will have a "mybranch" branch.

Once in a while, the BASELINE label gets moved to the newest approved base line, and developers are encouraged to rebase via a merge. The merge will do something for every element that has a "mybranch" branch and for which the version that BASELINE selects changed since the branch was made.

If one leaves zero versions on the "mybranch" branch behind, then this will cause copy merges, which won't affect the logical concistency of your view of the source tree, but will affect performance. Besides, zero versions just look sloppy.

Most sites add a post-rmbranch and post-unco trigger to remove the dangeling branch with only a zero version. The following code implements this trigger. Paul D. Smith wrote this trigger, and I added some code to deal with snapshot view weirdness:

#!/bin/perl
 
#--------------------------------------------------------------------
# Nothing special needed Perl-wise - allow Rational Perl to be used
#--------------------------------------------------------------------
require 5.001;

#--------------------------------------------------------------------
# Debugging aid. Overloading the semantics of the standard
# CLEARCASE_TRACE_TRIGGERS EV: if it's set to -2 we dump
# the runtime environment into a file in the current dir.
#--------------------------------------------------------------------
if (int($ENV{CLEARCASE_TRACE_TRIGGERS}) < 0 &&
        $ENV{CLEARCASE_TRACE_TRIGGERS} & 0x2) {
   open (EV, ">rm_empty_branch.txt");
   print EV "$x=$y\n" while (($x,$y) = each %ENV);
   close EV;
}

#--------------------------------------------------------------------
# See if the user wants to suppress this trigger's actions:
#--------------------------------------------------------------------
exit 0 if $ENV{CCASE_NO_RM_EMPTY_BRANCH};

#--------------------------------------------------------------------
# Use safest quoting possible - java creates files with $ in
# them, so I can't just universally use "
#--------------------------------------------------------------------
$q = ($ENV{OS} eq "Windows_NT" ? '"' : "'");

# Remove empty branches: if a branch has no elements (except 0 of
# course) after an uncheckout or rmver, or the parent of a
# just-rmbranched branch is now empty, remove it.
#
# If the branch in question is /main, don't do anything (another option
# would be to rmelem the entire element, but that seems like a very bad
# idea to me).
#
# Install like this:
#
#   ct mktrtype -element -global -postop uncheckout,rmver,rmbranch \
#       -c "Remove empty branches after uncheckout, rmver, or rmbranch." \
#       -exec /TRIGGERS/rm_empty_branch RM_EMPTY_BRANCH
#
# CAVEATS:
#   - Ignores attributes!
#   - Won't remove branches where the 0th element is labeled.
#   - Will fail if any branch names contain spaces.
#   - May fail if any branch or label is named ".*" or "*" exactly.
#
# CREATED BY:
#   Paul D. Smith <psmith@baynetworks.com>
#

$xname = $ENV{CLEARCASE_XPN};
$xname =~ s,\\,/,g if $ENV{OS} eq 'Windows_NT';

# For uncheckout commands, if the version isn't 0 we can punt early
#
exit 0 if ($ENV{CLEARCASE_OP_KIND} eq 'uncheckout' &&
      $xname !~ m,/0$,);

# Don't try to remove the /main branch
#
($branch = $xname) =~ s,/[^/]*$,,;
exit 0 if $branch =~ m,\@\@/main$,;

# Check if there are other versions, other branches, labels, or checked
# out versions on this branch: if so, don't do anything.
#
if (opendir(D, $branch)) {
  # this opendir succeeds only in a dynamic view
  @other_stuff = readdir(D);
  closedir(D);

  # in an empty branch, there are four thingies:
  # ".", "..", "0" and "LATEST". If there are more, then
  # it isn't an empty branch.
  exit 0 if (scalar(@other_stuff) != 4);
} else {
  # version extended name space not available implies
  # we're in a snapshot view, and we will have to work
  # a little harder here...
  ($pname, $brpath) = split($ENV{CLEARCASE_XN_SFX}, $branch);
  # an rmbranch will not reload the element...
  system("cleartool update -log /dev/null $q$pname$q")
    if ($ENV{CLEARCASE_OP_KIND} eq 'rmbranch');
  @vtree = `cleartool lsvtree -branch $brpath $q$pname$q`;
  chomp($latest = pop(@vtree));
  $latest =~ tr,\\,/, if $ENV{OS} eq 'Windows_NT';
  exit 0 unless $latest =~ m,$brpath/0$,;
}

# Remove it!
system("cleartool rmbranch -force -nc $q$branch$q");

exit 0;

1.2.11 I can see a file on one branch, but I can't see it on another branch for the same directory. How can I get the file to appear on the other branch? (Frederick Sena <fsena@nortelnetworks.com>)

You use the cleartool ln command. See 1.2.14 for figuring out how to specify the invisible file as an argument to that command.

1.2.12 When I do cleartool ls, it says "[eclipsed]". What does "eclipsed" mean? (Frederick Sena <fsena@nortelnetworks.com>)

An eclipsed element is seen only in dynamic views. It's basically when a view-private file/directory has the same name as an element in that same directory. Views always display view-private items first. It often occurs when one or more developers are working in the same area adding new features (for example: new classes/packages/namespaces for java/.net development). Since files typically start out as view-private, someone in one view may add their files to source control, then merge them into an integration branch. If a different view also has some of those files/directories with the exact same name and in the same directory (as view-private), then those view-private files/directories will "eclipse" those elements that now become visible.

To fix an eclipsed file/directory, simply rename it in that view that shows as eclipsed. You can then diff the now-visible element against the renamed view-private and if they are the same, delete the renamed view-private. If they are different, you may need to check out the now-visible element then manually merge the contents of the renamed view-private with the element. Note that you can't use cleartool merge/findmerge, as those commands work on different versions of the same element, not element vs. view-private or element vs. a different element.

1.2.13 How to check in a file that hasn't change (or is empty) (Bygland, Brian <Brian.Bygland@PSS.Boeing.com>)

Consider simply cancelling the checkout, but be aware that if the checkout was the result of a merge, cancelling the checkout will result in the merge arrow disappearing, forcing you to redo the merge next time. In this case, using the -identical flag of the checkin command may be preferable.

Answered by cg@miaow.com

1.2.14 How to see a file that your view / config spec can't see (Bygland, Brian <Brian.Bygland@PSS.Boeing.com>)

The reason why you're not seeing the file is that the version of the directory selected by your view doesn't have a link to that file. Therefore the solution is to figure out which version of that directory element has the link.

The easiest way to access such a file is to use a different view, namely, one that selects the appropriate version of the directory. Even if you are set to some view that doesn't, you can use the so-called view extended path to refer to the other view. On UNIX, this is done be prepending /view/viewtag to the full pathname.

In some situations, it may not be convenient or safe to use view extended paths. One problem is that while you are using a view extended path, someone else may be changing the config spec of that view. For logging purposes in particular, you are better off storing the object id of the element and letting ClearCase tell you a patnname that is valid in your view. In other words, first take a view that selects your invisible file and run this:

% cleartool setview otherview

% cleartool describe -fmt '%On\n' path/to/invisible/file@@
03fcf938.39c011d5.b891.00:01:80:ab:ed:ac

Note that the final @@ at the end of the path tells ClearCase that you are interested in the element's object id. Omitting the final @@ would give you the version's object id, whih may or may not be what you need. Now to retrieve a pathname valid in your view, do this:

% cleartool setview myview

% cleartool describe -fmt '%p\n' oid:03fcf938.39c011d5.b891.00:01:80:ab:ed:ac
/vob/somevobtag/path@@/main/2/to/main/1/invisible/main/3/file@@

Note how we enter version extended name space (or history mode on NT) very early in the path. This is natural, since our premise is that the file isn't visible in our current view. These paths can become quite long, easily exploding NT's stupid limit on path name length or command line length if you every try to use that pathname for some command.

Note that this technique is very useful for tracking down relocations. If in the example above the file was relocated to some unknown but visibile location, Clearcase would have shown that location instead. ClearCase is amazingly smart in figuring out the shortest possible pathname to a specific element.

Answered by cg@miaow.com

1.2.15 What's the difference between %u and %[owner]p ?

%u designates the user who created the object or event, and %[owner]p is the actual owner. This can be confusing when you change ownerships of elements and expect %u to return the owner.

1.3 Queries

1.3.1 How to see what changed between two labels?

Assuming that you always label all visible elements, and assuming that LABEL1 is applied prior to LABEL2, the following will do:

1. In a view selecting LABEL1, run this to obtain those elements which have been unlinked in LABEL2

   % ct find someplace -element 'lbtype_sub(LABEL1) && !lbtype_sub(LABEL2)'\
                    -print
   

2. In a view selecting LABEL2, run this to obtain those elements which have been added since LABEL1:

   % ct find vobtag> -element 'lbtype_sub(LABEL2) && !lbtype_sub(LABEL1)'\
                    -print
   

3. In the same view, locate those versions that have changed since LABEL1. Note that this will include elements found in (2).

   % ct find vobtag -version 'lbtype(LABEL2) && !lbtype(LABEL1)'
   

1.3.1a How to see what changed between two timestamps?

Use the created_since query construct, like so:

% ct find vobtag -version 'created_since(early) && !created_since(later)'

Note that this will exclude versions created exactly at timestamp later, so it's not an excact equivalent of the label based queries described in 1.3.1.

1.3.2 how to determine the vob of an element?

% ct lsvob pathname

1.3.3 findmerge takes forever on a single element

In order to set up a merge, findmerge needs to find the common ancestor of two versions. In complicated version trees, there can be many common ancestors, and finding the best one requires a non-trivial graph traversal algorithm.

The main problem is that while findmerge is looking for a common ancestor, it is holding a lock on the vob DB, preventing others from writing to the DB. In order to prevent an inordinately long amount of time in the lock, findmerge will interrupt its search, release and reacquire the lock and restart it at ever increasing intervals. There are two environment variables that can be used to tweak this behaviour, which may improve performance for specific elements:

CLEARCASE_FM_TRANS_THRESHOLD(default: 128)

This is the base value for how many versions are examined prior to a restart. This value is doubled, tripled etc as needed after every restart. Increasing this value will avoid a restart in those cases where it was "almost there", but may increase the risk that other developers will experience vob DB timeouts.

CLEARCASE_FM_MAX_LEVEL(default: 65536)

This sets the maximum number of calls that will be made in the quest for the best common ancestor. This value is set very high by default. Setting this to a low value will definitely acceletate findmerge, but may cause it to choose a very old common ancestor, forcing the merge to step through many many old changes.

Check out tech note 747 for more details.

1.3.4 findmerge takes forever over a vob

There are two good techniques to speed up findmerge, often by orders of magnitude:

• Use -fver instead of -ftag. Unless you have a very unusual situation, -fver should be good enough.
• Add -element queries to restrict the number of elements tested. If, for example, you use the common development branch/delivery branch technique, and want to merge the latest from the delivery branch into your development branch, you really only need to consider those elements that have a development branch. So, using the following command instead of a straight findmerge can result in huge performance improvements:

  % ct findmerge someplace\
                 -element 'brtype(dev_branch)'\
                 -fver .../del_branch/LATEST -merge
  

Using -avobs instead of recursive descent can also improve performance, but is a more risky techniques if directory merges are involved. Since you don't control the order of merges when using -avobs, you could conceivably merge a directory element which isn't visible yet because the parent directory element hasn't been merged yet. Using -avobs -visible will avoid error messages, but may cause you to miss some merges entirely.

1.4 Views & Config Specs

% cleartool describe -long vob:vobtag
versioned object base "vobtag"
  created 31-Dec-00.16:23:00 by ClearCase VOB admin account (vobadm.staff)
  VOB family feature level: 2
  VOB storage host:pathname "someplace"
  VOB storage global pathname "someplace"
  database schema version: 53
  VOB ownership:
    owner someone
    group some group
  Additional groups:
    ...
  VOB holds objects from the following views:
    ? [uuid c00c3821.f94411d4.ba94.00:01:80:a9:33:fe]
    ...

% cleartool rmview -force -avobs -uuid c00c3821.f94411d4.ba94.00:01:80:a9:33:fe
Removing references ...

% cleartool endview -server oldtag

% cleartool rmtag -view oldtag

% cleartool unregister -view old-location

% mv old-location new-location

% cleartool register -view new-location

% cleartool mktag -view -tag newtag new-location

% cleartool lsview -long viewtag
% ct lsview -l lt
Tag: viewtag
  Global path: someplace
  Server host: view-server
  Region: this-region
  Active: YES
  View tag uuid:48b5b6f8.752b11d4.a259.00:01:80:a9:33:fe
  View export ID (registry): 18
  ...

cleartool lsprivate -other

cleartool ls -recurse -view_only

- cleartool lsview -l <view-tag>
  This should give you it's uuid (view uuid: a bunch of hexadecimal stuff with colons and periods in it)  
  Copy the 2nd uuid entry and paste it in whereever you see <uuid> in the steps below (if you copy the first entry, you'll have
    uuid:<uuid> instead of <uuid>, which will fail):
- cleartool rmtag -view <view-tag>
- cleartool unregister -view -uuid <uuid>
- cleartool rmview -force -all -uuid <uuid>  (or use -avobs instead of -all)

1.5 Vobs

1.5.1 what is the recommended vob size?

1.5.2 How (and why) do I split vobs?

1.5.3 Why do I have to lock vobs prior to backing them up?

You must lock vobs to keep the database consistent with the storage containers where all the data (element versions) is stored. Write operations which occur during the backup break the consistency, the keys in the database are not fully correct and you may have trouble accessing certain elements. You can use cleartool checkvob -pool -source to check for errors.

Remember, inconsistencies in the database are hard to notice without the cleartool checkvob command. You might think that everything is okay but months later you will run into problems.

1.5.4 Why deal with storage pools?

1.5.5 I see a hyperlink described as "? -> ?". How do I get rid of it?

Use the checkvob command to repair broken hyperlinks:

cleartool checkvob -hlinks [-force]

1.5.6 How do I rename a vob?

Every Vob has a tag in each region. The easiest way to rename your vob is to remove the tag and create a new one:

cleartool lsvob -l <your old vob tag>
cleartool rmtag -vob <your old vob tag>
cleartool mktag -vob  -tag <new vob tag> <vob storage from lsvob output above>

Make sure that you use the correct host and access path for your new tag and add -public if necessary. Also, you must have access to the vob storage path or you won't be able to create the tag.

1.5.7 What are adminvobs? (Sakib Bhola <SBhola@DERIVION.com>)

As you know, metadata types like branches, labels, attributes etc. are stored per vob. Before you can create instances of them (e.g. mklabel) you have to create the object itself (e.g. mklbtype). If you have a project where different vobs belong together you usually want to make the types available in all vobs but of course you don't want to create them n times for n vobs. Admin vobs are made for this situation, you only create the types once in your admin vob and they are available in all other vobs which are linked to the admin vob.

In UCM, the project vob becomes automatically the admin vob and stores all necessary information.

1.5.8 What is in lost+found? (<ffarmer2@csc.com>)

In lost+found ClearCase puts all elements which are not referenced anymore. Imagine you remove a directory with rmname or rmelem. ClearCase won't recursively remove the elements in this directory but they cannot be accessed neither. Instead, they will be moved to lost+found.

1.5.9 The VOB is Empty! Where did it go? How to Mount a VOB

1.6 Clearmake, DO's and Winkins

1.6.1 How to list all of the Derived Objects stored within a ClearCase VOB in the current view? Bygland, Brian <Brian.Bygland@PSS.Boeing.com>

1.6.2 How to remove derived objects? Bygland, Brian <Brian.Bygland@PSS.Boeing.com>

1.7 Process, Policies etc

1.7.2 How can I visualize the branching policy used at a site?

The following script will take as input the output of any set of "lsvtree -short" commands, for example the output produced by:

% cleartool find . -print | xargs cleartool lsvtree -s

It will then produce an indented list of branch/sub-branch relationships and also detect cycles (for example if you have both /main/x/y and /main/y/x).

#!/bin/perl

while (<>) {
  next unless m,\@\@/(main/[^\@]*)$,;
  $branches = $1;
  @branches = split('/', $branches);
  pop(@branches);  # remove version
  $parent = shift; # parent is first entry (main)
  for $branch (@branches) {
    $ancestor_of{$branch}{$parent} = 1;
    $offspring_of{$parent}{$branch} = 1;
    $parent = $branch;
  }
}

make_node('main', 0);

sub make_node {
  my ($parent, $indent) = @_;

  print(' 'x$indent.$parent."\n");
  my $children = 0;
  my @offspring = sort(keys(%{$offspring_of{$parent}}));
  for my $child (@offspring) {
    if (scalar(keys(%{$ancestor_of{$child}})) == 1) {
      # a "real" child is one that has only one ancestor: $parent
      $children = 1;
      make_node($child, $indent+2);
    }
  }
  if (@offspring && !$children) {
    print(' 'x$indent.'  Cycle detected: '.join(' ',@offspring)."\n");
  }
}