HI_InterpolateData
HI_InterpolateData — interpolates a history and returns data.
Syntax
#include <cogent.h>
ST_STATUS HI_InterpolateData( | IP_hTASK | historian, |
| | char* | histname, |
| | char* | interpolator, |
| | double | start, |
| | double | duration, |
| | int | nxargs, |
| | char** | xargs, |
| | HI_stVALUE** | values, |
| | int* | nvalues); |
Arguments
- historian
- The task pointer to the Cascade Historian
program.
- histname
- The name of a history.
- interpolator
- The name of the interpolator to use, as
described below.
- start
- The
start of the time range of interest for query. If this value
is 0, it defaults to the time of the first
data value available for the history.
- duration
- The amount of time, in seconds, over which to
perform the interpolation. If this value is
0, it defaults to the length of time
between that specified by start and the
time of the last data value available for the
history.
- nxargs
- The
number of extra arguments to the
interpolator.
- xargs
- The
array of extra arguments to the interpolator, as
strings.
- values
- A
pointer to an HI_stVALUE*.
This is a return argument.
- nvalues
- The number of elements in values. This is a
return argument.
Returns
ST_OK on success. Otherwise
ST_ERROR, and the retbuf
will contain a NULL-terminated character string with an error message.
If the return value is ST_OK, the
retbuf may not contain useful information.
Description
This is a convenience function that combines HI_Interpolate,
HI_BufferIDLength,
HI_BufferIDRead,
and HI_BufferIDDestroy.
It causes the Cascade Historian to perform an
interpolation on its history data, producing a new, temporary,
un-named history, which is then copied to the client program. The
resulting data is returned in values, and
is nvalues in length.
![[Note]](images/note.gif) | The code for this function can be viewed in the Example for
HI_Interpolate. |
You
are responsible for freeing the values,
using the function ME_Free. The
xargs array is an array of NULL-terminated
strings. Numeric arguments are passed as strings containing their
printable ASCII representations.
The following
choices are available for the interpolator
argument:
| The NoInterpolator function is currently
the only one that requires no additional parameters, making
it possible to not supply start or
duration. For the other interpolator
functions, setting start or
duration to 0
forces the default values. |
- NoInterpolator simply
returns all data that falls within the specified time
range. No other processing is performed. When calling the
HI_Interpolate function, this
interpolator requires no extra arguments
(nxargs = 0,
xargs =
NULL).
- PeriodicInterpolator generates data as Y vs. time on an
even time interval. The first extra argument is a
double-precision float indicating the time interval in
seconds. The second (optional) extra argument is a
double-precision float indicating the maximum gap time: if
provided and the time between two data samples exceeds this
threshold, then data cannot be interpolated between the
points. This suppresses generating interpolated data during
'gaps' in the data.
- RelativeInterpolator generates Y
vs. X at all known values of
X. The first extra argument is a string
indicating the history name for X. The
history argument provided to
interpolate command (or the
histname argument provided to
HI_Interpolate function) is used as the
Y history.
- FixedRelativeInterpolator generates Y
vs. X on an even time interval. The
first extra argument is a string indicating the history name
for X. The second extra argument is a
double specifying the time interval. The
history argument provided to
interpolate command (or the
histname argument provided to
HI_Interpolate function) is used as the
Y history.
This function corresponds to the Cascade Historian hist_interpolate_data
dynamic library function.
