Cascade Historian: Version 4.1
Prev |  | Next

# describe

describe -- describes a history's current configuration.

## Syntax

    (describe history)

## Parameters

`history`

  The name of a history defined by the history command.

## Returns

The history information, formatted as described below, otherwise

        (error "History history does not exist")

## Description

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

The format of the return is:

        (describe "histname" "directory" "basename" "extension" ndigits
        "full_filename" flags deadband maxvalues point)

Any undefined string values are returned as `""`, not the string `"nil"`. The following values apply specifically:

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

The length of the reply (in bytes) can be up to the following sum:

              strlen(histname)
            + (strlen(directory) * 2)
            + (strlen(basename) * 2)
            + (strlen(extension) * 2)
            + (strlen(full_filename) * 2)
            + (strlen(point) * 2)
            + 64

This command corresponds to the Cogent API function `HI_Describe` and the `hist_describe` dynamic library function.

## Example

        [sh]$ lsend Hist
        Hist> (describe p3)
        (describe p3 "./data" "p3_" ".dat" 2 "./data/p3_01.dat" 0x102 nil 100 "p3")
        Hist>

Prev | Home | Next
delete | Up | disable

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