Object Model Overview

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.

Historian SDK Overview

The Historian Software Development Kit (SDK) is a COM object designed to simplify access to Historian services and data for the purposes of application development.

This object provides the following functionality to developers:
  • Browsing Available Historian Servers
  • Browsing and Configuring Tags
  • Browsing, Adding, and Modifying Data
  • Browsing, Adding, and Modifying Alarms and Events
  • Browsing and Adding Messages and Alerts
  • Controlling the Archiving Functions of the System
  • Controlling the Collection and Interface Functions of the System
  • Adherence to Historian Security Constraints
You can use the Historian SDK under any Win32 platform using a development language that supports Microsoft COM/DCOM. The SDK relies on the run-time version of the Historian API. You must install the Historian API prior to the installation of the SDK on any client that accesses the Historian system through the SDK. Refer to the Getting Started with Historian Manual located in the Historian Electronic Books for specific installation instructions.

The Historian SDK is a COM DL(ihSDK.dll) that must be instantiated prior to use. A single instance of the SDK may connect and converse with many Historian servers simultaneously. You can create multiple instances of the SDK, however, the developer must maintain this collection and respond to events from the appropriate instance.

The following table lists general information regarding SDK naming and dependencies.
SDK DLL ihSDK.dll
Class Name iHistorian_SDK
Version 5.0.0.x
Dependencies ihAPI50.dll

The following diagram describes the object model employed by the Historian SDK. For more information on the individual objects, refer to the SDK Object Reference.

Working with Comments

Comments are retrieved with a data query. To retrieve comments, request all fields from the DataValue object and then perform a DataRecordset.QueryRecordset. The comments will be contained in the DataValue.Comments collection. Comments are stored to the archive using the DataRecordset.WriteRecordset method. Store comments to the DataValue object first by calling the DataValue.AddComment method.

Adding Data

Use the DataValue object to insert data by setting the value, quality, and timestamp before calling the WriteRecordset method.

Sample SDK Program

A sample program for the SDK is included in the Samples\SDK folder when you install Historian. Refer to this sample for more detailed examples than the ones that appear in this Help system.
Note: The SDK sample is designed to work on Visual Basic 6 (VB6).

Connect the SDK to the Server

After instantiation of the SDK, connect to one or more servers by providing a valid user name and password for the target Historian server domain. The SDK does not support any other functions until you make a successful connection and authentication. The authenticated user also controls which functions may be performed through the SDK and potentially what data may be accessed.

The following example displays the Visual Basic code for instantiation of the SDK and connection to the target server.
Dim MyServer as Object
'Instantiate The SDK
Set MyServer = CreateObject("iHistorian_SDK.Server")

'Attempt Connection
If Not MyServer.Connect("USGB014", "Fred", "000") Then
Err.Raise 1, "Failed To Connect To USGB014" End If

In the example above, "MyServer" does not receive events from the Historian server. 
In order to receive events, Dim WithEvents MyServer As iHistorian_SDK.Server
'Instantiate The SDK
Set MyServer = New iHistorian_SDK.Server

'Attempt Connection
If Not MyServer.Connect("USGB014", "Fred", "000") Then
Err.Raise 1, "Failed To Connect To USGB014" End If
Note: After each session, disconnect each Server connection prior to exiting the application.

Working with Blob Data

Historian is capable of storing many different data types, such as Floating Point, Integer, String, Binary, and BLOB (undetermined binary data type, such as an Excel spreadsheet, a PDF file, or a Word file). The source of the data defines the ability of Historian to collect specific data types.

The following example demonstrates how to read and write a file into Historian. It contains a sample script for adding, writing, and reading a tag of BLOB data type. You will need to change the server name, folder, and file names as appropriate.

Dim MyServer As Server

Private Function Connect1() As Boolean 
If Not MyServer Is Nothing Then
MyServer.Disconnect
End If
Set MyServer = Nothing

Set MyServer = New Server

Connect1 = MyServer.Connect("FRIEDENTHAL") 
End Function

Private Function AddTag(Tagname As String) As Boolean
Dim Tags As TagRecordset
Dim NewTag As Tag

Set Tags = MyServer.Tags.NewRecordset 
Set NewTag = Tags.Add(Tagname) 
NewTag.DataType = Blob
AddTag = Tags.WriteRecordset

End Function

Private Function WriteBlob(Tagname As String, TimeStamp As Date, ByteArray() As Byte, FileName As String) As Boolean
Dim Data As DataRecordset
Dim NewValue As DataValue

Set Data = MyServer.Data.NewRecordset
Set NewValue = Data.Add(Tagname, TimeStamp) 
NewValue.Value = ByteArray 
NewValue.DataQuality = Good
'Store the file name as a comment 
NewValue.AddComment FileName 
WriteBlob = Data.WriteRecordset

End Function

Private Function ReadBlob(Tagname As String, TimeStamp As Date, ByteArray() As Byte, FileName As String) As Boolean
Dim Data As DataRecordset
Dim NewValue As DataValue

Set Data = MyServer.Data.NewRecordset
With Data.Criteria
.Tagmask = Tagname
.StartTime = DateAdd("s", -1, TimeStamp)
.EndTime = DateAdd("s", 1, TimeStamp)
.SamplingMode = RawByTime
End With
With Data.Fields
.AllFields
End With

ReadBlob = Data.QueryRecordset
ByteArray = Data.Item(1).Item(1).Value
FileName = Data.Item(1).Item(1).Comments.Item(1).Comment

End Function

Function ReadFile(FileName$, fileDirectory$) As Variant
Dim ByteArray() As Byte
Dim FileLen As Long 
Dim MyByte As Byte 
Dim i As Long
Dim fName As String 
fName = fileDirectory + FileName
Open fName For Binary Access Read As #1 ' Open file for reading.
FileLen = LOF(1) - 1
ReDim ByteArray(FileLen) 
For i = 0 To FileLen
Get #1, , MyByte 
ByteArray(i) = MyByte 
Next
Close #1
ReadFile = ByteArray

End Function
Function WriteFile(fName, ByteArray() As Byte)

Dim FileLen As Long
Dim i As Long
FileLen = UBound(ByteArray)
Open fName For Binary Access Write As #1
For i = 0 To FileLen - 1
Put #1, , ByteArray(i) 
Next
Close #1

End Function

Private Sub RunTest()
Dim ByteArray() As Byte
Dim i As Integer
Dim TheTime As Date
Dim FileName As String
FileName = "iHvbs.log"
Const ReadFileDirectory = "C:\"
Const WriteFileDirectory = "C:\Temp\" 
ReDim ByteArray(0 To 9)

If Not Connect1() Then

MsgBox "Did Not Connect" 
Exit Sub
End If

If Not AddTag("TestBlob2") Then
MsgBox "Did Not Add Tag" 
Exit Sub
End If
'Read the input file
ByteArray = ReadFile(FileName, ReadFileDirectory)

TheTime = Now
'Write the file to Historian
If Not WriteBlob("TestBlob2", TheTime, ByteArray, FileName) Then
MsgBox "Did Not Write Blob" 
Exit Sub
End If

Erase ByteArray
FileName = ""
'Read back the file from Historian
If Not ReadBlob("TestBlob2", TheTime, ByteArray, FileName) Then
MsgBox "Did Not Read Blob" 
Exit Sub
End If
FileName = WriteFileDirectory + FileName 'copy file to the write directory
WriteFile FileName, ByteArray
End Sub 

Private Sub CommandButton1_Click()
End Sub

Working with Archives

You can backup, restore, and create archives using the SDK. To restore an archive, you add an existing archive file to the archives collection using the Add method.

Example

The following code shows an example of how to restore an archive.

Dim myarchives As iHistorian_SDK.Archives 
Dim myarchive As iHistorian_SDK.Archive 
Dim i As Long
Set myarcives = DefaultServer.Archives
Set myarchive = myarchives.Add("MY_SERVER_archive001", "d:\program files\Historian\Archives\MY_SERVER_archive001_Backup.IHA", 100) 
If myarchive Is Nothing Then
MsgBox "An Error Occured Trying To Restore The Archive." + Chr(10) + Chr(10) + _
"The Details Of The Error Follow:" + Chr(10) + DefaultServer.Archives.LastError, vbCritical, "Historian" 
Err.Raise 1,, "Error Restoring Archive: " + DefaultServer.Archives.LastError
Else
MsgBox "success" 
End If