System API Tag Functions
You need tags to exist in Historian in order to write and read data samples. A read or write call requires a tagname as a parameter. The tag must exist before the data samples are written, the tag is not created automatically.
- A tag has a
tagname
. - A tag may have aliases which are previously used names left over from tag renames.
- A tag has a
tagid
which is a long number and does not change. If you convert this number to a string you can pass it in place of atagname
. If your tagnames are typically longer than 128 characters then using thetagid
would be shorter.
A tagname can contain any character except the two wild card characters * and ?.
There are many tag properties as listed in the ihTagProperties
data structures in the ihapi.h
. All properties are available to your application and are documented in the Historian electronic books. A subset of import- ant properties are given in the following table. This list that applies to tags being written to by user programs. All of the properties related to collectors are not documented in the following table.
ihTagProperties
Property | Type | Description |
---|---|---|
Tagname | ihString | The tag name that shows in the tag browse. |
Description | ihString | The description of the tag that shows in the tag browse. |
DataType | ihDataType | The data type of the tag. This can be a custom type also. |
FixedStringLength | UnsignedChar | Used only if data type is FixedString. |
HiEngineeringUnits | Double | Used only if you are using ArchiveDead- bandPercent. |
LoEngineeringUnits | Double | Used only if you are using ArchiveDead- bandPercent. |
ArchiveCompression | ihBoolean | TRUE if you are using percent or abso- lute archive. |
ArchiveDeadbandPercentRange | Float | It is one way to configure the deadband instead of absolute archive. |
InterfaceGeneral1 | ihString | Spare string field for application use. |
InterfaceGeneral2 | ihString | Spare string field for application use. |
InterfaceGeneral3 | ihString | Spare string field for application use. |
InterfaceGeneral4 | ihString | Spare string field for application use. |
InterfaceGeneral5 | ihString | Spare string field for application use. |
ReadSecurityGroup | ihString | Only needed if you are using tag level security. |
WriteSecurityGroup | ihString | Only needed if you are using tag level security. |
AdministratorSecurityGroup | ihString | Only needed if you are using tag level security. |
UTCBias | Long | You can store an offset from GMT+0 here, such as -300. But it is up to the client programs to use it. |
ArchiveCompressionTimeOut | ihUnsignedLong | -- |
ArchiveAbsoluteDeadbanding | ihBoolean | -- |
ArchiveAbsoluteDeadband | Double | -- |
TimeResolution | ihTimeResolution | If the tag is using seconds, milliseconds or microseconds. |
TagId | ihTagId | You can refer to tags by their tagname or their TagId |
EnumeratedSetName | ihString | If you want to retrieve using an Enumerated Set. This is optional. |
DataStoreName | ihString | Defines what data store the tag belongs to or should be added to during an write function. Blank means default data store. |
DefaultQueryModifiers | ihQueryModifiers | Query modifier string. This is optional. |
UserDefinedTypeName | ihString | If you are using custom data types. |
NumberOfElements | ihUnsignedlong | If you are using an array data type. |
DataDensity | ihTagDataDensity | -- |
Tag Functions
ihTagAdd
Use this function to add a tag to Historian.
Prototype
ihTagAdd {
ihServerHandle hServer, // handle from previous call to ihServerConnect
ihTagFields *hFields, // the tag fields you are providing in the ihTagProperties
ihTagProperties *hTag // tag property values such as tagname and data type
};
Remarks
There are many tag properties but the minimum set is that you need tagname and data type. Since you do not need to provide all properties, use the ihTagFields to indicate which properties you are providing in the ihTagProperties
Adding a tag that already exists will update that tag to the properties that you provide.
For examples, refer to the Sample Programs included with the SDK.
Returns
Returns | Description |
---|---|
ihSTATUS_OK | On success |
ihSTATUS_API_TIMEOUT | If the server name or IP address provided cannot be located. |
ihSTATUS_NOT_CONNECTED | If you are not currently connected. |
ihSTATUS_ACCESS_DENIED | If you are not allowed to add or modify tags. Possibly you are not a member of the ih Tag Adminsgroup. |
ihSTATUS_LIC_TOO_MANY_TAGS | If adding this tag would exceed your licensed tag count ihSTATUS_FAILED - for any other type of error. |
ihSTATUS_FAILED | For any other type of error. |
ihTagMultiAdd
Use this function to add more than one tag in a single call to Proficy Historian.
Prototype
ihTagMultiAdd {
ihServerHandle hServer,
ihTagFields *hFields,
ihTagProperties *hTag,
int NumTags
};
This function takes an array of tag structures and a count. Typically, you call ihTagAdd function to add or modify your tags. For more information on adding a single tag, refer to ihTagAdd()
function. If you have thousands of tags to add use ihTagMultiAdd()
function.
Returns
Returns | Description |
---|---|
ihSTATUS_OK | On success. |
ihSTATUS_API_TIMEOUT | If the server name or IP address provided cannot be located. |
ihSTATUS_NOT_CONNECTED | If you are not currently connected. |
ihSTATUS_ACCESS_DENIED | If you are not allowed to add or modify tags. Possibly you are not a member of the ih Tag Adminsgroup. |
ihSTATUS_LIC_TOO_MANY_TAGS | If adding this tag would exceed your licensed tag count. |
ihSTATUS_FAILED | For any other type of error. |
ihTagDelete
Use this function to delete a tag from Historian.
Prototype
ihTagDelete {
ihServerHandle hServer, // a server handle returned from ihServerConnect
ihString Tagname, // the tag to delete
ihBoolean DeletePermanent // FALSE if you only want to make the tag not appear in tag browse.
TRUE if you want to delete the tag and its data entirely.
};
Remarks
You can delete a tag if it was created by mistake or if you no longer need the data. In most cases, passing DeletePermanent=FALSE is sufficient and hides the tag from future tag lists. Only if you need to re-use the tagname should you pass DeletePermanent=TRUE.
Returns
Returns | Description |
---|---|
ihSTATUS_OK | On success. |
ihSTATUS_API_TIMEOUT | If the server name or IP address provided cannot be located. |
ihSTATUS_NOT_CONNECTED | If you are not currently connected. |
ihSTATUS_ACCESS_DENIED | If you are not allowed to add or modify tags. Possibly you are not a member of the ih Tag Adminsgroup. |
ihSTATUS_FAILED | For any other type of error. |
ihTagRename
Use this function to rename a tag in Historian.
Prototype
ihTagRename {
ihServerHandle hServer, // a server handle returned from ihServerConnect
ihString Tagname, // the current tagname
ihString NewTagname, // the new tagname
ihBoolean TrueRename // TRUE if you want to reject reads to the old tagname and want to make the
old tagname available for reuse.
};
Remarks
You can rename tags to a single, new name or keep the old name available to legacy clients. Only the current name appears in a tag browse. Pass TRUE to permanently rename a tag.
Returns
Returns | Description |
---|---|
ihSTATUS_OK | On success. |
ihSTATUS_API_TIMEOUT | If the server name or IP address provided cannot be located. |
ihSTATUS_NOT_CONNECTED | If you are not currently connected. |
ihSTATUS_ACCESS_DENIED | If you are not allowed to add or modify tags. Possibly you are not a member of the ih Tag Adminsgroup. |
ihSTATUS_FAILED | For any other type of error. |
ihTagFreeproperties (Tag Properties)
Use this function to correctly free one tag properties structure that was returned from an ihTagGetProperties()
call.
Prototype
void ihTagFreeProperties {
ihTagFields *hFields, // indicates which fields in the tag properties are valid
ihTagProperties *hTagProps // structure containing tag properties to be freed.
};
Use this function to correctly free one tag properties structure. You do not need to call this to free the tag recordset returned from a browse. Use
ihTagCloseRecordset()
instead.
Returns
Returns | Description |
---|---|
Void | Void |
ihTagOpenRecordset
This function is used to browse tags that exist in the Data Archiver.
ihTagOpenRecordset {
ihServerHandle hServer, // a server handle returned from ihServerConnect
ihTagFields *RequestedFields, // indicates which tag properties you want included with the returned tags
ihTagCriteria *Criteria, // used to determine which tags to return
ihTagFields *CriteriaFields, // used to indicate which criteria fields should be used
ihTagRecordset *TagRecordset // output parameter that contains the returned tag recordset
};
Remarks
This is the function used to browse tags that exist in the Data Archiver. You specify a criteria and which fields of each matching tag you want returned and a recordset of matching tags is returned. Since a tag has many properties it is a waste of resources to return all the tag properties if for example you only want the tagnames.
Using filtering criteria you can perform a simple wildcard search on tagname or description, or you can get all tags of integer data type, or otherwise use any condition on any tag property. The CriteriaFields is where you indicate which tag properties to use in the filter.
The tag recordset will contain a number of tags returned. It is possible that no tags match your criteria. After you are finished using the tag recordset you should free it using ihTagCloseRecordset().
Do not free any individual tag string fields.
An example of tag filtering and browsing is provided in SDK sample program.
Returns
Returns | Description |
---|---|
ihSTATUS_OK | On success and the tags are returned in the TagRecordset. |
ihSTATUS_API_TIMEOUT | The client program did not receive a portion of the tag list before the timeout expired. Large browses are sent back in multiple responses and the SystemAPI must receive at least a partial response before the timeout expires. For example if there is 90 second timeout configured, a browse can take several minutes or as long as at least a part of the response is received every 90 seconds. |
ihSTATUS_NOT_CONNECTED | If you are not currently connected to the Data Archiver. |
ihSTATUS_ACCESS_DENIED | If you are not allowed to add or modify tags. Possibly you are not a member of the ih Tag Adminsgroup. |
ihSTATUS_FAILED | For any other type of error. |
ihTagCloseRecordset
Use this function to return the recordset returned from an ihTagOpenRecordset() call.
Prototype
ihTagCloseRecordset {
ihTagRecordset *TagRecordset
};
Remarks
Use this function to return the recordset returned from an ihTagOpenRecordset()
call.
Returns
Returns | Description |
---|---|
ihSTATUS_OK | Always |
ihTagExists
This function checks if a given tag exists in Historian.
ihTagExists {
ihServerHandle hServer, // a server handle returned from ihServerConnect
ihString Tagname
};
Remarks
Use this function to check if a tag exists as it is easier than using ihTagOpenRecordset(). Tags that have been deleted are usually hidden and they still exist. ihTagOpenRecordset() only returns non-deleted tags.
Returns
Returns | Description |
---|---|
ihSTATUS_OK | If the tag exists. |
ihSTATUS_INVALID_PARAMETER | On invalid input parameters. |
This function is more convenient than using the ihTagOpenRecordset() function when you know the tag- name and want to check for tag existence or get more information about a tag.
If the call succeeds and properties are returned you should call ihTagFreeProperties()
to free any string properties.
ihTagGetProperties
This function returns the properties of the tags.
ihTagGetProperties {
ihServerHandle hServer, // a server handle returned from ihServerConnect
ihString Tagname, // the tagname to locate. Wildcards are not allowed.
ihTagFields *hFields, // the fields you want returned
ihTagProperties *hTag // an output parameter containing the returned tag properties
};
Remarks
This function is more convenient than using the ihTagOpenRecordset() function when you know the tag- name and want to check for tag existence or get more information about a tag.
If the call succeeds and properties are returned you should call ihTagFreeProperties()
to free any string properties.
Returns
Returns | Description |
---|---|
ihSTATUS_OK | If the tag exists. |
ihSTATUS_INVALID_PARAMETER | On invalid input parameters. |
ihTagFreeProperties
This function used to free the information returned by an ihTagGetProperties()
call.
Prototype
void ihTagFreeProperties {
ihTagFields *hFields, // the fields you want freed
ihTagProperties *hTag // contains the tag properties
};
Remarks
Use this function to free the information returned by an ihTagGetProperties()
call.
Returns
Returns | Description |
---|---|
Void | Void |
ihTagSetProperties
This function is used to set the tag properties.
Prototype
ihTagSetProperties {
ihServerHandle hServer, // a server handle returned from ihServerConnect
ihTagFields *hFields,
ihTagProperties *hTag
};
ihTagSubscribe
This function is used to setup a subscription to tag changes.
Prototype
ihTagSubscribe {
ihServerHandle hServer, // a server handle returned from ihServerConnect
ihString Tagname, // the tagname to monitor for changes. Wildcards are allowed
ihBoolean Subscribe // TRUE if you want to subscribe or FALSE to unsubscribe
};
Remarks
Use this function to setup a subscription to tag changes. A tag change would be a change to a tag prop- erty. Data being written to a tag is not a tag change but can be monitored using ihDataSubscribe.
You must register a callback function using ihTagRegisterCallback() and that function will be called on change.
To detect tag additions pass the wildcard * and you will be notified of all changes to all tags. Discard any incoming subscriptions you are not interested in.
An example of tag subscriptions is provided in the SDK sample program.
ihTagRegisterCallBack
This function returns which tag properties have changed
ihTagRegisterCallBack {
ihServerHandle hServer, // a server handle returned from ihServerConnect
ihTagCallbackFunction CallbackFunction, // the function to be called
void *UserParameter
};
When your callback function is called there will be an indication of what tag property changed.
ihTagClearAllFields
This function clears the tag properties.
Prototype
void ihTagClearAllFields {
ihTagFields *Fields
};
Returns
Returns | Description |
---|---|
Void | Void |