AlarmUpdateEx (statement)

Syntax AlarmUpdateEx Project$, AlarmId$ , ResourceId$ , Action%, DateTime, IsUTC [ , AlarmMessage$ [ , UserId$ [ , RefId$]]]
Parameter Description
Project$ String. The project to update the alarm on. An empty string "" indicates the current project.
AlarmId$ String. The ID of a non-point or point Alarm that is listed in the right-pane of the Workbench>Alarms section.
Note:
Non-point alarms must be a $CIMBASIC alarm type for all details, including the alarm message, to display correctly in an Alarm Viewer. Point alarms are not $CIMBASIC alarms. As a result, there are limitations and guidelines to be aware of if those alarm IDs are used in the script.  
ResourceId$ String. The Resource ID to update the alarm against. Used to control routing of the alarm.
Action Integer. Indicates whether to acknowledge or reset the alarm. Use the following constants to perform an acknowledgment and a reset.
  • AM_ACKNOWLEDGED
  • AM_RESET
Server Redundancy: By default, on a computer with Server Redundancy, alarm updates from the standby computer's Event Manager are ignored. To acknowledge or reset an alarm on the active computer from the standby computer, use either of the following to override the default behavior.
  • AM_ACKNOWLEDGED_M
  • AM_RESET_M
DateTime The DateTime parameter depends on the script type.
CimBasic Date Variant The Date and Now functions return the Date Variant type.
.NET C# System.DateTime type
VB .NET System.DateTime type
IsUTC BOOLEAN Whether or not the passed in timestamp is UTC.
TRUE The DateTime parameter is a UTC timestamp
FALSE The DateTime parameter is not  a UTC timestamp
Note: If you do not use UTC time, you will be responsible for making sure your system’s Time Zone settings, including DST, are properly set.
Message$ String. The update alarm message to display. Note: This string is substituted into the first variable field of the Alarm's message.
UserId$ String (optional). The User ID that updated the alarm.
RefId$ String (optional). A Reference ID used to distinguish identical alarms.
Master BOOLEAN (optional). By default on a computer with Server Redundancy, alarms sent by the standby computer's Event Manager are ignored. To allow an alarm to be generated from a script on a standby computer, set Master to True.
CimBasic Example 
'This example displays the syntax.
Sub Main()
theDate = Now()
    AlarmUpdateEx "TESTER","ALARM501","$SYSTEM", AM_ACKNOWLEDGED, theDate, FALSE "Device 501: Responded."
End Sub
.NET C# Example 
//This example displays the syntax.
public void Main()
{ DateTime dt = new DateTime(2012, 06, 18, 2, 5, 5);
Cimplicity.AlarmUpdateEx("TESTER", "TESTALARMGEN", "$SYSTEM", Cimplicity.AM_ACKNOWLEDGED, dt, true, "csAG Test")}
VB .NET Example 
'This example displays the syntax.
Public Sub Main()
            Dim DT2 As DateTime
            DT2 = New DateTime (2012,7,10,20,20,30,789)
            Cimplicity.AlarmUpdateEx("ALARMGENERATEUPDATE", "CB1", "$SYSTEM", Cimplicity.AM_RESET + Cimplicity.AM_ACKNOWLEDGED, DT2, True, "Updated", "OPERATOR")
End Sub

Guidelines: AlarmGenerateEx and AlarmUpdateEx

  • Message$ limitations and guidelines.
  • Non-Point alarm requirements.
  • Point alarm guidelines.

Note: Guidelines also apply to AlarmGenerate and AlarmUpdate .

Message$ Limitations and Guidelines

Messages that display in the Alarm Viewer draw from the following sources and have the following limitations.

The message, which is a string, is substituted into the first variable field of the alarm's configured message.

Message: User-defined alarm The substituted string will be the first %s in the Alarm Definition dialog box>Alarm Message field.
Message : Point alarm ID The substituted string will be the first variable field (%VAL, %ID) in an Alarm Definition dialog box (or Point Properties dialog box)>Alarm Message field. However, if a point alarm ID is used in an AlarmGenerateEx or AlarmUpdateEx script, because the alarm is not a $CIMBASIC alarm, the message will most likely not display as you would expect. Examples The entry in the Alarm Message field includes text and more than one variable POINT01 is %VAL : %STATE If the code:
Does not include a message
  • Text from the field will display; Variable values will not display.
  • The first variable position will be blank; BAD FIELD might display for the other variables.
POINT01 is  :BAD FIELD
Does include a message "Point in alarm state."
  • Text will display; the message in the code will display in the first variable position.
  • BAD FIELD might display for other variables.
POINT01 is Point in alarm state. BAD FIELD

Non-Point Alarm Requirements

The alarm definition (in an Alarm Definition dialog box) for a non-point alarm must include the following values.

Alarm type $CIMBASIC alarm.
Alarm message %s

Point Alarm Guidelines

When an alarm is generated using a point alarm ID, the alarm that is generated is actually no longer a point alarm.

However, like its point alarm counterpart, it also is not a $CIMBASIC alarm.

  • The alarm message may not display correctly.
  • A unique alarm in CIMPLICITY is defined by the Alarm ID, Resource ID and Reference ID combination.

Each unique alarm can be displayed as a distinct entry in the Alarm Viewer.

If the actual point alarm is in alarm state and displays in the Alarm Viewer, using the same alarm ID in:

  • AlarmGenerateEx will generate a separate alarm from the point alarm.
  • AlarmUpdateEx will acknowledge and/or reset the actual alarm depending on the command(s).

Note: If only the generated alarm is listed AlarmUpdateEx will acknowledge and/or reset that alarm.

  • Non-unique alarms are stacked, so that the user only sees the most recent occurrence. In general, the Resource ID is used to control the routing of alarms to users.
  • The Reference ID is used by an application to distinguish between different instances of the same alarm.