AlarmSumFind

Finds the alarm summary index for an alarm that you specify by the alarm record identifier and alarm activation time (OnTime). 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. If calling this function from a remote client, use the MsgRPC() function.

To work with a series of alarm summary records, call this function to get the index, and then call either AlarmSumNext() to move forwards in the summary, or AlarmSumPrev() to move backwards in the 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

AlarmSumFind(Record, OnTime [, ClusterName] )

Record:

The alarm record number, returned from any of the following alarm functions:

• AlarmFirstCatRec() or AlarmNextCatRec() - used to search for a record by alarm category, area, and type (acknowledged, disabled, etc.).
• AlarmFirstPriRec() or AlarmNextPriRec() - used to search for a record by alarm priority, area, and type (acknowledged, disabled, etc.).
• AlarmFirstTagRec() or AlarmNextTagRec() - used to search for a record by alarm tag, name, and description.

To store this value, use data type Int in Cicode or Long for variable tags (Long needs 4 bytes).

OnTime:

The ON time of the alarm associated with the Record, that is, the time that the alarm was activated.

AlarmSumFind() requires that the OnTime argument contains the number of seconds from Midnight, so the formulation:

iOnTime = StrToTime(AlarmSumGet(iIndex, "OnTime"));

will NOT yield the correct result. The correct formulation for this calculation is:

OnTime = StrToTime(AlarmSumGet(iIndex, "OnTime")) + TimeMidnight(TimeCurrent());

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 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, AlarmSumFirst, AlarmSumNext, AlarmSumLast, AlarmSumPrev, AlarmSplit, AlarmSumSplit

Example

/* This function sets the summary comment from the alarm record
			number and the ontime of the summary event. */
FUNCTION
SumSetComment(INT AN, STRING sComment)
    INT nRecord;
    INT iOnTime;
    INT hAlarm1;
    STRING AlmTag;

    AlmTag = AlarmGetDsp(AN, "Tag");
    iOnTime = StrToDate(AlarmGetDsp(AN,"OnDate"))+StrToTime(AlarmGetDsp(AN,"OnTime"));
    hAlarm1 = MsgOpen("Alarm", 0, 0);
    MsgRPC(hAlarm1, "AlmSvrSumSetComment", "^"" + AlmTag + "^"," + IntTostr(iOnTime) + ",^"" + sComment + "^"", 1);
    MsgClose("Alarm", hAlarm1);
END

FUNCTION 
AlmSvrSumSetComment(STRING AlmTag, INT iOnTime, STRING sComment)
    INT nRecord = AlarmFirstTagRec(AlmTag, "", "");
    INT Index = AlarmSumFind(nRecord, iOnTime);
    IF Index <> -1 THEN
        AlarmSumSet(Index, "Comment", sComment);
    END
END

See Also

Alarm Functions

Published June 2018