WHAT NCATOOL DOES

ClearCase allows its views to be exported via NFS to Unix platforms
which are not running ClearCase (either those for which CC is not
supported or where CC simply hasn't been installed). This is referred
to as Non-ClearCase Access or NCA for short. NCA-exported views may be
mounted and used like any other NFS filesystem but all ClearCase
specific functionality - most notably the ability to check out and in -
is lost. Most NCA users have to go back over to the "real" ClearCase
host and do their CC operations there.

Ncatool basically takes responsibility for doing this. It's generally
installed locally under the name "cleartool"; there will be no conflict
with the real cleartool since CC is not installed. If you then run, say

    % cleartool co foo

it determines what machine and view "foo" is exported from and
uses SSH to go there and perform the actual checkout. Something
similar takes place for every cleartool command.

Usage is generally identical to that of the real cleartool. All the
same commands and flags are available. It makes an NCA environment
feel remarkably like a real CC environment.

I know that a number of other people have written similar cleartool
emulators - in fact this is the second one I've written. I'd like this
one to have all the features that make sense, so if you've written or
have seen a similar tool with a capability this one doesn't have,
please send it to me and I'll try to stick it in if it makes sense.

There's a well-known problem with NCA access involving stale directory
caches. This is not exactly a bug but rather an unfortunate interaction
between NFS and ClearCase.  Ncatool includes code to force the caches
to be updated. See the section "NFS Problems with Non-ClearCase Access"
in cc_admin.pdf.

OTHER COMMANDS

Ncatool can also emulate "multitool" and "clearprompt". Just make links
to it under those names if desired.

Caveat: Note that clearprompt emulation doesn't currently do anything
special to deal with the file-based flags such as -outfile, -dfile, and
-default. The file will be written on the server but your script may
attempt to read it on the local system; the only obvious workaround is
to point to an NFS-mounted location which can be seen from both
systems.

ClearCase trigger scripts will run on the server system, not the NCA
machine, and thus any clearprompts they run will employ the real one on
the real CC host. Ncatool passes the DISPLAY variable over to the CC
host in order to facilitate this.

HOW TO INSTALL

There are three steps, of which the first two are basic sysadmin jobs
unrelated to ncatool:

1. Set up a Non-ClearCase Access environment.  This is well documented
in the ClearCase Administrator's Guide (cc_admin.pdf) Appendix D and
other places such as "man export_mvfs".

There are two reasonable ways to mount views on the NCA system. You can
mount them on the same path as the VOB tag, e.g.

    mount cchost:/view/myview/vobs/foo /vobs/foo

This emulates a setview enviroment but of course it limits you to
one view per NCA machine. The alternative is to emulate view-extended
space:

    mount cchost:/view/myview/vobs/foo /view/myview/vobs/foo

Other mounting styles are possible but these two are typical because
they parallel the way "real ClearCase" works.

2. Configure ssh to allow communication between the NCA system and the
"ClearCase host", i.e. the machine from which the view is exported,
without requiring a password. I.e. you should be able to run

    % ssh cchost date

and get the date back without typing a password. This can be tricky but
again is well documented within SSH. Typically the solution involves
ssh-keygen; see its man page.

3. The hard part is done. Compile ncatool and install it somewhere as
"cleartool". I usually install it as "ncatool" and make "cleartool" a
symbolic link to that. Although a sample Makefile is provided there's
no need to use it.  Compilation is as easy as

    % gcc -o ncatool ncatool.c

(substitute your compiler here).

When these three steps are completed, try using the fake cleartool just
as you would the real one. You may also want to make links
"clearprompt" and "multitool" to emulate those commands as well.

Ncatool "forwards" regular CCASE_* environment variables to the remote
server. It also accepts couple of its own environment variables. To
show the ssh command:

    % export NCA_VERBOSE=1

By default, the remote side does a setview to get "back" into the
exported view. It could use view-extended space instead which would
presumably be somewhat faster but can introduce some path
complications.  For instance, "ct desc /vobs/abc/def" is liable to fail
in a view-extended directory on the remote side. Also, filenames
mentioned in the CC output will be unnecessarily view extended. To turn
on view-extended mode:

    % export NCA_REMOTE_SETVIEW=0

TODO

-> It would be technically possible to truly emulate setview by (a)
ssh-ing to the server and mvfs_exporting the appropriate dirs and (b)
mounting them locally. Long ago I had a Perl version of NCATOOL which
did this. It would require some assumptions/conventions/permissions and
may not be practical in terms of cost/benefit, but a neat project
nonetheless.