contrib/php4/USAGE

   1 $Id$
   2
   3 --------------------------------------------------
   4 Usage:
   5
   6         Loading the rrdtool module is a little bit different with
   7 PHP4/Zend.  If you build the rrdtool module into PHP4 at compile
   8 time (see INSTALL file), then there is nothing you need to do
   9 in your scripts to use the rrd_* functions.
  10
  11
  12
  13         However, if you build the rrdtool module as a 'self-contained'
  14 module (see INSTALL file), you will need to load it for each
  15 php script you intend to use.  To do this, you will need a line
  16 such as this in your script:
  17
  18         <? dl("rrdtool.so"); ?>
  19
  20 Note that in PHP4/Zend, you cannot specify the directory where
  21 the module lives.  It restricts the search to a specifc directory
  22 which is defined at compile time.  'make install' will place
  23 this file in the appropriate location.
  24
  25
  26
  27 API:
  28
  29 --------------------------------------------------------------------
  30 string rrd_error()
  31
  32         rrd_error takes no arguments.
  33
  34         Use this function to retrieve the error message from
  35 the last rrd_* function that was called and failed.
  36
  37         If an error was set, a string will be returned.
  38
  39         If no error was set, a blank string will be returned.
  40
  41
  42
  43
  44 --------------------------------------------------------------------
  45 int rrd_last(string filename)
  46
  47         rrd_last takes only one argument, a filename of an RRD
  48 file.
  49
  50         If rrd_last is successful in obtaining the last modifiation
  51 time of the file, a date will be returned in the form of the
  52 number of seconds from the unix epoch (Jan 1, 1970, 00:00:00).
  53 You can then use any of php's excellent time functions on this
  54 value.
  55
  56         If rrd_last is not sucessful, a value of 0 will be returned,
  57 and the internal rrd error will be set.  You can access this error
  58 message via the rrd_error() function (if one was set).
  59
  60
  61 --------------------------------------------------------------------
  62 int rrd_update(string filename, string options)
  63
  64         rrd_update takes 2 arguments, a filename of an RRD file
  65 and a string with options to fill the RRD file with.
  66
  67         It has been designed to work similary to the rrd_update
  68 call in the RRDs perl library.
  69
  70 Example:  $result = rrd_update("/some.rrd", "N:123:9873:235");
  71
  72         If rrd_update is successful, 1 is returned.
  73
  74         If rrd_update is not successful, 0 is returned, and an
  75 error message should be obtainable by called 'rrd_error()'.
  76
  77
  78 --------------------------------------------------------------------
  79 int rrd_create(string filename, array options, int num_of_elements)
  80
  81         rrd_create takes 3 arguments, a filename of an RRD file to
  82 create, an array of options (exactly like you would pass in the RRDs
  83 perl library, or on the command line to 'rrdtool'), and the last
  84 argument is the number of elements in the array of options.  This
  85 can be obtained by simply calling " count($opt_array) ".  See the
  86 example scripts for a more clear example.
  87
  88         If rrd_update is successful, 1 is returned.
  89
  90         If rrd_update is not successful, 0 is returned, and an
  91 error message should be obtainable by called 'rrd_error()'.
  92
  93
  94
  95 --------------------------------------------------------------------
  96 mixed rrd_graph(string filename, array options, int num_of_elements)
  97
  98         rrd_graph takes 3 arguments, a filename of an RRD file,
  99 an array of options (exactly like you would pass in the RRDs perl
 100 library, or on the command line to 'rrdtool'), and the last argument
 101 is the number of elements in the array of options.  This can be
 102 obtained by simply calling " count($opt_array) ".  See the example
 103 scripts for a more clear example.
 104
 105
 106         If rrd_graph is successful, an array is returned.  The
 107 array is an associate array with 3 values:
 108
 109 $array[xsize]  -  The size of the image along the X axis.
 110 $array[ysize]  -  The size of the image along the Y axis.
 111 $array[calcpr] -  This is actually another array, that will contain
 112                   the results of any PRINT statements.
 113
 114
 115         If rrd_graph is not successful, a 0 is returned.
 116
 117 IMPORTANT NOTE:  In order for php not to complain about mis-using
 118 the return value, it is important that you check the type of the
 119 return value.  use the " is_array() " function to check if the
 120 returned value is an array (in which case rrd_graph was successful),
 121 or not an array (meaning rrd_graph was NOT successful).  See the
 122 examples for an illustration of this.
 123
 124
 125 --------------------------------------------------------------------
 126 mixed rrd_fetch(string filename, array options, int num_of_elements)
 127
 128         rrd_fetch takes 3 arguments, a filename of an RRD file,
 129 an array of options (exactly like you would pass in the RRDs perl
 130 library, or on the command line to 'rrdtool'), and the last argument
 131 is the number of elements in the array of options.  This can be
 132 obtained by simply calling " count($opt_array) ".  See the example
 133 scripts for a more clear example.
 134
 135
 136         If rrd_fetch is successful, an array is returned.  The
 137 array is an associate array with 5 values:
 138
 139 $array[start]   -  This is the start time of the data returned
 140                    (unix epoch timestamp format)
 141 $array[end]     -  This is the end time of the data returned
 142                    (unix epoch timestamp format)
 143 $array[step]    -  This is the step interval of the data returned,
 144                    in number of seconds.
 145 $array[ds_cnt]  -  This is the number of DS's returned from the
 146                    RRD file.
 147 $array[ds_namv] -  This is an array with the names of the DS's
 148                    returned from the RRD file.
 149 $array[data]    -  This is an array with all the values fetch'd
 150                    from the rrd file by rrd_fetch.
 151
 152 (This is very similar to the way rrd_fetch() in the RRDs
 153 perl library works, as well as the C function rrd_fetch()).
 154
 155         If rrd_fetch is not successful, a 0 is returned.
 156
 157 IMPORTANT NOTE:  In order for php not to complain about mis-using
 158 the return value, it is important that you check the type of the
 159 return value.  use the " is_array() " function to check if the
 160 returned value is an array (in which case rrd_fetch was successful),
 161 or not an array (meaning rrd_fetch was NOT successful).  See the
 162 examples for an illustration of this.
 163
 164
 165 --------------------------------------------------------------------
 166