NAME

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

SYNOPSIS

This is an overlay module for ClearCase::Wrapper containing David Boyce's 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 and thus -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 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.

• 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 view's 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 it's 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 you exit 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.

  However, 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.

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

• RECO/RECHECKOUT

  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".

• 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 -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 existed.

  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.

• 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.

• WINKOUT

  The winkout pseudo-cmd takes a set of view-private files as arguments and, using clearaudit, makes 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.

  If the -promote flag is given, the view scrubber will be run on the 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.

• 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, 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 AND LICENSE

Copyright (c) 1997-2002 David Boyce (dsb@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.

SEE ALSO

perl(1), ClearCase::Wrapper