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.
![[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
Cascade Historian deadband
command and the hist_deadband
dynamic library function.
