HI_Add

Cogent API and Utilities: Version 4.1
Prev |  | Next

# `HI_Add`

`HI_Add` -- adds a single value at a specified time.

## Syntax

    #include <cogent/cogent.h>

``ST_STATUS HI_Add`(IP_hTASK historian, char* retbuf, int buflen, char* histname, double value, time_t seconds, time_t nanoseconds);`

## Arguments

`historian`

  The task pointer to the Cascade Historian program.

`retbuf`

  An optional buffer containing an error message.

`buflen`

  The length in bytes of `retbuf`. If `retbuf` is non-NULL, this must be a valid non-zero length. If `retbuf` is NULL, this parameter is ignored.

`histname`

  The name of a history.

`value`

  The value to be added to the history.

`seconds`

  The time in seconds, normally seconds since Jan 1, 1970, GMT.

`nanoseconds`

  The nanoseconds within the second.

## 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 lets you add points and their values manually to the Cascade Historian. It injects a single value at the specified time, in seconds and nanoseconds. This is useful for sending data directly to the historian (without using Cascade Datahub) as well as for testing and debugging, where one or more points' values can be changed in a controlled way.

In order to guarantee the time-series data is ordered, the time of the previous data point is checked and if a time reversal is detected (i.e., the current timestamp preceeds that of the last one) then the timestamp of the data is modified to a small increment (1 micro-second) relative to the previous timestamp. This situation should only occur when there is more than one source of the same data, a situation that is never recommended.

The value for the point is stored internally as a `HI_stVALUE` structure, where `HI_stVALUE`.`xaxis` is the time, represented as a double-precision floating point number, and `HI_stVALUE`.`value` is the value.

Since the Cascade Historian handles points sequentially on a time-stamped basis, if you call this function several times on the same point each call should have increasing `seconds` and/or `nanoseconds` parameters.

This function corresponds to the Cascade Historian add command.

Prev | Home | Next
Cascade Historian Functions | Up | `HI_BufferIDDestroy`

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