hist_deadband

Cascade Historian: Version 4.1
Prev |  | Next

# `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 `flag`s are `t` for true and `nil` for false. Settings for `type`s 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 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"

Prev | Home | Next
`hist_count` | Up | `hist_delete`

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