Cogent C API and Utilities : Version 7.2
	Cascade Historian Functions

`HI_Deadband`

HI_Deadband — sets the history value deadband.

Syntax

#include <cogent.h>
ST_STATUS HI_Deadband( IP_hTASK   historian, 
  char*   retbuf, 
  int   buflen, 
  char*   histname, 
  char* flag|  flagtype|type, 
  double   setting);

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.
flag: A deadband flag, any of: enable or prior, as described below.
type: A deadband type, any of: absolute, percent, timelimit, or countlimit, as described below.
setting: A setting (possibly optional) corresponding to the specified type or flag. Settings for flags are 0 (0.0) for true and any non-zero value for false.

Returns

ST_OK on success, and the retbuf may be parsed to extract the complete response from the Cascade Historian (see the deadband command). Otherwise ST_ERROR, and the retbufa will contain a NULL-terminated character string with an error message.

Description

This function sets a deadband on a history, such that new values falling within that deadband are not recorded.

A deadband is used to reduce the amount of data stored by only storing data if there is a significant change in value. This approach is superior to simply reducing the sampling frequency, which will lose information when data changes quickly, and will waste storage by saving the same values when data doesn't change. The deadband approach defines a resolution below which changes in data are deemed to be 'noise' and therefore ignored.

Flags

enable turns the deadband on and off without affecting its configuration.
In order for this flag to be set to true, at least one type must be set to a non-zero value. Otherwise, it will return false.
prior records the value prior to any value that exceeds the deadband. If set to true (the default), when a value is encountered that exceeds the deadband, the value immediately prior to that is also recorded in the data set. This is done so that plotted data will be approximately correct. For example, if a value remains in a stable range for a long time, and then suddenly spikes to a large number, it is appropriate to keep the last known value within the deadband range before adding the spike value to the data set. When this data is plotted, the spike will actually show as a spike, rather than a gradual ramp.

Types

absolute sets the deadband range to a single value. Any value differing from the baseline by less than absolute will not be recorded. If a value's difference from the baseline is greater than or equal to absolute, that value is recorded and it becomes the new baseline for the absolute deadband.
percent sets the deadband range to be a percent of the last logged data value. Every new value is compared to that value, and if their percentage difference is less than percent, the new value will not be recorded. If the difference is greater than or equal to percent, the value is recorded and that value becomes the new baseline for the percent deadband.

If absolute and percent are used together there is an AND relationship between them. The Cascade Historian will ignore any value falling within either deadband. Only those values falling outside all deadbands (or equal to the outermost) will be recorded.

timelimit sets the maximum time period (in seconds, a real number) to deadband. When the timelimit is reached, the next new value received will be recorded, even if its value doesn't exceed the deadband. Note that the system does not automatically generate and insert a value when the timelimit is reached; it waits for the next new value. Whenever a new value is recorded the timelimit is restarted. If the timelimit parameter is not used, there is no time limit on how many values are ignored within a deadband.
countlimit sets a maximum number of received values to deadband. When the countlimit is reached, the next new value will be recorded, even if it doesn't exceed the deadband. Whenever a new value is recorded the countlimit is restarted. If the countlimit parameter is not used, there is no count limit on how many values are ignored within a deadband.

This function corresponds to the Cascade Historian deadband command and the hist_deadband dynamic library function.

`ST_STATUS HI_Deadband(`	IP_hTASK	`historian`,
	char*	`retbuf`,
	int	`buflen`,
	char*	`histname`,
	char* `flag`\|	`flagtype`\|`type`,
	double	`setting)`;


HI_Count		HI_Delete