Publish Functions

ihuPublishAddTag

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

Prototype

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

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

Prototype

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

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

Prototype

ihuPublishTagCloseCache
(void);

Remarks

To avoid memory leaks, close the cache.

Returns

The ihuPublishTagCloseCache function returns ihuSTATUS_OK on success.

ihuPublishGetTagPropertiesToCache

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.

Prototype

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

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.

Prototype

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

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

Prototype

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

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

Prototype

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

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

Prototype

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

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.

Prototype

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

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

Prototype

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

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

Prototype

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

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

Prototype

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

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

Prototype

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

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

Prototype

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.