AlarmSumSplit

Splits the alarm summary entry identified by index.

On operation success, the OffTime of the current alarm summary entry is filled with specified OnTime. Meanwhile, a new alarm summary entry is raised with the specified OnTime and no OffTime.

Note: This function will only work while the record is writable which is controlled by the ArchiveAfter Parameter. Refer to the topic Configure the Archiving Parameters in the main help for more information.

The operation represents a logical split at the specified OnTime to an active alarm instance. You can use this function to add a comment related to the specified OnTime.

The alarm summary entry must not have OffTime, or the function would return -1 and do nothing.

The function is 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.

This function can only be used if the alarm server is on the current machine. If the Alarm Server is not in the calling process, the calling process needs to run from the same machine as the alarm server.

In a redundant pair scenario, the function would return error condition and do nothing if the current server is not main. You can call this function on both the primary server and the standby server so that function can succeed on one of the two servers in the specified cluster. The change will be synchronized to the other server after a short period of time (typically in 5 seconds).

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

AlarmSumSplit(Index [, ClusterName, OnTime, OnMilli, bRedundant=true] )

Index:

The alarm summary index (returned from the AlarmSumFirst(), AlarmSumNext(), AlarmSumLast(), AlarmSumPrev(), AlarmSumAppend(), or AlarmSumFind() function).

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 "".

OnTime:

The alarm OnTime (if omitted or is equal to 0, will default to current time, i.e. the time the function was invoked).

OnMilli:

Milliseconds part of the alarm's ON time

bRedundant:(optional)

New alarm record is created on both redundant server instances.This parameter has been deprecated and is always set to true.

Return Value

The Index of the new entry, or -1 on error.

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, AlarmSumFind, AlarmSplit

Example

/* This function finds the first alarm summary entry that matches 
the specified tag, splits that entry and then adds the specified 
comment to the new entry. */

FUNCTION
AlarmSplitAdd(STRING Tag, STRING Comment)
    INT Index;
    STRING Name;
    Index=AlarmSumFirst();
    WHILE Index<>-1 DO
        Name=AlarmSumGet(Index,"Tag");
        IF Name=sTag THEN
            AlarmSumSplit(Index);
            Index=AlarmSumFirst();
            AlarmSumSet(Index,"Comment",Comment);
            Index=-1;
        ELSE
            Index=AlarmSumNext(Index);
        END
    END
END
			

See Also

Alarm Functions

Published June 2018