Alarms Object

You can use Historian to store data for alarms and events. From the SDK, you can add and query these alarms and events. This class is slightly different from other SDK classes in that you will mostly be accessing lower level functionality to add and query alarms and events. 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 methods for alarms and events 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 can now access the lower level alarms and events methods.

Query by Alarms and Events

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

Add Alarms and Events

You can add alarms and events to Historian by using the AlarmInfo object. In general, adding alarms or events is easy; declare a new AlarmInfo object, fill it up with the required details, and then run the Add function on the AlarmInfo object. In practice, you must 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, ensure that you follow the lifecycle rules below.

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

myAlarmInfo.AddMyServer myAlarmInfo.Clear

New Alarm

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

myAlarmInfo.StartTime= Now

State Change

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

Important: Do not specify a new start time. If you do so, 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. In addition, you must 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 source address 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 must be filled in for every call to add. In addition, populate the correct fields based on the current state in the lifecycle of your alarm (see above).


FieldName	Data Type	Required for Alarms or Events?	Description
AlarmType	Long	Both	Classifies this AlarmInfo as an alarm or an event. Enter 1 for an event and 4 for an alarm.
ItemID	String	None	The ItemID of the alarm or event. This contains the source address of the data access tag that 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	None	The Historian Tag Name associated with the alarm.
EventCategory	String	None	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	None	The start time or time stamp of the alarm or event.
EndTime	Date	None	The end time of the alarm. This does not apply to event data.
AckTime	Date	None	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	None	The message attached to the alarm or event.
Acked	Boolean	None	Stores the acknowledgement status of the alarm. If the alarm is acknowledged, this will be set to TRUE.
Severity	Long	None	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