HI_Interpolate

Arguments

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 function performs a query on history data, placing the result in a buffer for subsequent transfer. It generates a unique, sequentially numbered ID 'handle' for each query that is made, so clients can access the resulting buffer. The IDs have no meaning outside the Cascade Historian, and are only valid after a query and until the buffer is freed with the bufferIdDestroy command, the HIBufferIDDestroy Cogent C API function, or the hist_buffer_id_destroy dynamic library function, as appropriate.

This is the first of four steps (which can be done as commands, dynamic libary functions, or API functions) required to make an interpolation:

This task has been divided into four steps for convenience and performance. A buffer, once created, remains available to be read as required, potentially by multiple users, until it is no longer needed and can be destroyed. The buffers can also be very large, exceeding typical IPC message sizes, and requiring a relatively long time to transfer. That problem can be addressed by transferring the data in predictably-sized portions, allowing other processing to be done in between. The multi-step process defined above provides the flexibility needed for just such tailoring to the user's requirements. To run all four steps with one function call, see HI_InterpolateData in the Cogent C API manual or the hist_interpolate_data dynamic library function.

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.

This function corresponds to the Cascade Historian interpolate command and the hist_interpolate dynamic library function.

Example

The following example is the code for the HI_InterpolateData function. It demonstrates how HI_Interpolate is used with HI_BufferIDLength, HI_BufferIDRead, and HI_BufferIDDestroy.

ST_STATUS HI_InterpolateData (IP_hTASK historian, char* histname,
                              char* interpolator,
                              double start, double duration,
                              int nxargs, char** xargs,
                              HI_stVALUE** values, int *nvalues)
{
  static char           retbuf[256];
  ST_STATUS             status;
  int                   n, bufid;
  HI_stVALUE            *hvalues;

  status = HI_Interpolate (historian, retbuf, sizeof(retbuf),
                           histname, interpolator, start, duration,
                           nxargs, xargs, &bufid);
  if (status == ST_OK)
    {
      status = HI_BufferIDLength (historian, NULL, 0, bufid, &n);
      if (status == ST_OK)
        {
          hvalues = (HI_stVALUE*) ME_ZMalloc (n * sizeof(HI_stVALUE));
          if (hvalues)
            {
              status = HI_BufferIDRead (historian, NULL, 0,
                                        bufid, 0, n, hvalues);
              if (status == ST_OK)
                {
                  *values = hvalues;
                  *nvalues = n;
                }
              else
                {
                  ME_Free (hvalues);
                  *values = NULL;
                }
            }
        }
      HI_BufferIDDestroy (historian, NULL, 0, bufid);
    }
  return (status);