System API Functions

Important: You do not have the latest version of Historian! You are missing out on the newest capabilities and enhanced security. For information on all the latest features, see the Historian product page. For more information on upgrades, contact your GE Digital sales agent or e-mail GE Digital Sales Support. For the most up-to-date documentation, go here.

System API Connect Functions

This section provides detailed information about each available System API function. Use this information together with the sample programs provided to develop your own applications. The System API functions are grouped as follows:

Not every function and structure in the ihapi.h is documented or available for use in user written pro- grams. Please limit your programs to the documented functions or contact the Technical Support team at GE Intelligent Platforms for additional clarifications.

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

This function establishes the connection with the Historian server.
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

Returns Status Message
ihSTATUS_OK On success.
ihSTATUS_API_TIMEOUT If the server name or IP address provided cannot be located.
ihSTATUS_LIC_TOO_MANY_USERS If this connection would exceed your licensed number of connections.
ihSTATUS_NOT_VALID_USER If the user is not allowed to connect. This can happen whether you provided a username or connected as the process owner. Consult the Historian documentation for security behavior.
ihSTATUS_FAILED For any other type of error.

ihServerDisconnect

Use this function to disconnect from the Historian server.

Prototype
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

Returns Status Message
ihSTATUS_OK On success.

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

Returns Status Message
ihSTATUS_OK On success.
ihSTATUS_FAILED On failure.

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

Returns Status Message
TRUE

if you are currently successfully connected.

FALSE

if you were never connected or if the connection is currently down and being re-established.

ihServerGetTimeout

This function is used to return the messaging timeout value of the server connection identified by ihServer.
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

Returns Status Message
ihSTATUS_OK On success
ihSTATUS_FAILED On failure

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

Returns Status Message
ihSTATUS_OK On success and the desired information can be read from the output parameters.
ihSTATUS_FAILED On failure.

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

Returns Status Message
ihSTATUS_OK On success and the desired information can be read from the output parameter.
ihSTATUS_API_TIMEOUT If the call could not be completed.
ihSTATUS_NOT_CONNECTED When not currently connected to the Data Archiver.
ihSTATUS_FAILED When the other three return options otherwise do not apply.

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

Returns Status Message
ihSTATUS_OK On success and the desired information can be read from the output parameter.
ihSTATUS_FAILED On failure

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

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.

You can refer to a tag in the following ways:
  • 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 a tagname. If your tagnames are typically longer than 128 characters then using the tagid 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

Read and Write Functions

Data reading and writing is a key part of Historian functionality. There are many rules and best practices and many use cases that are not all documented here. With the following documentation you will see how to write raw values and read them back as raw values and then how to instruct the Data Archiver to perform calculations on the raw samples and return the result.

The method to pass filter parameters and query modifiers is shown but not the meaning of those parameters. Store and forward buffering is available for data writes but is an advanced topic not demonstrated here.

The Read and Write functions are:

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:

Returns Status Message
ihSTATUS_OK The data sample was successfully written.
ihSTATUS_API_TIMEOUT If the client program did not receive a return code before the timeout expired. This does not necessarily mean the write was not performed at the archiver, only that the client did not receive a response.
ihSTATUS_NOT_CONNECTED If you are not currently connected to the Data Archiver.
ihSTATUS_WRITE_IN_FUTURE If you specified a timestamp that was more than 15 minutes ahead of the Data Archiver PC clock. The Data Archiver will not accept writes that are too far into the future because it has no data file to hold them.
ihSTATUS_DUPLICATE_DATA If you set ErrorOnReplace to TRUE and you would have overwritten data.
ihSTATUS_WRITE_ARCH_OFFLINE If you wrote to a time period that has no archive.
ihSTATUS_ARCH_READONLY If the archive covering the timestamp written is set to read only in the Historian Administrator
ihSTATUS_ACCESS_DENIED If you are not allowed to write data to this tag and timestamp. Under most conditions, writes from user programs are allowed. But if you receive this error consider the following scenarios:
  • Your account is not a member of ihAuditedWriters or ihUnaudited Writers group.
  • The tag you are writing has tag level security enabled.
  • The entire archive is set to read only in the Historian Administrator.
The tag you are writing has tag level security enabled. The entire archive is set to read only in the Historian Administrator.
ihSTATUS_WRITE_OUTSIDE_ACTIVE The timestamp on the data sample is older than the data is read only"
ihSTATUS_INVALID_TAGNAME The tagname you wrote to does not exist in the Data Archiver configuration.
ihSTATUS_FAILED For any other type of error.

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

Returns Status Message
ihSTATUS_OK The data sample was successfully deleted.
ihSTATUS_API_TIMEOUT If the client program did not receive a return code before the timeout expired. This does not necessarily mean the write was not performed at the archiver, only that the client did not receive a response.
ihSTATUS_NOT_CONNECTED If you are not currently connected to the Data Archiver
ihSTATUS_WRITE_ARCH_OFFLINE If you wrote to a time period that has no archive.
ihSTATUS_ACCESS_DENIED If you are not allowed to write data to this tag and timestamp. Under most conditions, writes from user programs are allowed. But if you receive this error consider the following scenarios:
  • The tag you are writing has tag level security enabled.
  • The entire archive is set to read only in the Historian Administrator.
The tag you are writing has tag level security enabled. The entire archive is set to read only in the Historian Administrator.
ihSTATUS_WRITE_OUTSIDE_ACTIVE The timestamp on the data sample is older than the data is read only"
ihSTATUS_FAILED For any other type of error.

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 typ- ically 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 tags 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

Returns Status Message
ihSTATUS_OK The data sample was successfully read.
ihSTATUS_API_TIMEOUT The client program did not receive a portion of the returned values before the timeout expired. Large reads 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 read can take several minutes or more, 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 read data:
  • The tag you are reading has tag level security enabled.
  • You are not a member of the ihReaders security group. .
The tag you are writing has tag level security enabled. The entire archive is set to read only in the Historian Administrator.
ihSTATUS_WRITE_OUTSIDE_ACTIVE The timestamp on the data sample is older than the data is read only"
ihSTATUS_FAILED For any other type of error.

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

Returns Status Message
VOID Void

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

Returns Status Message
VOID Void

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
);
Remarks

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.

For Examples, refer Sample Programs section.
Returns Status Message
ihSTATUS_OK if the data was successfully read.
ihSTATUS_API_TIMEOUT

if the client program did not receive a portion of the returned values before the timeout expired. Large reads 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 read can take several minutes or more, 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_FAILED

For any other type of error.

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

Returns Status Message
ihSTATUS_OK The data sample was successfully read.
ihSTATUS_ACCESS_DENIED If you are not allowed to add or modify tags, or you are not a member of the ihReaders security group.
ihSTATUS_FAILED If the tag does not exist.

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

Returns Status Message
VOID Void

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.

For Examples, refer to the Sample Programs section.
Returns Status Message
ihSTATUS_OK The data sample was successfully read.
ihSTATUS_API_TIMEOUT The client program did not receive a portion of the returned values before the timeout expired. Large reads 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 read can take several minutes or more, 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_FAILED For any other type of error.

ihDataOpenMultiRecordset

This function is used if you need to do a single read but use different sampling or calculation modes or different start and end times.
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

Returns Status Message
ihSTATUS_OK The data sample was successfully read.
ihSTATUS_API_TIMEOUT The client program did not receive a portion of the returned values before the timeout expired. Large reads 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 read can take several minutes or more, 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 read data.
  • The tag you are reading has tag level security enabled.
  • You are not a member of the ihReaders security group
ihSTATUS_DATA_RETRIEVAL_COUNT_EXCEEDED If the read exceeded the Max Query Time or Max Query Intervals configured in Historian Administrator.
ihSTATUS_FAILED For any other type of error.

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

Returns Status Message
VOID Void

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

Returns Status Message
VOID Void

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
);
This returns the performance statistics about data writes, failed writes, and disk space usage.
Returns Status Message
ihSTATUS_OK If the option was successfully read
ihSTATUS_API_TIMEOUT If the option could not be read and you can try again later
ihSTATUS_NOT_CONNECTED If you are not currently connected to the Data Archiver
ihSTATUS_FAILED For any other type of error.

Archiver Configuration Functions

You can add and configure tags as part of Data Archiver configuration but there are other options that can be configured.

A subset of all the options and their meanings is given in this section, and the rest are listed in the ihapi.h file.

Most options are set as per data store and some are applicable for the overall Data Archiver.

Menu ihOptions

Option Description
ihArchiveDefaultPath The default path for new archive creations.
ihArchiveActiveHours Set to a larger number if you need to write data with timestamps in the past older than the "data is read only aftersetting in the Historian Administrator.
ihArchiveDefaultSize The default size for new archives, when you are not using ihArchiveDuration for time based archives.
ihArchiveAutomaticCreate, TRUE if new archives should be created or FALSE if old archives should be reused instead.
ihArchiveAutomaticFreeSpace The amount of disk space to be left free.
ihArchiveOverwriteOld TRUE if you should overwrite old archives instead of refusing incoming data.
ihArchiveDefaultBaseFileName The default base file name which typically matches the computer name but you can update this if you move the Data Archiver to a new computer.
ihArchiveDefaultBaseArchiveName The default base file name which typically matches the computer name but you can update this if you move the Data Archiver to a new computer.
ihArchiveDefaultBackupPath The default location for archive backups; typically this location is the same location as the online archives.
ihArchiveCreateOfflineArchive Set to TRUE if you need to write data with a timestamp before the first archive so that an archive gets created.
ihMessageOnDataUpdate Set to TRUE if you want an audit trail message for every data sample that is overwritten.
ihArchiverNumReadThreads Increase from default if you need more read threads so that you can perform parallel reads.
ihSecurityUseLocalGroups Set to FALSE if you want to use domain security groups.
ihArchiverMaxIntervalRetrievalCount Increase this number if you typically do large queries that return error ihSTATUS_DATA_RETRIEVAL_COUNT_EXCEEDED.
ihArchiverMaxQueryTime Increase this number if you typically do large queries that return error ihSTATUS_DATA_RETRIEVAL_COUNT_EXCEEDED.
ihArchiverMaintainAutoRecoveryFiles Set to FALSE if you do not want to use this feature.
ihArchiverAllowDataOverwrites Set to FALSE if you dont want to allow accidental or intentional data overwrites.
ihArchiverTargetPrivateBytes Leave as 0 for system managed unless you have a specific target.
ihArchiverNumWriteThreads Leave as default value.
ihSecurityStrictClientAuthentication True to only permit SSPI-based authentication.
ihSecurityStrictCollectorAuthentication True to only permit collector connections from 5.0 and and above.
ihArchiveTotalDuration Number of Hours that the archives for a DataStore can span (only used for trending DataStores).
ihArchiveDurationType The type of archive duration. It is the integer value of ihArchiveDurationType.
ihArchiveDuration Number of Units of time an archive can hold. Defined by ihArchiveDurationType.
StructFieldsInBrowsesByDefault TRUE if you want each field of a structure to appear as its own tag during tag browse. Useful for legacy clients that are not aware of structures.
ihOptionMax The highest option number for this version of historian. Use this to check for invalid option values.

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

Returns Status Message
ihSTATUS_OK On success.
ihSTATUS_API_TIMEOUT If the option could not be read. You can try again later.
ihSTATUS_NOT_CONNECTED If you are not currently connected to the Data Archiver.
ihSTATUS_FAILED For any other type of error.

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

Returns Status Message
Void Void

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

Returns Status Message
ihSTATUS_OK On success.
ihSTATUS_API_TIMEOUT If the option could not be read. You can try again later.
ihSTATUS_NOT_CONNECTED If you are not currently connected to the Data Archiver.
ihSTATUS_FAILED For any other type of error.

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

Returns Status Message
ihSTATUS_OK On success.
ihSTATUS_API_TIMEOUT If the option could not be read. You can try again later.
ihSTATUS_NOT_CONNECTED If you are not currently connected to the Data Archiver.
ihSTATUS_FAILED For any other type of error.

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

Returns Status Message
Void Void.

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

Returns Status Message
ihSTATUS_OK On success.
ihSTATUS_API_TIMEOUT If the option could not be read. You can try again later.
ihSTATUS_NOT_CONNECTED If you are not currently connected to the Data Archiver.
ihSTATUS_FAILED For any other type of error.

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.

Returns Status Message
ihSTATUS_OK On success.
ihSTATUS_API_TIMEOUT If the option could not be read. You can try again later.
ihSTATUS_NOT_CONNECTED If you are not currently connected to the Data Archiver.
ihSTATUS_FAILED For any other type of error.

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

Returns Status Message
Void Void.

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

Returns Status Message
ihSTATUS_OK On success.
ihSTATUS_API_TIMEOUT If the option could not be read. You can try again later.
ihSTATUS_NOT_CONNECTED If you are not currently connected to the Data Archiver.
ihSTATUS_FAILED For any other type of error.

ihArchiveBackupResponse

This function is used by the Alarm Archiver only.

Prototype

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

ihArchiveRemoveResponse

Remarks

None

Returns

None

This function is used by the Alarm Archiver only.

Prototype

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

ihConfigurationGetProperties

Remarks

None

Returns

None

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

Returns Status Message
Void Void.

Archiver Backup/Restore Functions

You can use Archive Backup/Restore functions to backup archive data.

There are synchronous and asynchronous calls for loading archives, making a backup and removing an archive. The synchronous functions are typically used for smaller archives because the operation completes in a few seconds. The asynchronous functions are typically used for larger archives because the operation can takes longer, one minute or more, to complete.

Archive Backup/Restore functions are as follows:

ihArchiveBackup

This function is used to back up archive (.iha) files. If you are storing Alarms and Events 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

Returns Status Message
ihSTATUS_OK If the option was successfully read.
ihSTATUS_ACCESS_DENIED If you are not allowed to perform the operations. For most options you need to be a member of the ihArchiveAdmins group
ihSTATUS_API_TIMEOUT If the option could not be read. You can try again later.
ihSTATUS_NOT_CONNECTED If you are not currently connected to the Data Archiver.
ihSTATUS_FAILED For any other type of error.

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

Returns Status Message
ihSTATUS_OK If the option was successfully read.
ihSTATUS_ACCESS_DENIED If you are not allowed to perform the operations. For most options you need to be a member of the ihArchiveAdmins group
ihSTATUS_API_TIMEOUT If the option could not be read. You can try again later.
ihSTATUS_NOT_CONNECTED If you are not currently connected to the Data Archiver.
ihSTATUS_FAILED For any other type of error.

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

Returns Status Message
ihSTATUS_OK If the option was successfully read.
ihSTATUS_ACCESS_DENIED If you are not allowed to perform the operations. For most options you need to be a member of the ihArchiveAdmins group
ihSTATUS_API_TIMEOUT If the option could not be read. You can try again later.
ihSTATUS_NOT_CONNECTED If you are not currently connected to the Data Archiver.
ihSTATUS_FAILED For any other type of error.

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.

The following are the scenarios which you can use with ihArchiveRemove() function:
If ShouldDeleteFile is: ZipRegistry enabled Zip successful Then...
TRUE YES YES Archive file is deleted.
TRUE YES NO The archive file is not deleted but unloaded.
FALSE YES YES The archive file is not deleted.
FALSE YES NO The archive file is not deleted.
Returns
Returns Status Message
ihSTATUS_OK If the option was successfully read.
ihSTATUS_ACCESS_DENIED If you are not allowed to perform the operations. For most options you need to be a member of the ihArchiveAdmins group
ihSTATUS_API_TIMEOUT If the option could not be read. You can try again later.
ihSTATUS_NOT_CONNECTED If you are not currently connected to the Data Archiver.
ihSTATUS_FAILED For any other type of error.

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:

If ShouldDeleteFile is: ZipRegistry enabled Zip successful Then...
TRUE YES YES Archive file is deleted.
TRUE YES NO The archive file is not deleted but unloaded.
FALSE YES YES The archive file is not deleted.
FALSE YES NO The archive file is not deleted.

Returns

Returns Status Message
ihSTATUS_OK If the option was successfully read.
ihSTATUS_ACCESS_DENIED If you are not allowed to perform the operations. For most options you need to be a member of the ihArchiveAdmins group
ihSTATUS_API_TIMEOUT If the option could not be read. You can try again later.
ihSTATUS_NOT_CONNECTED If you are not currently connected to the Data Archiver.
ihSTATUS_FAILED For any other type of error.

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

Returns Status Message
ihSTATUS_OK If the option was successfully read.
ihSTATUS_ACCESS_DENIED If you are not allowed to perform the operations. For most options you need to be a member of the ihArchiveAdmins group
ihSTATUS_API_TIMEOUT If the option could not be read. You can try again later.
ihSTATUS_NOT_CONNECTED If you are not currently connected to the Data Archiver.
ihSTATUS_FAILED For any other type of error.

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

Returns Status Message
ihSTATUS_OK If the option was successfully read.
ihSTATUS_ACCESS_DENIED If you are not allowed to perform the operations. For most options you need to be a member of the ihArchiveAdmins group
ihSTATUS_API_TIMEOUT If the option could not be read. You can try again later.
ihSTATUS_NOT_CONNECTED If you are not currently connected to the Data Archiver.
ihSTATUS_FAILED For any other type of error.

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

Returns Status Message
ihSTATUS_OK If the option was successfully read.
ihSTATUS_ACCESS_DENIED If you are not allowed to perform the operations. For most options you need to be a member of the ihArchiveAdmins group
ihSTATUS_API_TIMEOUT If the option could not be read. You can try again later.
ihSTATUS_NOT_CONNECTED If you are not currently connected to the Data Archiver.
ihSTATUS_FAILED For any other type of error.

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

Returns Status Message
ihSTATUS_OK If the option was successfully read.
ihSTATUS_ACCESS_DENIED If you are not allowed to perform the operations. For most options you need to be a member of the ihArchiveAdmins group
ihSTATUS_API_TIMEOUT If the option could not be read. You can try again later.
ihSTATUS_NOT_CONNECTED If you are not currently connected to the Data Archiver.
ihSTATUS_FAILED For any other type of error.

User Defined Type Functions

User defined data types should be added to the Data Archiver before they can be used in tags. The User defined type functions are as follows:

ihUserDefinedTypeAdd

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

Returns Status Message
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 the user defined types, perhaps you are not a member of the ihTagAdmins group.
ihSTATUS_FAILED For any other type of error.

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.

Returns Status Message
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 the user defined types, perhaps you are not a member of the ihTagAdmins group.
ihSTATUS_FAILED For any other type of error.

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
);
Remarks

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

Returns

Returns Status Message
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 the user defined types, perhaps you are not a member of the ihTagAdmins group.
ihSTATUS_FAILED For any other type of error.

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
);
Returns Status Message
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 the user defined types, perhaps you are not a member of the ihTagAdmins group.
ihSTATUS_FAILED For any other type of error.

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

Returns Status Message
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 the user defined types, perhaps you are not a member of the ihTagAdmins group.
ihSTATUS_FAILED For any other type of error.

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

Returns Status Message
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 the user defined types, perhaps you are not a member of the ihTagAdmins group.
ihSTATUS_FAILED For any other type of error.

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

Returns Status Message
Void Void.

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

Returns Status Message
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 the user defined types, perhaps you are not a member of the ihTagAdmins group.
ihSTATUS_FAILED For any other type of error.

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

Returns Status Message
Void Void.

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

Returns Status Message
Void Void.

Utility Functions

Utility functions help you to make use of the other System API calls such as data read and write and connect. Utility Functions are as follows:

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

Returns Status Message
ihuSTATUS_OK On success.

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

Returns Status Message
Void Void.

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

Returns Status Message
Void Void.

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

Returns Status Message
Void Void.

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
);
Remarks

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

Returns Status Message
Void Void.

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 dont want to provide your own.

Returns

Returns Status Message
Void Void.

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

Returns Status Message
Void Void.

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

Returns Status Message
ihSTATUS_OK On Success.
ihSTATUS_FAILED

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

Returns Status Message
ihSTATUS_OK On success.
ihSTATUS_FAILED For any other type of error.

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

Returns Status Message
1 On success.
0 Any type of error.

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.

Returns Status Message
Void Void.

ihQueryModifiersClear

Use this function to clear the modifiers.

Prototype

ihQueryModifiersClear {
 ihQueryModifiers *Modifiers
};

Remarks

This function would not be called by a user program.

Returns

Returns Status Message
Void Void.

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

Returns Status Message
Void Void.

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

Returns Status Message
True The modifier has already been added to the task.
False Otherwise.

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
};
Remarks

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

Returns Status Message
ihSTATUS_OK On success.
ihSTATUS_FAILED For any other type of error.

ihQueryModifierCloseRecordset

Use this function to free memory returned from ihQueryModifierOpenRecordset.

Prototype

ihQueryModifierCloseRecordset { ihQueryModiferRecordset *RecSet };

Remarks

Use this function and do not call any Microsoft Windows functions to free the memory.

Returns

Returns Status Message
Void Void

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

Returns Status Message
None None

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

Returns Status Message
ihSTATUS_OK On success.
ihSTATUS_NOT_PERMITTED If adding the data store would exceed your licensed count.
ihSTATUS_FAILED For any other type of error.

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

Returns Status Message
ihSTATUS_OK On success.
ihSTATUS_FAILED For any other type of error.

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

Returns Status Message
ihSTATUS_OK On success.
ihSTATUS_FAILED For any other type of error.

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

Returns Status Message
ihSTATUS_OK On success.
ihSTATUS_FAILED For any other type of error.

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

Returns Status Message
Void Void

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

Returns Status Message
ihSTATUS_OK On success.
ihSTATUS_API_TIMEOUT If the servername 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 r" 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.

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

Returns Status Message
ihSTATUS_OK On success.
ihSTATUS_FAILED For any other type of error. Other errors on their respective Network or Security failures.

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

Returns Status Message
Void Void

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

Returns Status Message
ihSTATUS_OK On success.
ihSTATUS_FAILED For any other type of error. Other errors on their respective Network or Security failures.

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

Returns Status Message
Void Void

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

Returns Status Message
ihSTATUS_OK On success.
ihSTATUS_FAILED For any other type of error. Other errors on their respective Network or Security failures.