David Boyce


ClearCase::Wrapper::DSB - David Boyce's contributed cleartool wrapper functions


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



    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.


    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 objects's 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.


    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 view's config spec.


    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 view's config spec.


    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 it's checked out reserved. Eclipsing elements can lead to dangerous confusion - use with care!


    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 you've 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 doesn't 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 didn't previously exist; the -nusers list will only be modified for existing locks.


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


    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.


    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.


    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 they'll match the registry, and an extension is made to allow multiple VOB tags to be passed to one mount command.


    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 view's 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 there's nothing it could break which could't be fixed with an administrator's help, but it should still be used with care. In particular, it's possible to specify values to -chmod which will confuse the view greatly.


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


    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.


    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 doesn't 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.


    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.


    Adds a -quiet option to strip out all those annoying Processing dir ... and End dir ... messages so you can see what files actually changed. It also suppresses logging by redirecting the log file to /dev/null.


    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.


    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 DO's. 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 DO's, 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 DO's 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.


    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, it's read before starting the user's 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.


Copyright (c) 1997-2002 David Boyce (dsbperl AT boyski.com). All rights reserved. This Perl program is free software; you may redistribute it and/or modify it under the same terms as Perl itself.


perl(1), ClearCase::Wrapper