HI_History

Arguments

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 creates a new history and assigns it a name. This is required before any other commands or functions on the specified history can be applied. The history will be enabled as soon as it is created. A history can be associated with a Cascade DataHub point, so that the history is updated whenever the datahub point is updated. (See the register command or the HI_Register function.)

Typically, the point and history names are the same, and the point argument need not be specified. By using the point argument, it becomes possible to associate more than one history to the same datahub point. In this case, a single datahub point update will cause all the associated histories to be updated. This can be useful if you need histories of the same data but with different deadband settings. (This could provide, for example, both a high-resolution history as well as a more compact history using the deadband filters). The point name can be completely different from the history name, or can be the same as one of the histories.

When 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. This applies when defining a new history: if a point is associated with a history that has already registered, then the new history is also automatically registered. If control is required over which histories (that share a common point) receive data, then the enable/disable commands (or their corresponding functions) must be used.

If the history already exists, this function does nothing.

This function corresponds to the Cascade Historian history command and the hist_history dynamic library function.