Utility Functions

ihTimeLCLPartsToUTCStructEx

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

ihTimeLCLPartsToUTCStructEx {

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

Remarks

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

Returns

ihTimeUTCStructToLCLPartsEx

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

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

);

Remarks

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

Returns

ihTimeCurrentUTCStruct

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

Prototype

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

Remarks

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

Returns

ihUtilAnsiToUnicode

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

Prototype

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

Remarks

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

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

Returns

ihUtilUnicodeToAnsi

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

Prototype

ihUtilUnicodeToAnsi {
char *MBStr,ihChar *WCStr
);

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

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

Returns

ihUtilErrorDesc

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

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

Remarks

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

Returns

Time Functions

ihTimeLCLPartsToUTCStruct

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

Prototype

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

Remarks

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

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

Returns

ihTimeUTCStructToLCLParts

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

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

Remarks

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

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

Returns

ihTimeUTCStructToFileTime

Use this function to convert UTC structure to FILETIME.

Prototype

ihTimeUTCStructToFileTime { 
ihTimeStruct *UTCTime,
void *FileTime
};

Remarks

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

Returns

ihTimeLCLFileTimeToUTCStruct

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

Prototype

ihTimeLCLFileTimeToUTCStruct {
void *FileTime, ihTimeStruct *UTCTime
};

Remarks

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

Returns

Query Modifiers Functions

ihQueryModifiersAssign

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

Prototype

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

Returns

This function would not be called by a user program.

ihQueryModifiersClear

Use this function to clear the modifiers.

Prototype

ihQueryModifiersClear {
 ihQueryModifiers *Modifiers
};

Remarks

This function would not be called by a user program.

Returns

ihQueryModifiersSet

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

Prototype

ihQueryModifiersSet {
ihQueryModifiers *Modifiers, ihQueryModifier Modifier
};

Remarks

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

Returns

ihQueryModifiersIsSet

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

Prototype

ihQueryModifiersIsSet {
ihQueryModifiers *Modifiers, ihQueryModifier Modifier
};

Remarks

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

Returns

ihQueryModifierOpenRecordset

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

Prototype

ihQueryModifierOpenRecordset {
ihServerHandle hServer, ihQueryModiferRecordset *QueryModiferRecordset
};

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

Free the returned recordset using the ihQueryModifierCloseRecordset function.

Returns

ihQueryModifierCloseRecordset

Use this function to free memory returned from ihQueryModifierOpenRecordset.

Prototype

ihQueryModifierCloseRecordset { ihQueryModiferRecordset *RecSet };

Remarks

Returns

ihDataCriteriaFromString

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

Prototype

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

Remarks

This function would not be called by a user program.

Returns

DataStore Functions

ihDataStoreAdd

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

Prototype

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

Remarks

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

Returns

ihDataStoreDelete

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

Prototype

ihDataStoreDelete {
ihServerHandle hServer, ihString DataStoreName
};
 

Remarks

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

Returns

ihDataStoreRename

Use this function to rename an existing data store.

Prototype

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

Remarks

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

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

Returns

ihDataStoreOpenRecordset

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

Prototype

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

Remarks

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

Free the returned list using the ihDataStoreCloseRecordset function.

Returns

ihDataStoreCloseRecordset

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

Prototype

ihDataStoreCloseRecordset { 
ihDataStoreRecordset *Recordset

};

Remarks

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

Returns

ihDataStoreSetProperties

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

Prototype

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

Remarks

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

Returns

Security Functions

ihSecurityGroupOpenRecordset

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

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

Prototype

ihSecurityGroupOpenRecordset {
ihServerHandle hServer, ihSecurityGroups *Grps
};

Remarks

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

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

You must free the returned recordset using the ihSecurityGroupCloseRecordset call.

Returns

ihSecurityGroupCloseRecordset

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

Prototype

ihSecurityGroupCloseRecordset {
ihSecurityGroups *Grps
};

Remarks

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

Returns

ihSecurityGetOption

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

Prototype

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

Remarks

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

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

options.

Returns

ihSecurityFreeOption

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

Prototype

ihSecurityFreeOption{
ihChar *OptionValue
};

Remarks

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

Returns

ihSecurityGetmemberships

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

Prototype

ihSecurityGetmemberships {
ihServerHandle hServer, ihSecurityGrpMembership *Memberships
};

Remarks

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

Returns