• NAME
• SYNOPSIS
• DESCRIPTION
• init
• new
• perform
• tostring
• pr
• prf
• rc
• msg

---

NAME

Communiware::Cmwctl - base class for all actions are called from cmwctl script

---

SYNOPSIS

        use Communiware::Cmwctl;
        use Communiware::Config;
        my $c = new Communiware::Config('cmw.conf');
        $n = new Communiware::Cmwctl($c->daemon('frontend')->command('start'));
        $n->perform;
        if ($n->rc eq CCRC_OK) {
                print "ok\n";
        }
        else {
                print $n->rc, ' ', $n->msg, "\n";
        }

---

DESCRIPTION

Script cmwctl before execution parses config file and builds tree of Communiware::Cmwctl subclasses objects. Each of them may be 'performed' and sets return code after this.

This module contains definition of base class as well as some needed constants.

init

$ret = init($node, $extra);

This function (not method!) is tool for use in Communiware::Cmwctl subclasses. It accepts the same arguments as new method and returns hash reference, which can be blessed into subclass object. Function fills these fields:

node

Equal to $node argument.

id

$node id attribute, if exists.

rc

Return code (see below). Is set to CCRC_UNKNOWN.

msg

After-executing message, is set to empty string.

nodetype

String, type of $node ('daemoncommand', 'filematch', etc).

retry

Sign that this node must re-executed even after success. See Communiware::Cmwctl::cmdblock for details.

new

$n = new Communiware::Cmwctl($node, \%extra);

Constructor. First argument is Communiware::Config object, which represents node in parsed config tree. Type of this node must be 'daemoncommand' or one of types allowed inside daemoncommand, such as exec, filecheck, cmdblock etc. In other words there must be corresponding Communiware::Cmwctl::* module.

Method requires such a module and calls new method of subclass. So Communiware::Cmwctl->new always returns object of Communiware::Cmwctl subclass or dies if there is no such module. Object itself must be hash reference. Some keys in it have special meaning, described below.

%extra (optional) is the hash with some extra parameters. It is used by init method to getting object prototype. Main of fields in %extra are

nest

Nesting level - 0 for top level etc. Is used for fancy trace printing.

trace

Do or not tracing.

The template for subclass constructor is:

        sub new {
                my ($class, $node, $env) = @_;
                my $ret = Communiware::Cmwctl::init($node, $env);
                bless $ret;
                ... do something, i.e. set fields in %$ret ...
                return $ret;
        }

If constructor creates another Communiware::Cmwctl objects from itself it must transmit them its env field as second constructor parameter. See constructors for do, cmdblock and daemoncommand classes for details.

perform

This method must be redefined in subclasses. It does something that means 'performing' for this node type. I.e. perform for checkprocess is to check if process, given by pidfile, is running.

After executing method must set these fields in itself:

msg

Message describing result of performing - on success as well as on fail. It may be 'string ... found in file ...' on success or 'pattern ... not found in file ...' on fail.

rc

Return code. One of following constants

CCRC_UNKNOWN

Nothing can be sayd about result. Method must not set this return code to itself.

CCRC_OK

Performing was successful.

CCRC_FAIL

Performing fails (inverse of CCRC_OK).

CCRC_ERROR

Performing fails, and execution of top-level command interrupts. For cmwctl this means ``to interrupt execution this command for this daemon''.

CCRC_FATAL

Fatal error. 'die' is called immediately after receiving such return code.

Here is possible template for subclasses perform:

sub perform { my ($self) = @_; $self->{rc} = CCRC_FAIL; if (something is wrong) { $self->{msg} = ``Wrong 1''; return; } ... do something, maybe use field from %$self are set in constructor ... if (something again wrong) { $self->{msg} = ``Wrong 2''; return; } ... do something ... $self->{msg} = ``I have done all you want!''; $self->{rc} = CCRC_OK; }

tostring

print $n->tostring, ``\n'';

Method returns string representation of Communiware::Cmwctl object. This string contains type of object and its main attributes, i.e.:

do errlevel=fail invert=0 repeat=1 retry=0 wait=1 what=backendIsNotRunning

pr

$n->pr('Here I am:', $n->tostring);

If tracing (see -t option by cmwctl) is on prints all argumens like usual print, but with left indent depended from nesting level and trailing newline. Without tracing and without quite work (-q cmwctl option) prints single dot. If quite work is set does nothing.

Use this method for printing trece messages from perform methods.

prf

$n->prf(``Executed: %s rc: %s'', $self->{nodetype}, $self->{rc})

Works similar pr method, but does format printing as printf.

rc

$rc = $n->rc

Just returns rc (return code) field of object.

msg

$m = $n->msg

Returns msg field of object.