prepare for the release of rrdtool-1.2.18

[rrdtool.git] / bindings / perl-piped / RRDp.pm

diff --git a/bindings/perl-piped/RRDp.pm b/bindings/perl-piped/RRDp.pm
index c644766..a2caeca 100644 (file)
--- a/bindings/perl-piped/RRDp.pm
+++ b/bindings/perl-piped/RRDp.pm
@@ -2,13 +2,13 @@ package RRDp;
 
 =head1 NAME
 
-RRDp - Attach rrdtool from within a perl script via a set of pipes;
+RRDp - Attach RRDtool from within a perl script via a set of pipes;
 
 =head1 SYNOPSIS
 
 use B<RRDp>
 
-B<RRDp::start> I<path to rrdtool executable>
+B<RRDp::start> I<path to RRDtool executable>
 
 B<RRDp::cmd>  I<rrdtool commandline>
 
@@ -16,19 +16,19 @@ $answer = B<RRD::read>
 
 $status = B<RRD::end>
 
-B<$RRDp::user>,  B<$RRDp::sys>, B<$RRDp::real>
+B<$RRDp::user>,  B<$RRDp::sys>, B<$RRDp::real>, B<$RRDp::error_mode>, B<$RRDp::error>
 
 =head1 DESCRIPTION
 
-With this module you can safely communicate with the rrdtool. 
+With this module you can safely communicate with the RRDtool. 
 
 After every B<RRDp::cmd> you have to issue an B<RRDp::read> command to get
-B<rrdtool>s answer to your command. The answer is returned as a pointer,
+B<RRDtool>s answer to your command. The answer is returned as a pointer,
 in order to speed things up. If the last command did not return any
 data, B<RRDp::read> will return an undefined variable. 
 
 If you import the PERFORMANCE variables into your namespace, 
-you can access rrdtools internal performance measurements.
+you can access RRDtool's internal performance measurements.
 
 =over 8
 
@@ -36,39 +36,49 @@ you can access rrdtools internal performance measurements.
 
 Load the RRDp::pipe module.
 
-=item B<RRDp::start> I<path to rrdtool executable>
+=item B<RRDp::start> I<path to RRDtool executable>
 
-start rrdtool. The argument must be the path to the rrdtool executable
+start RRDtool. The argument must be the path to the RRDtool executable
 
 =item B<RRDp::cmd> I<rrdtool commandline>
 
-pass commands on to rrdtool. check the rrdtool documentation for
-more info on the rrdtool commands.
+pass commands on to RRDtool. check the RRDtool documentation for
+more info on the RRDtool commands.
 
 =item $answer = B<RRDp::read>
 
-read rrdtools response to your command. Note that the $answer variable will
+read RRDtool's response to your command. Note that the $answer variable will
 only contain a pointer to the returned data. The reason for this is, that
-rrdtool can potentially return quite excessive amounts of data
+RRDtool can potentially return quite excessive amounts of data
 and we don't want to copy this around in memory. So when you want to 
 access the contents of $answer you have to use $$answer which dereferences
 the variable.
 
 =item $status = B<RRDp::end>
 
-terminates rrdtool and returns rrdtools status ... 
+terminates RRDtool and returns RRDtool's status ... 
 
 =item B<$RRDp::user>,  B<$RRDp::sys>, B<$RRDp::real>
 
 these variables will contain totals of the user time, system time and
-real time as seen by rrdtool.  User time is the time rrdtool is
+real time as seen by RRDtool.  User time is the time RRDtool is
 running, System time is the time spend in system calls and real time
-is the total time rrdtool has been running.
+is the total time RRDtool has been running.
 
 The difference between user + system and real is the time spent
 waiting for things like the hard disk and new input from the perl
 script.
 
+=item B<$RRDp::error_mode> and B<$RRDp::error>
+
+If you set the variable $RRDp::error_mode to the value 'catch' before you run RRDp::read a potential
+ERROR message will not cause the program to abort but will be returned in this variable. If no error
+occurs the variable will be empty.
+
+ $RRDp::error_mode = 'catch';
+ RRDp::cmd qw(info file.rrd);
+ print $RRDp::error if $RRDp::error;
+
 =back
 
 
@@ -85,11 +95,11 @@ script.
 
 =head1 SEE ALSO
 
-For more information on how to use rrdtool, check the manpages.
+For more information on how to use RRDtool, check the manpages.
 
 =head1 AUTHOR
 
-Tobias Oetiker <oetiker@ee.ethz.ch>
+Tobias Oetiker <tobi@oetiker.ch>
 
 =cut
 #'  this is to make cperl.el happy
@@ -110,7 +120,7 @@ sub cmd (@);
 sub end ();
 sub read ();
 
-$VERSION = 1.000331 ;
+$VERSION=1.2018;
 
 sub start ($){
   croak "rrdtool is already running"
@@ -128,6 +138,7 @@ sub start ($){
 sub read () {
   croak "RRDp::read can only be called after RRDp::cmd" 
     unless $Sequence eq 'C';
+  $RRDp::error = undef;
   $Sequence = 'R';
   my $inmask = 0;
   my $srbuf;
@@ -148,9 +159,10 @@ sub read () {
     $minibuf .= $srbuf;
     while ($minibuf =~ s|^(.+?)\n||s) {
       my $line = $1;
-      # print $line,"\n";
-      if ($line =~  m|^ERROR|) {
-       croak $line;
+      # print $line,"\n";      
+      $RRDp::error = undef;
+      if ($line =~  m|^ERROR|) {       
+       $RRDp::error_mode eq 'catch' ? $RRDp::error = $line : croak $line;
        $ERR = 1;
       } 
       elsif ($line =~ m|^OK u:([\d\.]+) s:([\d\.]+) r:([\d\.]+)|){