Alarm API Structure Definitions

The alarm manager defines several data structures.

The configuration structure is obtained and populated when commissioning an alarm. Alarm Configuration Structure
The status structure may be obtained and monitored to watch for changes to an alarm's state. Alarm Status Structure
The transaction structure contains information about an alarm event that is stored to the database including what changed (active state on or off...), the logged-on user, which workstation, etc. Alarm Transaction Structure
The record structure is the complete set of information for each entry in the alarm database. This includes both configuration and transaction information. Alarm Record Structure

Alarm Configuration Structure

Every alarm can be described using a known configuration structure. When configuring a new alarm, this structure should be created via a call to \AlarmManager\GetAlarmConfiguration, then populated with the appropriate values before a call is made to \AlarmManager\Commission.

ConfigurationStruct { All Boolean flags default to FALSE }
Name	Unique name for the alarm. Typically the unique ID, which can be obtained using GetAlarmName. If there are multiple built-in alarms in a tag, the convention is to concatenate the UniqueID with a separator and a unique integer or string per alarm. For example, Concat(Root\UniqueID, \AlarmSeparatorString, 0).
FriendlyName	Display name of the alarm's source. This is only needed for alarms that are not associated with a tag, such as service alarms. Tag alarms will always show the tag's Name as the display name.
Area	Area
Description	Description. See also: NoLegacyAlarmDesc
Priority	Priority. Must be valid to be commissioned. Must be an integer corresponding to the Alarm Priority tag values. A priority of 0 will be treated as an event and will not go on either the Active or Current lists.
Reserved
Disable	TRUE to disable the alarm.
DisableParmName	Name of the tag's disable parameter. Allows you to get the operator name who made the configuration change.
OnDelay	Seconds to delay before activating.
OffDelay	Seconds to delay before clearing.
RearmDelay	Seconds to delay before rearming after acknowledgment.
Setpoint	Setpoint of alarm evaluation. The value is compared against the setpoint.
ValueLabels	Array of labels to display instead of Value or Setpoint. Rarely used by tags other than digitals.
Units	Phrase Key of the setpoint units.
Function	Enumerated function for alarm evaluation. See: Alarm Manager Function Constants
AlarmType	String identifying the type of alarm. Used for display purposes only, in accordance with the ISA18.2 standard. Examples include "Low", "High", "Test".
Trip	TRUE if alarm only becomes unacked not active.
NormalTrip	TRUE if alarm becomes unacked when it clears.
OffNormal	TRUE if alarm only becomes active not unacked.
Deadband	Setpoint deadband.
PopupEnable	TRUE to enable popup display of active alarm.
SoundFile	Filename relative to app path of custom sound.
Custom	Number/String/Array/Dictionary/Structure containing custom data. This information is not shown anywhere on the AlarmPage by default, but could be displayed using a custom column.
AdHoc	TRUE if alarm is ad hoc. Should not be set explicitly. It is an internal flag that is set if the alarm object calls AdHocAlarm() rather than Commission()
ReactivateOnValueChange	If TRUE, the alarm will reactivate whenever the reported value changes.
DescPhraseID	PhraseID or a ParmPhrase structure to translate the description to current language.
NormalAck	TRUE to auto-ack the alarm when it clears.
Hook	The name of a module you supply, which will be called whenever any alarm event occurs for the given alarm, including events such as active / normal / acknowledge / shelve / disable / commission / etc. VTScada will look for the callback module starting in the AlarmObject that is provided in the call to Commission(), and will search upwards until it reaches Code level. This gives you flexibility to specify your callback module in your custom alarm tag, or in a custom ancestor tag, or in the application (AppRoot). The callback module must take a TransactionInfo structure as its only parameter. It is expected to return TRUE or Invalid to allow the transaction to be logged, or FALSE to prevent it.

GetAlarmConfiguration returns only a copy of the alarm's structure, not a reference. To update any property within the structure:

Obtain a copy using GetAlarmConfiguration.
Change values within that copy as required.
Include the copy in a new call to the Commission function.

Related Functions:

GetAlarmConfiguration

Commission

Alarm Status Structure

AlarmStatus Struct
IsActive	TRUE if alarm is on the Active list
IsUnacked	TRUE if alarm is on the Unacked list
IsShelved	TRUE if alarm is on the Shelved list
IsDisabled	TRUE if alarm is on the Disabled list
IsSuppressed	TRUE if alarm is on the Suppressed list
IsSilentlySuppressed	TRUE if alarm is suppressed but not on the Suppressed list

This structure should be used in all new code, replacing the older functions IsActive, IsUnacked, IsShelved and IsDisabled.

Related Functions:

GetAlarmStatus

Alarm Transaction Structure

TransactionInfo Struct
Name	Alarm name
Cfg	Alarm's configuration. Only required to bypass the alarm's commissioned configuration.
Action	Alarm action code that identifies the reason for the transaction. See following list.
Transaction	Alarm transaction string
Timestamp	Alarm timestamp (UTC)
Value	Tag value
Custom	Custom fields. Overrides Cfg\Custom
Reserved
MachineID	Workstation's MachineID. Defaults to local.
AccountID	AccountID of operator
Device	Name of client device
ExpiryTime	Time the record is to be removed (UTC)
RemovalGUID	Reference GUID for targeted removals
NoteInfo	Structure containing information about a note that has been attached to this transaction. It provides the Timestamp and GUID of this transaction.
IsReevaluation	TRUE if due to a reevaluation
FromPLC	TRUE if the action originated in a PLC's alarm block
Auto	TRUE if the action was automated such as in unshelving on time expiry
UserName	Account name of the security user
SessionID	Current user session ID
DoNormalAck	TRUE if this alarm should be acked when cleared but only if currently shelved/disabled/suppressed

The transaction string takes the form, "ListName+" or "ListName-". Several transactions can be combined in one string. The following example sets both the unacknowledged status and the active status off: "Unacked-Active-".

List names include the following: Active, Unacked, Shelved, Disabled, Configured.

Alarm Action Codes

Relates to "Action" in the Alarm Transaction Structure.
The action code is used for displaying a label in the "Event" column when viewing alarm history, and for filtering on specific kinds of historical events. The code is translated into a label by GetAlarmActionLabel().

The supported action codes are:

Ack - alarm acknowledged
Active - alarm became active and unacknowledged
ActiveAck - alarm became active and acknowledged
ClearAck - alarm became normal and acknowledged
ClearTrip - alarm became normal and unacknowledged
Commission - alarm commissioned
Decommission - alarm decommissioned
Disable - alarm disabled
Enable - alarm enabled
Event - an event
Modify - alarm modified
Notified - alarm notification sent
OffNormal - alarm became active without becoming unacknowledged
Purge - orphaned alarm purged
Rearm - alarm became active and unacknowledged again
Recommission - alarm recommissioned
Renamed - alarm renamed
Shelve - alarm shelved
Suppress - alarm suppressed
Trip - alarm became unacknowledged
Unshelve - alarm unshelved
Unsuppress - alarm unsuppressed

Alarm Record Structure

AlarmRecord Struct
TimeStamp	UTC time for the event
GenTimestamp	UTC time when the record was written
GUID	16 byte unique ID for the event
ReferenceGUID	GUID of original event that this cancels
ReferenceTime	Time when original canceled event occurred
Name	Alarm name, typically the tag name
Area	Alarm area
Transaction	List additions and deletions
Action	Alarm action to display for history event
Priority	Alarm priority (integer)
IsShelved	TRUE if this alarm is shelved
Database	UniqueID of the alarm database tag
Custom	Field to be used by OEM & app code
MachineID	Workstation where record originated
Device	Name of originating client computer
UserID	User associated with the event
Description	Alarm description/message
Reserved
ExpiryTime	Time shelved record is to be removed
OnDelay	Time to wait (seconds) before activating
OffDelay	Time to wait (seconds) before clearing
Value	Tag value at time of alarm event
Setpoint	Alarm setpoint
Units	Setpoint units
Function	Setpoint function. See: Alarm Manager Function Constants
AlarmType	Type of alarm
SetpointLabel	Label to display instead of Setpoint
ValueLabel	Label to display instead of Value
RearmDelay	Rearm delay (seconds)
Deadband	Analog deadband
SeqNum	Sequence Number (for history sort)
Trip	TRUE if alarm was tripped
AdHoc	TRUE if alarm was ad hoc
NoteAttached	TRUE if one of more notes attached to record
IsConfig	TRUE if the alarm configuration is changed
IsReevaluation	TRUE if due to a reevaluation
UTF8	TRUE if the record was stored with UTF8 encoding. Pre-multi-language records will not have this field in the packed records and this field will always be Invalid for those records. Used to determine if the record needs to translate fields to UTF8 upon reading.
DescPhraseID	PhraseID or a ParmPhrase structure to translate the description to current language. Pre-multi-language records will not have this field in the packed records and this field will always be Invalid for those records.
The following three fields, TagName, Workstation and UserName are the text (not the ID) versions of the names and are logged for the following reasons: a) after a tag or workstation or user is deleted, we can no longer convert the ID into a text name b) for logging to an external SQL database where converting IDs isn't possible These fields should be ignored unless the ID cannot be converted into a text version of the name.
TagName	Text version of the tag name of alarm (i.e. not the GUID of the tag.)
Workstation	Text version of the workstation where record originated
UserName	Text version of the UserName associated with the event
PopupEnable	TRUE if the alarm is configured as a popup
AckTimestamp	Timestamp when active alarm was acked
NormalTimestamp	Timestamp when unacked alarm went normal