HI_InterpolateData

Cogent API and Utilities: Version 4.1
Prev |  | Next

# `HI_InterpolateData`

`HI_InterpolateData` -- interpolates a history and returns data.

## Syntax

    #include <cogent/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.

| 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.

Prev | Home | Next
`HI_Interpolate` | Up | `HI_Latest`

Copyright 1995-2002 by Cogent Real-Time Systems, Inc.