NAME
perfSONAR_PS::Client::Status::SQL - A module that provides methods for interacting with a Status MA database directly.
DESCRIPTION
This module allows one to interact with the Status MA SQL Backend directly using a standard set of methods. The API provided is identical to the API for interacting with the MAs via its Web Services interface. Thus, a client written to read from or update a Status MA can be easily modified to interact directly with its underlying database allowing more efficient interactions if required.
The module is to be treated as an object, where each instance of the object represents a connection to a single database. Each method may then be invoked on the object for the specific database.
SYNOPSIS
use perfSONAR_PS::Client::Status::SQL;
my $status_client = new perfSONAR_PS::Client::Status::SQL("DBI:SQLite:dbname=status.db");
if (not defined $status_client) {
print "Problem creating client for status MA\n";
exit(-1);
}
my ($status, $res) = $status_client->open;
if ($status != 0) {
print "Problem opening status MA: $res\n";
exit(-1);
}
($status, $res) = $status_client->getAll();
if ($status != 0) {
print "Problem getting complete database: $res\n";
exit(-1);
}
my @links = ();
foreach my $id (keys %{ $res }) {
print "Link ID: $id\n";
foreach my $link ( @{ $res->{$id} }) {
print "\t" . $link->getStartTime . " - " . $link->getEndTime . "\n";
print "\t-Knowledge Level: " . $link->getKnowledge . "\n";
print "\t-operStatus: " . $link->getOperStatus . "\n";
print "\t-adminStatus: " . $link->getAdminStatus . "\n";
}
push @links, $id;
}
($status, $res) = $status_client->getLinkStatus(\@links, "");
if ($status != 0) {
print "Problem obtaining most recent link status: $res\n";
exit(-1);
}
foreach my $id (keys %{ $res }) {
print "Link ID: $id\n";
foreach my $link ( @{ $res->{$id} }) {
print "-operStatus: " . $link->getOperStatus . "\n";
print "-adminStatus: " . $link->getAdminStatus . "\n";
}
}
($status, $res) = $status_client->getLinkHistory(\@links);
if ($status != 0) {
print "Problem obtaining link history: $res\n";
exit(-1);
}
foreach my $id (keys %{ $res }) {
print "Link ID: $id\n";
foreach my $link ( @{ $res->{$id} }) {
print "-operStatus: " . $link->getOperStatus . "\n";
print "-adminStatus: " . $link->getAdminStatus . "\n";
}
}DETAILS
API
The API os perfSONAR_PS::Client::Status::SQL is rather simple and greatly resembles the messages types received by the server. It is also identical to the perfSONAR_PS::Client::Status::MA API allowing easy construction of programs that can interface via the MA server or directly with the database.
new($package, $dbi_string)
The new function takes a DBI connection string as its first argument. This specifies which DB to read from/write to.
open($self)
The open function opens the database to read from/write to. The function returns an array containing two items. The first is the return status of the function, 0 on success and non-zero on failure. The second is the error message generated if applicable.
close($self)
The close function closes the associated database. It returns 0 on success and -1 on failure.
setDBIString($self, $dbi_string)
The setDBIString function changes the database that the instance uses. If open, it closes the current database.
dbIsOpen($self)
The dbIsOpen function checks whether the database backend is currently open. If so, it returns 1, if not, 0.
getDBIString($self)
The getDBIString function returns the current DBI string
getAll($self)
The getAll function gets the full contents of the database. It returns the results as a hash with the key being the link id. Each element of the hash is an array of perfSONAR_PS::Status::Link structures containing a the status of the specified link at a certain point in time.
getLinkHistory($self, $link_ids)
The getLinkHistory function returns the complete history of a set of links. The $link_ids parameter is a reference to an array of link ids. It returns the results as a hash with the key being the link id. Each element of the hash is an array of perfSONAR_PS::Status::Link structures containing a the status of the specified link at a certain point in time.
getLinkStatus($self, $link_ids, $time)
The getLinkStatus function returns the link status at the specified time. The $link_ids parameter is a reference to an array of link ids. $time is the time at which you'd like to know each link's status. $time is a perfSONAR_PS::Time element. If $time is an undefined, it returns the most recent information it has about each link. It returns the results as a hash with the key being the link id. Each element of the hash is an array of perfSONAR_PS::Status::Link structures containing a the status of the specified link at a certain point in time.
updateLinkStatus($self, $time, $link_id, $knowledge_level, $oper_value, $admin_value, $do_update)
The updateLinkStatus function adds a new data point for the specified link. $time is a unix timestamp corresponding to when the measurement occured. $link_id is the link to update. $knowledge_level says whether or not this measurement can tell us everything about a given link ("full") or whether the information only corresponds to one side of the link("partial"). $oper_value is the current operational status and $admin_value is the current administrative status. $do_update tells whether or not we should try to update the a given range of information(e.g. if you were polling the link and knew that nothing had changed from the previous iteration, you could set $do_update to 1 and the server would elongate the previous range instead of creating a new one).
getUniqueIDs($self)
This function is ONLY available in the SQL client as the functionality it is not exposed by the MA. It does more or less what it sounds like, it returns a list of unique link ids that appear in the database. This is used by the MA to get the list of IDs to register with the LS.
SEE ALSO
perfSONAR_PS::DB::SQL, perfSONAR_PS::Status::Link,perfSONAR_PS::Client::Status::MA, Log::Log4perl
To join the 'perfSONAR-PS' mailing list, please visit:
https://mail.internet2.edu/wws/info/i2-perfsonarThe perfSONAR-PS subversion repository is located at:
https://svn.internet2.edu/svn/perfSONAR-PS Questions and comments can be directed to the author, or the mailing list.
VERSION
$Id$
AUTHOR
Aaron Brown, aaron@internet2.edu
LICENSE
You should have received a copy of the Internet2 Intellectual Property Framework along with this software. If not, see <http://www.internet2.edu/membership/ip.html>
COPYRIGHT
Copyright (c) 2004-2007, Internet2 and the University of Delaware
All rights reserved.