AlarmSumFirst | Alarm Functions

Cicode Programming Reference > Cicode Function Categories > Alarm Functions > AlarmSumFirst

AlarmSumFirst

Gets the index of the oldest alarm summary entry. You can use this index in the AlarmSumGet() function to get field data from an alarm record, in the AlarmSumSet() function to change the existing data in that record, or in the AlarmSumDelete() function to delete the record.

To work with a series of alarm summary records, call this function to get the index, and then call AlarmSumNext() within a loop, to move forwards in the alarm summary.

This function can only be used if the Alarm Server is on the current machine. When the Alarm Server is not in the calling process, this function will become blocking and cannot be called from a foreground task. In this case, the return value will be undefined and a Cicode hardware alarm will be raised.

Note: The index passed to AlarmSum* functions must be current. ie either:
- the index returned by most recent call to AlarmSumFirst/Last/Find/Next/Prev, OR
- the index returned by the most recent call to AlarmSumAppend OR AlarmSumSplit

Syntax

AlarmSumFirst( [ClusterName] )

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 index of the oldest alarm summary entry, or -1 if no alarm summary entry is found.

Note: The index is a 32-bit integer. Storing it in a variable that is smaller than 32 bit integer (such as a 16-bit integer) may cause overflow which may result in an incorrect value.

Related Functions

AlarmSumCommit, AlamSumDelete, AlarmSumSet, AlarmSumType, AlarmSumAppend, AlarmDelete, MsgRPC, AlarmSumGet, AlarmSumNext, AlarmSumLast, AlarmSumPrev, AlarmSumFind, AlarmSplit,AlarmSumSplit

Example

/* This function finds all alarm summary entries that match the 
specified tag and sets the "OffTime" to the time specified. The 
alarm entry is not acknowledged or set to the off state, the alarm 
summary "OffTime" field is all that is affected. */


FUNCTION
SumSetTime(STRING sTag, INT Time)
    INT Index;
    STRING Name;
    Index=AlarmSumFirst();
    WHILE Index<>-1 DO
        Name=AlarmSumGet(Index,"Tag");
        IF Name=sTag THEN
            AlarmSumSet(Index,"OffTime",Time);
        END
        Index=AlarmSumNext(Index);
    END
END