---
task: Switch on alarming for an item, test an alarm, read and acknowledge alarms
version: R1.03
source: IM 36K10L15-01EN §2.1–§2.3, IM 36K10C20-01EN §A2, §A5, §A12; IM 36K01A50 (ODBC acknowledge); practiced on CI-Eng-Sample 2026-10-01
status: verified
---

# Item alarming

Sample file: `examples/CI-Eng-Sample/16_item_alarm_df.qli` (loaded with `dssqld -m`).
The item needs limits (`LOW_LOW_LIMIT`, `LOW_LIMIT`, `HIGH_LIMIT`, `HIGH_HIGH_LIMIT`, skill
`item-engineering`); its status then follows the value and maps to an alarm state through
`STATUS_DF` (installed: HIGH 10 → Alarm 2 prio 2, HIGH HIGH 11 → Alarm 3 prio 1, LOW/LOW LOW
likewise, NORMAL 9 → Normal prio 15).

## 1. Switch on alarming (modify the item)

```
@FIELDS
NAME,ALARMING,ACKN_TYPE,AOI_1

@ITEM_DF
"<Section>.<Tag>",1,"<ACK_TYPE>","<AOI_NAME>"
```

Other `ITEM_DF` alarm fields: `ALARM_INHIBIT`, `DELAY`, `REPEAT` (seconds, 0 = off),
`DIAG`, `FO_GROUP` + `FO_ITEM`, `COL_GROUP` (first-out **or** collection, not both),
`ITEM_STAT_n` / `ALARM_STATE_n` / `PRIORITY_n` / `ALARM_TEXT_n` / `ALARM_COLOR_n` /
`MNEMONIC_n` / `SHELVE_ENABLED_n` (n = 1–6, per-item status overrides).

Any change of these fields makes ALM send a NORMAL event (acknowledged automatically when the
item is normal): it **clears a pending unacknowledged return to normal**. Avoid changing alarm
settings of items with standing alarms without the operator knowing.

Check: `almdbg` 14 → `<Section>.<Tag>` shows *Alarm monitoring: yes*, the ack type number,
repeat and delay (`alarm-checks.md`).

## 2. Test an alarm (test items only)

```
itmval -g -n <Section>.<Tag>            # note the value to restore
itmval -p -n <Section>.<Tag> -v <value above HIGH_LIMIT>
itmval -g -n <Section>.<Tag>            # Status 10 (HIGH), Options without "ack"
```

Unacknowledged alarms lose the `ack` option word; `t1` / `t2` appear while an alarm is direct
or delayed.

## 3. Read current alarms and history

Filter file (one per dataset), then `dssqld -e <out>.qli <filter>.qli -c`:

```
@SELECT
'ITEM_NAME = "<Section>.<Tag>"'
@ALARM_CURRENT
```

- `ALARM_CURRENT`: standing alarms and unacknowledged returns to normal. Key `NAME` =
  `"<DD-MON-YY hh:mm:ss.mmm>/<id>"`; useful fields `ALARM_TIME`, `ALARM_ORIG_TIME`,
  `ALARM_ACK_TIME`, `OLD_VALUE`, `NEW_VALUE`, `PRIORITY`, `RPT_COUNT`, `ACK`, `OLD_STATUS`,
  `NEW_STATUS`, `EVENT_TYPE`, `ALARM_TEXT`, `OLD_STATE`, `NEW_STATE`.
- `ALARM_CHRONO` (history; only exported when named): same fields; add a time range for big
  histories, e.g. `'ITEM_NAME = "<Section>.<Tag>" and ALARM_TIME > "01-10-2026 11:00:00"'`.

## 4. Acknowledge from a script

```
@FIELDS
NAME,ACK

@ALARM_CURRENT
"<NAME from the export>",1
```

`dssqld -m` → summary *Modified 1*; the item gets `ack` again, history gets an `ACKNOW` event
(plus a second `ACKNOW` with the node name when `alm.sup` has `ACK_INFO`). Use the `NAME` key,
not `ITEM_NAME` (same rule as the ODBC known issue, IM 36K01A50). Acknowledging is an operator
action: only with the user's approval.

## 5. Delay and repeat

`DELAY` = d: DIRECT at once, DELAY after d seconds (same original time); back to normal earlier
gives NORMAL and no DELAY. `REPEAT` = r: REPEAT every r seconds after the (delayed) alarm,
`RPT_COUNT` 1, 2, …. The current alarm overview shows DIRECT only if `wfladi.sup` `EVENTS`
contains `DIRECT` (not installed by default).

## Verified (CI-Eng-Sample `TANK1.LEVEL`, limits 10/20/80/90, ack type `CIENG_ACK` = MANUAL matrix)

| Step | Result |
|---|---|
| `ALARMING` 1 loaded | `NORMAL` event, ack 1 |
| 44.4 → 85 | Status 10, `ALARM` HIGH Normal → Alarm 2, prio 2, `ACK` 0; in `ALARM_CURRENT` |
| Acknowledge via `ALARM_CURRENT` | `ack` option back; two `ACKNOW` records |
| 85 → 50 after ack | `NORMAL`, acknowledged automatically, `ALARM_CURRENT` empty |
| 50 → 95 → 50 without ack | `ALARM` HIGH HIGH (Alarm 3, prio 1), `NORMAL` stays in `ALARM_CURRENT` with `ACK` 0 until acknowledged |
| `DELAY` 5, `REPEAT` 10, 50 → 85 for 27 s | `DIRECT` 11:36:57, `DELAY` 11:37:02, `REPEAT` 11:37:12 and 11:37:22 (`RPT_COUNT` 1, 2), `NORMAL` 11:37:24 |
| Reset `DELAY`/`REPEAT` to 0 while the NORMAL was unacknowledged | new `NORMAL` event with ack 1; alarm gone from `ALARM_CURRENT` |
| Full sample remove/reload | 0 errors; the alarm test passed again |

No alarm line from `ALDPRT` appeared in `umhlog.log` (ISS-035).