hist_exchange_buffer

Parameters

Returns

t (true) if the transformation was performed with no errors, otherwise nil.

Description

This function swaps the X and Y values for each data pair in the buffer. The buffer is modified in place (i.e., a new buffer is not created, and the old values cannot be recovered).

This function is used to obtain certain data queries that are not directly supported by the Cascade Historian's interpolation services. For example, if we want to interpolate x (typically time or position) at all actual (non-interpolated) values of y, the Cascade Historian does not directly support this, since the interpolator services only interpolate the Y value. The desired result can be obtained by making the inverse query and exchanging the buffer results.

This function corresponds to the Cogent C API function HI_ExchangeBuffer.

Example

/* Assume we have a "position" history and some "ydata" history, and
   we want to graph ydata vs position.
   We cannot assume ydata and position samples share the same timestamp
   or even sample frequency, but since both histories are time series,
   we can use the "RelativeInterpolator" to interpolate one at the
   timestamps of the other's data.
   Here we want to maintain the ydata values and interpolate position.
*/
query = hist_interpolate (historian, "position", "RelativeInterpolator",
                          start_time, end_time - start_time, "ydata");
if (query)
{
    buf = hist_buffer_id_read (historian_tsk, query);
    hist_buffer_id_destroy (query));

    /* yields pairs of (ydata, interpolated position), but we want
       position as the x axis (to feed to a graphing widget) */

    hist_exchange_buffer(buf);

    /* result is (interpolated position, ydata values) */
}