Returns the alarm priority and/or state of the current highest priority alarm for the given equipment in conjunction with the selected filter criteria.
Syntax
LONG AlarmHighestPriority(INT Mode [, STRING EquipmentFilter] [, STRING FilterCriteria] [, LONG KeepAliveSeconds] [, INT CachedMode] [, INT IncludingReference])
Mode
0 - return the priority of the highest priority alarm.
1 - return the alarm state of the highest priority alarm.
2 - return the results of mode 0 and 1 combined into a two-byte integer result. Use LowByte() to extract the priority of the highest priority alarm and use HighByte() to extract the alarm state of the highest priority alarm.
3 - return the current setting for the alarm server's Highest Priority Order field ("Priority, Alarm State" or "Alarm State, Priority").
4- Same as mode 0. Alarm Priorities where Show on Indicator is set to False are excepted.
5- Same as mode 1. Alarm Priorities where Show on Indicator is set to False are excepted.
6- Same as mode 2. Alarm Priorities where Show on Indicator is set to False are excepted.
For more information about the field Show on Indicator refer to the topic Configure Display Properties for an Alarm Priority in the main help.
EquipmentFilter:
A comma-separated list of equipment names to filter alarms prior to applying the filter specified in the FilterCriteria argument. Each equipment name may be a part of full equipment name from the root. For example, "Region.Plant" will count alarms with equipment names literally starting with "Region.Plant" that includes "Region.PlantA" and "Region.Plant.AreaB". If it is needed to count children of a particular equipment tree only, the equipment name should end with a period('.'). A comma in between equipment expressions is regarded as an OR operator. If an empty string is specified, return Highest Priority for all Alarms.
FilterCriteria:
A filter name OR filter text. See the topic Implementing Alarm Filters Using Cicode in the main Citect SCADA help for more information about filter syntax.
KeepAliveSeconds:
Optional length of time (in seconds) for which the count will remain in memory. Default is 30 seconds.
The CachedMode parameter affects the behavior of this parameter. Refer to the section below for more information.
CachedMode:
Optional flag that causes the current cached value to be supplied even when the value is being refreshed. This makes the function non-blocking. If the property has not yet been cached, an error is set.
0 - Do not force cached read. Cicode is blocking
1 - Force cached read. Cicode is non-blocking
Default value is 1 (true).
A priority value in the cache is accessed when its filter criteria matches the filter criteria in a subsequent call, and the priority value's "KeepAliveSeconds" duration is extended. A priority will stay in the cache for 'at least' the duration specified by "KeepAliveSeconds", and may stay in the cache for an unspecified period of time before being discarded.
The period set for an existing priority will be overridden in the event a longer duration is set using "KeepAliveSeconds".
A priority that is added to the cache is not immediately available for reading, so a foreground call to AlarmHighestPriority that causes a new count to be added will return a value of -1 and an error of 345 (Data not ready).
IncludingReference:
0 - Do not include alarms belonging to referenced equipment in AlarmHighestPriority for current equipment
1 - Include alarms belonging to referenced equipment in AlarmHighestPriority for current equipment. Set to 1 by default.
Type:
The rule used to determine the relative priority of alarms (currently fixed to 0).
Return Value
For Mode 0, return the priority ID of the current highest priority alarm.
For Mode 1, return the alarm state of the current highest priority alarm:
For Mode 3, return the current setting for the alarm server's Highest Priority Order field:
Related Functions
Example
// Priority of highest priority alarm in Plant.Area.Room* equipment and all referenced equipment (default non-blocking Cicode).
iRet = AlarmCountEquipment(0, "Plant.Area.Room");
// Alarm state of highest priority alarm in Plant.Area.Room* equipment and all referenced equipment (default non-blocking Cicode).
iRet = AlarmCountEquipment(1, "Plant.Area.Room");
// Priority of highest priority alarms in Plant.Area.Room*, Plant.Area.Flat* equipment and all referenced equipment with category 10 (non-blocking Cicode).
iRet = AlarmCountEquipment(0, "Plant.Area.Room, Plant.Area.Flat", "Category=10", 1, 1);
// Alarm state of highest priority alarms in Plant.Area.Room*, Plant.Area.Flat* equipment and all referenced equipment with category 10 (non-blocking Cicode).
iRet = AlarmCountEquipment(1, "Plant.Area.Room, Plant.Area.Flat", "Category=10", 1, 1);
See Also
Published June 2018