HI_Describe

Arguments

Returns

ST_OK on success. Otherwise ST_ERROR, and the retbuf will contain a NULL-terminated character string with an error message.

Description

This function returns a description of the current configuration of a history in retbuf, which is not optional.

The information returned will be truncated at 1000 bytes.

The format of the return is:

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

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 buflen must be at least the sum of:

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

This function corresponds to the Cascade Historian describe command and the hist_describe dynamic library function..