Publish Functions

Important: You do not have the latest version of Historian! You are missing out on the newest capabilities and enhanced security. For information on all the latest features, see the Historian product page. For more information on upgrades, contact your GE Digital sales agent or e-mail GE Digital Sales Support. For the most up-to-date documentation, go here.

Publish Functions Overview

Publish Functions

You can use the publish functions to manage the data forwarding of local Historian server tags to one or more remote destination servers by using the Server-to-Server Distributors. When you publish a tag, you initiate continuous transmission of its historical data values to a destination server.

ihuPublishAddTag

Prototype

Use the ihuPublishAddTag function to publish a tag to a destination server. When you publish, a tag is created in the destination server.

ihuPublishAddTag (
long hSourceServer,
MSO Char *InterfaceName,
MSO Char *SourceTagname,);

Remarks

After you publish a tag, any new data for the SourceTagname is written to the DestinationTagname.

The tag is added to the destination server with default parameters that you can modify by using ihuPublishGetTagPropertiesToCache and ihuPublishSetTagProperties.

Returns

The ihuPublishAddTag function returns ihuSTATUS_OK on success, or an error if the tag was not added to the destination server.

ihuPublishRemoveTag

Prototype

Use the ihuPublishRemoveTag function to prevent tag publishing by a specified collector.

ihuPublishRemoveTag
( long hServer,
  MSO Char *DestinationTagname,
  MSO Char *SourceTagname );

Remarks

The ihuPublishRemoveTag function does not remove the tag from the source server. but marks it as deleted in the destination server. To completely stop data collection, you must disable collection.

Returns

The ihuPublishRemoveTag function returns ihuSTATUS_OK on success.

ihuPublishTagCloseCache

Prototype

Use the ihuPublishTagCloseCache function to close a cache returned by the ihuPublishGetTagPropertiesToCache function.

ihuPublishTagCloseCache
(void);

Remarks

To avoid memory leaks, close the cache.

Returns

The ihuPublishTagCloseCache function returns ihuSTATUS_OK on success.

ihuPublishGetTagPropertiesToCache

Prototype

Use the ihuPublishGetTagPropertiesToCache function to retrieve a list of tags published by the specified Server-to-Server Distributor. Be sure to match tags with the exact tag name or a name with a specified wildcard mask.

Note: A separate published tag properties cache exists for each process thread. To avoid confusion and unexpected results, ensure that all cache-related function calls are invoked on the same thread. When threads are mixed, two or more distinct caches are referenced, which enables concurrent access to multiple different cached results at the cost of additional memory.

ihuPublishGetTagPropertiesToCache
( long hServer,
  MSO Char *DistributorName,
  MSO Char *DestinationTagnameOrMask,
  out int *NumTagsFound
);

Remarks

The ihuPublishGetTagPropertiesToCache function returns the number of tags found in the NumTagsFound parameter.

Use this function to retrieve tags before you get and set string or numeric tag properties by using the ihuPublishTagGetNumericPropertyByTagname or ihuPublishTagSetStringProperty and similar functions.

Returns

The ihuPublishGetTagPropertiesToCache function returns ihuSTATUS_OK on success, even if no tags are found. The function returns errors if any out-of-memory issues occur during dynamic memory allocation.

ihuPublishTagGetNumericPropertyByTagname

Prototype

Use the ihuPublishTagGetNumericPropertyByTagname function to retrieve a numeric tag property, such as the deadband for a tag. The tag is identified by name within the cache previously populated by ihuPublishGetTagPropertiesToCache.

ihuPublishTagGetNumericPropertyByTagname
( MSO Char *Tagname,
ihuTagProperties TagProperty,
*Value );

Remarks

The ihuPublishTagGetNumericPropertyByTagname function returns the numeric tag property value.

Returns

The ihuPublishTagGetNumericPropertyByTagname function returns ihuSTATUS_OK on success, or returns an error if any out-of-memory issues occur during dynamic memory allocation.

ihuPublishTagGetNumericPropertyByIndex

Prototype

Use the ihuPublishTagGetNumericPropertyByIndex function to retrieve a single numeric tag property from the cache.

ihuPublishTagGetNumericPropertyByIndex 
(
  int Index,
  ihuTagProperties TagProperty,
  double *Value );

Remarks

The ihuPublishTagGetNumericPropertyByIndex function returns the numeric tag property retrieved. The index is zero-based.

Returns

The ihuPublishTagGetNumericPropertyByIndex function returns ihuSTATUS_OK on success, or returns an error if any out-of-memory issues occur during dynamic memory allocation.

ihuPublishTagGetStringPropertyByTagname

Prototype

Use the ihuPublishTagGetStringPropertyByTagname function to retrieve a single string tag property by tagname from the cache.

ihuPublishTagGetStringPropertyByTagname
(
  MSO Char *Tagname,
  ihuTagProperties TagProperty,
  MSO Char *Value,
  int ValueLength );

Remarks

The ihuPublishTagGetStringPropertyByTagname function returns a single string tag property by tagname from the cache.

Returns

The ihuPublishTagGetStringPropertyByTagname function returns ihuSTATUS_OK on success, or returns an error if any out-of-memory issues occur during dynamic memory allocation.

ihuPublishTagGetStringPropertyByIndex

Prototype

Use the ihuPublishTagGetStringPropertyByIndex function to retrieve a single string tag property from the cache. The index is zero-based.

ihuPublishTagGetStringPropertyByIndex (
  int Index,
  ihuTagProperties TagProperty, MSO Char *Value,
  int ValueLength );

Remarks

The ihuPublishTagGetStringPropertyByIndex function returns the string tag property from the cache. The index is zero-based.

Returns

The ihuPublishTagGetStringPropertyByIndex function returns ihuSTATUS_OK on success, or returns an error if any out-of-memory issues occur during dynamic memory allocation.

ihuPublishSetTagProperties

Prototype

Use the ihuPublishSetTagProperties function to define properties such as the deadband for a published tag. Before you call this function, set properties by using ihuPublishTagSetStringProperty or ihuPublishTagSetNumericProperty.

A separate collection of tag properties is available for each process thread, similar to the published tag properties cache. To avoid confusion, be sure to invoke this function on the same thread as ihuPublishTagSetNumericProperty, ihuPublishTagSetStringProperty, and ihuPublishTagClearProperties.

ihuPublishSetTagProperties (
  long hServer,
  MSO Char *InterfaceName,
  MSO Char *DestinationTagname,
);

Remarks

After you add a tag by using the ihuPublishAddTag function, use the ihuPublishSetTagProperties function to set tag properties.

Returns

The ihuPublishSetTagProperties function returns ihuSTATUS_OK on success, or returns an error if any out-of-memory issues occur during dynamic memory allocation.

ihuPublishTagSetNumericProperty

Prototype

Use the ihuPublishTagSetNumericProperty function to define a numeric tag property before you invoke ihuPublishSetTagProperties.

ihuPublishTagSetNumericProperty
(
  ihuTagProperties TagProperty,
  double Value
);

Remarks

The ihuPublishTagSetNumericProperty function returns the numeric tag property.

Returns

The ihuPublishTagSetNumericProperty function returns ihuSTATUS_OK on success, or errors on invalid input parameters or if any out-of-memory issues occur during dynamic memory allocation.

ihuPublishTagSetStringProperty

Prototype

Use the ihuPublishTagSetStringProperty function to define a string tag property before you invoke ihuPublishSetTagProperties.

ihuPublishTagSetStringProperty (
  ihuTagProperties TagProperty,
  MSO Char *Value
);

Remarks

The ihuPublishTagSetStringProperty function returns the string tag property.

Returns

The ihuPublishTagSetStringProperty function returns ihuSTATUS_OK on success, or errors on invalid input parameters or if any out-of-memory issues occur during dynamic memory allocation.

ihuPublishTagClearProperties

Prototype

Use the ihuPublishTagClearProperties function to clear any previously defined tag properties.

ihuPublishTagClearProperties
(
  void
);

Remarks

The ihuPublishTagClearProperties function clears previously defined tag properties.

Returns

The ihuPublishTagClearProperties function returns ihuSTATUS_OK on success, or returns an error if any out-of-memory issues occur during dynamic memory allocation.

ihuPublishGetDestinationServer

Prototype

Use the ihuPublishGetDestinationServer function to retrieve the name of the destination Historian server configured for a specific distributor.

ihuPublishGetDestinationServer (
long hServer,
MSO Char *InterfaceName,
MSO Char **DestinationServer );

Remarks

The ihuPublishGetDestinationServer function returns the destination Historian server name.

Returns

The ihuPublishGetDestinationServer function returns ihuSTATUS_OK on success, or returns an error if any out-of-memory issues occur during dynamic memory allocation.

ihuPublishSetDestinationServer

Prototype

Use the ihuPublishSetDestinationServer function to define the destination Historian server for a specific collector.

ihuPublishSetDestinationServer (
  long hServer,
  MSO Char *InterfaceName,
  MSO Char *DestinationServer
);

Remarks

The ihuPublishSetDestinationServer function returns the Historian server name that is defined for the specified collector. The new name is assigned without a collector restart, and can be used at any time the distributor is restarted.

Returns

The ihuPublishSetDestinationServer function returns ihuSTATUS_OK on success, or returns an error if any out-of-memory issues occur during dynamic memory allocation.