GetAlarms

Register a callback to receive a list of active alarms from an alarm server.

Function

void GetAlarms(server: string, port: int, pageIndex: int, pageSize: int, callback: function, useHttps: bool)

Parameters

• server (string): the server portion of the alarm server url.
• port (int): the port portion of the alarm server url.
• pageIndex (int): which page of alarms to get – starts counting from 1.
• pageSize (int): how many alarms per page of alarms.
• callback (function): receives the response from the alarm server.
• useHttps (bool): if true, https will be used to retrieve alarms. Defaults to false if not specified, which uses http.

Callback

The function passed to [name] through the callback parameter is passed one argument.

function callback(alarms) { /* ... */ }
SYM3.GetAlarms("localhost", 20013, 1, 100, callback);

If alarms is undefined, then the alarm server could not be contacted. Otherwise it contains the list of active alarms based on the parameters given to [name]. That is to say, if alarms is an array with a length of zero, then the server reported that there were no active alarms matching the parameters given.

For example, if you made the following call to your alarm server:

SYM3.GetAlarms(host, port, 1, 10, callback); 

And there were 8 active alarms, you would receive an alarms with a 8 entries in it. If you were to then make the following call, and the set of active alarms had not changed in the meantime:

SYM3.GetAlarms(host, port, 2, 10, callback);

You would be asking for alarms 11-20, and as in this example there are only 8 alarms, you would receive an array with a length of zero, because there’s not enough alarms to make a second page.

Alarm Object

The objects that make up the entries of the alarms array given to the callback are structured as follows:

{
    equipmentName: string;
    message: string;
    onTime: string;
}

Fields:

• equipmentName (string): the equipment name that this alarm is associated with, appropriate to pass to AttachTooltip etc.
• message (string): the message associated with this alarm.
• onTime (string): an ISO 8601 date string of when this alarm was triggered.

The contents of these fields depends on how your project is set up. For example, if your alarms aren’t associated with equipment in your project, then equipmentName will be null. Any field that is not present in the data returned by the alarm server will be null. If you do not have control over the alarm server you are querying, then be sure to verify that the fields are present before trying to use them.

Example

Try to list the first 42 active alarms from a locally running alarm server to the console.

function callback(alarms)
{
    if (alarms === undefined)
    {
        console.error("Could not contact alarm server.");
        return;
    }
    for (let i = 0; i < alarms.length; ++i)
    {
        let alarm = alarms[i];
        let msg = `Alarm ${i+1}: `;
        if (alarm.equipmentName !== null)
        msg += `equipment:${alarm.equipmentName} `;
        if (alarm.message !== null)
            msg += `message:${alarm.message} `;
        if (alarm.onTime !== null)
            msg += `onTime:${alarm.onTime}`;
        console.log(msg);
    }
}
SYM3.GetAlarms("localhost", 20013, 1, 42, callback);