AlarmGenerateEx (method)

  • Syntax.
  • Guidelines.
Syntax AlarmGenerateEx Project$ , AlarmId$ , ResourceId$ , Message$, DateTime, IsUTC [ , UserId$ [ , RefId$ [ , Master]]]
Parameter Description
Project$ String. The project to generate 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 generate the alarm against. Used to control routing of the alarm.
Message$ String. The generated alarm message to display. Note: This string is substituted into the first variable field of the alarm's configured message.
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.
UserId$ String (optional). The User ID that generated 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 slave computer's Event Manager are ignored. To allow an alarm to be generated from a script on a slave computer, set Master to True.
CimBasic Example 1 
'This example displays the syntax.
Sub Main()
theDate = Now()
    AlarmGenerateEx "PROJECT01","ALARM501","$SYSTEM","Device 501 needs attention.", theDate, FALSE
End Sub
Example 2 ''This example displays time in microseconds. 
Sub Main()
TheDate = #2012/1/12 10:49:0# + 0.000002
AlarmGenerateEx "FORSHOW","MYALARM","$MAC_FR","Hello", TheDate, true
End Sub
.NET C# Example 1 
//This example displays the syntax.
public void Main()
{ DateTime dt = new DateTime(2012, 06, 18, 2, 5, 5); Cimplicity.AlarmGenerateEx("TESTER","TESTALARMGEN","$SYSTEM","csAG Test",dt, true)}
Example 2 
//This example displays time in microseconds.
public void Main()
    {
            DateTime dt = new DateTime(2012, 7, 1, 0,0,0,123);
// Add One extra millisecond + a few Nano100seconds (10000 milliseconds in a Nano100Seconds)
            dt = dt.AddTicks(10100);
            Cimplicity.AlarmGenerateEx("FORSHOW","MYALARM","$MAC_FR",".net", dt, false);
    }
VB .NET Example 
'This example displays the syntax.
Public Sub Main()
            Dim DT1 As DateTime
            DT1 = New DateTime(2012,7,1,15,30,22,123)
            Cimplicity.AlarmGenerateEx("ALARMGENERATEUPDATE","CB1","$SYSTEM","Test VB alarm", DT1, False)
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.