AlmQuery

Technical Reference > CtAPI Functions > Function Reference > AlmQuery

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:

hCtapi: Handle to a valid CtAPI client instance.
szTableName: Command string for the almquery, see below.
szFilter: Not used for Almquery. Just pass in NULL.
hObject: Handle to the first record retrieved for the query.
dwFlags: Not used for Almquery. Just pass in 0.

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

Syntax

`ALMQUERY,Database,TagName,Starttime,StarttimeMs,Endtime,EndtimeMs,Period'

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.

Database:

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

TagName:

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.

Starttime:

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

StarttimeMs:

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

Endtime:

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

EndtimeMs:

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

Period:

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.

DateTime: The time of the alarm sample in seconds since 1970 as an integer. This Time is in UTC (Universal Time Coordinates).
MSeconds: The millisecond component of the time of the trend sample as an integer. This value is in between 0 and 999.
Comment: The comment associated with the alarm sample as a string.
Value: The alarm value of the sample as an unsigned integer. See below for a detailed description of the alarm value. The alarm value contains information describing the state of the alarm at the time of the sample:

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:

Expired (0)- The alarm state information has expired. We no longer know what state the alarm was, we just know the alarm was on at this time. This occurs if you set the Citect.ini parameter [Alarm]SumStateFix = 0.
Deviation High (1)- The alarm has deviated above the Setpoint by more than the specified threshold.
Deviation Low (2)- The alarm has deviated below the Setpoint by more than the specified threshold.
Rate of Change (3)- The alarm has changed at a faster rate than expected.
Low (4)- The alarm has entered the low alarm range of values.
High (5)- The alarm has entered the high alarm range of values.
Low Low (6)- The alarm has entered the low low alarm range of values.
High High (7)- The alarm has entered the high high alarm range of values.

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

000 (0)- Digital tags for the alarm are off.
00A (1)- Tag A is on, B and C are off.
0B0 (2)- Tag B is on, A and C are off.
0BA (3)- Tags B and A are on, C is off.
C00 (4)- Tag C is on, B and C are off.
C0A (5)- Tag C and A are on, B is off.
CB0 (6)- Tag C and B are on, A is off.
CBA (7)-Digital tags for the alarm are on.

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