Technical Reference > CtAPI Functions > Function Reference > AlmQuery


Provides an interface into the alarm summary archive from external applications, replacing the old CtAPIAlarm query. AlmQuery performs significantly better than CtAPIAlarm.

AlmQuery is performed through the same mechanism as CtAPIAlarm. To establish the query and return the first record, you call ctFindFirst. Then, to browse the remaining records, you call ctFindNext. To access the data of the current record, ctGetProperty is called for each field of the record.

ctFindFirst is called with the following parameters:

The szTableName is the command string for the query and contains the parameters for the query.



Note: Arguments need to be comma-separated. Spaces between arguments are supported but not necessary. We recommend no spaces between arguments as they require more processing and take up more space in the query string.


The Alarm database that the alarm is in (alarm type). The following databases are supported: DigAlm (Digital), AnaAlm (Analog), AdvAlm (Advanced), HResAlm (Time Stamped), ArgDigAlm (Multi-Digital), ArgAnaAlm (Argyle Analog), TsDigAlm (Time Stamped Digital), TsAnaAlm (Timestamped Analog).


The Alarm tag as a string. This query only supports the retrieval of alarm data for one alarm at a time. Although it is supported by CitectSCADA, do not declare two different alarms with the same tag and of the same type. You will not be able to retrieve the alarm data for both as this query expects the combination of alarm type (database) and tag to be unique.


The start time of the alarm query in seconds since 1970 as an integer in UTC time.


The millisecond portion of the start time as an integer. It is expected to be a number between 0 and 999.


The end time of the alarm query in seconds since 1970 as an integer in UTC time.


Millisecond portion of the end time as an integer. It is expected to be a number between 0 and 999.


Time period in seconds between the samples returned as a floating point value. The only decimal separator supported is the `.'.

Return Value

The maximum number of samples returned is the time range divided by the period, plus 3 (one for the sample exactly on the end time, and two for the previous and next samples).

Note: Divide the period evenly into the time range, otherwise one extra sample may be returned.

The AlmQuery does not return interpolated samples in periods where there were no alarm samples. However, to stay within the allowable number of samples, the raw alarm samples will be compressed when more than one sample occurs in one period.

When this compression occurs, the returned sample is flagged as a multiple sample. The timestamp is then an average of the samples within the period. The value and comment returned reflects that of the last sample in the period.

The following properties are returned for each data record of the query.

bGood (Bit 0)- Future use only, intended to show when the quality of the alarm data goes bad. At the moment every sample has this bit set to 1 to say the sample is good.

bDisabled (Bit 1)- 1 if the alarm is disabled at the sample's time, 0 otherwise.

bMultiple (Bit 2)- 1 if the alarm sample is based on multiple raw samples, 0 if it is based on only 1 raw sample.

bOn (Bit 3)- 1 if the alarm is on at the sample's time, 0 otherwise.

bAck (Bit 4)- 1 if the alarm is acknowledged at the sample's time, 0 otherwise.

state (Bits 5 - 7)- Contains the state information of the alarm at the sample's time.

The alarm state represents the different states of the different alarm types. The state only contains relevant information if the alarm is on.

For analog, Argyle analog, and time-stamped analog alarms the state can be as follows:

For Multi-Digital Alarms the state can be as follows:

For the rest of the alarm types ignore the state information.