At the end of the preceding lesson, you were in the bin directory, in a shell set to view USER_HOST_tut. Verify that you are still in the same situation. Then, return to the source directory, src.

% cleartool pwv -short
USER_HOST_tut
% pwd
VOBTAG/bin
% cd ../src

If you've gotten lost, you may need to use a full pathname to find the source directory.

cd VOBTAG/src

If this command fails, it is probably because you exited the shell that was set to your view. Enter the following commands to reestablish your view context and your working directory within the VOB.

cleartool setview USER_HOST_tut
cd VOBTAG/src

Like SCCS and RCS, ClearCase uses a “checkout-edit-checkin” paradigm to control creation of new versions of elements. Before you start working, use the lscheckout (“list checkouts”) command to determine whether any other user, working in another view, is currently using any of the source files.

% cleartool lscheckout
%

It's unlikely that anyone else would intrude on your tutorial, but not impossible. Any user working on your host can use the mount(1M) command to see that a VOB is mounted at VOBTAG. Your umask value at the time the REL1REL2 script created the VOB determines whether other users can access the data in your VOB.

Just to be mischievous, let's try to defeat the system. If you own a standard file, you can make it writable with chmod(1). But this doesn't work for a ClearCase element.

% ls -l util.c
-r--r--r--   1 akp      user         223 May 20 17:05 util.c
% chmod 644 util.c
chmod: util.c: Read-only file system

(The exact text of the error message varies from system to system.)

The only way to make an element writable is to perform a checkout command. Similarly, you cannot delete util.c, even though you own it and you own the directory in which it resides. To the standard UNIX rm(1) command, a VOB is a read-only file system.

The only way to modify the contents of element util.c is to perform a checkout command. In ordinary version-control systems, the “double-think” comes into play here. For example, if util.c were under SCCS control, you would enter a command that reads one file (s.util.c in the “real” source tree) and writes another file (util.c in your sandbox).

ClearCase simplifies your life (and your system administrator's) by dispensing with the double-think. You name the element itself in the checkout command; the only apparent change is that the file goes from read-only to read-write. But ClearCase has done more than a simple chmod(1)—it has made a copy of the read-only file you listed in Step 20, creating a read-write “checked-out” version. Your view makes this file appear to be located in the current working directory, VOBTAG/src. In fact, the checked-out version is stored within your view's private storage area, under a name that only ClearCase cares about.

Figure 2-1. Using the checkout Command

% cleartool checkout util.c
Checkout comments for "util.c":
shorten HOME string
.
Checked out "util.c" from version "/main/1".
% ls -l util.c
-rw-rw-r--   1 USER      user         223 DATESTRING util.c
% cleartool ls -short util.c
util.c@@/main/CHECKEDOUT

The cleartool ls command verifies that the checked out version now appears in your view.

---

Note: By default, cleartool prompts you for a comment when you perform a checkout. This comment gives you a chance to “declare your intentions”. It will be visible to all other ClearCase users while you have the file checked out .

---

Whenever you are prompted for a comment by any cleartool subcommand, you can type as many lines as you like. The comment ends when you type <EOF> (typically, <Ctrl-d>) at the beginning of a line, or when you enter a line that contains a single “.” character.

The only change to be made in util.c is an update to the env_home() function. If the pathname in the HOME environment variable starts with the string “/net/”, we assume that it has the form “/net/hostname/usr/...”. (Such home directory pathnames are typical of environments using automount(1M) to access remote file systems.) Accordingly, we strip off the first two components of the pathname, and return the remainder.

---

Note: In this step, and throughout this tutorial, you will not edit files using a text editor. Instead, you'll overwrite a checked-out version with a file from a repository of guaranteed-correct files, the doc/tutorial subdirectory of the ClearCase installation directory (/usr/atria or $ATRIAHOME).

---

% cp /usr/atria/doc/tutorial/ut.2 util.c
% cleartool diff util.c@@/main/1 util.c
********************************
<<< file 1: util.c@@/main/1
>>> file 2: util.c
********************************
--------------[after 15]-----------|------------[inserted 16-17]-----------
                                  -|     char *b,*c;
                                   | 
                                   |-
-----------[changed 19-20]---------|-----------[changed to 21-31]----------
    else                           |     else {
      return home_env;             |       if ( strncmp(“/net/”, home_env, +
                                  -|         /* strip prefix from pathname +
                                   |         b = strchr(home_env+1, `/');
                                   |         c = strchr(b+1, `/');
                                   |         return c;
                                   |       } else {
                                   |         /* use pathname as-is */
                                   |         return home_env;
                                   |       }
                                   |     }
                                   |-

This invocation of the cleartool diff command answers the question, “What changes have I made since I checked out this file?”. How can you determine which historical version to compare the current version with? The output from the checkout command in Step 21 indicates that you checked out version 1. Entering a cleartool lscheckout command would verify this. But the best procedure is to use the –pred option:

cleartool diff -pred util.c

With this option, ClearCase automatically determines the predecessor to the specified version. The predecessor of the checkedout version of util.c is defined to be the version from which it was checked out, in this case /main/1.

In the future, we will use diff –pred whenever we need to ask “what's changed in this file?”.

To test the revised algorithm, build the program and run it. ClearCase software builds are performed with clearmake, an upward-compatible version of the UNIX make(1) utility. When it considers rebuilding object module hello.o, clearmake determines that it can instead wink-in the instance of hello.o built for the second release in view USER_HOST_old. That is, it makes the existing instance of hello.o in view USER_HOST_old appear in your view, too. (The USER_HOST_old view-tag was created for you automatically by the REL1REL2 script.)

% clearmake -v hello
No candidate in current view for "hello.o"
Wink in derived object "VOBTAG/src/hello.o"
     (`wink-in'existing object, instead of rebuilding it)		
No candidate in current view for "util.o"     
======== Rebuilding "util.o" ========
        cc -c util.c
Will store derived object "VOBTAG/src/util.o"
========================================================

Must rebuild "hello" - due to rebuild of subtarget "util.o"

======== Rebuilding "hello" ========
        cc -o hello hello.o util.o
Will store derived object "VOBTAG/src/hello"
=======================================================

We'll explore wink-in and other aspects of derived objects in Lesson 3. First, let's see if the pathname-truncation algorithm works.

Run the hello program, using ./ to ensure that you're getting the one you just built in the current working directory, rather than one somewhere on your search path.

% ./hello
Hello, USER!
Your home directory is /home/USER.
It is now DATESTRING
.

The good news is that the algorithm works; the bad news is that the bug is still there! Don't worry—you'll get to fix it soon.

To complete the checkout-edit-compile-test-checkin cycle conscientiously, you must checkin all the files that you checked out. Perhaps you know that the lscheckout command has an option that reports only your view's checkouts, but what is the correct syntax? If you've forgotten it (or never knew it!), ClearCase offers two levels of help. First, you can get a syntax summary.

% cleartool help lscheckout
Usage: lscheckout | lsco [-long | -short | -fmt format] 
      [-cview] [-brtype branch-type] [-me | -user login-name]
      [-recurse | -directory | -all | -avobs |-areplicas] 
      [pname ...]

If this is not sufficient, you can display the manual page for the lscheckout command.

% cleartool man lscheckout
cleartool       MISC. REFERENCE MANUAL PAGES        cleartool

NAME
       lscheckout - list checkouts of an element

SYNOPSIS
      lsc/heckout | lsco [ -r/ecurse | -d/irectory | -all |
          -avo/bs | -areplicas] [ -l/ong | -s/hort | 
          -fmt format-string ] [ -me | -use/r login-name ] 
          [ -cvi/ew ] [ -brt/ype branch-type-name ] 
          [ pname ...  ]

DESCRIPTION
       Lists the checkout records (the “checkouts”) for one or more elements. You can restrict the listing to particular elements and/or to checkouts made in the current view...  
 .
 .
 .

(This is equivalent to the shell command man ct+lscheckout.) The option you want is –cview. Let's use it.

ClearCase differs from some other source-control systems in that it considers an element to be checked out to a particular view, not to a particular user. This makes it easy for a small group of developers to work together in a single view.

% cleartool lscheckout -cview
DATESTRING   USER   checkout version "util.c" from /main/1 (reserved)
  "shorten HOME string"

There also is a –me option to lscheckout, which lists all elements checked out to your login name, across all views.

Reserved and Unreserved Checkouts. The information listed for each checked-out file includes a (reserved) or (unreserved) annotation. In a multi-user environment, several users may wish to revise the same source file at the same time. In general, any number of users (more correctly, any number of views) can checkout the same version of a file. Each view gets its own, private checked-out version, so that they can all be revised independently. ClearCase imposes order on this potential free-for-all by defining two kinds of checkouts:

The checkin command places a copy of your working version of util.c into the version tree of file element util.c, as a successor to the version you checked out. You can turn the checkout comment you specified in Step 21 into the checkin comment by typing . followed by <Return>. (Alternatively, you can enter another comment, effectively discarding the checkout comment.)

% cleartool checkin util.c
Default:
shorten HOME string
Checkin comments for "util.c":  ("." to accept default)
.
Checked in "util.c" version "/main/2".

Superficially (for example, to UNIX ls), the only change to a checked-in element is that the file changes from read-write to read-only. But ClearCase commands show that much more has happened.

% ls -l util.c
-r--r--r--   1 USER   GROUP      357 DATESTRING util.c
% cleartool ls -short util.c
util.c@@/main/2                  


      


(no longer checked-out)
% cleartool lshistory util.c
DATESTRING     USER       create version "util.c@@/main/2"
  "shorten HOME string"
20-May-1992    cory       create version "util.c@@/main/1" (REL2)
  "define user, home, time functions"
20-May-1992    cory       create version "util.c@@/main/0"
20-May-1992    cory       create branch "util.c@@/main"
20-May-1992    cory       create file element "util.c@@"
  "define user, home, time functions"
% cleartool lsvtree -all util.c
util.c@@/main
util.c@@/main/0
util.c@@/main/1 (REL2)
util.c@@/main/2                  


   (new version added to branch)

We introduced an additional cleartool command here, lshistory (“list history”). This command displays a chronological listing of events in the lifetime of element util.c. Contrast this with lsvtree, which displays the current structure of the element, without regard to how and when the structure grew.