Cascade Historian: Version 4.1
Prev |  | Next

# 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 `flag`s 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 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)

Prev | Home | Next
count | Up | delete

Copyright 1995-2002 by Cogent Real-Time Systems, Inc.