Cogent C API and Utilities : Version 7.2
	Cascade Historian Functions

`HI_Describe`

HI_Describe — describes a history's current configuration.

Syntax

#include <cogent.h>
ST_STATUS HI_Describe( IP_hTASK   historian, 
  char*   retbuf, 
  int   buflen, 
  char*   histname);

Arguments

historian: The task pointer to the Cascade Historian program.
retbuf: A required buffer containing an error message.
buflen: The length in bytes of retbuf, with a minimum as described below.
histname: The name of a history.

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

`ST_STATUS HI_Describe(`	IP_hTASK	`historian`,
	char*	`retbuf`,
	int	`buflen`,
	char*	`histname)`;


HI_Delete		HI_Disable