Cascade Historian™ : Version 7.2
	Dynamic Library Functions

`hist_deadband`

hist_deadband — sets the history value deadband.

Syntax

hist_deadband (hist_task, history[, (flag|type[, setting...])...])
hist_deadband (hist_task, history[, parm_list])

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 be set or queried.

flag

The deadband flag(s), any of: enable or prior, as described below.

type

The deadband type(s), 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 t for true and nil for false. Settings for types are strings or numbers.

parm_list

A list with the format:

((type|flag [setting...])...)

Returns

The current deadband configuration for the history, if the function completed successfully. Otherwise returns nil and sets _last_error_ to the error string returned by the Cascade Historian. The deadband configuration is returned as a list of parameter settings. Parameters without args (such as on and off) are returned as string objects, while those with args are returned as a list of parameter name (as a string) and the value.

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 deadband command, and the Cogent C API function HI_Deadband.

Example

Gamma> hist_history (historian, "p6");
t
Gamma> a = hist_deadband (historian, "p6");
(("enable" nil) ("prior" t))
Gamma> hist_deadband(historian, "p6", "percent", 2, "enable", t, "prior", nil);
(("enable" t) ("percent" 2) ("prior" nil))
Gamma> hist_deadband(historian, "p6", a);
(("enable" nil) ("percent" 2) ("prior" t))
Gamma> hist_deadband(historian, "p6", "bogus", 1.2);
nil
Gamma> _last_error_;
"Invalid parameter "bogus" for deadband on point p1"


hist_count		hist_delete