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:

    ConstantComment
    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 C 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>