describe

Parameters

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>