ihapi.h File Overview

System API Functions and Data Structures

#pragma pack(push,BeforeihAPI)
#pragma pack(1)

// Setup a link dependency on the ihAPI lib
#define ihAPILIB_NAME "ihAPI55.lib"
#define ihAPIDLL_NAME L"ihAPI55.dll"
#define ihAPIDLL_VERSION 550

The version specified in the given example changes for each version of Historian. The version of your program should match the version of Historian installed.

#ifdef _WCHAR_T_DEFINED
typedef ihPUBLIC wchar_t ihChar; 
#else 
typedef ihPUBLIC unsigned short ihChar; 
#endif 

typedef struct ihTimeStruct {
MSO_ULONG Seconds; 
MSO_ULONG Nanoseconds; 
} ihTimeStruct; // (Must match MSOTimeStruct) 

Timestamps are nanosecond resolution in the System API. However, only microseconds are exposed to users.

// Error Statuses typedef enum 
ihStatus { ihSTATUS_OK = 0,
 ... 
} ihStatus; 

There is a fixed set of error codes and you cannot add new ones. Your program can receive errors on reads or writes or tag adds and those errors will be described with the function documentation.

 typedef enum ihQualityStatus {
ihOPCBad = 0,
... 
} ihQualityStatus;
typedef enum ihQualitySubStatus {
ihOPCNonspecific = 0,
...
} ihQualitySubStatus;

Historian uses a fixed set of quality and subquality data and you cannot add new ones.

 typedef enum ihDataType {
ihDataTypeUndefined = 0,
... } ihDataType; 

There are a fixed set of data types and user-defined data types. You cannot add new native data types.

 typedef enum ihSamplingMode {
 ihSamplingModeUndefined=0, 
... 
} ihSamplingMode;
typedef enum ihCalculationMode {
ihCalculationModeUndefined=0, 
... 
} ihCalculationMode; 

To read data you should specify a sampling mode, calculation mode, a filter condition (optional), and a query modifier (optional).

typedef ihHIDDEN struct ihBlobData {
ihVoidPtr Blob;
MSO_ULONG BlobSize; 
} ihBlobData; 

The blob data type is a size and a pointer in the system API

typedef struct ihTagProperties { 
ihString Tagname; 
... 
} ihTagProperties; 

A tag has a fixed set of properties as listed in this structure. Some tag properties may not exist in the earlier versions of Historian and new properties may be added in the future. You are limited to the set of properties available in the version of the ihapi.h shipped with this SDK and you cannot add new tag properties.

 typedef struct ihDataProperties {
 ihTimeStruct TimeStamp;
 ihDataType ValueDataType;
 ihValue Value;
 ihQuality Quality;
 unsigned char NumberOfComments;
 ihCommentsPtr Comments; 
ihGeoLocation Unsupported; 
} ihDataProperties; 

typedef struct ihDataRecordset {
 ihDataFields Fields;
 ihDataCriteria Criteria;
 ihUNSIGNED long NumberOfResults; // (Num items in results)
 ihDataResultPtr Results; // (array. One for each matching tag) 
} ihDataRecordset;

The given prototype is a collection of data samples that you get back from a data read or subscription.

Callback Prototypes/typedefs

typedef void (__stdcall *ihInterfaceGetCurrentValueCallbackFunction) (ihServerHandle hServer, void *UserParameter, 
ihUNSIGNED long NumberOfSourceAddresses, 
ihString *SourceAddresses, ihCallbackId CallbackId); 

A lot of information can be communicated to your program using callback if you subscribe to changes which is optional. The following sections describe this in more detail.

extern ihC_DEC ihAPIStatus __stdcall ihConfigurationGetProperties 
(ihServerHandle hServer, ihConfigurationProperties *Properties);
extern ihC_DEC void __stdcall ihConfigurationFreeProperties 
(ihConfigurationProperties *Properties);

You can get information about the Data Archiver in addition to reading and writing data.

ihServer Function

extern ihC_DEC ihAPIStatus  stdcall ihServerConnect(ihString ServerName, ihString Username, ihString Password,
ihString BufferFileName, ihServerHandle *hServer); 
extern ihC_DEC ihAPIStatus  stdcall ihServerConnectClient(ihString ServerName, ihString Username, ihString 
Password, ihString BufferFileName, ihServerHandle *hServer, ihString ClientName);  
extern ihC_DEC ihAPIStatus  stdcall ihServerDisconnect(ihServerHandle hServer);
extern ihC_DEC ihBoolean stdcall ihServerIsConnected(ihServerHandle hServer);

extern ihC_DEC ihAPIStatus  stdcall ihServerAdd(ihString ServerName, ihString Username, ihString Password, 
ihBoolean IsDefault, ihString BufferFileName, ihServerHandle *hServer,ihULong ConnectionTimeout);  
extern ihC_DEC ihAPIStatus  stdcall ihServerDelete(ihString ServerName);
extern ihC_DEC ihAPIStatus  stdcall ihServerOpenRecordset(ihString ServerNameMask, ihServerRecordset 
*ServerRecordset); 
extern ihC_DEC void  stdcall ihServerCloseRecordset(ihServerRecordset *ServerRecordset);

You can set up a collection of servers with their timeouts and usernames. However, you can simply call connect to establish a connection.

ihTag Functions

extern ihC_DEC ihAPIStatus  stdcall ihTagAdd(ihServerHandle hServer, ihTagFields *hFields, ihTagProperties
*hTag); 
extern ihC_DEC ihAPIStatus  stdcall ihTagOpenRecordset(ihServerHandle hServer, ihTagFields *RequestedFields, 
ihTagCriteria *Criteria, ihTagFields *CriteriaFields, ihTagRecordset *TagRecordset);
extern ihC_DEC ihAPIStatus  stdcall ihTagGetProperties(ihServerHandle hServer, ihString Tagname, ihTagFields 
*hFields, ihTagProperties *hTag);

You can add and browse tags using these functions

ihData Functions

extern ihC_DEC ihAPIStatus  stdcall ihDataAdd(ihServerHandle hServer, ihUNSIGNED long NumberOfTags, ihString 
*Tagnames, ihDataProperties *DataValues, ihAPIStatus *ErrorStatuses, ihBoolean WaitForReply, ihBoolean ErrorOnRep 

You can add and delete data and subscribe to data changes

ihDataStore Functions

extern ihC_DEC ihAPIStatus  stdcall ihDataStoreOpenRecordset(ihServerHandle hServer, ihString 
DataStoreMask, ihDataStoreRecordset *Recordset);

You need not configure data stores, the defaults should be fine.

ihComment Functions

extern ihC_DEC ihAPIStatus  stdcall ihCommentAdd (ihServerHandle hServer, ihString Tagname, ihTimeStruct 
*CommentAdd, ihCommentData *ihCommentData, ihString SuppliedUser, ihString SuppliedPassword);

You can add comments to data and get them back when you read the data but this is not commonly used.

ihTime Functions

extern ihC_DEC void stdcall ihTimeLCLPartsToUTCStruct(int Year, int Month, int Day, int Hour, int Minute, 
int MilliSecond, ihTimeStruct *UTCTime); 
extern ihC_DEC void stdcall ihTimeUTCStructToLCLParts(int *Year, int *Month, int *Day, int *Hour, int 
*Minute, int *Second, int *MilliSecond, ihTimeStruct *UTCTime);

The System API has utility functions for working with time zones and daylight saving time.

ihUtil Functions

extern ihC_DEC void stdcall ihUtilAnsiToUnicode(char *MBStr, ihChar *WCStr);
extern ihC_DEC void stdcall ihUtilUnicodeToAnsi(char *MBStr, ihChar *WCStr);

The System API has utility functions for converting between Unicode and ANSI strings.