hist_interpolate

Cascade Historian: Version 4.1
Prev |  | Next

# `hist_interpolate`

`hist_interpolate` -- queries history data.

## Syntax

    hist_interpolate (hist_task, history, interpolator[, start[, duration[, args...]]])

## Parameters

`hist_task`

  The task object corresponding to the Cascade Historian. See `locate_task` in the Gamma manual.

`history`

  The name of the history to query.

`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` or is not supplied, 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` or is not supplied, it defaults to the length of time between that specified by `start` and the time of the last data value available for the history.

`args`

  Arguments to the specified interpolator, as required, passed as strings.

## Returns

A query ID number (queries are numbered sequentially, starting with 0) that can be used to access the data generated by the interpolation.

## 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 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:

1. A call to interpolate, `hist_interpolate`, or `HI_Interpolate` performs a query on history data, placing the result in a buffer for subsequent transfer.

2. A call to bufferIdLength, `hist_buffer_id_length`, or `HI_BufferIDLength` gets the length of the interpolation buffer.

3. A call to bufferIdData, bufferIdDataAscii, `hist_buffer_id_read`, or `HI_BufferIDRead` brings in the data from the interpolation buffer.

4. A call to bufferIdDestroy, `hist_buffer_id_destroy`, or `HI_BufferIDDestroy` destroys the interpolation buffer. This should always be done to free up memory.

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

- `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 interpolate command, and the Cogent API function `HI_Interpolate`.

## Example

        Gamma> hist_interpolate(tsk, "p6", "NoInterpolator");
        2
        Gamma> hist_interpolate(tsk, "p6", "PeriodicInterpolator", 0.0, 0.0, "0.1");
        3
        Gamma> length (a = hist_buffer2array (hist_read_buffer_id(tsk, 3)));
        37
        Gamma> a[12];
        {HI_stVALUE (value . 103.018446) (xaxis . 1025721206.7)}

Prev | Home | Next
`hist_history` | Up | `hist_interpolate_data`

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