AlarmHighestPriority

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.

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 Implement Alarm Filters Using Cicode 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:

• 1 - On and Unacknowledged

• 2 - Off and Unacknowledged

• 3 - On and Acknowledged

• 4 - Disabled

For Mode 3, return the current setting for the alarm server's Highest Priority Order field:

• 0 - Priority, Alarm State

• 1 - Alarm State, Priority

Example

INT nPriority;

INT nState;

INT nCombined;

INT nSetting;

// Priority of highest priority alarm in Plant.Area.Room* equipment and all referenced equipment (default non-blocking Cicode).

nPriority = AlarmHighestPriority(0, "Plant.Area.Room");

// Alarm state of highest priority alarm in Plant.Area.Room* equipment and all referenced equipment (default non-blocking Cicode).

nState = AlarmHighestPriority(1, "Plant.Area.Room");

// State and Priority of highest priority alarms in Plant.Area.Room*, Plant.Area.Flat* equipment and all referenced equipment with category 10 as a two-byte integer (non-blocking Cicode).

nCombined = AlarmHighestPriority(2, "Plant.Area.Room, Plant.Area.Flat", "Category=10", 1, 1);

nPriority = LowByte(nCombined);

nState = HighByte(nCombined);

// Current setting for the alarm server's Highest Priority Order field

nSetting = AlarmHighestPriority(3);

Related Functions

AlarmCount, AlarmCountEquipment, AlarmCountList

See Also

Alarm Functions