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 Functions

• ihuCreateTagCacheContext
• ihuFetchTagCache
• ihuFetchTagCacheEx
• ihuFetchTagCacheEx2
• ihuFetchTagCacheEx3
• ihuGetTagNameCacheIndex
• ihuGetTagNameCacheIndexEx2
• ihuGetNumericTagPropertyByTagname
• ihuGetNumericTagPropertyByIndex
• ihuGetNumericTagPropertyByIndexEx2
• ihuGetStringTagPropertyByTagname
• ihuGetStringTagPropertyByTagnameEx2
• ihuGetStringTagPropertyByIndex
• ihuGetStringTagPropertyByIndexEx2
• ihuTagAdd
• ihuTagDelete
• ihuTagRename
• ihuTagCacheCriteriaClear
• ihuTagCacheCriteriaClearEx2
• ihuTagCacheCriteriaSetStringProperty
• ihuTagCacheCriteriaSetStringPropertyEx2
• ihuTagCacheCriteriaSetNumericProperty
• ihuTagCacheCriteriaSetNumericPropertyEx2
• ihuTagClearProperties
• ihuTagSetStringProperty
• ihuTagSetNumericProperty
• ihuCloseTagCache
• ihuCloseTagCacheEx2

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.

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

Prototype

void * IHUAPI ihuCreateTagCacheContext {
};

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.

Prototype

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

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.

Prototype

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

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.

Prototype

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

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.

Prototype

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

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.

Prototype

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

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.

Prototype

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

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

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.

Prototype

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

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

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.

Prototype

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

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.

Prototype

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

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.

Prototype

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

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.

Prototype

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

Use the ihuTagAdd function to add or modify tags.

Prototype

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.

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

Use the ihuTagDelete function to delete tags from the server.

Prototype

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

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

Prototype

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

Returns

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

Use the ihuTagRename function to rename tags.

Prototype

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

Returns

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

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

Prototype

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

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

Prototype

void IHUAPI ihuTagCacheCriteriaClear();
};

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

Prototype

void IHUAPI ihuTagCacheCriteriaClearEx2
(
void * TagCacheContext,
};

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

Prototype

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

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

Prototype

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

Use the ihuTagCacheCriteriaSetNumericProperty function to set up tag browse criteria.

Prototype

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

Returns

• ihuSTATUS_OK
• ihuSTATUS_INVALID_PARAMETER
• ihuSTATUS_INVALID_TAGNAME

Use the ihuTagCacheCriteriaSetNumericPropertyEx2 function to set up tag browse criteria.

Prototype

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

Returns

• ihuSTATUS_OK
• ihuSTATUS_INVALID_PARAMETER
• ihuSTATUS_INVALID_TAGNAME

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

Prototype

void IHUAPI ihuTagClearProperties()
};

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

Prototype

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

Returns

• ihuSTATUS_OK

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

Prototype

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

Returns

• ihuSTATUS_OK

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.

Prototype

ihuCloseTagCache {
};

Returns

• ihuSTATUS_OK in all cases

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.

Prototype

ihuCloseTagCache {
void * TagCacheContext
};

Returns

• ihuSTATUS_OK in all cases