System API Tag Functions

ihTagProperties

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

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

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

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

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

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

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

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

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

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

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