SYNOPSIS

  use PatrolPerl qw(:DEFAULT);


DESCRIPTION

PatrolPerl is a small wrapper around the BMC PemAPI ( which is provided with BMC Patrol ) to access some ( not all ) functions of the API via Perl.

What is implemented:

 scalar=patconnect (agent hostname,tcp port of agent, username , password )
        Logon at a Agent with username/password/port
        Other than the default within BMC, TCP is used instead of UDP.
        ( I decided to support ONLY tcp, because esp. in firewalled environments
        tcp is normaly much more easy to allow than the udp stuff )
  
        on success, a handle is returned, otherwise NULL and $errstr is set.
  
        
 scalar=patclose($handle)
        Logout from the Agent identified by $handle
        
        returns 1 on success or 0 of failure
 array=patgetapplist($handle)
        Returns a array containing ALL running Applications on the Agent
        ( Applications is in the BMC KM meaning on application )
        if you get back undef, you might find a message in $errstr in case
        of an error
 array=patgetinstlist($handle,Application)
        Returns a array containing ALL running Instances of a specified
        Application on the Agent identified by $handle
        ( Instance is in the BMC KM meaning on instance )
        if you get back undef, you might find a message in $errstr in case
        of an error
 array=patgetparalist($handle,Application,Instance)
        Returns a array containing ALL running Parameters of a specified
        Instance of the specified Application
        ( Parameter is in the BMC KM meaning on parameter )
        if you get back undef, you might find a message in $errstr in case
        of an error
 scalar=patgetvalue ($handle,Application, Instance, Parameter )
        Returns the current value of the specified parameter
        ( like in PSL a get("/Application/Instance/Parameter/value) ; )
 scalar=patgetXvalue ($handle,Application, Instance, Parameter,Type )
        Returns the current value of the variable "type"  of the specified parameter
        possible types are:
        PEMN_PARAMNAME
        PEMN_PARAMCURRENTTIME
        PEMN_PARAMPOLLINGINT
        PEMN_PARAMRETRIES
        PEMN_PARAMCURRENTVALUE
        PEMN_PARAMSTATE
        PEMN_PARAMOUTPUTMODE
        PEMN_PARAMAUTOSCALE
        PEMN_PARAM_Y_AXIS_MIN
        PEMN_PARAM_Y_AXIS_MAX
        So this means, that a patgetXvalue ($hande,App,Inst,Para,PEMN_PARAMCURRENTVALUE)
        is the same as patgetvalue ($hande,App,Inst,Para)
 scalar=patsendevent($handle,Event Catalog, EventClass, Origin, OldState, NewState, EventType, Serverity, Message)
        Returns 1 if the event has been send or a ErrorMessage on failure.
        $handle : Connection Handle set up with  patconnect()
        EventCatalog: either the name of your Catalog like "MY_CATALOG" or use the return value
                        of STD_EVENT_CATALOG for the standard event catalog
        EventClass:   the class to be used
        Origin:       the origin of the event ( will be showed in PEM )
        OldState:     the old state of the parameter    
        NewState:     the new state of the parameter    
        EventType:    the type of the event
        Severity:     the severity as number from 1 to 5
        Message:      a array containing lines of messages
        Values: Old/NewState should be "" "VOID" "OFFLINE" "OK" "WARN" "ALARM"
                Eventtype should be
                        EV_TYPE_INFORMATION
                        EV_TYPE_CHANGE_STATUS
                        EV_TYPE_ERROR
                        EV_TYPE_WARNING
                        EV_TYPE_ALARM
                        EV_TYPE_RESPONSE
                        EV_TYPE_ACK
                        EV_TYPE_MAX


INSTALLATION

        1. unpack this module ( imho, you can read this, you did it?! ;-) )
        2. specify where to find the Patrol API, either by setting up the
           $PATROL_HOME variable (e.g. by running . ./patrolrc.sh in the install
           directory), OR by setting the PATROL_LIB and PATROL_INCLUDE
           variables to the directories, the *.a files (for LIB) and *.h files
           (for INCLUDE) are.
        3. run perl Makefile.PL or 
             PATROL_LIB=<place to find *.a> \
             PATROL_INCLUDE=<place to find *.h> \
             perl Makefile.PL
        4. run make
        5. if you would like to, modify test.pl to you own settings to query an agent
        6. run make install as a user that has the permissions to ;)
        7. enjoy the perl module ;-) at the examples section here is something maybe
           interesting and furthermore test.pl contains some stuff.


EXPORTS

 Description see above
        patconnect
        patgetvalue
        patgetXvalue
        patclose
        patgetapplist
        patgetinstlist
        patgetparalist
        patsendevent
        PEMN_PARAMNAME
        PEMN_PARAMCURRENTTIME
        PEMN_PARAMPOLLINGINT
        PEMN_PARAMRETRIES
        PEMN_PARAMCURRENTVALUE
        PEMN_PARAMSTATE
        PEMN_PARAMOUTPUTMODE
        PEMN_PARAMAUTOSCALE
        PEMN_PARAM_Y_AXIS_MIN
        PEMN_PARAM_Y_AXIS_MAX
        STD_EVENT_CATALOG
        EV_TYPE_INFORMATION
        EV_TYPE_CHANGE_STATUS
        EV_TYPE_ERROR
        EV_TYPE_WARNING 
        EV_TYPE_ALARM 
        EV_TYPE_RESPONSE
        EV_TYPE_ACK
        EV_TYPE_MAX
        $errstr


EXAMPLES

get the all running applications on agent 192.168.1.2

        use PatrolPerl qw(:DEFAULT);
        my $handle=patconnect('192.168.1.2','3181','patrol','thepatrolpassword') || die $errstr;
        foreach $app(patgetapplist($handle)) {
                print "Running application: $app \n";
        }
        patclose($handle) || die "some thing strange in close.. \n";

get the Value of the Filesystem Capacity on an unix agent

        use PatrolPerl qw(:DEFAULT);
        my $handle=patconnect('192.168.1.2','3181','patrol','thepatrolpassword') || die $errstr;
        my $val=patgetvalue($handle,'FILESYSTEM','root','FSCapacity');
        print "Filesystem capacity of root is: $val \n";
        patclose($handle) || die "some thing strange in close.. \n";

get the Alarm status of the Filesystem Capacity on an unix agent

        use PatrolPerl qw(:DEFAULT);
        my $handle=patconnect('192.168.1.2','3181','patrol','thepatrolpassword') || die $errstr;
        my $val=patgetXvalue($handle,'FILESYSTEM','root','FSCapacity',PEMN_PARAMSTATE);
        print "Filesystem capacity of root status: $val \n";
        patclose($handle) || die "some thing strange in close.. \n";


LIMITATIONS

The module only supports the API calls described above. The PEM API has a lot of more functionality inside, which is not implemented in this Perl module, because I had no need for it. Furthermore - all limitations of the PEM Api described in the PEM API handbook, are also in the Perl module - a wonder? :)


AUTHOR

Martin Mersberger, Cable&Wireless Germany GmbH, OSS Europe martinm@cw.net


HOMEPAGE

http://portal-to-web.de/PatrolPerl


SEE ALSO

perl(1), http://www.bmc.com, http://www.bmc.com/supportu/documents/30/12/53012/53012.pdf (PemAPI description)