David Boyce > ClearCase-Argv-1.54 > ClearCase::Argv

Download:
ClearCase-Argv-1.54.tar.gz

Dependencies

Annotate this POD

CPAN RT

Open  3
View/Report Bugs
Module Version: 1.54   Source  

NAME ^

ClearCase::Argv - ClearCase-specific subclass of Argv

SYNOPSIS ^

    # OO interface
    use ClearCase::Argv;
    ClearCase::Argv->dbglevel(1);
    # Note how the command, flags, and arguments are separated ...
    my $describe = ClearCase::Argv->new('desc', [qw(-fmt %c)], ".");
    # Run the basic "ct describe" command.
    $describe->system;
    # Run it with with stderr turned off.
    $describe->stderr(0)->system;
    # Run it without the flags.
    $describe->system('-');
    # Run it through a pipe.
    $describe->pipecb(sub { print shift; return 1; });
    $describe->pipe;
    # Create label type XX iff it doesn't exist
    ClearCase::Argv->new(qw(mklbtype -nc XX))
            if ClearCase::Argv->new(qw(lstype lbtype:XX))->stderr(0)->qx;
    # Create a multitool ipc session in autochomp mode
    my $mtx = ['/opt/rational/clearcase/bin/multitool'];
    my $mt = new ClearCase::Argv({ipc=>1, ct=>$mtx, autochomp=>1});

    # Functional interface
    use ClearCase::Argv qw(ctsystem ctexec ctqx ctpipe);
    ctsystem('pwv');
    my @lsco = ctqx(qw(lsco -avobs -s));
    # Similar to OO example: create label type XX iff it doesn't exist
    ctsystem(qw(mklbtype XX)) if !ctqx({stderr=>0}, "lstype lbtype:XX");
    ClearCase::Argv->pipecb(sub { print "GOT: " . shift() . "\n"; 1 });
    ctpipe({autochomp => 1},'lsview', ['-l']);

There are more examples in the ./examples subdir that comes with this module. Also, the test script is designed as a demo and benchmark and is a good source for cut-and-paste code.

The r directory contains a few regression test cases, unfortunately not general enough to be run from make test. The file test.cfg allows to tailor some of them for one's environment.

DESCRIPTION ^

ClearCase::Argv is a subclass of Argv for use with ClearCase. It exists to provide an abstraction layer over the cleartool command-line interface. A program written to this API can be told to send commands to ClearCase via the standard technique of executing cleartool or via the ClearCase::CtCmd module or via a pipe to cleartool (aka IPC mode) by flipping a switch.

To that end it provides a couple of special methods ctcmd and ipc. The ctcmd method can be used to cause cleartool commands to be run in the current process space using ClearCase::CtCmd. Similarly, ipc will send commands to a cleartool co-process. See the documentation of these modules for details on what they do, and see ALTERNATE EXECUTION INTERFACES below for how to invoke them. Sample scripts are packaged with ClearCase::Argv in ./examples.

A new ct optional attribute is introduced in the constructor invocation. It may be used to create ClearCase::Argv objects using a tool alternative to the default plain cleartool. This may be multitool, or cleartool under another account via sudo, or even a ClearCase::Wrapper. It is supported for the fork and the ipc modes.

As ClearCase::Argv is in most other ways identical to its base class, see perldoc Argv for substantial further documentation.

OVERRIDDEN METHODS

A few methods of the base class Argv are overridden with modified semantics. These include:

ADDITIONAL METHODS

These are methods not offered by Argv.

ALTERNATE EXECUTION INTERFACES ^

The ->ctcmd method allows you to send cleartool commands directly to ClearCase via the CtCmd interface rather than by exec-ing cleartool itself.

When called with no argument it returns a boolean indicating whether CtCmd mode is on or off. When called with a numerical argument, it sets the CtCmd mode as follows: if the argument is 0, CtCmd mode is turned off and subsequent commands are sent to real cleartool via the standard execution interface. With an argument of 1, it attempts to use CtCmd mode but if CtCmd fails to load for any reason it will (silently) run commands via CAL instead. With an argument of 2 the behavior is the same but a warning ("CtCmd not found - using CAL instead") is printed. With an argument of 3 the warning becomes a fatal error, thus using CtCmd only if the compiled version is installed.

Examples

    # Use CtCmd if available, else continue silently using CAL
    ClearCase::Argv->ctcmd(1);
    # Use CtCmd if available, else print warning and use CAL
    ClearCase::Argv->ctcmd(2);
    # Use CtCmd if available, else die with error msg
    ClearCase::Argv->ctcmd(3);
    # Turn off use of CtCmd
    ClearCase::Argv->ctcmd(0);

Typically ->ctcmd will be used as a class method to specify a place for all cleartool commands to be sent. However, it may also be invoked on an object to associate just that instance with CtCmd.

A similar sequence is observed for ->ipc mode except for the different method name, e.g.:

    # Use IPC if available, else abort
    ClearCase::Argv->ipc(3);

Note: you can tell which mode is in use by turning on the dbglevel attribute. Verbosity styles are as follows:

    + cleartool pwv             # standard (fork/exec)
    +> pwv                      # CtCmd
    => pwv                      # IPC

CtCmd mode is not compatible with the ->ctpipe method. Therefore, when a pipe is requested it will result in a new process created by the traditional execution interface.

A final note on IPC and CtCmd modes: turning on one will automatically, and silently, turn off the other. I.e. the sequence

    ClearCase::Argv->ipc(2);
    ClearCase::Argv->ctcmd(2);

will not throw any exceptions and will leave you in CtCmd mode. The coprocess will be shut down.

FUNCTIONAL INTERFACE ^

For those who don't like OO style, or who want to convert existing scripts with the least effort, the execution methods are made available as traditional functions. Examples:

        use ClearCase::Argv qw(ctsystem ctexec ctqx ctpipe);
        my $cwv = ctqx(pwv -s);
        ctsystem('mklbtype', ['-global'], 'FOO') && exit $? >> 8;
        my @vobs = ctqx({autochomp=>1}, 'lsvob -s');
        ctpipe('lsview', ['-l'], sub { print "GOT: " . shift() . "\n"; 1 });

These interfaces may also be imported via the :functional tag:

        use ClearCase::Argv ':functional';

CAREFUL PROGRAMMERS WANTED ^

If you're the kind of programmer who tends to execute whole strings such as system("cleartool pwv -s") reflexively or who uses backquotes in a void context, this module won't help you much because it can't easily support those styles. These are deprecated techniques regardless of whether you use ClearCase::Argv and you should strive to overcome them.

STICKINESS ^

A subtlety: when an execution attribute is set in a void context, it's "sticky", meaning that it's set until explicitly reset. But in a non-void context the new value is temporary or "non-sticky"; it's pushed on a stack and popped off after being read once. This applies to both class and instance uses. It's done this way to allow the following locutions:

    ClearCase::Argv->stdout(0); # turn off stdout for all objects
    $obj1->stdout(0);           # turn off stdout for this object, forever
    $obj2->stdout(0)->system;   # suppress stdout, this time only

This allows you to set up an object with various sticky attributes and keep it around, executing it at will and overriding other attrs temporarily. In the example below, note that another way of setting sticky attrs is illustrated:

    my $obj = ClearCase::Argv->new({autofail=>1, autochomp=>1});
    my $view = $obj->argv('pwv -s')->qx;
    my $exists = $obj->argv('lstype', 'brtype:FOO')->autofail(0)->qx;

Here we keep an object with attrs 'autochomp' and 'autofail' (autofail means to exit on any failure) around and use it to exec whichever commands we want. While checking to see if a type exists, we suppress autofail temporarily. On the next use the object will have both attributes again.

BUGS ^

I suspect there are still some special quoting situations unaccounted for in the quote method. This will need to be refined over time. Bug reports or patches gratefully accepted.

Commands using a format option defining a multi-line output fail in many cases in fork mode, because of the underlying Argv module.

ClearCase::Argv will use IPC::ChildSafe if it finds it, which may introduce differences of behavior with the newer code to replace it. It should probably just drop it, unless explicitly driven to use it.

Autochomp should be equivalent in all modes on all platforms, which is hard to test (ipc w/wo IPC::ChildSafe, ctcmd, on Unix and Windows, with system and qx...). The autochomp setting should not affect system() in ipc mode!? Hopefully it doesn't anymore. Problem: change not satisfactorily tested on Windows yet (where the output prior to the last change seemed ok...)

Argv uses the first-found of three different modules for cloning, and Marc Girod suspects that only the first one (Clone, in recent versions) performs correctly with GLOB objects... work-around in place.

The use of 'cleartool -status' was restored, because of the failure to handle interactive comments without it. The ClearCase bug, with setview exiting the interactive session to the shell (Found from 2002.05.00 to 7.0.1 and resulting in a hang under the ipc mode) is worked around by starting a new coprocess in the new view.

Cygwin support on Windows.

The 'exit' cleartool command is dangerous in ipc mode: it will stop the coprocess unconditionally, without Argv updating its ipc status, and the ipccount. This will affect any other users of the same coprocess. Another symptom of the problem is a 'broken pipe' error. Argv writes to the coprocess, but obviously fails to read anything coming back.

Some multiline commands work in the fork mode, but not in the ipc one.

E.g. $ct->des(['-fmt', "%[owner]p\n"], 'vob:.')->system

This example is easily rewritten to work in both modes as either:

    $ct->des(['-fmt', '%[owner]p\n'], 'vob:.')->system
    $ct->des([qw(-fmt %[owner]p\n)], 'vob:.')->system

PORTABILITY ^

ClearCase::Argv should work on all supported ClearCase platforms and versions. It's currently maintained on Solaris 9 and Windows XP with CC 7.0 using Perl5.8.x. Viability on other platforms and/or earlier versions is untestable by me.

Marc Girod's testing environment: Solaris 10 (sparc and i386), GNU/Linux 2.6, and Windows Vista, without IPC::ChildSafe, with Clone. Perl 5.8.8, 5.10, 5.14, 5.16. Tatiana Shpichko's testing environment: RedHat Linux 4, with and without CtCmd, and Windows XP without CtCmd.

FILES ^

This is a subclass of Argv and thus requires Argv to be installed. ClearCase::CtCmd is required for ctcmd mode in Unix. In Windows, Win32-Process-Info or Win32::ToolHelp is required for pipe support.

SEE ALSO ^

perl(1), Argv, ClearCase::CtCmd

AUTHOR ^

David Boyce <dsbperl AT boyski.com>

COPYRIGHT ^

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

GUARANTEE ^

Double your money back!

syntax highlighting: