Object Model 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.

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. For instructions, refer to installing Client Tools.

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

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

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