ci-server-engineer/.claude/skills/alarm-management/tasks/item-alarming.md

---

task: Switch on alarming for an item, test an alarm, read and acknowledge alarms version: R1.05 (first written for R1.03) source: IM 36K10L15-01EN §2.1–§2.3, IM 36K10C20-01EN §A2, §A5, §A12 (4th editions, Feb. 2026; content as in the 3rd editions, Sep. 2023); IM 36K01A50 §1.16 (ODBC acknowledge, unchanged in the 5th edition); IM 36K10C50-01EN §2.22, §4.12 (custom acknowledgement, R1.04+); practiced on CI-Eng-Sample 2026-10-01 status: verified on R1.03 (2026-10-01). R1.05 - ITEM_DF alarm fields, STATUS_DF, ALARM_CURRENT and ALARM_CHRONO definitions identical to R1.03; the sample alarm on TANK1.LEVEL (ALARMING, CIENG_ACK, CIENG_TANKS) loaded with 0 errors on the R1.05 test server (2026-10-08, load check only). Raising, acknowledging, delaying and repeating an alarm were not re-tested on R1.05 (shared server). Custom acknowledgement with reason and approver - from docs, not tested (ISS-099). Re-tested on R1.05 2026-10-09 on the shared test server with the user's approval (temporary sample records, everything removed, before/after snapshot identical): raise, acknowledge via ALARM_CURRENT (two ACKNOW records), return to normal, DELAY 5 / REPEAT 10 (V10).

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.

4.1 Acknowledge with a reason and an approver (R1.04 and later, from docs)

From R1.04 an operator display can ask for a reason (up to 256 characters) and an approver (up to 128 characters) when an alarm is acknowledged; both are stored in the audit trail (AUDIT_TRAIL fields APPROVAL_REASON and APPROVER, present in the R1.05 data dictionary). The ALARM Service itself is unchanged: the alarm datasets and setup files are the same as on R1.03, and the acknowledgement still ends up as an ACKNOW event. Two ways, both built in the Edit Module (skill graphics, tasks/create-display.md; C50 §2.22, §4.12):

• the alarm overview's custom acknowledgement properties (Use Custom Acknowledgement, the External Acknowledgement group with alarm key, approver, reason and trigger) — for item alarms and external alarms;
• an Update item/parameter action on the item's Acknowledged attribute with reason and approver — item alarms only.

The record is written by the AUDIT Service, so check the audit settings (skill audit-trail). Not tested on either version (ISS-099): it needs a display change, which is not allowed on the shared R1.05 test server.

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 on R1.03 (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).

R1.05 (R1.05 test server)

• 2026-10-09 (V10, with approval, removed afterwards): same results as the R1.03 table. 50 → 85: status 10, options without ack, one ALARM_CURRENT row; acknowledged with dssqld -m (NAME,ACK) → ack back, two ACKNOW records (the second with the node name); back to 50 → NORMAL, ALARM_CURRENT empty. With DELAY 5 / REPEAT 10 and 27 s above the limit: DIRECT, DELAY +5 s, REPEAT +15 s and +25 s (RPT_COUNT 1, 2), NORMAL (unacknowledged), then a NORMAL with ack 1 after resetting DELAY/REPEAT. Note: an ALARM_CHRONO export with @FIELDS must include NAME (the primary index), otherwise DSS-E-PIDX_FST and nothing is exported. Alarm history and audit records of a test cannot be removed afterwards.

• 2026-10-08: the reduced sample load switched on alarming for TANK1.LEVEL (CIENG_ACK, CIENG_TANKS) with 0 errors and removed it again with 0 errors. This was a load check only: no alarm was raised or acknowledged.

• 2026-10-09 (read-only): ITEM_DF, STATUS_DF, ALARM_CURRENT and ALARM_CHRONO definitions, alm.sup, aldprt.sup and wfladi.sup (no DIRECT in EVENTS) are identical to R1.03, so the steps above are expected to behave the same. Awaiting user verification: steps 2–5 on a test item of a non-shared R1.05 system (expected results as in the table above).

• Read ALARM_CHRONO only with a filter on item name and a time range: big history reads load the alarm storage process that all clients share (ISS-136).