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