NAME

Liz::PingSet - Perform ping tests to indicated IP-numbers


SYNOPSIS

 use Liz::PingSet;

 $file = new Liz::PingSet;


EXAMPLES

 #!/usr/local/bin/perl

 use Liz::PingSet;


DESCRIPTION

The Liz::PingSet package allows for very simple storage of sets of ping-results in a database.


Incorporate into Client Module

The Liz::PingSet module itself works best when incorporated into a client module because it moves the responsibility of aquiring a connection to a database to the client module and it allows any customisation to take place transparently to the developer.

Take for example the PingSet method of HN.pm module:

 sub PingSet {

 # Obtain the parameters
 # Start the file using the $hn handle as the database handle
 # Return the finished object

 my( $hn,$token ) = @_;
 my( $pingset ) = Liz::PingSet->new( $hn,$token );
 $pingset;
 }

Because of the above code in HN.pm, it is now possible to write the following code:

 $hn = new HN;
 $pingset = $hn->PingSet( 'technology' );

Note that the database connection of the file is hidden in the creation of the $hn object.


CLASS METHODS

The following methods can be called without an object specification, but as a class method such as Liz::PingSet->method().


pingsets

Return list of file identification names of all pingsets in the database specified. Usually not called by itself, but rather incorporated inside a Client Module.

Input Parameters

 1 Liz::SQL compatible handle or reference to routine that performs connect
   (default: &Connect from caller's namespace)
 2 wildcard specification to match
   (default: all)
Output Parameters

 1 reference to list of identification names in the current database
 2 reference to hash with full names
Example

 $hn = new HN;
 ($id,$name) = $hn->PingSets;
 $pingsets = @{$id};
 print "All $pingsets pingsets in Hospitality Net:\n";
 foreach( @{$id} ) {
   print " PingSet '$$name{$_}' ($_)\n";
 }

In HN.pm:

 sub PingSets { Liz::PingSet->pingsets( @_ ) }


new

Create a new Liz::PingSet object. Creates connection or re-establishes connection with the MySQL database. Usually not called by itself, but rather incorporated inside a Client Module.

Input Parameters

 1 Liz::SQL compatible handle or reference to routine that performs connect
   (default: &Connect from caller's namespace)
 2 identification name of file set
   (default: default file set for database)
Output Parameters

 1 instantiated object
 2 flag whether PingSet was just created
Example

 $hn = new HN;
 $pingset = $hn->PingSet( 'technology' );

In HN.pm:

 sub PingSet { Liz::PingSet->new( @_ ) }


CONTENT METHODS

The following methods allow changes to information that is associated with an entire pingset.


From

Specify or return the hostname or IP-number from which each test is performed. This can only be specified if there are no ping tests in the database. If there are any, any attempt at changing this will be ignored.

The IP-number will be set to the output of the 'hostname' command when the pingset is created.

Input Parameters

 1 new hostname/IP-number
   (default: no change)
Output Parameters

 1 current/old IP-number of host from where test is performed
Example

 $xxlink = new xxLINK;
 ($pingset,$new) = $xxlink->PingSet( 'A2000' );
 $pingset->From( 'wasp.xxLINK.nl' ) if $new;
 $from = $pingset->From;


Name

Specify or return the current name of the pingset object. The name can be anything to further identify the goal of the pingset.

Input Parameters

 1 new name of pingset
   (default: no change)
Output Parameters

 1 current/old name of pingset
Example

 $xxlink = new xxLINK;
 $pingset = $xxlink->PingSet( 'a2000' );
 $pingset->Name( 'Pingtest voor thuiswerkers bij A2000' );


PacketSize

Specify or return the number of bytes in a packet that is sent in each test. This can only be specified if there are no ping tests in the database. If there are any, any attempt at changing this will be ignored.

The packetsize is set to 56 when the pingset is created.

Input Parameters

 1 new number of bytes in packets
   (default: no change)
Output Parameters

 1 current/old number of bytes in packets
Example

 $xxlink = new xxLINK;
 ($pingset,$new) = $xxlink->PingSet( 'A2000' );
 $pingset->PacketSize( 1024 ) if $new;
 $packetsize = $pingset->PacketSize;


Pings

Specify or return the number of pings that should be performed by each test. This can only be specified if there are no ping tests in the database. If there are any, any attempt at changing this will be ignored.

The number of pings is set at 100 when the pingset is created.

Input Parameters

 1 new number of pings to be performed
   (default: no change)
Output Parameters

 1 current/old name of pings to be performed
Example

 $xxlink = new xxLINK;
 ($pingset,$new) = $xxlink->PingSet( 'A2000' );
 $pingset->Pings( 10 ) if $new;
 $pings = $pingset->Pings;


Program

Specify or return the current name of the external program to perform the ping test. The default at creation of the PingSet is 'ping'.

Input Parameters

 1 new name of external program
   (default: no change)
Output Parameters

 1 current/old name of external program
Example

 $xxlink = new xxLINK;
 $pingset = $xxlink->PingSet( 'eurest' );
 $pingset->Program( '/sbin/ping' );
 $program = $pingset->Program;


PING METHODS

The following methods allow changes to a single ping test in a PingSet.


delete

Delete a specific Liz::PingSet::Record object from the database.

Input Parameters

 1..N identifiers of the Liz::PingSet::Record to be deleted
Output Parameters

 1    flag: whether action was successful
Example

 $record->delete;


Last

Create a Ping object for the last test of the given IP-number/hostname.

Input Parameters

 1 IP-number/hostname to create Ping object for
Output Parameters

 1 instantiated Liz::PingSet::Ping object
Example

 $last = $pingset->Last( 'node14da.a2000.nl' );


Ping

Create a new Liz::PingSet::Ping object, either from existing information or for a new entry. For more documentation, see the Liz::PingSet::Ping object itself.

Input Parameters

 1 ID to create Ping object with
   (default: none = new record)
Output Parameters

 1 instantiated Ping object
Example

 $hn = new HN;
 $pingset = $hn->PingSet( 'xxLINK' );

 $ping = $pingset->Ping;
 $ping = $pingset->Ping( $ID );


LIST METHODS

The following methods return lists associated with the PingSet.


IPHosts

Return a list of different IP numbers and hostnames for which ping tests have been performed. Usually intended to be used with <PULLDOWN... >.

Input Parameters

 1     extra condition to be applied
       (default: none)
Output Parameters

 1..2N IP-number/hostname pairs
Example

 <PULLDOWN IP "(qw(extended &nbsp; all),$pingset->IPHosts)">


IPs

Return the list of different IP numbers for which ping tests have been performed.

Input Parameters

 1    extra condition to be applied
      (default: none)
 2    flag to indicate packed IP-numbers
      (default: unpacked)
Output Parameters

 1..N (packed) IP-numbers for which tests have been done
Example

 @IP = $pingset->IPs;


List

Return an SQL statement handle for a list of events.

The following fields may be specified with the 2nd parameter:

 ID
 The unique ID of the record

 IP
 The IP-number which was being pinged

 created
 Timestamp value when this record was created

 lost
 Number of packets lost

 dups
 Number of duplicated packets found

 minroundtrip
 Smallest number of micro-seconds for the roundtrip

 avgroundtrip
 Average number of micro-seconds for the roundtrip

 maxroundtrip
 Highest number of micro-seconds for the roundtrip
Input Parameters

 1 fields to return (comma delimited)
   (default: 'ID,IP,created,lost,dups,minroundtrip,avgroundtrip,maxroundtrip,elapsed' );
 2 fieldname on which to order the result
   (default: 'created')
 3 extra condition to be applied
   (default: none)
Output Parameters

 1 SQL statement handle (on which method "fetchrow" can be applied)


Test

Perform a ping test on a specific hostname or IP-number and store the result in the PingSet as a Ping record.

Input Parameters

 1 hostname/IP-number to perform test on
Output Paremeters

 1 number of packets lost
 2 number of duplicates found
 3 minimum round trip in microseconds
 4 average round trip in microseconds
 5 maximum round trip in microseconds
 6 elapsed time in wallclock seconds
Example

 $pingset->Test( 'node14da.a2000.nl' );
Example

 $lost = $pingset->Test( 'a2000.ronaldlens.com' );
 warn "There were $lost packets lost\n" if $lost>=5;


AUTHOR

Elizabeth Mattijsen ( lizperl@INC.nl )


COPYRIGHT

(C) 1999 International Network Consultants


HISTORY

Version 0.22, 25 November 1999

Put module name between quotes to fix obscure bug in Perl 5.005x under ModPerl in method Ping.

Version 0.21, 30 September 1999

Now no longer adds Exporter to ISA: it wasn't necessary.

Version 0.2, 1 September 1999

Method Last added: create a Ping object for the last test of a given hostname/IP-number;

Version 0.1, 29 August 1999

First version of this true Perl module.