contrib/php3/USAGE

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