ClearCase::Wrapper::DSB Perl module contains David Boyces contributed cleartool wrapper functions.

SYNOPSIS

This is an overlay module for ClearCase::Wrapper containing David Boyces non-standard extensions. See perldoc ClearCase::Wrapper for more details.

CLEARTOOL ENHANCEMENTS

CATCS

1. New -expand flag
Follows all include statements recursively in order to print a complete config spec. When used with the -cmnt flag, comments are stripped from this listing.
2. New -sources flag
Prints all files involved in the config spec (the config_spec file itself plus any files it includes).
3. New -attribute flag
This introduces the concept of user-defined view attributes. A view attribute is a keyword-value pair embedded in the config spec using the conventional notation
##:Keyword: value ...
The value of any attribute may be retrieved by running
< cmd-context> catcs -attr keyword ...
And to print all attributes:
< cmd-context> catcs -attr -all
4. New -start flag
Prints the preferred initial working directory of a view by examining its config spec. This is simply the value of the Start attribute as described above; in other words -start is a synonym for -attr Start.
The workon command (see) uses this value. E.g., using workon instead of setview with the config spec:
##:Start: /vobs_fw/src/java
element * CHECKEDOUT
element * /main/LATEST
would set the view and automatically cd to /vobs_fw/src/java.

COMMENT

For each ClearCase object specified, dump the current comment into a temp file, allow the user to edit it with his/her favorite editor, then change the objectss comment to the results of the edit. This is useful if you mistyped a comment and want to correct it.

The -new flag causes it to ignore the previous comment.
See edattr for the editor selection algorithm.

DESCRIBE

Enhancement. Adds the -parents flag, which takes an integer argument N and runs the describe command on the version N predecessors deep instead of the currently-selected version. into temp files and diffs them. If only one view is specified, compares against the current working views config spec.

DIFFCS

New command. Diffcs dumps the config specs of two specified views into temp files and diffs them. If only one view is specified, compares against the current working views config spec.

ECLIPSE

New command. Eclipses an element by copying a view-private version over it. This is the dynamic-view equivalent of "hijacking" a file in a snapshot view. Typically of use if you need temporary write access to a file when the VOB or current branch is locked, or its checked out reserved. Eclipsing elements can lead to dangerous confusion - use with care!

EDATTR

New command, inspired by the edcs cmd. Edattr dumps the attributes of the specified object into a temp file, then execs your favorite editor on it, and adds, removes or modifies the attributes as appropriate after youve modified the temp file and exited the editor. Attribute types are created and deleted automatically. This is particularly useful on Unix platforms because as of CC 3.2 the Unix GUI doesnt support modification of attributes and the quoting rules make it difficult to use the command line.
If the -view flag is used view attributes are edited instead. See the enhanced catcs command for further discussion of view attributes.
The environment variables WINEDITOR, VISUAL, and EDITOR are checked in that order for editor names. If none of the above are set, the default editor used is vi on UNIX and notepad on Windows.

GREP

New command. Greps through past revisions of a file for a pattern, so you can see which revision introduced a particular function or a particular bug. By analogy with lsvtree, grep searches only "interesting" versions unless -all is specified. Note that this will expand cleartext for all grepped versions.
Flags -nnn are accepted where nnn represents the number of versions to go back. Thus grep -1 foo would search only the predecessor.

LOCK

New -allow and -deny flags. These work like -nuser but operate incrementally on an existing -nuser list rather than completely replacing it. When -allow or -deny are used, -replace is implied.
When -iflocked is used, no lock will be created where one didnt previously exist; the -nusers list will only be modified for existing locks.

LSREGION

A surprising lapse of the real cleartool CLI is that theres no way to determine the current region. This extension adds a -current flag to lsregion.

MKBRTYPE,MKLBTYPE

Modification: if user tries to make a type in the current VOB without explicitly specifying -ordinary or -global, and if said VOB is associated with an admin VOB, then by default create the type as a global type in the admin VOB instead. In effect, this makes -global the default iff a suitable admin VOB exists.

MKLABEL

The new -up flag, when combined with -recurse, also labels the parent directories of the specified pnames all the way up to their vob tags.

MOUNT

This is a Windows-only enhancement: on UNIX, mount behaves correctly and we do not mess with its behavior. On Windows, for some bonehead reason cleartool mount -all gives an error for already-mounted VOBs; these are now ignored as on UNIX. At the same time, VOB tags containing / are normalized to so theyll match the registry, and an extension is made to allow multiple VOB tags to be passed to one mount command.

PROTECTVIEW

Modifies user or group permissions for one or more views. Analogous to the native ClearCase command protectvob (see). Most flags accepted by protectview behave similarly to those of protectvob.
The -replace flag is special; it uses the administrative fix_prot tool to completely replace any pre-existing identity information. This gives the views permissions a "clean start"; in particular, any grants of access to other groups will be removed.

This operation will not work on a running view. Views must be manually stopped with endview -server before reprotection may proceed.
Warning: this is an experimental interface which has not been tested in all scenarios. It cannot destroy any data, so theres nothing it could break which couldt be fixed with an administrators help, but it should still be used with care. In particular, its possible to specify values to -chmod which will confuse the view greatly.

RECO/RECHECKOUT

Redoes a checkout without the database operations by simply copying the contents of the existing checkouts predecessor over the view-private checkout file. The previous contents are moved aside to " .reco". The -keep and -rm options are honored by analogy with uncheckout.

RMELEM

It appears that when elements are removed with rmelem they often remain visible for quite a while due to some kind of view cache, though attempts to actually open them result in an I/O error. Running cleartool setcs -current clears this up. Thus rmelem is overridden here to add an automatic view refresh when done.

SETCS

Adds a -clone flag which lets you specify another view from which to copy the config spec.
Adds a -sync flag. This is similar to -current except that it analyzes the CS dependencies and only flushes the view cache if the compiled_spec file is out of date with respect to the config_spec source file or any file it includes. In other words: setcs -sync is to setcs -current as make foo.o is to cc -c foo.c.
Adds a -needed flag. This is similar to -sync above but it doesnt recompile the config spec. Instead, it simply indicates with its return code whether a recompile is in order.
Adds a -expand flag, which "flattens out" the config spec by inlining the contents of any include files.

SETVIEW

ClearCase 4.0 for Windows completely removed setview functionality, but this wrapper emulates it by attaching the view to a drive letter and cd-ing to that drive. It supports all the flags setview for CC 3.2.1/Windows supported (-drive, -exec, etc.) and adds two new ones: -persistent and -window.
If the view is already mapped to a drive letter that drive is used. If not, the first available drive working backwards from Z: is used. Without -persistent a drive mapped by setview will be unmapped when the setview process is exited.
With the -window flag, a new window is created for the setview. A beneficial side effect of this is that Ctrl-C handling within this new window is cleaner.
The setview emulation sets CLEARCASE_ROOT for compatibility and adds a new EV CLEARCASE_VIEWDRIVE.
UNIX setview functionality is left alone.

UPDATE

Adds a -quiet option to strip out all those annoying Processing dir ... and End dir ... messages so you can see what files actually changed.

WINKIN

The -tag flag allows you specify a local file path plus another view; the named DO in the named view will be winked into the current view, e.g.:
< cmd-context> winkin -tag otherview /vobs_myvob/dir1/dir2/file
The -vp flag, when used with -tag, causes the "remote" file to be converted into a DO if required before winkin is attempted. See the winkout extension for details. Note: this feature depends on setview and thus will not work on Windows where setview has been removed. However, it would be possible to re-code it to use the setview emulation provided in this same package if you really want the feature on Windows.

WINKOUT

The winkout pseudo-cmd takes a set of view-private files as arguments and, using clearaudit, turns them into derived objects. The config records generated are meaningless but the mere fact of being a DO makes a file eligible for forced winkin from another view.

If the -promote flag is given, the view scrubber will be run on these new DOs. This has the effect of promoting them to the VOB and winking them back into the current view.

If a meta-DO filename is specified with -meta, this file is created as a DO and caused to reference all the other new DOs, thus defining a DO set and allowing the entire set to be winked in using the meta-DO as a hook. E.g. assuming view-private files X, Y, and Z already exist:
ct winkout -meta .WINKSET X Y Z
will make them into derived objects and create a 4th DO ".WINKSET" containing references to the others. A subsequent
ct winkin -recurse -adirs /view/extended/path/to/.WINKSET
from a different view will wink all four files into the current view.
The list of files to convert may be derived via -dir/-rec/-all/-avobs, provided in a file containing a list of files with -flist, or specified as a literal list of view-private files. When using -dir/-rec/-all/-avobs to derive the file list only the output of lsprivate -other is considered unless -do is used; -do causes existing DOs to be re-converted. Use -do with care as it may convert a useful CR to a meaningless one.
The "-flist -" flag can be used to read the file list from stdin, which may be useful in a script.

WORKON

New command, similar to setview but provides hooks to cd to a preferred initial working directory within the view and to set up any required environment variables. The initial working directory is defined as the output of ct catcs -start (see).

If a file called .viewenv.pl exists in the initial working directory, its read before starting the users shell. This file uses Perl syntax and must end with a "1;" like any require-d file. Any unrecognized arguments given to workon following the view name will be passed on to .viewenv.pl in @ARGV. Environment variables required for builds within the setview may be set here.