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.
![[Note]](images/note.gif) | 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"
