AlarmCountEquipment

Counts the available alarms for specified equipment and referenced equipment in conjunction with the selected filter criteria.

Syntax

LONG AlarmCountEquipment(INT Type [,STRING EquipmentFilter, [STRING FilterCriteria [, LONG KeepAliveSeconds [, INT CachedMode, [INT IncludingReference]]]]])

nType:

The type of alarms to display:

Non-hardware alarms

0 - All active alarms, that is Types 1 and 2

1 - All unacknowledged alarms, ON and OFF

2 - All acknowledged ON alarms

3 - All disabled alarms

4 - All configured (non-hardware) alarms, that is Types 0 to 3, plus acknowledged OFF alarms.

Hardware alarms

5 - All active alarms, that is Types 6 and 7

6 - All unacknowledged alarms, ON and OFF

7 - All acknowledged ON alarms

8 - All disabled alarms

9 - All configured alarms, that is Types 5 to 8

Alarm General

11 - All ON alarms

12 - All OFF alarms

13 - All ON hardware alarms

14 - All OFF hardware alarms

17 - All unacknowledged ON alarms

18 - All unacknowledged OFF alarms

If you omit the Type, the default is 1.

EquipmentFilter:

A comma-separated list of equipment names or categories (RefCat) to filter alarms prior to applying the other filter specified on the FilterCriteria argument. This field has been extended to support wildcards, and hence accept partial filter strings.

Filtering using an equipment name or category (RefCat):

Expression has been extended to allow:

• "EQUIPMENT=XYZ" (this may have an asterisk as the last character, which is interpreted as a wildcard). This restricts the result to only equipment that match this filter. Multiple "EQUIPMENT=" elements are treated as having an "OR" condition. This filter is evaluated on the client.

• "REFCAT=XYZ" (this may have an asterisk as the first and/or last character, these are interpreted as wildcards). This restricts the result to only equipment that match this filter, however, this filter is applied after any equipment filters and reference expansions have taken place. Multiple "REFCAT=" elements are treated as having an "OR" condition, and these in turn are treated as having an "AND" condition with the "EQUIPMENT=" elements. This filter is evaluated on the client.

• "PAGE=XYZ" (this is an exact literal match only). This restricts the result to only those equipment that match this filter. This filter cannot be combined with other equipment filter elements. This filter is evaluated on the server.

What this means is:

• "XYZ" is equivalent to "EQUIPMENT=XYZ*"

• "PAGE=PageXYZ" includes all the equipment that have "PageXYZ" in the PAGE field in the Equipment table.

Note: FIlters that take the form "XYZ" should no longer be used. It is recommended you use the "EQUIPMENT=XYZ" form, further "XYZ" can now be expressed as "EQUIPMENT=XYZ,EQUIPMENT=XYZ.*" as this will include all items on the "XYZ" equipment and all items on sub-equipment of the "XYZ" equipment.

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) that the count will remain in memory. Default is 30 seconds.

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 count in memory will be accessed when its filter criteria matches a subsequent filter criteria and the count’s KeepAliveSeconds period will be extended.

A count 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 count will be overridden in the event a longer duration is set using KeepAliveSeconds.

A count that is added to the cache is not immediately available for reading, so a foreground call to AlarmCount 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 Alarm Count for current equipment

1 - Include alarms belonging to referenced equipment in Alarm Count for current equipment. This is set by default.

Return Value

Returns counted alarms for the selected filter criteria. Returns -1 when an error is detected.

Example

// counts all unacknowledged alarms, ON and OFF (default non-blocking Cicode) in Plant.Area.Room* equipment and any lower-level equipment.
iRet = AlarmCountEquipment(1, "Plant.Area.Room");

// counts all disabled alarms (default non-blocking Cicode) in any lower-level equipment from Plant.Area.
iRet = AlarmCountEquipment(3, "Plant.Area.");

// counts all unacknowledged alarms in Plant.Area.Room*, Plant.Area.Flat* equipment and any lower-level equipment with category 10 (non-blocking Cicode)
iRet = AlarmCountEquipment(1, "Plant.Area.Room, Plant.Area.Flat", "Category=10", 1, 1);

// counts all unacknowledged alarms in Plant.Area.Room.*, Plant.Area.Flat.* equipment and any lower-level equipment with category 10 (non-blocking Cicode).
// Note that Plant.Area.Room and Plat.Area.Flat equipment themselves do not count as a period is given at the end of each expression.
iRet = AlarmCountEquipment(1, "Plant.Area.Room., Plant.Area.Flat.", "Category=10", 1, 1);

Related Functions

AlarmCount, AlarmCountList

See Also

Alarm Functions