<HTML>
<HEAD>
<TITLE>RRDs</TITLE>
<LINK REV="made" HREF="mailto:karrer@iis.ee.ethz.ch">
</HEAD>
<BODY>
<A NAME="__index__"></A>
<!-- INDEX BEGIN -->
<!--
<UL>
<LI><A HREF="#name">NAME</A></LI>
<LI><A HREF="#synopsis">SYNOPSIS</A></LI>
<LI><A HREF="#description">DESCRIPTION</A></LI>
<UL>
<LI><A HREF="#calling sequence">Calling Sequence</A></LI>
<LI><A HREF="#error handling">Error Handling</A></LI>
<LI><A HREF="#return values">Return Values</A></LI>
</UL>
<LI><A HREF="#author">AUTHOR</A></LI>
</UL>
-->
<!-- INDEX END -->
<P>
<H1><A NAME="name">NAME</A></H1>
<P>RRDs - Access rrdtool as a shared module</P>
<P>
<HR>
<H1><A NAME="synopsis">SYNOPSIS</A></H1>
<PRE>
use RRDs;
RRDs::error
RRDs::last ...
RRDs::info ...
RRDs::create ...
RRDs::update ...
RRDs::graph ...
RRDs::fetch ...
RRDs::tune ...</PRE>
<P>
<HR>
<H1><A NAME="description">DESCRIPTION</A></H1>
<P>
<H2><A NAME="calling sequence">Calling Sequence</A></H2>
<P>This module accesses rrdtool functionality directly from within perl. The
arguments to the functions listed in the SYNOPSIS are explained in the regular
rrdtool documentation. The commandline call</P>
<PRE>
rrdtool update mydemo.rrd --template in:out N:12:13</PRE>
<P>gets turned into</P>
<PRE>
RRDs::update ("mydemo.rrd", "--template", "in:out", "N:12:13");</PRE>
<P>Note that</P>
<PRE>
--template=in:out</PRE>
<P>is also valid.</P>
<P>
<H2><A NAME="error handling">Error Handling</A></H2>
<P>The RRD functions will not abort your program even when they can not make
sense out of the arguments you fed them.</P>
<P>The function RRDs::error should be called to get the error status
after each function call. If RRDs::error does not return anything
then the previous function has completed its task successfully.</P>
<PRE>
use RRDs;
RRDs::update ("mydemo.rrd","N:12:13");
my $ERR=RRDs::error;
die "ERROR while updating mydemo.rrd: $ERR\n" if $ERR;</PRE>
<P>
<H2><A NAME="return values">Return Values</A></H2>
<P>The functions RRDs::last, RRDs::graph, RRDs::info and RRDs::fetch return their
findings.</P>
<P><STRONG>RRDs::last</STRONG> returns a single INTEGER representing the last update time.</P>
<PRE>
$lastupdate = RRDs::last ...</PRE>
<P><STRONG>RRDs::graph</STRONG> returns an pointer to an ARRAY containing the x-size and y-size of the
created gif and results of the PRINT arguments.</P>
<PRE>
($averages,$xsize,$ysize) = RRDs::graph ...
print "Gifsize: ${xsize}x${ysize}\n";
print "Averages: ", (join ", ", @$averages);</PRE>
<P><STRONG>RRDs::info</STRONG> returns a pointer to a hash. The keys of the hash
represent the property names of the rrd and the values of the hash are
the values of the properties.</P>
<PRE>
$hash = RRDs::info "example.rrd";
foreach my $key (keys %$hash){
print "$key = $$hash{$key}\n";
}</PRE>
<P><STRONG>RRDs::fetch</STRONG> is the most complex of
the pack regarding return values. There are 4 values. Two normal
integers, a pointer to an array and a pointer to a array of pointers.</P>
<PRE>
my ($start,$step,$names,$data) = RRDs::fetch ...
print "Start: ", scalar localtime($start), " ($start)\n";
print "Step size: $step seconds\n";
print "DS names: ", join (", ", @$names)."\n";
print "Data points: ", $#$data + 1, "\n";
print "Data:\n";
foreach my $line (@$data) {
print " ", scalar localtime($start), " ($start) ";
$start += $step;
foreach my $val (@$line) {
printf "%12.1f ", $val;
}
print "\n";
}</PRE>
<P>See the examples directory for more ways to use this extension.</P>
<P>
<HR>
<H1><A NAME="author">AUTHOR</A></H1>
<P>Tobias Oetiker <<A HREF="mailto:oetiker@ee.ethz.ch">oetiker@ee.ethz.ch</A>></P>
</BODY>
</HTML>
