NAME

ClearCase::Proc::ClearTool - OO interface to Rational's cleartool/multitool command interpreters

VERSION

This document describes version 0.13, released May, 2004.

DEPENDENCIES

Dependencies for this class include the following.

1)  Rational's ClearCase "cleartool" and/or "multitool" commands

2)  An operating system on which Perl can fork a child process.

3)  File modules "IO-1.20" (or later) including
    IO::File, IO::Handle and IO::Pipe.

SYNOPSIS

    use ClearCase::Proc::ClearTool;
or  use MultiSite::Proc::MultiTool;

    $cleartool = new ClearCase::Proc::ClearTool;
or  $multitool = new MultiSite::Proc::MultiTool;

or  $cleartool = new ClearCase::Proc::ClearTool("/path/to/cleartool");
or  $cleartool = new ClearCase::Proc::ClearTool("nostart");

    ($result,$stat,$err) = $cleartool->run( $command_string );

or  $result     = $cleartool->run( $command_string );
or  ($stat,$err)= $cleartool->status;


When the "new" method was called with a "nostart" parameter, the child
cc/mt process must be started prior to calling the "run" method.

    $cleartool->start;
or  $multitool->start;

The "isRunning" method can be used to conditionally start the child cc/mt
process, or otherwise determine if a child process is currently running.

    $cleartool->start  unless $cleartool->isRunning;
    $multitool->start  unless $multitool->isRunning;


To disable use of the cc/mt "-status" mode with CC v.5 and later:

    use ClearCase::Proc::ClearTool qw( noStatusMode );
or  use MultiSite::Proc::MultiTool qw( noStatusMode );

    $cleartool = new ClearCase::Proc::ClearTool( undef, "noStatusMode" );
or  $multitool = new MultiSite::Proc::MultiTool( undef, "noStatusMode" );

Or, when the "new" method was called with a "nostart" parameter,
a "noStatusMode" parameter may be passed to the "start" method.

    $cleartool->start( undef, "noStatusMode" );
or  $multitool->start( undef, "noStatusMode" );

DESCRIPTION

ClearCase::Proc::ClearTool (or MultiSite::Proc::MultiTool) will run a ClearCase cleartool (or multitool) command interpreter as a child process. Sub-commands are invoked and output is returned via the run method. This improves overall performance as a new command interpreter is not started for each and every sub-command.

A persistent process is also necessary when running the setenvent sub-command to modify the date/user/group of various VOB modification transactions. A setenvent will only last for the duration of a single cleartool process. Further details on setevent are included, below.

Constructor

new ( [ { ProgName | 'nostart' } ] [, 'noStatusMode' ] )

Create a new cleartool or multitool child process.

ProgName

This parameter is optional. When specified, it should be one of

cleartool
multitool
/full/path/to/cleartool
/full/path/to/multitool
"nostart"

Use nostart to delay launching the interpreter as a sub-process.

Otherwise ProgName defaults to the appropriate interpreter, depending on the class used. Either class can run either interpreter but, for semantic clarity, the defaults should probably be used as shown in the Synopsis section, above.

'noStatusMode'

Pass a second parameter of 'noStatusMode' to disable use of the cc/mt "-status" mode with CC v.5 and later. See the Warnings section, below, for further details.

Methods

run ( Command )

Pass a cleartool or multitool sub-command to the child process. While the following examples only show a $cleartool object, $multitool objects work in a corresponding manner.

($result,$stat,$err) = $cleartool->run( "lsvobs -s" );

For commands that require multiple lines of input, all of the necessary input must be included in the cmd string. It is not currently possible to pass additional input to a sub-command through subsequent calls to the run method. E.g., to add the necessary response for the rmelem sub-command, use this.

$cleartool->run( "rmelem $elem \nyes" );

Objects of this class ensure that the appropriate result of each sub-command is returned to the calling script, and there should not be any instances where i/o 'hangs' waiting for command output. I.e., this class will 'self synchronize' when reading from the cleartool/multitool child, even when errors or warnings occur.

Omitting the '\nyes' response from the above command, for example, should not cause scripts using objects of this class to hang. However, in these types of cases, care should be taken by the user to ensure that the command did complete successfully. No error msg or status code will be available. Therefore, check the resulting text output (or test for existance of the element), etc.

(Of course, in the above example, it would be a better idea to add a -force option and omit the ' \nyes' all together. The example simply demonstrates the syntax necessary for multi line input.)

result

Collect the result of the previous cleartool/multitool command. The result is also available via the run command, above.

$result = $cleartool->result;

status

stat

warn

err

Determine the status of the previous cleartool/multitool command. The status is also available via the run command, above.

$cleartool->run("lsvob -s");
($stat,$err) = $cleartool->status;

$stat  = $cleartool->stat;      # status number in scalar context
($err) = $cleartool->stat;      # error message in array context

Note: currently, when a Warning: is emitted by cleartool or multitool, this is indicated by a value for $err and a $stat of '0'. Use the following methods to test for errs and warns.

    $msg = $cleartool->warn;
or  $msg = $cleartool->err;

exit

stop

terminate

Terminate the child process associated with the current object. Either use the stop method, undefine the object variable, or simply allow the object variable to fall out of scope. Of course, after calling stop, any calls to the run method will fail.

    $cleartool->stop;
or  ($stat,$err) = $cleartool->stop;

or  undef $cleartool;
or  die "<error condition>";
or  exit;

start ( [ Command ] [, 'noStatusMode' ] )

Start/restart a child process for association with current object. After invoking the stop method it is possible to launch another child process. The new child will have no relation to the original.

    $cleartool->start;
or  $cleartool->start("/path/to/cleartool");
or  $cleartool->start("/path/to/cleartool", "noStatusMode");

In addition, the start method must be called if the new method was invoked in such a way that no child was started. For example, to delay spawning the child when instantiating the object use this.

$cleartool = new ClearCase::Proc::ClearTool("nostart");

And then, before a first call to the run method, make sure that the child process started successfully.

($stat,$err) = $cleartool->start;
$stat and die $err;

$cleartool->run( $ctCommand );

The first parameter to the start method is the same Command string as defined in the run method. Optionally, pass a second parameter of 'noStatusMode' to disable use of the cc/mt "-status" mode with CC v.5 and later.

isRunning

started

Determine if a child process is currently running.

$cleartool->start  unless $cleartool->isRunning;

Parsing Output

The most difficult part of scripting cleartool and multitool commands is obtaining meaningful results from the output. As a data base query tool these commands leave much to be desired. To aleviate the problem this class is designed to facilitate output parsing.

It is possible to pass a text parsing class to the run method, the assumption being that this will instantiate an object. This is a parameter of the run method since it is expected that the output from only some sub-commands will probably be parsed. The parser class should have methods to parse, set and setErr.

    use ClearCase::Vob::Info;
    $parser = "ClearCase::Vob::Info";       # parser as a class
or  $parser = new ClearCase::Vob::Info;     # parser as an object

    $vobObj = $cleartool->run("lsvob -l", $parser);

    print $vobObj->dump;        # e.g., to display the results.

At this point, error conditions will be equivalent in the objects.

    ($stat,$err) = $cleartool->status;
or  ($stat,$err) = $vobObj->status;
    

parser ( { ParserClass | ParserObject } )

A default parser class/object can be defined such that an extra parameter is not required for the run method. This will mean that, for sub-commands where the resulting text is ignored, there will be a bit of extra overhead. For commands with no resulting outupt, there is no added overhead. The $parser parameter passed here is expected to be the same class or object as described above.

$cleartool->parser( $parser );

To prevent parsing overhead when output will simply be ignored, add a noparse parameter to the run method. This way the default parser is not invoked for a particular subcommand.

$cleartool->run( $ctCommand, 'noparse' );

Modifying Event Meta Data

It is possible to create a ClearCase object with modified date and user info. To make this work, use the setevent method just prior to a checkin or other element creation event (mkbrtype, etc.)

setevent ( Date, Uname [, Gname ] [, UserName ] [, HostName ] )

setevent ( 'unset' )

When calling the setevent method the $date parameter can be either a Unix epoch date number or the normal setevent date string as shown below.

Note that a setevent is only successful when the cleartool process is running as either the VOB owner or root (superuser).

    $cleartool->setevent($date, $uname);
or  $cleartool->setevent($date, $uname, $gname, $userName, $hostName);

unsetevent

The following is equivalent to running setevent( 'unset' ) as described above.

    $cleartool->unsetevent;
or  $cleartool->setevent("unset");

Additional notes on the cleartool setevent sub-command.

This is a sub-command recognized by cleartool that allows creating new VOB objects as if they were created at another time and/or by another user. The syntax is as follows for cleartool 4.2.

Usage: setevent -time date-time -user login-name [-group group-name]
                [-name user-full-name] [-host host-name]
       setevent [-unset]

Where a valid <date-time> consists of the following.

<date-time> = <date>.<time> | <date> | <time> | "now" | "none"
<date>      = d[d]-<month>[-[yy]yy] | <day-of-week> | "today" | "yesterday"
<time>      = h[h]:m[m][:s[s]][UTC[+|-][h[h][:mm]]] (24-hour time)

Rational does not document this command. Testing shows the following:

.  the cleartool process must be run by "root" or the "vob admin" user

.  for the <login-name> and <group-name> parameters apparently a uid 
   or gid number works equally well (at least on HP-UX)

For file and directory elements:

.  a "checkin" of the new element must complete successfully or the 
   modified meta-data will not be associated with the new element

.  the "checkin" must complete before the cleartool process stops,
   or before the "-unset" option is used

INHERITANCE

The MultiSite::Proc::MultiTool class inherits directly from this class.

WARNINGS

At version 0.10 of this module, it now supports the '-status' mode (available with CC V.5 and later). The possibility of 'hanging' the child ct/mt process has been reintroduced. Unfortunately, in 'status' mode, we can no longer use the simple work around that is still available when not using the new status mode.

This module attempts to automatically detect ClearCase V.5 and later. If the '/usr/atria/java' path exists, either as as subdir or a symlink, then we are running ClearCase V.5 or later and will use the '-status' option when it starts the ct/mt co-process unless it is told otherwise.

To force ct/mt commands V.5 and later to not use the '-status' mode, add a 'noCmdStatus' parameter to the 'use' statement, or pass the same parameter to the 'new' or 'start' methods. Any one of the following are equivalent in this functionality.

use ClearCase::Proc::ClearTool qw( noCmdStatus );

$cleartool = new ClearCase::Proc::ClearTool("","noCmdStatus");

$cleartool->start("","noCmdStatus");

The only time that this script should experience a 'hang' situation is when the calling script passes a badly formed ct/mt subcommand. If the subcommand results in the ct/mt co-process issuing a prompt for additional information then a hang will occur.

See the run method, above, for examples of avoiding this situation.

SEE ALSO

See MultiSite::Proc::MultiTool, ClearCase::Vob::Info and ClearCase::Vob::Info::InfoBase.

AUTHOR

Chris Cobb, <chris@ccobb.net>

COPYRIGHT

Copyright (c) 2002-2004 by Hewlett-Packard. All rights reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm ClearCase::Vob::Info

perl -MCPAN -e shell
install ClearCase::Vob::Info