Historian for Linux - User API

Contents
Historian for Linux User API - an Overview 1
Historian for Linux User API - an Overview 1
Connect Functions 2
Connect Functions 2
ihuConnect function 2
ihuConnectEx function 3
ihuDisconnect function 4
ihuSetConnectionParameters function 4
ihuRestoreDefaultConnectionParameters function 5
ihuServerRegisterCallbacks function 5
Interface Functions 7
ihuBrowseCollectors Function 7
Tag Functions 8
Tag Functions Overview 8
Tag Property Value Types 8
ihuCreateTagCacheContext Function 10
ihuFetchTagCache Function 10
ihuFetchTagCacheEx Function 11
ihuFetchTagCacheEx2 Function 11
ihuFetchTagCacheEx3 Function 12
ihuGetTagNameCacheIndex Function 12
ihuGetTagNameCacheIndexEx2 Function 13
ihuGetNumericTagPropertyByTagname Function 13
ihuGetNumericTagPropertyByIndex Function 14
ihuGetNumericTagPropertyByIndexEx2 Function 14
ihuGetStringTagPropertyByTagName Function 15
ihuGetStringTagPropertyByTagNameEx2 Function 16
ihuGetStringTagPropertyByIndex Function 16
ihuGetStringTagPropertyByIndexEx2 Function 17
ihuTagAdd Function 17
ihuTagDelete Function 18
ihuTagRename Function 18

ii Historian for Linux - User API

ihuTagCacheCriteriaClear Function 19
ihuTagCacheCriteriaSetStringProperty Function 19
ihuTagCacheCriteriaSetStringPropertyEx2 Function 20
ihuTagCacheCriteriaSetNumericProperty Function 20
ihuTagCacheCriteriaSetNumericPropertyEx2 Function 20
ihuTagClearProperties Function 21
ihuTagSetStringProperty Function 21
ihuTagSetNumericProperty Function 21
ihuCloseTagCache Function 22
ihuCloseTagCacheEx2 Function 22

iii
Historian for Linux User API - an Overview

Historian for Linux User API - an Overview

The Historian User API is a 'C' library intended to provide high speed read/write access to Historian data
and Historian tags. Note that there is no access to archives, alarms, events, or messages.
Use the API to develop applications, which read and write data to the Historian server when the REST
Query API & Web admin console does not meet the requirement for performance or programming
language.
Sample programs are provided with the API, demonstrating how to perform common tasks. Additional
information can be found in comments in the sample code and API header.
Note: The user of the Historian for Linux User API is assumed to be familiar with the Historian features
and functionality.

Supported platforms
Historian User API is compiled on Ubuntu 16.04 LTS & on Alpine 3.6.

1
Connect Functions

Connect Functions
This group of functions enables you to connect to and disconnect from an Historian server. A minimal
number of properties are exposed.

Connect Function List

The following is the list of available Connect functions:
• ihuConnect
• ihuConnectEx
• ihuDisconnect
• ihuSetConnectionParameters
• ihuRestoreDefaultConnectionParameters
• ihuServerRegisterCallbacks

ihuConnect function
Use the ihuConnect function to connect to a Historian Server. This function will provide a server handle
to be used in subsequent calls.

Prototype

ihuErrorCode ihuConnect
(
char * server,
char * username,
char * password,
int * serverhandle
);

Remarks
The inputs to the function are server, username, and password. Each has a default value if NULL is passed.
Server - if NULL is passed, then the connection attempt will be to the local machine.
Username/Password - if NULL is passed, then the username that owns the process is used. Most of the
time this is the same as the user logged into the operating system. However, in the case of a program
running as a service you can specify a username and password that the process should use.
The output of the function is a server handle.
Server handles are only valid for the lifetime of the process. They should not be saved to a file and reused.
You do not need to call connect more than one time for a username and password. If the connection to
server was lost and restored, the handle can be used after reconnect. If the server was not there at
connect time, a handle will still be returned and you can use that as soon as the connection becomes
available. Reconnects are 2 Proficy Historian User API performed inside of the API. The application should
wait, retry reads and writes with the returned server handle. The reads and writes will succeed once the
underlying connection is re-established.

2
 You should still call disconnect with the server handle returned, even if an error is returned.

Returns
ihuConnect returns the following values:
• IhuSTATUS_OK
• ihuSTATUS_FAILED
• ihuSTATUS_API_TIMEOUT
• ihuSTATUS_NOT_VALID_USER
• ihuSTATUS_LIC_TOO_MANY_USERS

ihuConnectEx function
Use the ihuConnectEx function to connect to a server with the support of store and forward.

Prototype
ihuErrorCode ihuConnectEx
(
char * server, //[in] Server name
char * username, //[in] User name
char * password, //[in] Password
char * buffername, //[in] Buffer file name should
be unique
unsigned int MaxMegMemory, //[in] Maximum Memory in
MB
unsigned int MinMegDiskFree, //[in] Minimum Free disk
space in MB
int * serverhandle //[out]Server handle
);

Remarks
The inputs to the function are server, username, password, buffername, MaxMegMemory, and
MinMegDiskFree.
Server - if NULL is passed, then the connection attempt will be to the local machine.
Username/Password - if NULL is passed, then the username that owns the process is used. Most of the
time this is the same as the user logged into the operating system. However, in the case of a program
running as a service you can specify a username and password that the process should use.
Buffer Name - The filename and location to store buffered data. Make sure the buffer file name is unique.
MaxMegMemory - Maximum memory in MB. Buffered data is stored in this memory until it is full, later it is
stored to disk.
MinMegDiskFree - Minimum free disk space in MB.
The output of the function is a server handle.
Server handles are only valid for the lifetime of the process. They should not be saved to a file and reused.
You do not need to call connect more than one time for a username and password. If the connection to
server was lost and restored, the handle can be used after reconnect. If the server was not there at
connect time, a handle will still be returned and you can use that as soon as the connection becomes
available. Reconnects are performed inside of the API. The application should wait, retrying reads and

3
 writes with the returned server handle. The reads and writes will succeed once the underlying connection
is re-established.
You should still call disconnect with the server handle returned, even if an error is returned.

Returns
ihuConnect returns the following values:
• IhuSTATUS_OK
• ihuSTATUS_FAILED
• ihuSTATUS_API_TIMEOUT
• ihuSTATUS_NOT_VALID_USER
• ihuSTATUS_LIC_TOO_MANY_USERS

ihuDisconnect function
Use the ihuDisconenct function to release connection resources.
Prototype

ihuErrorCode ihuDisconnect
(
int serverhandle
);

Returns
ihuDisconnect returns the following values:
• ihuSTATUS_OK

ihuSetConnectionParameters function
Use the ihuSetConnectionParameters function to set the socket connection timeout.

Prototype
ihuErrorCode
ihuSetConnectionParameters(IHU_CONNECTION_PARAMETERS *Params);

Remarks

/* Client-side, global connection parameters */

typedef struct {
int Size; // Structure size in bytes
int TCPConnectionWindow; // Max time to establish a TCP connection
with server in seconds (default 5s) }
IHU_CONNECTION_PARAMETERS;

The default connection timeout is 5 seconds. There is no maximum value, but it is not recommended to
set the value to more than 60 seconds. If you increase the timeout, attempts to connect a server will take
longer time to return if the server is not available.

4
 Sample Code
If an archiver is busy to process the connections, then you can set a longer timeout using the following
code:

IHU_CONNECTION_PARAMETERS params;
params.Size = sizeof(IHU_CONNECTION_PARAMETERS);
params.TCPConnectionWindow = 30; // extend window to 30s
ihuSetConnectionParameters(&params);

Note: This code only applies to the connections made from your program. You need to make this call each
time you run your program.

Returns
ihuSetConnectionParameters returns the following values:
• ihuSTATUS_OK on success.
• ihuSTATUS_FAILED on fail.

ihuRestoreDefaultConnectionParameters function
Use the ihuRestoreDefaultConnectionParameters function to reset all connection parameters
such as the socket connection timeout to default values.

Prototype

ihuErrorCode ihuRestoreDefaultConnectionParameters { void};

Remarks
Resets the connection timeout to 5 seconds.

Returns
IhuSTATUS_OK

ihuServerRegisterCallbacks function
Use the ihuServerRegisterCallbacks function if you want your program to be notified of changes
in buffering or connection state. For example, you can be notified of connection loss or buffering becoming
full.

Prototype

ihuErrorCode ihuServerRegisterCallbacks
(
int hServer, //[in] Server handle
void *UserParameter, //[in] User parameters if any
int *RegisterCallbacksStatus, //[in] Status for Buffer state /
Connection state callbacks
void *BufferCallbackFunction, //[in] Callback function for Buffer

5
 state
void *ConnectionCallbackFunction //[in] Callback function for
Connection status
);

Remarks
The inputs to the function are hServer, UserParameter, RegisterCallbacksStatus,
BufferCallbackFunction,and ConnectionCallbackFunction.
hServer - server handle from the connect. The callbacks are as per server handle, so you can have
callbacks for some connections and not others or you can have different callbacks for different handles.
UserParameter - NULL or an integer value that you want passed back to you in the callback.
RegisterCallbacksStatus - The success or failure of setting up the callbacks.
BufferCallbackFunction - callback function for buffer state changes.
ConnectionCallbackFunction - callback function for connection state changes.

Returns
ihuServerRegisterCallbacks returns the following values:
• IhuSTATUS_OK
• ihuSTATUS_FAILED

6
Interface Functions

ihuBrowseCollectors Function
Use the ihuBrowseCollectors function to browse collectors that are connected to the archiver.

Prototype

ihuErrorCode ihuBrowseCollectors
(
int hServer, //[in] from which to server read interfaces
char *InterfaceNameMask, //[in] pass * for all interfaces, or
interface name or detailed mask for efficiency
IHU_COLLECTOR **Collectors, //[out] the returned interfaces /
collectors
int *NumOfCollectors //[out] returns number of interfaces
found
);

Remarks
The inputs to the function are hServer and InterfaceNameMask.
hServer - server handle indicating which server to be browsed.
*InterfaceNameMask - pass * for all interfaces, or interface name or detailed mask for efficiency. The
output of the function is.
**Collectors - returns list of interfaces / collectors.
*NumOfCollectors - returns number of interfaces found.

Returns
ihuBrowseCollectors returns the following values:
• IhuSTATUS_OK
• ihuSTATUS_FAILED

7
Tag Functions

Tag Functions Overview

The group of tag functions provides browse, add, modify and delete access to the configured tags on a
server. For each tag, the tag properties can be retrieved with User API calls. An example of this use would
be to retrieve user defined collection parameters for a tag prior to collection. Or, user configured display
parameters can be retrieved from a tag in preparation for plotting.
Both string and numeric tag properties can be retrieved. 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 User API.
You can browse tags in 3 different ways depending on if you need complex criteria or if you need multiple
browses open at the same time. The simplest browse uses ihuFetchTagCache which lets you filter by
tagname. If you need to filter by additional properties such as data type or collectorname, use the
ihuFetchTagCacheEx. Finally, if you need to have multiple browses open at the same time, such as
browsing all the tags on one server and another server and comparing them, use the
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

8
Property Value Type

ihuTagPropLoadBalancing Numeric

ihuTagProptime stampType Numeric

ihuTagPropHighEngineeringUnits Numeric

ihuTagPropLowEngineeringUnits Numeric

ihuTagPropInputScaling Numeric

ihuTagPropHighScale Numeric

ihuTagPropLowScale Numeric

ihuTagPropCollectorCompression Numeric

ihuTagPropCollectorDeadbandPerc Numeric
entRange

ihuTagPropArchiveCompression Numeric

ihuTagPropArchiveDeadbandPercen Numeric
tRange

ihuTagPropSpare1 String

ihuTagPropSpare2 String

ihuTagPropSpare3 String

ihuTagPropSpare4 String

ihuTagPropSpare5 String

ihuTagPropReadSecurityGroup String

ihuTagPropWriteSecurityGroup String

ihuTagPropAdministratorSecurity String
Group

ihuTagPropLastModified (not currently String

implemented)

ihuTagPropLastModifiedUser String

ihuTagPropInterfaceType Numeric

ihuTagPropStoreMilliseconds Numeric

ihuTagPropUTCBias Numeric

ihuTagPropNumberOfCalculationDe Numeric
pendencies

ihuTagPropCalculationDependenci String
es (only the first dependency is returned)

9
 Property Value Type

ihuTagPropAverageCollectionTime Numeric

ihuTagPropCollectionDisabled Numeric

ihuTagPropArchiveCompressionTim Numeric
eout

ihuTagPropCollectorCompressionT Numeric
imeout

ihuTagPropDataDensity Numeric

Note: Tag data density categories are minimum (1),

medium (4), and maximum (7).

ihuTagPropNumberOfElements Numeric

Note: If the NumberOfElements value is -1,

the tag is an array tag.

ihuCreateTagCacheContext Function
This function creates tag cache context to be used in the ihuFetchTagCacheEx2 or
ihuFetchTagCacheEx3.

Prototype

ihuCreateTagCacheContext { };

ihuFetchTagCache Function
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.

Prototype

ihuErrorCode ihuFetchTagCache
(
int serverhandle, // [in] which server to fetch from
char * tagmask, // [in] pass * for all tags, or tagname or detailed
mask for efficiency
int * NumTagsFound // [out] returns num tags found
);

Remarks
The function retrieves properties for each tag received.

10
 There is a single API tag cache. The previous tag cache must be freed before doing another fetch from the
same or a different server. Keep this in mind when accessing the tag cache from multiple threads in the
same application. Or, use the ihuCreateTagCacheContext and ihuFetchTagCacheEx2 or
ihuFetchTagCacheEx3 functions.

Returns
• ihuSTATUS_OK
• ihuSTATUS_INVALID_PARAMETER

ihuFetchTagCacheEx Function
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.

Prototype

ihuErrorCode ihuFetchTagCacheEx
(
int serverhandle, // [in] which server to fetch from
int * NumTagsFound // [out] returns num tags found
);

Remarks
The function uses the criteria setup by ihuTagCacheCriteriaSetStringProperty and
ihuTagCacheCriteriaSetNumericProperty for tag browse.

Returns
• ihuSTATUS_OK
• ihuSTATUS_INVALID_PARAMETER

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

Prototype

ihuErrorCode ihuFetchTagCacheEx2
(
void * TagCacheContext, // [in] which tag cache context to use
int serverhandle, // [in] which server to fetch from
char * tagmask, // [in] pass * for all tags, or tagname or
detailed mask for efficiency
int * NumTagsFound // [out] returns num tags found
);

11
 Remarks
The function uses the criteria setup by ihuTagCacheCriteriaSetStringProperty and
ihuTagCacheCriteriaSetNumericProperty for tag browse.

Returns
• ihuSTATUS_OK
• ihuSTATUS_INVALID_PARAMETER

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

Prototype

ihuErrorCode ihuFetchTagCacheEx3
(
void *TagCacheContext, // [in] which tag cache context to use
int serverhandle, // [in] which server to fetch from
int *NumTagsFound // [out] returns num tags found
);

Remarks
The function uses the criteria setup by ihuTagCacheCriteriaSetStringProperty and
ihuTagCacheCriteriaSetNumericProperty for tag browse.

Returns
• ihuSTATUS_OK
• ihuSTATUS_INVALID_PARAMETER

ihuGetTagNameCacheIndex Function
This function finds the index of the given tagname in the cache. The index can be used 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

ihuErrorCode ihuGetTagnameCacheIndex
(
char *Tagname, // [in] the tagname for the property
// the tagname is not case sensitive
unsigned int *CacheIndex // [out] tag index in cache
);

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

Returns
• ihuSTATUS_OK
• ihuSTATUS_INVALID_TAGNAME

ihuGetTagNameCacheIndexEx2 Function
This function finds the index of the given tagname in the cache at thread level context. The index can be
used 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

ihuErrorCode ihuGetTagnameCacheIndexEx2
(
void *TagCacheContext, // [in] which tag cache context to use
char *Tagname, // [in] the tagname for the property
// the tagname is not case sensitive
unsigned int *CacheIndex // [out] tag index in cache
);

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

Returns
• ihuSTATUS_OK
• ihuSTATUS_INVALID_TAGNAME

ihuGetNumericTagPropertyByTagname Function
This function retrieves the value of a given numeric tag property from the API tag cache for a given tag.
This call does not query the archiver, it queries the cache. The tag property may have changed since the
cache was fetched.

Prototytpe

ihuErrorCode ihuGetNumericTagPropertyByTagname
(
char *Tagname, // [in] the tagname to read
ihuTagProperties TagProperty, // [in] the property to read
double *Value // [out] the tag property value
);

13
 Remarks
The get by tagname function is slower than the get by index function because it has to loop through all
tags in the cache looking for the requested tag. If you will be retrieving multiple properties for a tag,
consider calling the ihuGetTagnameCacheIndex function to get the cache index of a tag so that the
get by index functions can be used.

Returns
• ihuSTATUS_OK
• ihuSTATUS_INVALID_PARAMETER
• ihuSTATUS_INVALID_TAGNAME

ihuGetNumericTagPropertyByIndex Function
This function retrieves the value of a given numeric tag property from the API tag cache at a given cache
index. This call does not query the archiver, it queries the cache. The tag property may have changed since
the cache was fetched.

Prototype

ihuErrorCode IHUAPI ihuGetNumericTagPropertyByIndex

(
int Index, // [in] the 0 based index of the tag in the
cache
ihuTagProperties TagProperty, // [in] the property to read
double *Value // [out] the tag property value
);

Remarks
Use the get property by index functions when you have already located the tag using the
ihuGetTagnameCacheIndex or when you want to iterate through all tags in the cache. The index is
zero based. Tags are not returned from the cache in any particular order.

Returns
• ihuSTATUS_OK
• ihuSTATUS_INVALID_PARAMETER
• ihuSTATUS_INVALID_TAGNAME

ihuGetNumericTagPropertyByIndexEx2 Function
This function retrieves the value of a given numeric tag property from the API tag cache at a given cache
index. This call does not query the archiver, it queries the cache. The tag property may have changed since
the cache was fetched.

Prototype

ihuErrorCode ihuGetNumericTagPropertyByIndexEx2
(

14
 void *TagCacheContext, // [in] which tag cache context to use
int Index, // [in] the 0 based index of the tag in the
cache
ihuTagProperties TagProperty,// [in] the property to read
double *Value // [out] the tag property value
);

Remarks
Use the get property by index functions when you do not know the tagname. The index is zero based. Tags
are not returned from the cache in any particular order.

Returns
• ihuSTATUS_OK
• ihuSTATUS_INVALID_PARAMETER
• ihuSTATUS_INVALID_TAGNAME

ihuGetStringTagPropertyByTagName Function
This function retrieves the value of a given string tag property from the API tag cache for a given tag. This
call does not query the archiver, it queries the API cache. The tag property may have changed since the
cache was fetched.

Prototype

ihuErrorCode ihuGetStringTagPropertyByTagname
(
char *Tagname, // [in] the tagname to read
ihuTagProperties TagProperty, // [in] the property to read
char *Value, // [out] the tag property value
int ValueLength // [in] the length of the Value buf passed
in
);

Remarks
The get by tagname function is slower than the get by index function because it has to loop through all
tags in the cache looking for the requested tag. If you will be retrieving multiple properties for a tag,
consider calling the ihuGetTagnameCacheIndex function to get the cache index of a tag so that the
get by index functions can be used.

Returns
• ihuSTATUS_OK
• ihuSTATUS_INVALID_PARAMETER
• ihuSTATUS_INVALID_TAGNAME

15
ihuGetStringTagPropertyByTagNameEx2 Function
This function retrieves the value of a given string tag property from the API tag cache for a given tag. This
call does not query the archiver, it queries the API cache. The tag property may have changed since the
cache was fetched.

Prototype

ihuErrorCode ihuGetStringTagPropertyByTagnameEx2
(
void *TagCacheContext, // [in] which tag cache context to use
char *Tagname, // [in] the tagname to read
ihuTagProperties TagProperty, // [in] the property to read
char *Value, // [out] the tag property value
int ValueLength // [in] the length of the Value buf
passed in
);

Remarks
The get by tagname function is slower than the get by index function because it has to loop through all
tags in the cache looking for the requested tag. If you will be retrieving multiple properties for a tag,
consider calling the ihuGetTagnameCacheIndex function to get the cache index of a tag so that the
get by index functions can be used.

Returns
• ihuSTATUS_OK
• ihuSTATUS_INVALID_PARAMETER
• ihuSTATUS_INVALID_TAGNAME

ihuGetStringTagPropertyByIndex Function
This function retrieves the value of a given string tag property from the API tag cache at a given cache
index. This call does not query the archiver, it queries the cache. The tag property may have changed since
the cache was fetched.

Prototype

ihuErrorCode ihuGetStringTagPropertyByIndex
(
int Index, // [in] the 0 based index of the tag in the
cache
ihuTagProperties TagProperty, // [in] the property to read
char *Value, // [out] the tag property value
int ValueLength // [in] the length of the Value buf passed
in
);

16
 Remarks
Use the get property by index functions when you have already located the tag using the
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 Function
This function retrieves the value of a given string tag property from the API tag cache at a given cache
index. This call does not query the archiver, it queries the cache. The tag property may have changed since
the cache was fetched.

Prototype

ihuErrorCode ihuGetStringTagPropertyByIndexEx2
(
void *TagCacheContext, // [in] which tag cache context to use
int Index, // [in] the 0 based index of the tag in the cache
ihuTagProperties TagProperty, // [in] the property to read
char *Value, // [out] the tag property value
int ValueLength // [in] the length of the Value buf passed in
);

Remarks
Use the get property by index functions when you do not 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 Function
Use this function to add or modify tags.

Prototype

ihuErrorCode ihuTagAdd
(
int serverhandle // [in] which server to add to
);

17
 Remarks
This function uses serverhandle as a parameter.
If the tag name contains special characters "?" and "*" then the tag will not be added to the server.
To modify a tag, you must add a tag again with the new set of properties. Whenever you change or copy a
tag name, the information about the old tag name, new tag name, and time stamps are all recorded in the
audit trail.

Returns
• ihuSTATUS_OK on success.
• ihuSTATUS_INVALID_PARAMETER on invalid input parameters.
• ihuSTATUS_LIC_TOO_MANY_TAGS if the tag add would exceed the licensed tag count.
• ihuSTATUS_ACCESS_DENIED if you do not have permission to add tags.

ihuTagDelete Function
This function deletes a tag from the server. You can pass a wildcard to delete multiple tags.

Prototype

ihuErrorCode ihuTagDelete
(
int serverhandle, // [in] which server to delete from
char * TagName // [in] pass * for all tags,or tagname or detailed
mask for efficiency
);

Remarks
This function uses serverhandle and Tagname as parameters.

Returns
• ihuSTATUS_OK on success
• ihuSTATUS_INVALID_PARAMETER on invalid input parameters
• ihuSTATUS_ACCESS_DENIED if you do not have permission to add tags.

ihuTagRename Function
Use this function to rename tag names.

Prototype

ihuErrorCode ihuTagRename
(
int serverhandle, // [in] server which contains old tag
char * OldTagName, // [in] old TagName
char * NewTagName // [in] New TagName
);

18
 Remarks
This function uses serverhandle, OldTagName, and NewTagName as parameters.
• serverhandle - Parameter used to fetch from a specified Historian server.
• OldTagname - Name of the old tag you want to rename.
• NewTagname - Name of the new tag.
Tag renaming will only update or modify tag names without modifying or changing the tag properties.
If you want to modify a renamed tag property, be aware that of all the alias' tag properties will also be
updated.

Returns
• ihuSTATUS_OK on success
• ihuSTATUS_INVALID_PARAMETER on invalid input parameters
• ihuSTATUS_ACCESS_DENIED if you do not have permission to add tags.

ihuTagCacheCriteriaClear Function
Use this function to clear the criteria before setting up the tag browse criteria.

Prototype

void ihuTagCacheCriteriaClear();

ihuTagCacheCriteriaSetStringProperty Function
Use this function to setup the tag browse criteria before calling ihuFetchTagCacheEx.

Prototype

ihuErrorCode ihuTagCacheCriteriaSetStringProperty
(
ihuTagProperties TagProperty, // [in] the query criteria property
to set
char *Value // [in] the tag property value to use in query
);

Remarks
ihuFetchTagCacheEx 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

19
ihuTagCacheCriteriaSetStringPropertyEx2 Function
Use this function to setup the tag browse criteria before calling ihuFetchTagCacheEx.

Prototype

ihuErrorCode ihuTagCacheCriteriaSetStringPropertyEx2
(
void *TagCacheContext, // [in] which tag cache context to use
ihuTagProperties TagProperty, // [in] the query criteria property to
set
char *Value // [in] the tag property value to use in query
);

Remarks
ihuFetchTagCacheEx 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 Function
Use this function to setup the tag browse criteria.

Prototype

ihuErrorCode IHUAPI ihuTagCacheCriteriaSetNumericProperty

(
ihuTagProperties TagProperty, // [in] the query criteria property
to set
double Value // [in] the tag property value to use in
query
);

Returns
• ihuSTATUS_OK
• ihuSTATUS_INVALID_PARAMETER
• ihuSTATUS_INVALID_TAGNAME

ihuTagCacheCriteriaSetNumericPropertyEx2 Function
Use this function to setup the tag browse criteria.

20
 Prototype

ihuErrorCode ihuTagCacheCriteriaSetNumericPropertyEx2
(
void *TagCacheContext, // [in] which tag cache context to use
ihuTagProperties TagProperty, // [in] the query criteria property
to set
double Value // [in] the tag property value to use in query
);

Returns
• ihuSTATUS_OK
• ihuSTATUS_INVALID_PARAMETER
• ihuSTATUS_INVALID_TAGNAME

ihuTagClearProperties Function
Use this function to clear the tag properties before adding tags in to a server.

Prototype

void ihuTagClearProperties();

ihuTagSetStringProperty Function
Use this function to set a string tag property before calling ihuTagAdd.

Prototype

ihuErrorCode ihuTagSetStringProperty
(
ihuTagProperties TagProperty,
char *Value
);

Returns
• ihuSTATUS_OK

ihuTagSetNumericProperty Function
Use this function to set a numeric tag property before calling ihuTagAdd .

Prototype

ihuErrorCode ihuTagSetNumericProperty
(
ihuTagProperties TagProperty,

21
 double Value
);

Returns
• ihuSTATUS_OK

ihuCloseTagCache Function
This function will free the API cache from memory. You should always close the tag cache when not in use
to free memory and prevent accidental usage.

Prototype

ihuErrorCode ihuCloseTagCache ();

Returns
• ihuSTATUS_OK always

ihuCloseTagCacheEx2 Function
This function will free the API tag cache context from memory. You should always close the tag cache
when not in use to free memory and prevent accidental usage.

Prototype

ihuErrorCode ihuCloseTagCacheEx2
(
void * TagCacheContext
);

Returns
• ihuSTATUS_OK always

22