/ 
CASCM-Wrapper-0.04
River stage one • 1 direct dependent • 1 total dependent
/ CASCM::Wrapper

NAME

CASCM::Wrapper - Run CA-SCM (Harvest) commands

VERSION

This document describes CASCM::Wrapper version 0.04

SYNOPSIS

use CASCM::Wrapper;

# Initialize
my $cascm = CASCM::Wrapper->new();

# Set Context
$cascm->set_context(
    {    # Set a global context. This is applied to all commands where required
       global => { b  => 'harvest',
                   eh => 'user.dfo',
       },

       # Set 'hco' specific context, applied only to hco commands
       hco => { up => 1,
                vp => '\repository\myapp\src',
                pn => 'Checkout Items',
       },

       # Similarly for 'hci'
       hci => { vp => '\repository\myapp\src',
                pn => 'Checkin Items',
                de => 'Shiny new feature',
       },

       # And 'hcp'
       hcp => { st => 'development',
                at => 'userid',
       },
    }
) or die $cascm->errstr;

# Create Package
my $pkg = 'new_package';
$cascm->hcp($pkg) or die $cascm->errstr;

# Checkout files
my @files = qw(foo.c bar.c);
$cascm->hco( { p => $pkg }, @files ) or die $cascm->errstr;

# Update Context
$cascm->update_context( { hci => { p => $pkg }, } ) or die $cascm->errstr;

# Checkin files
$cascm->hci(@files) or die $cascm->errstr;

DESCRIPTION

This module is a wrapper around CA-SCM (formerly known as Harvest) commands. It provides a perl-ish interface to setting the context in which each command is executed, along with optional loading of context from files as well as parsing output logs.

CONTEXT

The context is a hash of hashes which contain the following types of keys:

global

This specifies the global context. Any context set here will be applied to every command that uses it.

my $global_context = {
                       global => { b  => 'harvest',
                                   eh => 'user.dfo',
                       },
  };
command specific

This provides a command specific context. Context set here will be applied only to those specific commands.

my $hco_context = {
                    hco => { up => 1,
                             vp => '\repository\myapp\src',
                             pn => 'Checkout Items',
                    },
};

The global and command context keys are synonymous with the command line options detailed in the CA-SCM Reference Manual. Options that do not require a value should be set to '1'. i.e. {hco => {up => 1} } is equivalent to hco -up. The methods are intelligent enough to apply only the context keys that are used by a command. For e.g. a global context of vp will not apply to hcp.

The 'common' options i and di are not applicable and ignored for all commands. See "SECURITY"

The following methods are available to manage context

set_context($context)

Sets the context. Old context is forgotten. The argument provided must be a hash reference

update_context($context)

Updates the current context. The argument provided must be a hash reference

load_context($file)

This loads the context from an 'INI' file. The root parameters defines the global context. Each sectional parameter defines the command specific context. Old context is forgotten.

# Load context file at initialization. This will croak if it fails to read the context file
my $cascm = CASCM::Wrapper->new( { context_file => $file } );

# Alternatively
$cascm->load_context($file) or die $cascm->errstr;

This is a sample context file

# Sample context file

# Root parameters. These define the 'global' context
b  = harvest
eh = user.dfo

# Sectional parameters. These define the 'command' context

[hco]
	up = 1
	vp = \repository\myapp\src

[hcp]
	st = development

NOTE: This method requires Config::Tiny in order to read the context file.

get_context()

Returns a hash reference of current context

my $context = $cascm->get_context();
use Data::Dumper;
print Dumper($context);

CA-SCM METHODS

Almost every 'h' command that uses a context is supported. The command names are synonymous with the methods used to invoke them.

Every method accepts two optional arguments. The first is an hash reference that overrides/appends to the context for that method. This allows setting a context only for that specific method call. The second is an array of arguments that is passed on to the 'h' command. Any arguments provided is passed using the '-arg' option.

# No parameters. Everything required is already set in the context
$cascm->hdlp() or die $cascm->errstr;

# Array of arguments
$cascm->hci( @files ) or die $cascm->errstr;

# Override/Append to context
$cascm->hci( { p => 'new_package' }, @files ) or die $cascm->errstr;

The methods can be called in a 'dry run' mode. Where the method returns the full command line, without executing anything. This can be useful for debugging.

$cascm = CASCM::Wrapper->new( { dry_run => 1 } );
$cascm->set_context($context);
$cmd = $cascm->hsync();
print "Calling hsync() would have executed -> $cmd";

The following CA-SCM commands are available as methods

haccess
hap
har
hauthsync
hcbl
hccmrg
hcrrlte
hchgtype
hchu
hci
hcmpview
hco
hcp
hcpj
hcropmrg
hcrtpath
hdbgctrl
hdelss
hdlp
hdp
hdv
hexecp
hexpenv
hfatt
hformsync
hft
hgetusg
himpenv
hlr
hlv
hmvitm
hmvpkg
hmvpth
hpg
hpkgunlk
hpp
hppolget
hppolset
hrefresh
hrepedit
hrepmngr
hri
hrmvpth
hrnitm
hrnpth
hrt
hsigget
hsigset
hsmtp
hspp
hsql
hsv
hsync
htakess
hucache
hudp
hup
husrmgr
husrunlk

SECURITY

This module uses the di option for executing CA-SCM commands. This prevents any passwords from being exposed while the command is running. The temporary di file is deleted irrespective if the outcome of the command.

LOGGING

Since CA-SCM commands output only to log files, this module allows parsing and logging of a command's output. Log::Any is required to use this feature, which in turn allows you to use any (supported) Logging mechanism. When using this, any 'o' or 'oa' options specified in the context will be ignored. Your scripts will need to load the appropriate Log::Any::Adapter to capture the log statements. The CA-SCM log is parsed and the messages are logged either as 'INFO', 'WARN' or 'ERROR'.

# Using Log4perl

use CASCM::Wrapper;
use Log::Log4perl;
use Log::Any::Adapter;

Log::Log4perl->init('log4perl.conf');
Log::Any::Adapter->set('Log4perl');

# Get logger
my $log = Log::Log4perl->get_logger();

# Set parse_logs to true. This will croak if Log:Any is not found.
my $cascm = CASCM::Wrapper->new( { parse_logs => 1 } );

# Set Context
my $context = { ... };
$cascm->set_context($context);

# Calling the method automatically will parse the log output into the Log4perl object
# The output is also logged in the 'CASCM::Wrapper' category.

$cascm->hco(@files) or die $cascm->errstr;

ERROR HANDLING

All methods return true on success and undef on failure. The error that most likely caused the last failure can be obtained by calling the errstr method.

INSTALLATION

To install using Module::Build, run the following

perl Build.PL
./Build
./Build test
./Build install

To install using ExtUtils::MakeMaker, run the following

perl Makefile.PL
make
make test
make install

To install using CPAN

cpan CASCM::Wrapper

DEPENDENCIES

CA-SCM r12 (or higher) client. Harvest 7.1 might work, but has not been tested.

The CA-SCM methods depends on the corresponding commands to be available in the PATH

At least Perl 5.6.1 is required to run.

Optionally, Config::Tiny is required to read context files

Optionally, Log::Any and Log::Any::Adapter is required to parse CA-SCM log files

BUGS AND LIMITATIONS

No bugs have been reported.

Please report any bugs or feature requests to bug-cascm-wrapper@rt.cpan.org, or through the web interface at http://rt.cpan.org.

SOURCE

The repository for CASCM::Wrapper is available at http://github.com/mithun/perl-cascm-wrapper

ACKNOWLEDGEMENTS

Sean Blanton and Rachana Gaddam for their ideas and input.

AUTHOR

Mithun Ayachit <mithun@cpan.org>

LICENCE AND COPYRIGHT

Copyright (c) 2010, Mithun Ayachit <mithun@cpan.org>. All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.

DISCLAIMER OF WARRANTY

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.