Object Reference

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.

Object Summary

This section contains the Historian objects that are available in the Historian Software Development Kit.

Alarms Object

Historian can be used to store Alarms and Events. From the SDK, you can Add and Query these Alarms and Events. This class is slightly different then other SDK classes in that you will mostly be accessing lower level functionality to add and query alarms. By following the directions below, you should be able to perform these tasks fairly easily.

Add Historian Type Library to the Project

As previously mentioned, access to Alarm and Event methods is lower level. You must add the Historian COM 1.1 Type Library to your project. In Visual Basic, in the Project menu, select References, and then add the library. You should now have access to the lower level A&E methods.

Query by Alarms and Events

For detailed instructions on querying for alarms and events, see the help for the AlarmRecordSet function.

Add Alarms and Events

Alarms and Events can be added to Historian by using the AlarmInfo object. In general, adding alarms or events is easy, simply declare a new AlarmInfo object, fill it up with the required details, and then run the Addfunctionon the AlarmInfo object. In practice, you need to be aware of the lifecycle of your alarm.

Create a new AlarmInfo Object

To create a new AlarmInfo object, use the CreateObject method as follows:

Dim myAlarmInfo As AlarmInfo
                Set myAlarmInfo = CreateObject("Historian_API.AlarmInfo")

Alarm or Event?

Historian distinguishes between Alarms and Events. Alarms follow a lifecycle as described below, while Events are generally one shot deals. Example events include Set Point Events, Login Events, or other audit trail events. Alarms are generally characterized by a Tag going into and out of an abnormal condition. You must identify your AlarmInfo object as an Alarm or Event by setting the AlarmType field.

Alarm:myAlarmInfo.AlarmType = ihALARM_CONDITION 
                    Event: myAlarmInfo.AlarmType = ihALARM_TRACKING

Alarm Life Cycle

As previously mentioned, Alarms generally follow a lifecycle. To avoid BAD quality Alarms in the Archive, when adding alarms, be sure to follow the lifecycle rules below.

Note: For each lifecycle phase, you should create and add a new AlarmInfo object. Or, if you prefer to use the same AlarmInfo object for each lifecycle phase, you can CleartheAlarmInfo object after you've added it.

myAlarmInfo.AddMyServer myAlarmInfo.Clear

New Alarm

To instantiate a new alarm, specify the starttime in the AlarmInfo object.

myAlarmInfo.StartTime= Now

State Change

If the alarm changes states (from HI to HIHI for example), you need only specify the new subcondition (along with the other required fields detailed below).You can optionally specify the starttime field as the original start time (when the alarm first went to HI), but that is not necessary.

CAUTION:

Do NOT specify a new start time, or a new Alarm will be created instead.

myAlarmInfo.SubConditionName= "HIHI"

Wrong:'myAlarmInfo.StartTime= Now

OK:'myAlarmInfo.StartTime=AlarmStartTime

Acknowledge an Alarm

To acknowledge an alarm, set the Acked field in the AlarmInfo to True, and also specify the time of the acknowledgement by populating the AckTime alarm field. On top of that, you should populate the starttime field with the start time of the alarm (when it first went into an alarm condition, NOT the last state change).

myAlarmInfo.Acked= TRUE 
                myAlarmInfo.AckTime = Now 
                myAlarmInfo.StartTime =AlarmStartTime

Return to Normal

When your alarm condition has ended, specify the endtime in the AlarmInfo Object. Similar to the state change and acknowledgements, you can optionally specify the start time of the alarm in the starttime alarm field.

myAlarmInfo.EndTime= Now myAlarmInfo.StartTime = AlarmStartTime

Associating Alarms and Events with Tag Data

The easiest way to associate alarms and events with tag data is to specify the TagName in the AlarmInfo. Historian will sort out everything behind the scenes. However, if you are adding alarms before the associated tag actually exist in Historian, this avenue will not work. You must populate the ItemId field with the SourceAddress of the future tag, and populate the DataSourceName field with the collector name of the tag. When the tag is added to the system, the alarms will be correctly linked.

myAlarmInfo.Tagname=TheTagName

myAlarmInfo.DataSourceName= MyCollector.Name myAlarmInfo.ItemId =TheSourceAddress

AlarmInfoFields

The following table lists the AlarmInfo fields. The fields that are marked as required need to be filled out for every call to Add. On top of these required fields, be sure to populate the correct fields based on the current state in the lifecycle of your alarm (see above).

FieldName	Data Type	Required	Description
AlarmType	Long	Both	Classifies this AlarmInfo as an Alarm or Event. 1 for Event, 4 for Alarm.
ItemID	String		The ItemID of the alarm or event. This contains the source address of the data access tag the alarm is associated with. This can be NULL if the alarm is not associated with a tag.
Source	String	Both	This is the unique identifier used for the alarm or event.
DataSourceName	String	Both	The collector interface name associated with the alarm or event.
Tagname	String		The Historian Tag Name associated with the alarm.
EventCategory	String		The event category of the alarm or event.
ConditionName	String	Alarms	The condition of the alarm. This does not apply to event data. This, combined with the Source, comprises an alarm.
SubConditionName	String	Alarms	The sub-condition of the alarm. This does not apply to event data. This is the state of the alarm.
StartTime	Date		The start time or time stamp of the alarm or event.
EndTime	Date		The end time of the alarm. This does not apply to event data.
AckTime	Date		The time the alarm was acknowledged. This does not apply to event data.
Timestamp	Date	Both	The time stamp of the alarm or event.
Message	String		The message attached to the alarm or event.
Acked	Boolean		Stores the acknowledgement status of the alarm. If the alarm is acknowledged, this will be set to TRUE.
Severity	Long		The severity of the alarm or event. This is stored as an integer value with a range of 1-1000
Actor	String		The operator who acknowledged the alarm, or caused the tracking event.
Quality	Long	Alarms	The quality of the alarm or event. 0 for Bad, 3 for Good.

Example

Dim MyServer As iHistorian_SDK.Server
Set MyServer = GetServer
Dim myAlarmInfo As AlarmInfo
Set myAlarmInfo = CreateObject("iHistorian_API.AlarmInfo") 
Dim AlarmStartTime As Date
AlarmStartTime = Now
' New Alarm myAlarmInfo.AlarmType = ihALARM_CONDITION 
myAlarmInfo.ConditionName = "SampleCondition" 
myAlarmInfo.DataSourceName = "SampleDataSource" 
myAlarmInfo.Message = "Sample Alarm"
myAlarmInfo.Source = "SampleSource"
myAlarmInfo.StartTime = AlarmStartTime
myAlarmInfo.SubConditionName = "HI"
myAlarmInfo.Timestamp = Now
myAlarmInfo.Quality = 3
myAlarmInfo.Add MyServer
myAlarmInfo.Clear
' State Change myAlarmInfo.AlarmType = ihALARM_CONDITION
myAlarmInfo.ConditionName = "SampleCondition"
myAlarmInfo.DataSourceName = "SampleDataSource"
myAlarmInfo.Message = "Sample Alarm State II"
myAlarmInfo.Source = "SampleSource"
' Not required, but pointing out the start time of the alarm doesn't hurt
myAlarmInfo.StartTime = AlarmStartTime
myAlarmInfo.SubConditionName = "HIHI"
myAlarmInfo.Timestamp = Now
myAlarmInfo.Quality = 3
myAlarmInfo.Add MyServer
myAlarmInfo.Clear
' Ack the HIHI state
myAlarmInfo.Acked = True
myAlarmInfo.AckTime = Now
myAlarmInfo.AlarmType = ihALARM_CONDITION
myAlarmInfo.ConditionName = "SampleCondition"
myAlarmInfo.DataSourceName = "SampleDataSource"
myAlarmInfo.Source = "SampleSource"
myAlarmInfo.StartTime = AlarmStartTime
myAlarmInfo.SubConditionName = "HIHI"
myAlarmInfo.Timestamp = Now
myAlarmInfo.Quality = 3
myAlarmInfo.Add MyServer myAlarmInfo.Clear
' Return to Normal
myAlarmInfo.AlarmType = ihALARM_CONDITION
myAlarmInfo.ConditionName = "SampleCondition"
myAlarmInfo.DataSourceName = "SampleDataSource"
myAlarmInfo.EndTime = Now
myAlarmInfo.Source = "SampleSource"
' Not required, but pointing out the start time of the alarm doesn't hurt
myAlarmInfo.StartTime = AlarmStartTime
myAlarmInfo.Timestamp = Now
myAlarmInfo.Quality = 3
myAlarmInfo.Add MyServer
myAlarmInfo.Clear

Archive Object

The Archive object contains the configuration and status information for a single archive file on the Historian server.

Archives Object

The Archives object provides access to Historian archive configuration information and performance statistics. It also provides functionality to add, delete, and modify Historian archives.

Alarms.PurgeAlarmsById

The following sample is used to develop an SDK sample for purging alarms by their alarm IDs.

Dim Alarms() As String
Dim AlarmIds() As Long
Dim i As Long
Dim numberOfAlarms As Long
Dim AlarmsObj As iHistorian_SDK.Alarms
Dim Status As Boolean
i = 0
numberOfAlarms = 0
Status = False
If CheckConnection = True Then
    Set AlarmsObj = ConnectedServer.Alarms
    If TextAlarmIds.Text = "" Then
    MsgBox "Alarms cannot be empty", vbCritical, "Historian"
    Exit Sub
End If
Trim (TextAlarmIds.Text)
'Multiple alarms are separated by semicolon
Alarms() = Split(TextAlarmIds.Text, ";")
numberOfAlarms = UBound(Alarms)
If numberOfAlarms <> 0 Then
ReDim AlarmIds(0 To numberOfAlarms) As Long
    For i = 0 To numberOfAlarms
    If Alarms(i) <> "" Then
        AlarmIds(i) = CLng(Alarms(i)) 
      End If
    Next
    Status = AlarmsObj.PurgeAlarmsById(AlarmIds()) 
    If Status <> True Then
    MsgBox "An error occurred while deleting the alarms. See the Historian Alerts for more details.", vbCritical, "Historian"         
  Else
    MsgBox "Successfully deleted the alarms.", vbInformation, "Historian" 
  End If
    TextAlarmIds.Text = "" 
  Else
   MsgBox "Please enter Alarm Ids followed by ';'", vbCritical, "Historian"
   End If
 Else
   MsgBox "Not connected", vbCritical, "Historian" 
  End If

Collector Object

The Collector object contains the configuration and status information for a single collector connected to the Historian Server.

Collectors Object

The Collectors Object provides access to the Historian Collector configuration information and performance statistics. It also provides functionality to add, delete, and modify Historian Collectors.

Data Objects

Data Object

The Data object provides access to Historian data and provides functionality to add, delete, and modify data samples in the Historian archives.

DataComments Object

The DataComments object contains a collection of comments attached to a specific DataValue record.

DataCriteria Object

The DataCriteria object sets the criteria for the retrieval of DataValue records into a DataRecordset Object. For example, you may want values between a certain start and end time.

DataFields Object

The DataFields object identifies which DataValue fields a DataRecordset query retrieves. For example, you may not want to retrieve comments with your data.

DataRecordset Object

The RecordSet contains a collection of DataValue records. Use the DataRecordset object to add, delete, or modify data samples.

To add, modify, or delete a DataValue record:

Create a DataRecordset Object.
Add, delete, or modify the DataValue Records.
Perform a WriteRecordset operation to save the changes to the Historian archives.

DataValue Object

TheDataValue object contains data for a single tag and timestamp. It also contains a data quality and one or more comments attached to the specific data value. You can modify the Value, DataQuality, and Comments properties and commit them to the Historian server by using the WriteRecordset Method of the DataRecordsetObject. You cannot modify the timestamp.

Message Objects

Message Object

The Message object provides access to a single message retrieved from the Historian server.

MessageCriteria Object

The MessageCriteria object sets the criteria for retrieval of message records into a MessageRecordset object.

MessageFields Object

The MessageFields object identifies which message fields the MessageRecordset query retrieves.

MessageRecordset Object

The MessageRecordset contains a collection of messages from the Historian Server. Use the Mes- sageRecordset Object to add and retrieve messages. To add new messages, create a MessageRecordset, add the appropriate messages, and then perform the WriteRecordset operation to store the changes in the Historian archives.

Messages Object

The Messages object contains Historian messages and provides functionality for adding new messages to the Historian Server. For example, you may want only alerts or you may want messages associated with a certain user.

OPC Objects

OPCBrowse Object

The OPCBrowse object allows you to retrieve hierarchical areas from OPC AE servers.

OPCFilters Object

Returns whether Auto-Reconnect logic is Enabled/Disabled.

Option Object

This object acts a simple container for providing a name and values for a named parameter. The possible option values are found in Options.bas.

Server Objects

Server Object

Use the Server object to establish and maintain a connection to a specific Historian server. All other configuration and data access objects are subordinate to the Server object.

ServerManager Object

The ServerManager object permits you to browse the available servers registered on the client. The ServerManager object also provides functionality for adding new server connections and for setting the default login information.

Tag Objects

Tag Object

The Tag object contains configuration information for a single tag. You can modify properties of the Tag object and save them to the Historian server by using the WriteRecordset method of the TagRecordset object.

TagCriteria Object

The TagCriteria object sets the criteria for retrieval of Tag records into a TagRecordset object.

TagDependencies Object

TheTagDependencies object represents a list of Historian Tags which trigger a given calculation when their values change.

TagFields Object

TheTagFields object identifies which tag fields are retrieved in a TagRecordset query.

TagRecordset Object

The TagRecordset object is a collection of tag records that contain tag configuration information.

To add, modify, or delete tags:

Create a TagRecordset object.
Add, delete, and modify tag records.
Perform a WriteRecordset operation to save the changes to the Historian tag database.

Tags Object

TheTags object contains Historian tag configuration information and provides functionality for adding, deleting, and modifying this configuration.

The following figure describes the Tags object.

UserCalcFunction Object

The UserCalcFunction object contains the definition of a user function that can be stored in the Calculation library.