Searches for the first occurrence of an alarm priority and type. You can search all areas, the current area only, or specify an area to limit the search.
This function returns an alarm record identifier that you can use in other alarm functions, for example, to acknowledge, disable, or enable the alarm, or to get field data on that alarm.
Note: Record numbers obtained from AlarmGetDsp are not valid for this function.
This is a blocking function. If the function is called from a foreground task that is unable to block, the return value will be -1 and a hardware alarm set. Use IsError() to retrieve the error code.
Note: This function will return a match for an Acknowledge Off alarm with [Alarm]AckHold=1 even after it has been cleared using AlarmClear or AlarmClearRec.
Syntax
LONG AlarmFirstPriRec(INT Priority, INT Type [, INT Area] [, STRING ClusterName] )
Priority:
The alarm Priority or group handle of a group of alarm priorities. Set Priority to 0 (zero) to match all alarm priorities.
The number of alarms to display.
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.
Area:
The area in which to search for alarms. If you do not specify an area, or if you set Area to -1, only the current area will be searched.
ClusterName:
Specifies the name of the cluster in which the Alarm Server resides. This is optional if you have one cluster or are resolving the alarm server via the current cluster context. The argument is enclosed in quotation marks "".
Return Value
The alarm record identifier or -1 if no match is found. If you do not specify an area, only alarms in the current area on the alarms server are searched.
Related Functions
GrpOpen, AlarmNextCatRec, AlarmNextPriRec, AlarmGetFieldRec, AlarmAckRec, AlarmDisableRec, AlarmEnableRec, AlarmGetThresholdRec, AlarmSetThresholdRec
Example
/* Acknowledge all unacknowledged (Type 1) alarms of the specified
alarm priority. */
FUNCTION
AutoAccept(INT iPriority)
INT iCurrent;
INT iNext;
iCurrent=AlarmFirstPriRec(iPriority,1,-1);
WHILE iCurrent <>-1 DO
iNext=AlarmNextPriRec(iCurrent,iPriority,1,-1);
AlarmAckRec(iCurrent);
iCurrent=iNext;
END
END
See Also
Published June 2018