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.
If there are multiple built-in alarms in a tag, the convention is to concatenate the UniqueID with a separator and a unique integer per alarm. For example, Concat(Root\UniqueID, \AlarmSeparatorString, 0).
FriendlyName Display name of the alarm's source.
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.
DisplayInfo Sub-structure of display information. For display only, not evaluation.

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

  1. Obtain a copy using GetAlarmConfiguration.
  2. Change values within that copy as required.
  3. 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

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.

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
  • Enabled - 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
  • Trip - alarm became unacknowledged
  • Unshelve - alarm unshelved

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