Tag 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.

Tag Functions Overview

Tag Functions

Tag functions provide browse, add, modify, and delete access to the configured tags on a server. You can retrieve the properties for each tag with User API calls. For example, you can retrieve user-defined collection parameters for a tag before collection, or retrieve user-configured display parameters to prepare for plotting.

You can retrieve string and numeric tag properties. Every tag property is classified as string or numeric (double float). For example, Boolean properties are converted to double float and time data type properties are converted to string.

You can add, delete, or modify tags using the User API.

You can browse tags in three different ways. The simplest mode uses ihuFetchTagCache to filter by tagname. To filter by additional properties. such as data type or collector name, use ihuFetchTagCacheEx. Finally, to browse in multiple browser windows at the same time, for example, to compare the tags on one server with those on another server, use ihuFetchTagCacheEx2 or ihuFetchTagCacheEx3.

Tag Property Value Types

The following table lists the current set of tag properties that are exposed, and indicates whether they are numeric or string. Use ihuGetNumericTagPropertyByIndex and ihuGetNumericTagPropertyByTagname to retrieve numeric properties, and ihuGetStringTagPropertyByIndex and ihuGetStringTagPropertyByTagname to retrieve string properties.

Table 1. Tag Property Value Types
Property Value Type
ihuTagPropTagname String
ihuTagPropDescription String
ihuTagPropEngineeringUnits String
ihuTagPropComment String
ihuTagPropDataType Numeric
ihuTagPropFixedStringLength Numeric
ihuTagPropInterfaceName String
ihuTagPropSourceAddress String
ihuTagPropCollectionType Numeric
ihuTagPropCollectionInterval Numeric
ihuTagPropCollectionOffset Numeric
ihuTagPropLoadBalancing Numeric
ihuTagProptime stampType Numeric
ihuTagPropHighEngineeringUnits Numeric
ihuTagPropLowEngineeringUnits Numeric
ihuTagPropInputScaling Numeric
ihuTagPropHighScale Numeric
ihuTagPropLowScale Numeric
ihuTagPropCollectorCompression Numeric
ihuTagPropCollectorDeadbandPercentRange Numeric
ihuTagPropArchiveCompression Numeric
ihuTagPropArchiveDeadbandPercentRange Numeric
ihuTagPropSpare1 String
ihuTagPropSpare2 String
ihuTagPropSpare3 String
ihuTagPropSpare4 String
ihuTagPropSpare5 String
ihuTagPropReadSecurityGroup String
ihuTagPropWriteSecurityGroup String
ihuTagPropAdministratorSecurityGroup String
ihuTagPropLastModified (not currently implemented) String
ihuTagPropLastModifiedUser String
ihuTagPropInterfaceType Numeric
ihuTagPropStoreMilliseconds Numeric
ihuTagPropUTCBias Numeric
ihuTagPropNumberOfCalculationDependencies Numeric
ihuTagPropCalculationDependencies (only the first dependency is returned) String
ihuTagPropAverageCollectionTime Numeric
ihuTagPropCollectionDisabled Numeric
ihuTagPropArchiveCompressionTimeout Numeric
ihuTagPropCollectorCompressionTimeout Numeric
ihuTagPropDataDensity
Note: Tag data density categories are minimum (1), medium (4), and maximum (7).
 Numeric
ihuTagPropNumberOfElements
Note: If the NumberOfElements value is -1, the tag is an array tag.
 Numeric

ihuCreateTagCacheContext

Prototype

Use the ihuCreateTagCacheContext function to create tag cache context to use in the ihuFetchTagCacheEx2 or ihuFetchTagCacheEx3 functions.

void * IHUAPI ihuCreateTagCacheContext {
};

ihuFetchTagCache

Prototype

Use this function to fetch a current set of tags and properties from the Historian server and place them into an API cache for subsequent queries, such as ihuGetNumericTagPropertyByTagname.

ihuFetchTagCache {
  in long serverhandle,
  in MSO Char * tagmask,
  out int * NumTagsFound
};

Remarks

The function retrieves properties for each tag received.

There is a single API tag cache. You must free the previous tag cache before you do another fetch from the same or a different server. Keep this in mind when you access the tag cache from multiple threads in the same application. Alternatively, use the ihuCreateTagCacheContext and ihuFetchTagCacheEx2 or ihuFetchTagCacheEx3 functions.

Returns

  • ihuSTATUS_OK
  • ihuSTATUS_INVALID_PARAMETER

ihuFetchTagCacheEx

Prototype

Use the ihuFetcTagCacheEx function to fetch a current set of tags and properties from the Historian server and place them into an API cache for subsequent queries, such as ihuGetNumericTagPropertyByTagname.

ihuFetchTagCacheEx {
  in long serverhandle,
  out int * NumTagsFound,
};

Remarks

This function uses the criteria set up by ihuTagCacheCriteriaSetStringProperty and ihuTagCacheCriteriaSetNumericProperty for tag browsing.

Returns

  • ihuSTATUS_OK
  • ihuSTATUS_INVALID_PARAMETER

ihuFetchTagCacheEx2

Prototype

Use the ihuFetchTagCacheEx2 function to fetch a current set of tags and properties from the Historian server and place them into an API cache for subsequent queries.

ihuFetchTagCacheEx2 {
void * tagCacheContext,
long serverhandle,
MSO Char * tagmask,
int * NumTagsFound
};

Remarks

This function uses the criteria specified in ihuTagCacheCriteriaSetStringProperty and ihuTagCacheCriteriaSetNumericProperty for tag browsing.

Returns

  • ihuSTATUS_OK
  • ihuSTATUS_INVALID_PARAMETER

ihuFetchTagCacheEx3

Prototype

Use the ihuFetchTagCacheEx3 function to fetch a current set of tags and properties from the Historian server and place them into an API cache for subsequent queries.

ihuFetchTagCacheEx3 {
void * tagCacheContext,
long serverhandle,
int * NumTagsFound
};

Remarks

This function uses the criteria specified in ihuTagCacheCriteriaSetStringProperty and ihuTagCacheCriteriaSetNumericProperty for tag browsing.

Returns

  • ihuSTATUS_OK
  • ihuSTATUS_INVALID_PARAMETER

ihuGetTagNameCacheIndex

Prototype

Use the ihuGetTagNameCacheIndex function to find the index of the specified tagname in the cache. You can use the index for fast access in subsequent get property by index calls. This call only queries the API tag cache. It does not access the archiver.

ihuGetTagnameCacheIndex {
 in MSO Char *Tagname
 out unsigned int *CacheIndex
};

Remarks

The value returned in CacheIndex is a zero-based index suitable to be passed into the get property by index functions. The index is valid only if the function returns a success error code.

Returns

  • ihuSTATUS_OK
  • ihuSTATUS_INVALID_TAGNAME

ihuGetTagNameCacheIndexEx2

Prototype

Use the ihuGetTagNameCacheIndexEx2 function to find the index of the specified tagname in the cache. You can use the index for fast access in subsequent get property by index calls. This call only queries the API tag cache. It does not access the archiver.

ihuGetTagnameCacheIndexEx2 {
Void *TagCacheContext,
MSO Char *Tagname
unsigned int *CacheIndex
};

Remarks

The value returned in CacheIndex is a zero-based index suitable to be passed into the get property by index functions. The index is valid only if the function returns a success error code.

Returns

  • ihuSTATUS_OK
  • ihuSTATUS_INVALID_TAGNAME

ihuGetNumericTagPropertyByTagname

Use the ihuGetNumericTagPropertyByTagname function to retrieve the value of a specified numeric tag property from the API tag cache for a specified tag. This call queries the cache, but not the archiver. The tag property may have changed since the cache was fetched.

Prototype

ihuGetNumericTagPropertyByTagname {
  in MSO Char *Tagname,
  in ihuTagProperties TagProperty,
  out double *Value
};

Remarks

The get by tagname function is slower than the get by index function because it loops through all tags in the cache to find the requested tag. To retrieve multiple properties for a tag, consider calling ihuGetTagnameCacheIndex to get the cache index of a tag so that you can use the get by index functions.

Returns

  • ihuSTATUS_OK
  • ihuSTATUS_INVALID_PARAMETER
  • ihuSTATUS_INVALID_TAGNAME

ihuGetNumericTagPropertyByIndex

Prototype

Use the ihuGetNumericTagPropertyByIndex function to retrieve the value of a specified numeric tag property from the API tag cache at a specified cache index. This call queries the cache, but not the archiver. The tag property may have changed since the cache was fetched.

ihuGetNumericTagPropertyByIndex {
  in int Index,
  in ihuTagProperties TagProperty,
  out double *Value
};

Remarks

Use the get property by index functions after you locate tags with ihuGetTagnameCacheIndex, or when you want to iterate through all tags in the cache.

The index is zero-based.

Tags are returned from the cache in no particular order.

Returns

  • ihuSTATUS_OK
  • ihuSTATUS_INVALID_PARAMETER
  • ihuSTATUS_INVALID_TAGNAME

ihuGetNumericTagPropertyByIndexEx2

Use the ihuGetNumericTagPropertyByIndexEX2 function to retrieve the value of a specified numeric tag property from the API tag cache at a specified cache index. This call queries the cache, but not the archiver. The tag property may have changed since the cache was fetched.

Prototype

ihuGetNumericTagPropertyByIndexEx2 {
void * TagCacheContext,
int Index,
ihuTagProperties TagProperty,
double *Value
};

Remarks

Use the get property by index functions when you do not know the tagname.

The index is zero-based.

Tags are returned from the cache in no particular order.

Returns

  • ihuSTATUS_OK
  • ihuSTATUS_INVALID_PARAMETER
  • ihuSTATUS_INVALID_TAGNAME

ihuGetStringTagPropertyByTagName

Prototype

Use the ihuGetStringTagPropertyByTagname function to retrieve the value of a specified string tag property from the API tag cache for a specified tag. This call queries the cache, but not the archiver. The tag property may have changed since the cache was fetched.

ihuGetStringTagPropertyByTagname {
  in MSO Char *Tagname,
  in ihuTagProperties TagProperty,
  in int valuelength,
  out MSO Char *Value
};

Remarks

The get by tagname function is slower than the get by index function because it loops through all tags in the cache to find the requested tag. To retrieve multiple properties for a tag, consider calling ihuGetTagnameCacheIndex to get the cache index of a tag so that you can use the get by index functions.

Returns

  • ihuSTATUS_OK
  • ihuSTATUS_INVALID_PARAMETER
  • ihuSTATUS_INVALID_TAGNAME

ihuGetStringTagPropertyByTagNameEx2

Prototype

Use the ihuGetStringTagPropertyByTagnameEx2 function to retrieve the value of a specified string tag property from the API tag cache for a specified tag. This call queries the cache, but not the archiver. The tag property may have changed since the cache was fetched.

ihuGetStringTagPropertyByTagnameEx2 {
void * TagCacheContext, MSO
Char * Tagname,
ihuTagProperties TagProperty,
MSO Char * Value,
int valuelength,
};

Remarks

The get by tagname function is slower than the get by index function because it loops through all tags in the cache to find the requested tag. To retrieve multiple properties for a tag, consider calling ihuGetTagnameCacheIndex to get the cache index of a tag so that you can use the get by index functions.

Returns

  • ihuSTATUS_OK
  • ihuSTATUS_INVALID_PARAMETER
  • ihuSTATUS_INVALID_TAGNAME

ihuGetStringTagPropertyByIndex

Prototype

Use the ihuGetStringTagPropertyByIndex function to retrieve the value of a specified string tag property from the API tag cache at a specified cache index. This call queries the cache, but not the archiver. The tag property may have changed since the cache was fetched.

ihuGetStringTagPropertyByIndex {
  in int Index,
  in ihuTagProperties TagProperty,
  out MSO Char *Value,
  in int valuelength,
};

Remarks

Use the get property by index functions after you locate tags with ihuGetTagnameCacheIndex, or when you want to iterate through all tags in the cache.

The index is zero-based.

Returns

  • ihuSTATUS_OK
  • ihuSTATUS_INVALID_PARAMETER
  • ihuSTATUS_INVALID_TAGNAME

ihuGetStringTagPropertyByIndexEx2

Prototype

Use the ihuGetStringTagPropertyByIndexEx2 function to retrieve the value of a specified string tag property from the API tag cache at a specified cache index. This call queries the cache, but not the archiver. The tag property may have changed since the cache was fetched.

ihuGetStringTagPropertyByIndexEx2 {
void * TagCacheContext,
int Index,
ihuTagProperties TagProperty,
MSO Char * Value,
int valueLength,
};

Remarks

Use the get property by index functions when you do not know the tag name, or when you want to iterate through all tags in the cache.

The index is zero-based.

Returns

  • ihuSTATUS_OK
  • ihuSTATUS_INVALID_PARAMETER
  • ihuSTATUS_INVALID_TAGNAME

ihuTagAdd

Prototype

Use the ihuTagAdd function to add or modify tags.

ihuTagAdd {
  in long serverhandle,
};

Remarks

This function uses serverhandle as a parameter.

Tag names that contain question marks (?) or asterisks (*) are not added to the server.

To modify a tag, you must add it again with new properties. Whenever you change or copy a tag name, the old and new tag names and time stamps are recorded in the audit trail.

Returns

  • ihuSTATUS_OK: Success
  • ihuSTATUS_INVALID_PARAMETER: Invalid input parameters
  • ihuSTATUS_LIC_TOO_MANY_TAGS: Added tags exceed the licensed tag count
  • ihuSTATUS_ACCESS_DENIED: You do not have rights to add tags

ihuTagDelete

Prototype

Use the ihuTagDelete function to delete tags from the server.

ihuTagDelete {
  in long serverhandle,
  in MSO Char * tagname,
};

Remarks

This function uses serverhandle and tagname as parameters.

Returns

  • ihuSTATUS_OK: Success
  • ihuSTATUS_INVALID_PARAMETER: Invalid input parameters
  • ihuSTATUS_ACCESS_DENIED: You do not have rights to delete tags

ihuTagDeleteEx

Prototype

You can use the ihuTagDeleteEx function to permanently delete a tag by passing TRUE as a parameter.

ihuTagDeleteEx {
  in long serverhandle,
  in MSO Char * tagname,
  BOOL DeletePermanent
};

Remarks

Use DeletePermanent to create a new tag with a previously used name. The ihuTagDeleteEx function uses the following parameters:

  • serverhandle: The Historian server from which to fetch tags
  • tagname: Name of the tag to be deleted, which must be returned in a tag browse
  • DeletePermanent: Permanently deletes a tag when set to TRUE
Note: After you permanently delete a tag, you can no longer query its data, and the tag name is available for reuse.

Returns

  • ihuSTATUS_OK: Success
  • ihuSTATUS_INVALID_PARAMETER: Invalid input parameters
  • ihuSTATUS_ACCESS_DENIED: You do not have rights to delete tags
Note: You must be a member of the ihTag Admin security group to delete tags.

ihuTagRename

Prototype

Use the ihuTagRename function to rename tags.

ihuTagRename {
  in long serverhandle,
  in MSO Char * OldTagName,
  in MSO Char * NewTagName,
};

Remarks

This function uses the following parameters:

  • serverhandle: The Historian 4.0 server from which to fetch tags
  • OldTagname: Name of the tag to be renamed
  • NewTagname: New tag name
Note: When you use this function to update or modify tag names, the tag properties are not modified. If you modify a renamed tag property, be aware that all the tag properties for the alias are also updated.

Returns

  • ihuSTATUS_OK: Success
  • ihuSTATUS_INVALID_PARAMETER: Invalid input parameters
  • ihuSTATUS_ACCESS_DENIED: You do not have rights to rename tags

ihuTagRenameEx

Prototype

You can use the ihuTagRenameEx function to permanently rename a tag by passing TRUE as a parameter.

ihuTagRenameEx {
  in long serverhandle,
  in MSO Char * OldTagName,
  in MSO Char * NewTagName,
BOOL TrueRename,
};

Remarks

You can permanently rename tags that you do not want to read and write with their previous names. This function uses the following parameters:

  • serverhandle: The Historian 4.0 server from which to fetch tags
  • OldTagname: Name of the tag to be renamed
  • NewTagname: New tag name
  • TrueRename: Permanently renames a tag when set to TRUE.

Returns

  • ihuSTATUS_OK: Success
  • ihuSTATUS_INVALID_PARAMETER: Invalid input parameters
  • ihuSTATUS_ACCESS_DENIED: You do not have rights to rename tags
Note: You must be a member of the ihTag Admin security group to rename tags.

ihuTagCacheCriteriaClear

Prototype

Use the ihuTagCacheCriteriaClear function to clear any cached criteria before you set up tag browse criteria.

void IHUAPI ihuTagCacheCriteriaClear();
};

ihuTagCacheCriteriaClearEx2

Prototype

Use the ihuTagCacheCriteriaClear function to clear any cached criteria before you set up tag browse criteria.

void IHUAPI ihuTagCacheCriteriaClearEx2
(
void * TagCacheContext,
};

ihuTagCacheCriteriaSetStringProperty

Prototype

Use the ihuTagCacheCriteriaSetStringProperty function to set up tag browse criteria before you call ihuFetchTagCacheEx.

ihuTagCacheCriteriaSetStringProperty {
  in ihuTagProperties TagProperty,
  in MSO Char *Value,
};

Remarks

This function fetches a current set of tags and properties from the Historian server and places them into an API cache for subsequent queries, such as ihuGetNumericTagPropertyByTagname.

Returns

  • ihuSTATUS_OK
  • ihuSTATUS_INVALID_PARAMETER
  • ihuSTATUS_INVALID_TAGNAME

ihuTagCacheCriteriaSetStringPropertyEx2

Prototype

Use the ihuTagCacheCriteriaSetStringPropertyEx2 function to set up tag browse criteria before you call ihuFetchTagCacheEx.

ihuTagCacheCriteriaSetStringPropertyEx2 {
void * TagCacheContext,
ihuTagProperties TagProperty,
MSO Char *Value,
};

Remarks

This function fetches a current set of tags and properties from the Historian server and places them into an API cache for subsequent queries, such as ihuGetNumericTagPropertyByTagname.

Returns

  • ihuSTATUS_OK
  • ihuSTATUS_INVALID_PARAMETER
  • ihuSTATUS_INVALID_TAGNAME

ihuTagCacheCriteriaSetNumericProperty

Prototype

Use the ihuTagCacheCriteriaSetNumericProperty function to set up tag browse criteria.

ihuTagCacheCriteriaSetNumericProperty {
  in ihuTagProperties TagProperty,
  in double Value,
};

Returns

  • ihuSTATUS_OK
  • ihuSTATUS_INVALID_PARAMETER
  • ihuSTATUS_INVALID_TAGNAME

ihuTagCacheCriteriaSetNumericPropertyEx2

Prototype

Use the ihuTagCacheCriteriaSetNumericPropertyEx2 function to set up tag browse criteria.

ihuTagCacheCriteriaSetNumericPropertyEx2 {
void * TagCacheContext,
ihuTagProperties TagProperty,
double Value,
};

Returns

  • ihuSTATUS_OK
  • ihuSTATUS_INVALID_PARAMETER
  • ihuSTATUS_INVALID_TAGNAME

ihuTagClearProperties

Prototype

Use the ihuTagClearProperties function to clear tag properties before you add tags to a server.

void IHUAPI ihuTagClearProperties()
};

ihuTagSetStringProperty

Prototype

Use the ihuTagSetStringProperty function to set string tag properties before you call ihuTagAdd.

ihuTagSetStringProperty {
  in ihuTagProperties TagProperty,
  in MSO Char *Value,
};

Returns

  • ihuSTATUS_OK

ihuTagSetNumericProperty

Prototype

Use the ihuTagSetNumericProperty function to set numeric tag properties before you call ihuTagAdd.

ihuTagSetNumericProperty {
  in ihuTagProperties TagProperty,
  in double.Value,
};

Returns

  • ihuSTATUS_OK

ihuCloseTagCache

Prototype

Use the ihuCloseTagCache function to free the API cache from memory. Be sure to close the tag cache when not in use to free memory and prevent accidental usage.

ihuCloseTagCache {
};

Returns

  • ihuSTATUS_OK in all cases

ihuCloseTagCacheEx2

Prototype

Use the ihuCloseTagCacheEx2 function to free the API cache from memory. Be sure to close the tag cache when not in use to free memory and prevent accidental usage.

ihuCloseTagCache {
void * TagCacheContext
};

Returns

  • ihuSTATUS_OK in all cases