HI_Register

HI_Register — registers histories with the Cascade DataHub.

Syntax

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

Arguments

historian

The task pointer to the Cascade Historian program.

retbuf

An optional buffer containing an error message.

buflen

The length in bytes of retbuf. If retbuf is non-NULL, this must be a valid non-zero length. If retbuf is NULL, this parameter is ignored.

histpattern

A globbing pattern specifying a group of histories.

Returns

ST_OK on success. Otherwise ST_ERROR, and the retbuf will contain a NULL-terminated character string with an error message. If the return value is ST_OK, the retbuf may not contain useful information.

Description

This function causes the Cascade Historian to register each history matching the pattern with the Cascade DataHub point of the same name. Any subsequent value changes transmitted by the Cascade DataHub will be treated exactly the same as if add or HI_Add were called with that history, value and timestamp. If a history has already been registered, this function does nothing. If the Cascade DataHub is not running, no registration occurs. If multiple histories are associated with the same point, registering or unregistering one of the histories will do the same to all the other histories sharing the same point.

A Cascade DataHub point is a unit of storage in the datahub. Points have a name (a string), a value (real, integer, or string), and a time associated with them. They can be written to the Cascade DataHub in a number of ways, including for example the Cascade DataHub writept command and the Gamma write_point function. The Cascade Historian receives a point's data from the Cascade DataHub by registering for it with the register command or HI_Register function.

This function corresponds to the Cascade Historian register command and the hist_register dynamic library function.