Cascade Historian™ : Version 5.4
	Commands

`deadband`

deadband — sets the history value deadband.

Syntax

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

Parameters

history: The name of a history defined by the history command.
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.

Returns

The deadband status in the following foramt:

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

if successful, where (except for enable) only those types or flags that have been configured are reported. Otherwise, one of the following errors:

(error "History history does not exist")

(error "No value for deadband on point history")
(error "Bad type type|flag for deadband on point history")

Description

This command 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 command corresponds to the Cogent C API function HI_Deadband and the hist_deadband dynamic library function.

Examples

Setting deadbands

Hist> (deadband p6 (enable t) (absolute 50))        (1)
(deadband p6 (enable t) (absolute 50))
Hist> (deadband p6)                                 (2)
(deadband p6 (enable t) (absolute 50))
Hist> (deadband p6 (enable nil))                    (3)
(deadband p6 (enable nil) (absolute 50))
Hist> (deadband p6 (percent 10) (timelimit 5))                                     (4)
(deadband p6 (enable nil) (absolute 50) (percent 10) (timelimit 5))
Hist> (deadband p6 (enable t) (countlimit 15) (timelimit 12))                      (5)
(deadband p6 (enable t) (absolute 50) (percent 10) (timelimit 12) (countlimit 15))
Hist> (deadband p6 (absolute 0) (percent 0) (timelimit 0) (countlimit 0))          (6)
(deadband p6 (enable nil))
Hist> (deadband p6 (percent 7))                     (7)
(deadband p6 (enable nil) (percent 7))
Hist> (deadband p6 (enable t))                      (8)
(deadband p6 (enable t) (percent 7))

(1)	Enables the deadband and sets a type or flag.
(2)	Queries for all types or flags.
(3) (6)	Disables the deadband.
(4) (5) (7)	Adds/changes type or flag setting(s).
(8)	Enables the deadband.

You can set a deadband with a single command, or with multiple commands. For example, this command:

Hist> (deadband p8 (enable t) (percent 15) (timelimit .5))
(deadband p8 (enable t) (percent 15) (timelimit .5))

gives the same result as these three commands:

Hist> (deadband p8 (percent 15))
(deadband p8 (enable nil) (percent 15))
Hist> (deadband p8 (timelimit .5))
(deadband p8 (enable nil) (percent 15) (timelimit .5))
Hist> (deadband p8 (enable t))
(deadband p8 (enable t) (percent 15) (timelimit .5))

Storing prior values

This example shows what happens when prior values are stored (prior t), and when they are not (prior nil). The default is (prior t). The deadband settings are:

(deadband p6 (enable t) (absolute 5) (percent 10))

Values written to the point:

writept p6 100       # initial value
writept p6 101       # within deadband
sleep 1
writept p6 99        # within deadband
writept p6 102       # value prior to exceeding deadband
writept p6 120       # value exceeds percent deadband
writept p6 121       # within deadband
writept p6 119       # within deadband
writept p6 122       # within deadband
sleep 1
writept p6 119       # value prior to exceeding deadband
writept p6 1000      # value exceeds percent deadband

Values recorded for (prior t):

(998917943.449015 100.000000)
(998917943.466446 102.000000)
(998917944.503114 120.000000)
(998917944.526436 119.000000)
(998917945.543039 1000.000000)

Values recorded for (prior nil):

(998917943.449015 100.000000)
(998917944.503114 120.000000)
(998917945.543039 1000.000000)

Percent and absolute used together

This example shows how if both percent and absolute deadbands are used, they must both be exceeded for a value to be recorded. Although the percent deadband is exceeded for every new value in this example, only when the absolute deadband is also exceeded is the point recorded. The deadband settings are:

(deadband p6 (enable t) (absolute 5) (percent 10))

Values written to the point:

writept p6 0         # initial value
writept p6 2         # within absolute deadband
writept p6 4         # value prior to exceeding deadband
writept p6 6         # exceeds percent AND absolute deadband
writept p6 8         # within deadband
writept p6 10        # value prior to exceeding deadband
writept p6 12        # exceeds percent AND absolute deadband
sleep 1
writept p6 1000      # exceeds percent AND absolute deadband

Values recorded:

(998917946.583085 0.000000)
(998917946.594751 4.000000)
(998917946.600725 6.000000)
(998917946.611944 10.000000)
(998917946.617748 12.000000)
(998917947.633108 1000.000000)


count		delete