hist_describe

Cascade Historian: Version 4.1
Prev |  | Next

# `hist_describe`

`hist_describe` -- describes a history's current configuration.

## Syntax

    hist_describe (hist_task, history)

## 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 described.

## Returns

A list containing the objects described below if successful. Otherwise returns `nil` and sets `_last_error_` to the error string returned by the Cascade Historian.

## Description

This command returns a summary of the configuration parameters associated with the specified history.

The object list returned contains the following (in the given order):

- The `histname` as previously set with the history command, or the `HI_History` function.

- The `directory`, `basename`, `extension` and `ndigits` as previously set with the filebase command, or the `HI_FileBase` function.

- The `full_filename` indicates the pathname of the current file to which the data will be written, as set up by the four filebase parameters mentioned above.

- The `flags` are given in hexadecimal format (ie. `0x0064`). The following constants define the individual flag bits and may be used to test the flags value:

  Constant | Comment
  --- | ---
  `HIST_DISABLED` | Indicates history logging state.
  `HIST_REGISTERED` | Indicates history is registered with the Cascade DataHub for value updates.
  `HIST_DEADBAND` | Overall deadband state (`on`/`off`)
  `HIST_DEADBAND_FORCE` | Internal state bit.
  `HIST_DEADBAND_PRIOR` | Indicates `PRIOR` mode is set.
  `HIST_DEADBAND_PERCENT` | Indicates `PERCENT` deadband is set.
  `HIST_DEADBAND_ABSOLUTE` | Indicates `ABSOLUTE` deadband is set.
  `HIST_DEADBAND_TIMELIMIT` | Indicates `TIMELIMIT` deadband is set.
  `HIST_DEADBAND_COUNTLIMIT` | Indicates `COUNTLIMIT` deadband is set.
  `HIST_DEADBAND_TYPES` | Bit-`OR` of the deadband type flags (`PERCENT`, `ABSOLUTE`, `TIMELIMIT`, and `COUNTLIMIT`, useful for testing if any deadband type is set.

- The status of the `deadband`, `t` (indicating on) or `nil` (indicating off). The deadband command (or `HI_Deadband` API function or `hist_deadband` DLL function) should be used to determine the actual deadband configuration.

- The `maxvalues` as previously set with the bufsize command, or the `HI_Bufsize` function.

- The `point` associated with the history, as previously set with the history command, or the `HI_History` function.

This function corresponds to the describe command, and the Cogent API function `HI_Describe`.

## Example

        Gamma> d = hist_describe(tsk, "p3");
        ("./data" "p3_" ".dat" 2 "./data/p3_01.dat" 0x102 nil 100 "p3")
        Gamma> abs_on = (HIST_DEADBAND_ABSOLUTE == (HIST_DEADBAND_ABSOLUTE & car(nth_cdr(d,5))));
        t

Prev | Home | Next
`hist_delete` | Up | `hist_disable`

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