Counts the available alarms for the selected filter criteria.
Alarm counts will display and update at different rates depending on how extensively they are used in your system. Consider the number of counts being used on pages, combined with the number of clients using those pages at any one time. The number of configured alarms will also contribute to the alarm count update rate. For example on a system with 50,000 configured alarms and 10 clients displaying a page with 100 alarm counts, the alarm count update rate will be degraded.
This function is a blocking function if CachedMode is set to zero (0).
Syntax
LONG AlarmCount(INT Type [, STRING FilterCriteria [, LONG KeepAliveSeconds [, INT CachedMode]]])
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 Summary
10 - All summary alarms
15 – Sequence of events with configuration events filtered out
16 - Sequence of events
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.
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) 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).
Return Value
Returns counted alarms for the selected filter criteria. Returns -1 when an error is detected.
Example
INT iRet, iErr; // return values
INT iCountWhile=0; // loop counter
// counts all unacknowledged alarms, ON and OFF, default non-blocking cicode
iRet = AlarmCount(1);
iErr = IsError(); //check error code
// repeat the above non-blocking function
INT iCountWhile=0; // loop counter
WHILE (iRet = 0) AND (iErr = 0) AND (iCountWhile < 10) DO
SleepMS(100);
iRet = AlarmCount(1);
iErr = IsError();
iCountWhile = iCountWhile + 1;
END
// counts all disabled alarms, default non-blocking cicode
iRet = AlarmCount(3);
iErr = IsError();
// repeat this non-blocking function as shown above (see while loop)
// counts all unacknowledged alarms with category 10 – non-blocking cicode
iRet = AlarmCount(1,"Category=10",1,1);
iErr = IsError();
// repeat this non-blocking function as shown above (see while loop)
// counts all unacknowledged alarms with category 10 – blocking cicode
iRet = AlarmCount(1,"Category=10",1,0);
IF iRet = -1 THEN
iErr = IsError(); // get error code)
END
// counts all unacknowledged tag alarms of equipA without it's children equipment
// and keeps the count in memory for 3 seconds - blocking cicode
// (where is equipment structure is equipA.equipB.equipC.equipD)
iRet = AlarmCount(1,"Equipment=equipA",3,0);
IF iRet = -1 THEN
iErr = IsError(); // get error code)
END
// counts all acknowledged ClusterA tag ON alarms of equipA and it's children equipment
// and keeps the count in memory for 3 seconds - blocking cicode
// (where is equipment structure is equipA.equipB.equipC.equipD)
iRet = AlarmCount(2,"Equipment=equipA*;cluster=ClusterA",3,0);
IF iRet = -1 THEN
iErr = IsError(); // get error code)
END
// counts all active tag alarms of equipB and it's children equipment
// and keeps the count in memory for 3 seconds - non-blocking cicode
// (where is equipment structure is equipA.equipB.equipC.equipD)
iRet = AlarmCount(0,"Equipment=equipA.equipB*",3,1);
iErr = IsError()
// counts all ON alarms of equipB and it's children equipment
// and keeps the count in memory for 3 seconds - non-blocking cicode
// (where is equipment structure is equipA.equipB.equipC.equipD)
iRet = AlarmCount(11,"Equipment=equipA.equipB*",3,1);
iErr = IsError()
// This example shows how to count the alarms using a named filter
// This example requires that the named filter "Myfilter" exists.
INT nActiveAlarmType;
INT nCount;
INT nError;
nCount = AlarmCount(nActiveAlarmType, "MyFilter");
IF nCount greater 0 THEN
nError = IsError();
ELSE
nError = 0;
END
Related Functions
See Also
Published June 2018