HI_Describe

Cogent API and Utilities: Version 4.1
Prev |  | Next

# `HI_Describe`

`HI_Describe` -- describes a history's current configuration.

## Syntax

    #include <cogent/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..

Prev | Home | Next
`HI_Delete` | Up | `HI_Disable`

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