System API Functions

Connect Functions

To perform a connection you need to just use the connect functions. The API will complete the connection and do further necessary reconnects when the Data Archiver is restarted. Your program does not need to manage and monitor connections as it is done by the API.

Connections are subjected to Historian security, which is based on Microsoft Windows Security.

It is expected that user written programs will connect a minimal number of times for staying connected and using that connection for all read and write calls. Connecting and disconnecting rapidly is not efficient. The connect functions are:

ihServerConnect

ihServerConnect(

ihString ServerName,// the computer name or IP address of the Machine running the Data Archiver. You can pass 
NULL or the empty string ” to attempt connection to a Data Archiver on your local machine.
ihString Username,// The windows username to use when connecting or NULL if you want to connect as the process 
owner of your program, typically the logged in user. ??You would specify a username if the process owner was unable to 
connect or did not have sufficient Historian Security permissions. 
ihString Password,// if you passed a Username you can pass the password or ” if there is no password or 
otherwise just pass NULL
ihString BufferFileName, // an optional bufferfilename if your program will be using store and forward to 
deliver written data     
ihServerHandle *hServer // this is an output parameter that will contain the server handle that you would use in  
later read and write calls
);

Remarks

A server is a computer running a Data Archiver. You can specify a server by including the computer name or IP address.

ihServerConnect() will initiate a connection, but you should really use ihServerIsConnected() to determine if the connect actually completed.

If you setup a connection callback function with ihServerRegisterConnectionCallback() you will be notified of connection changes. Your security permissions for reads and writes will be established at connect time and are based on the user name and password provided.

Returns

ihServerDisconnect

Use this function to disconnect from the Historian server.

ihSeverDisconnect {
ihServerHandle hServer // the handle returned by a previous call to ihServerConnect

);

Remarks

You should call ihServerDisconnect() function even if the connection attempt returned an error.

Returns

ihServerIsConnected

This function returns whether the Historian server is currently connected or not. It is an indication that if you try to read and write data the call should be successful.

Prototype

ihServerIsConnected {
ihServerHandle hServer // a server handle returned from ihServerConnect

};

Returns

ihServerSetTimeout

This function is used to configure the timeout of the server connection.

Prototype

TihServerSetTimeout {
ihServerHandle hServer, // a server handle returned from ihServerConnect
int Timeout // the timeout, in seconds, to use
};

Use this to configure the timeout to a larger or smaller value. If the System API does not receive any response, even a partial response, during the timeout value, a ihSTATUS_API_TIMEOUT will be returned from the API call.

Set the timeout any time after connecting and the timeout stays in effect until it is changed or disconnect is issued.

Returns

ihServerGetTimeout

ihServerGetTimeout {
ihServerHandle hServer, ihULong *timeout
};

Remarks

Call ihServerConnect() to make a connection, then ihServerSetTimeout() to set the timeout if you want a non default value. You can use the ihServerGetTimeout() function to determine the timeout value that is being used.

The returned timeout value is in seconds.

Returns

ihServerGetVersion

This function returns the Historian server version and connection status.

Prototype

ihServerGetVersion {
ihServerHandle hServer, // a serverhandle returned from a previous call to ihServerConnect
int *Major, // output parameter to contain the major version of the Data Archiver. 
For example 4 when the Data Archiver version is 4.5.
int *Minor, // output parameter to contain the minor version of the Data Archiver. 
For example 5 when the Data Archiver version is 4.5.
int *Build, // output parameter to contain the build number of the Data Archiver. This is typically not used. 
int *Revision // output parameter to contain the revision number of the Data Archiver. This is typically not used

};
You will not receive an immediate callback with the current connection status. You will be notified of the next change in status

Remarks

You will not receive an immediate callback with the current connection status. You will be notified of the next change in status.

Returns

ihSecurityGetMembership

This function returns your membership list. Your group memberships determine your security permissions and what calls you can make on this Proficy Historian server connection.

Prototype

ihSecurityGetMembership {
ihServerHandle hServer, // handle from previous call to ihServerConnect 
ihSecurityGrpMembership *Memberships // output parameter to contain the group membership list

};

Remarks

You can optionally use this call after a successful connect to determine whether the Data Archiver considers your membership list. You need to be completely connected, not just initiate a connection, before this call can be used. The best way is to use ihServerIsConnected() after ihServerConnect() to determine that the connection completed.

Returns

ihServerOpenRecordset

This function returns the list of Historian servers that exist in the Windows registry.

Prototype

ihServerOpenRecordset {
ihString ServerNameMask, // typically NULL to get all servers but could be a mask

ihServerRecordset *ServerRecordset // output parameter containing the recordset

};

Remarks

Use this function to get the list of servers that exist in the Registry. This is a local call and does not need the Data Archiver.

The default server is stored in the Registry and can be used to query instead of hardcoding a server name in your program or prompting the user. The default server is established during product install and can be changed anytime later

Returns

ihServerCloseRecordset

This function is used to free any memory such as server names that were allocated in the System API.

Prototype

void ihServerCloseRecordset {
ihServerRecordset *ServerRecordset // recordset returned from ihServerOpenRecordset
};

Use this function to free any memory such as server names that were allocated in the System API in the ihServerOpenRecordset() call.

Returns

void

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

ihDataAdd

Use this function to add data to the Data Archiver:

Prototype

ihDataAdd {
ihServerHandle hServer, // server handle returned from previous call to ihServerConnect
ihUNSIGNED long NumberOfTags, // the number of data samples being written
ihString *Tagnames, // the tagname of each sample
ihDataProperties *DataValues, // the timestamp, value, and quality of each sample 
ihAPIStatus *ErrorStatuses, // output parameter for per data sample errors
ihBoolean WaitForReply, // TRUE if the call should wait for success or failure from Data Archiver. 
FALSE means that you do not want to do any error checking
ihBoolean ErrorOnReplace // TRUE if you want an error returned instead of overwriting data
);

Remarks

Although the parameter is called NumberOfTags it is really NumberOfSamples. Even if you are writing multiple samples to the same tagname you need to pass the tagname with each data sample. Every data sample you pass needs a tagname in the Tagnames parameter and a timestamp, value, and quality in the DataValues parameter.

The application would write data timestamps that are in GMT+0 timezone. The Data Archiver does not do any conversion. If your timestamps are in local time and the data is retrieved in other clients, the timestamps will not be adjusted to your time zone. The System API uses the ihTimeLCLPartsToUTCStructEx () function to help you convert timestamps.

Part of your application design is to bundle multiple data samples into one write. You can send one sample per call to ihDataAdd or send 100,000 samples or more. In most cases you can write data periodically to make it available to clients in bundles of 1,000 to 10,000 samples per call to ihDataAdd

Part of your application design is to determine what to consider bad or uncertain quality and what sub- quality to use. Your tags may be in a Data Archiver with many other tags from many other sources, these include tags written by collectors or Excel Import. You must be consistent with those tags so that clients need not have special logic for specific tags. For example, collectors use a quality of bad and a subquality of ihOffline to indicate that collection has stopped at this time in the real world. Consider including such a data sample and using the same quality and subquality in your program. In this way reports and trends need not know where the data came from.

The data type you write in the ihDataProperties does not need to match the data type of the tag in the Data Archiver. The Data Archiver will do the conversion prior to storing the data.

You should typically write with WaitForReply=TRUE so that you can check for errors and implement error handling such as retries. If you have no error handling strategy or if you are relying on the store and for- ward functionality to deliver data you can write with wait = FALSE. This is a rare use case. Understand that store and forward functionality only make sure that the data reaches the Data Archiver, not that the data is stored in the Historian archive. There could be security errors or the Archiver may be out of disk space. The most reliable way to write data is to check for errors and even possibly to read back the data that was written.

If you do get a per data sample error that does not mean the whole write failed. Samples that return ihSTATUS_OK were written successfully.

If your program only writes data going forward in time, there is no risk of replacing data and you can pass either TRUE or FALSE for the ErrorOnReplace parameter. Otherwise, pass TRUE if you do not want accidental data overwrite or FALSE to intentionally overwrite existing data.

There are rules about writes having timestamps that are too old or too new and those are not all given here. But, you will receive an error if your write is rejected.

Returns

If you write with WaitForReply=FALSE then the return code will be ihSTATUS_OK. When using WaitForReply=FALSE the return value of the overall function will be ihSTATUS_OK on success and non ihSTATUS_OK on error which means you should investigate the per data sample error returned in the ErrorStatuses output parameter. Those errors include these values:

If you write with WaitForReply=FALSE then the return code will be ihSTATUS_OK. When using WaitForReply=FALSE the return value of the overall function will be ihSTATUS_OK on success and non ihSTATUS_OK on error which means you should investigate the per data sample error returned in the ErrorStatuses output parameter. Those errors include these values:

ihDataDelete

This function is used to delete data. By using this function you are not actually deleting the data from the Data Archiver but instead hiding it and marking it as deleted.

Prototype

ihDataDelete {
ihServerHandle hServer, // server handle returned from previous call to ihServerConnect
ihUNSIGNED long NumberOfTags, // the number of data samples included in the Tagnames and DataValues parameters
ihString *Tagnames, // the tagname of the data sample to be deleted
ihDataProperties *DataValues, // the list of data samples to be deleted
ihAPIStatus *ErrorStatuses // output parameter containing error codes for individual data samples

);

Remarks

Deleting data is not actually done and this function does not clear or reset an entire tag. The reason is that the data is only hidden and not truly deleted. If you write and delete the same time range repeatedly the Historian storage becomes very inefficient.

Use the delete function to delete individual data samples so they are not returned in raw data queries or considered in calculation modes. Delete a small range of data if you have recalculated values and want to discard the previous calculations. You do not need to delete data prior to data overwrite.

The return codes for a delete are much like the ones returned from a write. ihSTATUS_OK - the data sample was successfully deleted.

Returns

ihDataOpenRecordset

This function is used to read values for one or more tags for a single start and end time, and sampling mode.

Prototype

ihDataOpenRecordset {
ihServerHandle hServer, // server handle returned from previous call to ihServerConnect
ihDataFields *Fields, // which fields such as value and quality and comments you want returned
ihDataCriteria *Criteria, // all of the parameters for the read including the tagname and time range and 
sampling mode
ihDataRecordset *DataRecordset // output parameter containing the retutned data samples or any per tag errors
);

Remarks

This function is used to read values for a single start and end time and sampling mode. This function is typically used to read a single tagname. However, a wildcard can be passed or multiple individual tagnames can be passed.

The list of sampling and calculation modes, filtering parameters and query modifiers are passed to this function to indicate if you want raw samples returned or you want the Data Archiver to perform some calculation or summarization of the data and return the results. For example you can instruct the Data Archiver to perform hourly averages and return the results instead of returning the samples themselves.

All calculated values are returned as Double Float, regardless of the data type of the tag. Sampling modes such as lab or interpolated will return data in the tag???s current data type, even if the data type was changed over a period of time.

The start and end time that you enter are assumed to be in the GMT+0 time zone. If you need to convert local time zone timestamps to UTC use the ihTimeLCLPartsToUTCStructEx() utility function. The returned data will also be in GMT+0 timezone and you can use the ihTimeUTCStructToLCLPartsEx() function to convert to local time in preparation for trending or reporting.

The memory holding the returned data must be freed but do not free each field directly. Simply call the ihDataCloseRecordset() function.

For examples, refer to SDK Sample Programs.

Returns

ihDataCloseRecordset

This function used to free the data recordset that was allocated inside the System API in a previous read call.

Prototype

void ihDataCloseRecordset {
ihDataRecordset *DataRecordset // the recordset to be freed. This comes from a previous call to 
ihDataOpenRecordset
);

Remarks

Use this function to free the data recordset that was allocated inside the System API in a previous read calls.

Returns

ihDataClearAllFields

This function is used to clear the set of requested data fields.

void ihDataClearAllFields {
ihDataFields *Fields ??// structure to be cleared
);

Remarks

Use this function to clear the set of requested data fields (timestamp,value,quality and so on) in preparation for doing a read. After

clearing, you should set the fields that you want returned.

Returns

ihDataSubscribe

This function is used to subscribe or unsubscribe the data changes for a tag or tags in the Data Archiver.

Prototype

ihDataSubscribe {
ihServerHandle hServer, // server handle returned from previous call to ihServerConnect
ihChar *Tagname, // the tagname or wildcard of tagnames to subscribe
ihUNSIGNED long MinimumElapsedTime, // the fastest rate in milliseconds that you want data returned or 0 to return every data change
ihBoolean Subscribe // TRUE to setup a subscription or FALSE to stop receiving changes from an existing subscription
);

Use this function to subscribe or unsubscribe to data changes for a tag or tags in the Data Archiver. ??Subscriptions will be delivered within a few seconds of data change and are delivered to you as DataRecordset structures through the callback you previously registered with ihDataRegisterCallback() callback function. You must register a callback first if you want to receive changes. This ihDataSubscribe() function indicates the tags you want to monitor.

You can subscribe to one tag by passing a specific tagname or pass a * or other wildcard to get changes for multiple tags. ??If you need to monitor multiple individual tag names, then call ihDataSubscribe() function once for each tag.

Most applications will pass a 0 for minimum elapsed time indicating they want all data changes. ??But you can specify a minimum rate. However, you may not be notified of every change. ??As you are notified, you should receive the data, possibly queuing the data change, and return from the callback.

Subscriptions stay in place even after ??the connection lost to archiver. However, once you call ihServerDisconnect() all subscriptions are cleared. It is not necessary to unsubscribe before calling disconnect but it is suggested.

ihDataGetCurrentValue

Use this function to get the current values of the one or more tags.

Prototype

ihDataGetCurrentValue {
ihServerHandle hServer, 
ihDataFields *Fields, 
unsigned long NumberOfTags,
ihChar **Tagnames,
ihDataProperties *DataValues,
ihAPIStatus *ErrorStatuses
);

Remarks

The ihDataGetCurrentValue function returns timestamp, value, quality, and comments. You can choose to return any of these values using the ihDataFields.

Values are returned based on the tag data type. You should free the returned values using ihDataFreeCurrentValue() function. Do not free the memory in your program.

You can have per tag errors. For example, if the tag does not exist or you are not allowed to read it.

Returns

ihDataFreeCurrentValue

Use this function to free the memory in your program for the current value of the selected tags.

Prototype

ihDataFreeCurrentValue {
ihUNSIGNED long NumberOfRecords,
ihDataProperties *DataValues
);

Remarks

Use this function to free what is returned from ihDataGetCurrentValue() function. Do not free the memory any other way.

Returns

ihDataSubscribe

Use this function to subscribe or unsubscribe to data changes for a tag or tags in the Data Archiver. Subscriptions will be delivered within a few seconds of data change and are delivered to you as DataRecordset structures through the callback you previously registered with ihDataRegisterCallback() callback function. You must register a callback first if you want to receive changes. This ihDataSubscribe() function indicates the tags you want to monitor.

You can subscribe to one tag by passing a specific tagname or pass a * or other wildcard to get changes for multiple tags. If you need to monitor multiple individual tag names, then call ihDataSubscribe() function once for each tag.

Most applications will pass a 0 for minimum elapsed time indicating they want all data changes. But you can specify a minimum rate. However, you may not be notified of every change. As you are notified, you should receive the data, possibly queuing the data change, and return from the callback.

Subscriptions stay in place even after the connection lost to archiver. However, once you call ihServer- Disconnect() all subscriptions are cleared. It is not necessary to unsubscribe before calling disconnect but it is suggested.

ihDataOpenMultiRecordset

ihDataOpenMultiRecordset {
ihServerHandle hServer,
ihUNSIGNED long NumberOfRequests,
ihDataFields *Fields, 
ihDataCriteria *Criteria, 
ihDataRecordset *DataRecordset
);

Remarks

This function can be used if you need to do a single read but use different sampling or calculation modes or different start and end times. You do not need to use this function simply to read multiple tags.

After checking the return value of the API call you can check the return value of each included query.

Returns

ihDataCloseMultiRecordset

This function is used to free the multiple recordsets returned from a ihDataOpenMultipleRecordset() call.

Prototype

void ihDataCloseMultiRecordset {
ihUNSIGNED long NumberOfRequests,
ihDataRecordset *DataRecordsetd
);

Remarks

Use this function to properly free the multiple recordsets that were allocated inside the System API in a previous read call.

Returns

ihArchiver options

ihArchiverFreeOption Function

Prototype

ihArchiveFreeOption{
ihChar *OptionValue // the string returned from ihArchiveGetOption()
);            

Remarks

Use this function to free the memory inside the structure. Do not free the fields in your code.

Returns

ihArchiverGetOption

This function retrieves an Archiver option from the data store.

ihArchiverGetOption {
ihServerHandle hServer,// server handle returned from previous call to ihServerConnect 
ihOptionEx *Option, // the option and data store name
ihChar **OptionValue // output parameter containing the option value
);

This function retrieves an Archiver option from a data store. You can indicate the data store in the ihOptionEx structure. You can pass NULL as the data store name to use the default data store.

You can get an option value to confirm it is set as requested by your application, or you can use this call to verify that a set option call was successful.

ihArchiverSetOption

This function sets an Archiver option from a data store.

ihArchiverGetStatistics

This function is used to get performance statistics from the Data Archiver.

ihArchiverGetStatistics(
ihServerHandle hServer, 
ihArchiveStatistics *Statistics
);

Menu ihOptions

Archiver Configuration Functions

ihArchiveOpenRecordset

This function is used to get the list of archives listed in the server.

Prototype

ihArchiveOpenRecordset
(
ihServerHandle hServer,
ihArchiveCriteria *Criteria,
ihArchiveRecordset *ArchiveRecordset

);

Remarks

Use the criteria if you only want a specific archive or archives from a specific data store. Otherwise you can get all archives and loop through them to see their start and end times and sizes for example.

Call ihArchiveCloseRecordset() to free the memory when you are done. Do not free memory in your program.

Returns

ihArchiveCloseRecordset

This function is used to free up the memory associated with the ArchiveRecordset.

Prototype

ihArchiveCloseRecordset(

ihArchiveRecordset *ArchiveRecordset
);

Remarks

Use this function to free the memory associated with the ArchiveRecordset that was returned from ihArchiveOpenRecordset(). Do not free the fields in your code.

Returns

ihArchiveGetOption

This function retrieves an Archiver option from the data store. This option controls the behavior of the Data Archiver for writes, security and timeouts.

Prototype

ihArchiveGetOption {

ihServerHandle hServer, ihOptionEx *Option, ihChar **OptionValue

);

Remarks

This function retrieves an Archiver option from a data store. You can indicate the data store in the ihOptionEx structure. You can pass NULL as the data store name to use the default data store. You can get an option value to confirm it is set as requested by your application, or you can use this call to verify that a set option call was successful.

Returns

ihArchiveSetOption

This function sets an Archiver option from a data store

Prototype

ihArchiveSetOption {

ihServerHandle hServer, ihOptionEx *Option, ihChar *OptionValue

);

Remarks

This function sets an Archiver option from a data store. You can indicate the data store in the ihOptionEx structure. You can pass NULL as the data store name to use the default data store.

The list of possible options in ihapi.h is listed in the Archiver Configuration Functions. Set an option value when the default does not meet the needs of your application or to confirm that no other application has changed it. Archive option changes are audited in the Historian messages and you can see them using ihMessageOpenRecordset call.

Returns

ihArchiverFreeOption

This function is used to free the memory inside the structure returned from an ihArchiveGetOption().

Prototype

ihArchiveFreeOption{

ihChar *OptionValue // the string returned from ihArchiveGetOption()

);

Remarks

Use this function to free the memory inside the structure. Do not free the fields in your code.

Returns

ihArchiveGetProperties

This function retrieves the properties for an archive in a data store identified by the ArchiveDescriptor.

Prototype

ihArchiveGetProperties (
ihServerHandle hServer, 

ihArchiveDescriptor *ArchiveDescriptor,

ihArchiveProperties *Archive
);

Remarks

You can pass NULL as the data store name to use the default data store.

The ihArchiveProperties contains information such as the StartTime and EndTime and size of the archive.

Make sure to free the archive properties using ihArchiveFreeProperties() function.

Returns

ihArchiveSetProperties

This function sets the properties for an archive.

Prototype

ihArchiveSetProperties {
ihServerHandle hServer,

ihArchiveProperties *Archive
);

Remarks

This is the only archive property set by a user program to make the archive read only.

ihArchiveFreeProperties

This function is used to free up the memory associated with the ArchiveProperties returned from an ihArchiveGetProperties call.

Prototype

ihArchiveFreeProperties {
ihArchiveProperties *ArchiveProperties
);

Remarks

Use this function to free the memory. Do not free the memory by calling operating system functions.

Returns

ihArchiveGetStatistics

This function is used to get performance statistics from the Data Archiver of a particular data store.

Prototype

ihArchiveGetStatistics {
ihServerHandle hServer, ihString DataStoreName, ihArchiveStatistics *Statistics
);

Remarks

This returns the performance statistics about data writes, failed writes, and disk space usage. To get the performance of a particular data store you need pass the data store name.

Returns

ihArchiveBackupResponse

This function is used by the Alarm Archiver only.

Prototype

ihArchiveBackupResponse
(
ihServerHandle hServer, ihCallbackId CallbackId, ihAPIStatus Status, ihBoolean FinalMessage
);

Remarks

None

Returns

None

ihArchiveRemoveResponse

This function is used by the Alarm Archiver only.

Prototype

ihArchiveRemoveResponse {
ihServerHandle hServer, ihCallbackId CallbackId, ihAPIStatus Status, ihBoolean FinalMessage
);

Remarks

None

Returns

None

ihConfigurationGetProperties

This function returns the configuration properties such as the Data Archiver version.

Prototype

ihConfigurationGetProperties {
ihServerHandle hServer, // server handle returned from previous call to ihServerConnect

ihConfigurationProperties *Properties // output parameter to contain the properties
);

ihConfigurationFreeProperties

This function is used to free the memory inside the structure.

Prototype

void ihConfigurationFreeProperties {
ihConfigurationProperties *Properties // pointer to the structure filled in by 
ihConfigurationGetProperties
);

Remarks

Use this function to free the memory inside the structure. Do not free the fields within your code.

Returns

ihArchiveBackup

This function is used to back up archive (.iha) files. If you are storing alarms and events data in Historian, an IHA backup also backs up any alarms.

Prototype

ihArchiveBackup {
ihServerHandle hServer, // server handle returned from previous call to ihServerConnect 

ihArchiveDescriptor *ArchiveDescriptor,

ihString BackupFileName

);

Remarks

This function is used to back up the archive (.iha) files residing on the server specified. The ArchiveDescriptor specifies the archive name that you want to add and the DataStore name to which it should be added. The BackupFileName has the backup of the IHA file with the name and the file location that you specified. For example: C:\Program Files\Historian Data\Archives\myarchive.iha.

Returns

ihArchiveBackupEx

This function is used to back up the archive (.iha) files and process Windows messages at the same time.

Prototype

ihArchiveBackupEx {
ihServerHandle hServer,// server handle returned from previous call to ihServerConnect 

ihArchiveDescriptor *ArchiveDescriptor,

ihString BackupFileName, long hWnd);

Remarks

This function is used to back up the archive (.iha) files residing on the server specified. The ArchiveDescriptor specifies the archive name that you want to add and the DataStore name to which it should be added. The BackupFileName has the backup of the IHA file with the name and the file location that you specified. For example: C:\Program Files\Historian Data\Archives\myarchive.iha.

Returns

ihArchiveRegisterBackupCallBack

This function is used to register a callback which should be called after the ihArchiveBackup() function completes. Archive backup can take several minutes. By using this callback, your System API program can know that the backup is complete.

Prototype

ihArchiveRegisterBackupCallBack {
ihServerHandle hServer, // server handle returned from previous call to ihServerConnect 

ihArchiveBackupCallbackFunction CallbackFunction,
void *UserParameter
);

Remarks

The register callback will be performed when the Archive backup is completed on Historian.

Returns

ihArchiveRemove

This function is used to delete or unload an archive file. You can unload a file if you no longer need it at the current time but may need it later or in another archive. You can delete a file if you do not expect to need it again or if you have made a backup.

Prototype

ihArchiveRemove {
ihServerHandle hServer, // server handle returned from previous call to ihServerConnect 

ihArchiveDescriptor *ArchiveDescriptor,

ihBoolean ShouldDeleteFile

)

Remarks

This function is used to delete or unload the archive file residing on the server specified. The ArchiveDescriptor specifies the archive name that you want to add and the DataStore name to which it should be added. ShouldDeleteFile determines whether the file should be deleted or not.

ihArchiveRemoveEx

This function is used to delete or unload the archive files and process Windows messages at the same time.

Prototype

ihArchiveRemoveEx {
ihServerHandle hServer, // server handle returned from previous call to ihServerConnect 

ihArchiveDescriptor *ArchiveDescriptor,

ihBoolean ShouldDeleteFile,

long hWnd
);

Remarks

This function is used to delete or unload the archive file residing on the server specified. The ArchiveDescriptor specifies the archive name that you want to add and the DataStore name to which it should be added. ShouldDeleteFile determines whether the file should be deleted or not.

The following are the scenarios which you can use with ihArchiveRemoveEX() function:

Returns

ihArchiveRegisterRemoveCallback

This function allows you to register a callback for removing an archive. This callback function is called when you remove the archive from Proficy Historian.

Prototype

ihArchiveRegisterRemoveCallback {
ihServerHandle hServer, // server handle returned from previous call to ihServerConnect 

ihArchiveRemoveCallbackFunction CallbackFunction,

void *UserParamter
);

Remarks

To register a function as a callback, you must have a callback or a function with the same signature as ihArchiveRemoveCallback function, and then pass it to ihArchiveRegisterRemoveCallback.

Returns

ihArchiveAdd

This function is used to create a new archive or load an existing one.

Prototype

ihArchiveAdd {
ihServerHandle hServer, // server handle returned from previous call to ihServerConnect 

ihArchiveDescriptor *ArchiveDescriptor,

ihString FileLocation, ihBoolean ShouldCreateFile,

ihUNSIGNED long FileSize
);

Remarks

This function is used to create or load the archive file residing on the server specified. The ArchiveDescriptor specifies the archive name that you want to add and the DataStore name to which it should be added. Then, specify the FileLocation. To determine whether the file should be created or not with the specified FileSize, use ShouldCreateFile.

Returns

ihArchiveAddEx

This function is used to create a new archive or load an existing one.

Prototype

ihArchiveAddEx {
ihServerHandle hServer, // server handle returned from previous call to ihServerConnect 

ihArchiveDescriptor *ArchiveDescriptor,

ihString FileLocation, 

ihBoolean ShouldCreateFile, 

ihUNSIGNED long FileSize, 

long hWnd

);

Remarks

This function is used to create or load the archive file residing on the server specified. The ArchiveDescriptor specifies the archive name that you want to add and the DataStore name to which it should be added. Then, specify the FileLocation. To determine whether the file should be created or not with the specified FileSize, use ShouldCreateFile.

Returns

ihArchiveRegisterLoadCallback

This function allows you to register a callback for adding an archive file. That registered callback is called when you add the archive file in Historian. It can take several minutes to load large archive files, so by using callbacks your System API program can be notified when the archives finish loading.

Prototype

ihArchiveRegisterLoadCallback {

ihServerHandle hServer, // server handle returned from previous call to ihServerConnect 

ihArchiveLoadCallbackFunction CallbackFunction,

void *UserParameter
);

Remarks

You need to have a callback or a function with the same signature as ihArchiveLoadCallback function, and then pass it to ihArchiveRegisterLoadCallback to register that function as a callback.

Returns

This function is used to add a user defined type.

Prototype

ihUserDefinedTypeAdd(

ihServerHandle hServer, // server handle returned from previous call to ihServerConnect 

ihUserDefinedTypeProperties *UserDefinedType, // structure containing the user defined type

ihString *ErrorMsg // output parameter to contain any error string if there is error. The memory, if there is an error,
will be allocated in the System API and should be freed using ihUserDefinedTypeFreeError
);

Remarks

If the set already exists, it is overwritten by this new set. You need to be an ihTagAdmin to add or modify a set. The memory, if there is an error, will be allocated in the System API and should be freed using ihUserDefinedTypeFreeErrorMessage.

Returns

ihUserDefineTypeDelete

This function is used to delete a user defined type.

Prototype

ihUserDefinedTypeDelete(

ihServerHandle hServer, // server handle returned from previous call to ihServerConnect

ihString UserDefinedTypeName, // the name of the user defined type. Any characters can be used other than * or ?

ihString *ErrorMsg // output parameter to contain any error string if there is error. The memory, if there is an error,
will be allocated in the System API and should be freed using ihUserDefinedTypeFreeError
);

Remarks

You need to be an ihTagAdmin to be able to delete a User Defined type. The memory, if there is an error, will be allocated in the System API and should be freed using ihUserDefinedTypeFreeErrorMessage.

ihUserDefinedTypeRename

This function is used to rename the existing user defined type name.

Prototype

ihUserDefinedTypeRename(

ihServerHandle hServer, // server handle returned from previous call to ihServerConnect 

ihString UserDefinedTypeName, // the current name of the user defined type

ihString NewUserDefinedTypeName // the new name
);

After you rename, the old name is available for reuse.

Returns

ihUserDefinedTypeExists

Use this function to check whether the user defined type exists or not.

Prototype

ihUserDefinedTypeExists(

ihServerHandle hServer, // server handle returned from previous call to ihServerConnect 

ihString UserDefinedTypeName // the name to check
);

ihUserDefinedTypeSetProperties

This function is used to set the user defined type properties.

Prototype

ihUserDefinedTypeSetProperties(

ihServerHandle hServer, // server handle returned from previous call to ihServerConnect 

ihUserDefinedTypeProperties *UserDefinedType, // the name and properties to set

ihString *ErrorMsg // output parameter to contain any error string if there is error. The memory, if there is a
an error, will be allocated in the System API and should be freed using ihUserDefinedTypeFreeError
);

Remarks

You need to be an ihTagAdmin to set the properties. The memory, if there is an error, will be allocated in the System API and should be freed using ihUserDefinedTypeFreeErrorMessage.

Returns

ihUserDefinedTypeGetProperties

This function returns the user defined type properties.

Prototype

ihUserDefinedTypeGetProperties(

ihServerHandle hServer, // server handle returned from previous call to ihServerConnect 

ihString UserDefinedTypeName , // the name of the custom data type

ihUserDefinedTypeProperties *UserDefinedType // output parameter containing the returned properties. The return
);

Remarks

You need to be an ihTagAdmin to get the properties.

Returns

ihUserDefinedTypeFreeProperties

This function is used to free the memory allocated by the ihUserDefinedTypeGetProperties() call.

Prototype

void ihUserDefinedTypeFreeProperties(

ihUserDefinedTypeProperties *UserDefinedTypeProps // properties as returned from an 
ihUserDefinedTypeGetProperties call
);

Remarks

You need to call this once to free all memory in the recordset. Do not free the memory in your program.

Returns

ihUserDefinedTypeOpenRecordset

This function is used to return the list of user defined types.

Prototype

ihUserDefinedTypeOpenRecordset(

ihServerHandle hServer, // server handle returned from previous call to ihServerConnect 

ihString Mask, // * or specific set name or some other mask to specify the list

ihUserDefinedTypeRecordset *RecordSet // output parameter to contain the returned list. The list should be
freed with ihUserDefinedTypeFreed when done using the ihUserDefinedTypeCloseRecordset()
);

Remarks

You need to specify the user defined type set name to open the recordset. This function call should be freed after the retrieval using ihUserDefinedTypeCloseRecordset.

Returns

ihUserDefinedTypeCloseRecordset

This function used to free the user defined type recordset that was allocated inside the System API in a previous read call.

Prototype

void ihUserDefinedTypeCloseRecordset(

ihUserDefinedTypeRecordset *Recordset // recordset to be freed
);

Returns

ihUserDefinedTypeFreeErrorMessage

This function is used to free the memory from the previous error message call.

Prototype

ihUserDefinedTypeFreeErrorMessage(

ihString ErrorMsg // string to be freed as returned from a previous call
);

Returns

ihTimeLCLPartsToUTCStructEx

This function returns timestamps that can be used in read and write functions.

ihTimeLCLPartsToUTCStructEx {

ihServerHandle hServer, // server handle returned from previous call to ihServerConnect or just pass 
ihINVALID_HANDLE if not using server time zone
int Year, // the 4 digit year such as 1998 or 2004 in the local time zone 
int Month, // the month 1 (January) to 12 (December) in the local time zone 
int Day, // the day 1 to 31 in the local time zone
int Hour, // the hour 0 to 23 in the local time zone
int Minute, // the minute 1 to 59 in the local time zone 
int Second, // the second 1 to 59 in the local time zone
int MilliSecond, // the millisecond 0 to 999 in the local time zone 
ihTimeZones TimeZoneFlag, // client or server or explicit timezone 
int TimeZoneBiasExplicit, // only used if TimeZoneFlag is explicit
int DaylightSavingsTime, // TRUE if you want to use the Daylight Saving Time setting in Control Panel, 
FALSE if you want to never use Daylight Saving Time.
ihTimeStruct *Time // the output parameter containing the converted timestamp
);

Remarks

Use this function to return timestamps to be used in data read and write functions for start and end time of queries. The function takes a server handle however, you need not be connected to the server unless you specify the TimeZoneFlag as server time zone. If you are just using timestamps in local time zone you can use ihTimeLCLPartsToUTCStruct().

Returns

ihTimeUTCStructToLCLPartsEx

This function is used to convert the timestamps returned by System API into your local time zone.

void ihTimeUTCStructToLCLPartsEx {
ihServerHandle hServer, // server handle returned from previous call to ihServerConnect or just pass 
ihINVALID_HANDLE if not using server time zone
int *Year, // output parameter to contain the 4 digit year
int *Month, // output parameter to contain the month 1 to 12
int *Day, // output parameter to contain the day 1 to 31
int *Hour, // output parameter to contain the hour 0 to 23
int *Minute, // output parameter to contain the minute 0 to 59 
int *Second, // output parameter to contain the second 0 to 59
int *MilliSecond, // output parameter to contain the milliseconds 0 to 999
ihTimeZones TimeZoneFlag, // client or server or explicit timezone
int TimeZoneBiasExplicit, // only used if TimeZoneFlag is explicit
int DaylightSavingsTime, // TRUE if you want to use the Daylight Saving Time setting in Control Panel, 
FALSE if you want to never use Daylight Saving Time. 
ihTimeStruct *UTCTime // the timestamp to be converted

);

Remarks

Use this function to convert timestamps returned by the System API into your local time zone for display. The function takes a server handle however, you need not be connected to the server unless you specify the TimeZoneFlag as server time zone. If you are just using client time zone you can use ihTimeUTCStructToLCLParts().

Returns

ihTimeCurrentUTCStruct

This function returns the current time stamp as UTC. You can add and subtract seconds from this time to read and write data with timestamps relative to now.

Prototype

void ihTimeCurrentUTCStruct {
ihTimeStruct *UTCTime // output parameter containing the current time
);

Remarks

Use this function to get the current time so that you can use it in other System API functions such as the end time of a query or the timestamp of a data write.

Returns

ihUtilAnsiToUnicode

This function is used to convert Unicode string to ANSI format which can be used by API applications and other programs.

Prototype

ihUtilAnsiToUnicode {
char *MBStr, // the non Unicode string
ihChar *WCStr // the output buffer to contain the converted Unicode string
);

Remarks

Use this function if you want to convert any Unicode string returned by the System API to ANSI format that can be used by other API application and programs.

You must allocate the buffer for the Unicode string. Allocate a large enough buffer as System API does not validate the length.

Returns

ihUtilUnicodeToAnsi

This function is used to convert ANSI strings to Unicode in order to pass them into System API functions.

Prototype

ihUtilUnicodeToAnsi {
char *MBStr,ihChar *WCStr
);

Use this function to convert ANSI strings to Unicode for passing them into the System API connect or read or write functions and so on.

You must allocate the buffer for the ANSI string. Allocate a large enough buffer as System API does not validate the length.

Returns

ihUtilErrorDesc

This function returns a string for a numeric error code. The string is not translated into other languages.

ihUtilErrorDesc {
ihStatus ErrorNum, // the error number
ihString ErrorDesc, // the output parameter to contain the string 
int Len // the length of the output buffer
);

Remarks

This utility function returns an English language string for a numeric error code if you don???t want to provide your own.

Returns

Time Functions

ihTimeLCLPartsToUTCStruct

Use this function to convert Local Date/Time Parts to Universal Time Coordinated Structure.

Prototype

ihTimeLCLPartsToUTCStruct {
int Year,
int Month, 
int Day,
int Hour,
int Minute,
int Second,
int MilliSecond,
ihTimeStruct *UTCTime};

Remarks

The System API functions that read and write data require timestamps to be in GMT+0 timezone. This function can be used to convert your local timestamps into a format that can be passed into other System API functions such as ihDataAdd.

Enter your timestamp in the first 6 parameters and the converted timestamp gets returned in the UTC Time parameter. The time that you enter should be in the timezone of the system that is running your program. If you need additional control of the time zone and Daylight Saving Time parameters then use the ihTimeLCLPartsToUTCStructEx function.

Returns

ihTimeUTCStructToLCLParts

Use this function to convert Universal Time Coordinated (UTC) time zone structure to Local Date/Time parts.

ihTimeUTCStructToLCLParts { 
int *Year,
int *Month, 
int *Day, 
int *Hour, 
int *Minute, 
int *Second,
int *MilliSecond,
ihTimeStruct *UTCTime
};

Remarks

Enter your timestamp in as the UTCTime parameter and the converted timestamp is returned in the first 6 parameters. For example the samples returned from an ihDataOpenRecordset have timestamps that can be converted with this function.

The hours and minutes and seconds will be returned in the timezone of the system running your program. If you need additional control over the time zone or Daylight Saving Time parameters then use the ihTimeUTCStructToLCLPartsEx function.

Returns

ihTimeUTCStructToFileTime

Use this function to convert UTC structure to FILETIME.

Prototype

ihTimeUTCStructToFileTime { 
ihTimeStruct *UTCTime,
void *FileTime
};

Remarks

Use this function to convert Historian UTC timestamps into a FILETIME that could be passed into other Microsoft Windows functions.

Returns

ihTimeLCLFileTimeToUTCStruct

Use this function to convert FILETIME (LOCAL) to UTC structure.

Prototype

ihTimeLCLFileTimeToUTCStruct {
void *FileTime, ihTimeStruct *UTCTime
};

Remarks

If you got a FILETIME from some Microsoft Windows call, use this function to convert it to a format that can be used by other System API functions. The FILETIME is assumed to be in UTC timezone. ??If the FILETIME is in local time then use the ihTimeLCLFileTimeToUTCStruct function.

Returns

Query Modifiers Functions

ihQueryModifiersAssign

Use this function to clear the previously assigned modifiers and then set new modifiers.

Prototype

ihQueryModifiersAssign {
ihQueryModifiers *Modifiers, int NumModifiers, ...
};

Returns

This function would not be called by a user program.

ihQueryModifiersClear

Use this function to clear the modifiers.

Prototype

ihQueryModifiersClear {
 ihQueryModifiers *Modifiers
};

Remarks

This function would not be called by a user program.

Returns

ihQueryModifiersSet

Use this function to add a modifier to a mask of modifiers.

Prototype

ihQueryModifiersSet {
ihQueryModifiers *Modifiers, ihQueryModifier Modifier
};

Remarks

Use this function to add a querymodifer to a mask of modifiers that would then be passed into a data read call. The set of available modifiers is available in the ihQueryModifier enumeration.

Returns

ihQueryModifiersIsSet

Use this function to check whether the specified modifier is already present in the modifier mask.

Prototype

ihQueryModifiersIsSet {
ihQueryModifiers *Modifiers, ihQueryModifier Modifier
};

Remarks

You can use this function to prepare a query modifier mask which can then be passed to a data read call.

Returns

ihQueryModifierOpenRecordset

Use this function to get a list of possible query modifiers from the destination archiver. Older versions of Historian might support fewer modifiers than the version your program is running on.

Prototype

ihQueryModifierOpenRecordset {
ihServerHandle hServer, ihQueryModiferRecordset *QueryModiferRecordset
};

You should use this function if your program can be communicating with older Data Archivers to ensure your query modifier is available.

Free the returned recordset using the ihQueryModifierCloseRecordset function.

Returns

ihQueryModifierCloseRecordset

Use this function to free memory returned from ihQueryModifierOpenRecordset.

Prototype

ihQueryModifierCloseRecordset { ihQueryModiferRecordset *RecSet };

Remarks

Returns

ihDataCriteriaFromString

Use this function to build a data criteria from the criteria string.

Prototype

ihDataCriteriaFromString {
ihServerHandle hServer, ihDataCriteria *Criteria, ihString CriteriaString
};

Remarks

This function would not be called by a user program.

Returns

DataStore Functions

ihDataStoreAdd

Use this function to create additional data stores if your license allows it.

Prototype

ihDataStoreAdd { ihServerHandle hServer,
ihString DataStoreName, 
ihBoolean   IsDefault, 
ihString Description,
ihDataStorageType StorageType
};

Remarks

Some data stores are created automatically when the Data Archiver is started. Use this function if you need to create additional ones. The number of data stores is licensed on your key.

Returns

ihDataStoreDelete

Use this function to delete a data store on the specified Data Archiver.

Prototype

ihDataStoreDelete {
ihServerHandle hServer, ihString DataStoreName
};
 

Remarks

You can only delete a data store if all tags have been removed from it. You cannot delete the System data store.

Returns

ihDataStoreRename

Use this function to rename an existing data store.

Prototype

ihDataStoreRename {
ihServerHandle hServer, ihString DataStoreName, ihString NewDataStoreName
};

Remarks

Once the data store is renamed it can only be referred to by its new name.

You must be a member of the ihArchive Admin security group to perform renames.

Returns

ihDataStoreOpenRecordset

Use this function to get the details of the configured data stores on the specified Data Archiver.

Prototype

ihDataStoreOpenRecordset {
ihServerHandle hServer, ihString DataStoreMask, ihDataStoreRecordset *Recordset
};

Remarks

You can specify a name mask or just pass NULL or ???r;* to get all data stores.

Free the returned list using the ihDataStoreCloseRecordset function.

Returns

ihDataStoreCloseRecordset

Use this function to free the memory in the list returned from ihDataStoreOpenRecordset.

Prototype

ihDataStoreCloseRecordset { 
ihDataStoreRecordset *Recordset

};

Remarks

Use this function to free the memory, do not use Microsoft Windows calls to free the memory.

Returns

ihDataStoreSetProperties

Use this function to set or change properties of an existing data store. You use ihArchiverSetOption to set options and use this function to indicate a data store is the default or to set the description.

Prototype

ihDataStoreSetProperties {
ihServerHandle hServer,
ihString DataStoreName, 
ihBoolean IsDefault,
ihString Description,
ihDataStorageType StorageType
};

Remarks

Most data store configuration will be done by setting options but this function is available if you need to change the default data store.

Returns

Security Functions

ihSecurityGroupOpenRecordset

Use this function to get the list of security groups that exist in the operating system where the Data Archiver is running. This can be a different list than where your client program is running.

All security groups would be returned, not just the specific ihSecurity Admins, ihTag Admins, and so on. You must free the returned recordset using the ihSecurityGroupCloseRecordset call.

Prototype

ihSecurityGroupOpenRecordset {
ihServerHandle hServer, ihSecurityGroups *Grps
};

Remarks

To know the list of security groups while setting up a tag to use tag level security, use this function call to give you the name of any groups that exist at the archiver. And when you assign that name to a tag read security group, then the Data Archiver will check that group when the tag is read. This is why you need the list of groups at the Data Archiver and not at the client PC, because the Data Archiver should be able to access the group and its members.

All security groups would be returned, not just the specific ih Security Admins, ih Tag Admins, and so on.

You must free the returned recordset using the ihSecurityGroupCloseRecordset call.

Returns

ihSecurityGroupCloseRecordset

Use this function to free the list returned from a ihSecurityGroupOpenRecordset call.

Prototype

ihSecurityGroupCloseRecordset {
ihSecurityGroups *Grps
};

Remarks

Use this function instead of freeing the memory via operating system calls.

Returns

ihSecurityGetOption

Use this function to get the value of security options from the specified Data Archiver.

Prototype

ihSecurityGetOption {
ihServerHandle hServer, ihOption Option, ihChar **OptionValue
};

Remarks

You could get the value of security related options such as ihSecurityStrictClientAuthentication or ihSecurityStrictCollectorAuthentication.

You need to be a member of ih Readers security group to be able to get

options.

Returns

ihSecurityFreeOption

Use this function to free the memory returned by a previous ihSecurityGetOption call.

Prototype

ihSecurityFreeOption{
ihChar *OptionValue
};

Remarks

Use this function to free the option value. Do not free the memory using operating system calls.

Returns

ihSecurityGetmemberships

Use this function on an established connection to determine what Proficy Historian security groups that the Data Archiver considers you a member of. This will determine what permissions you have within Historian.

Prototype

ihSecurityGetmemberships {
ihServerHandle hServer, ihSecurityGrpMembership *Memberships
};

Remarks

Group memberships are established at connect time. If groups are created or your account is added to groups then you need to disconnect and connect again to get the correct level of permissions.

Returns