---
manual: IM 36K10L25-01EN
title: Audit Trail Management Engineering
edition: 3rd Edition, Sep. 2023
version: R1.03
status: processes, scripts, adtsys.sup, classifiers, ADT group, AUDIT_TRAIL contents, selection groups and ADTLOG (default and filtered) verified on the test system 2026-10-01; distributor, extra collectors, classifier extension in C and operator-side ITEM.* events from docs
---

# Audit Trail Management Engineering (R1.03)

AUDIT Service records who changed what and when: value and limit changes, definition inserts /
modifies / deletes, alarm acknowledgements, logins and logouts. Events are stored in the history
storage group `ADT` and read through dataset `AUDIT_TRAIL`. The manual is written for system
integrators (processes, setup file, extending the classifier tables in C). Section numbers refer
to the manual; "installed" means checked on the R1.03.00 test system.

## 1. Interfaces and data stores (§1)

| Interface / store | Use |
|---|---|
| Notification | Applications report an event (routine `adt_evt_not`); only one field of a stored event, the *modifiable ASCII application info*, can be changed afterwards |
| Distribution | Connected processes (AUDIT destinations) receive events as they are stored, optionally filtered by a selection group |
| Retrieval | Reading stored events (collector process; `AUDIT_TRAIL` dataset) |
| History management | Storage group `ADT` is managed by HISTORY Service (rollover, lifetime, units) |
| Event classifier file | Which event types exist and whether each is **stored** — dataset `AUDIT_EVENT_CLAS_DF` (`tls\dat\adt_ecl.dat`) |
| Selection group file | Named, compiled selection expressions — dataset `AUDIT_SELGRP_DF` (`tls\dat\adt_sgp.dat`) |

Single events cannot be deleted; only whole storage units or the whole group (HISTORY Service).

## 2. Processes (§1.2, §2, §4.1)

| Process | Job |
|---|---|
| `ADTSTO` (storage) | Creates group `ADT` if missing (rollover 1 day, unit lifetime 2 days), fills the classifier file with the basic set (existing entries kept), creates the selection group file, stores events, sends them to destinations. Ignores events while storage of `ADT` is stopped. Must run on the node of the history manager `HIS` |
| `ADTCOL01` (+ `ADTCOL02`…) | Answers retrieval requests, also while storage is stopped; extra images share the queue `adtcol01` (load sharing). Exits if group `ADT` does not exist, so `ADTSTO` must start first |
| `ADTDST` (distributor) | Optional relay on another node when several destinations there want events (3 + N instead of 3 × N BUS messages) |
| `ADTLOG` (logging) | Optional destination that prints events as text (stdout or `PRT_DEV`), optionally only a selection group |

Gaps are signalled with *missing events* records/messages (storage queue overflow, lost
connection, unexpected sequence number). Destinations check sequence numbers and periodic
flow-control messages; a missing flow-control message makes them reconnect.

**Installed:** `tls\com\audit_start.cmd` does nothing if `adtsto` already runs, refuses to start
when `his` is not running, then starts `adtsto -n adtsto` and `adtcol -n adtcol01`. `adtcol02`,
`adtlog` and `adtdst` are present as commented-out lines. `audit_stop.cmd` stops `adt*` with
`durstp`. Executables in `tls\exe`: `adtsto`, `adtcol`, `adtdst`, `adtlog`, `adtimport`
(undocumented), `adtxdb` (service debugger, not documented).

## 3. Event classifiers (§3.1, Appendix 1)

An event classifier is four names `<SUBJECT>.<ATTRIBUTE>.<ACTION>.<SOURCE>`, e.g.
`ITEM.VALUE.MODIFY.HMI`. Each name has an internal code; stored events keep only the codes, so
codes must never change once used.

- **Subjects**: ALN-DEST, ALN-USR, CLASS, CLASS-ATTR, DATASET, EQUIPMENT, F/T-SYSTEM,
  INSTALLATION, ITEM, OBJECT, OBJECT-ATTR, SECTION, STATION, SUB-ITEM, TRIGGER-GROUP, UNIT,
  USER-PROFILE, ACKNOWLEDGE-TYP.
- **Attributes** (about 170): item properties (VALUE, STATUS, HIGH-LIMIT, LOW-LIMIT, DESCRIPTION,
  ENGINERING-UNIT, ALARM-INHIBIT, ALARM-SHELVE, ENABLE-AUDIT-TR …), point/line properties,
  alarm notification users and schedules, NULL-ATTR (no attribute).
- **Actions**: ACKNOWLEDGE, DELETE, INSERT, LOGIN, LOGIN-ATTEMPT, LOGOUT, MODIFY, SHELVE,
  UN-SHELVE (the manual's explanations of SHELVE and UN-SHELVE are swapped).
- **Sources**: COMPUTE (PROCESS Service), DSS-CLIENT, ENT-EDIT-MOD, ENT-ENG-MOD, ENT-QUALIZATION,
  FTEXCHANGE, HMI (Engineering Module), LOC-EDIT-MOD, LOC-ENG-MOD, ODBC, OPC-DA-SERVER,
  OPER-INTERFACE, OTHERS, QUICKLOAD.

The notifying routine checks a cached copy of the classifier's **storage** flag and sends
nothing when storage is off; the cache refreshes every `ECL_REFRESH` seconds (default 1800), so
a change to the storage flag may take up to 30 minutes to reach running programs.

**Installed:** `AUDIT_EVENT_CLAS_DF` fields `NAME` (the four names joined), `SUBJECT`,
`ATTRIBUTE`, `AGITATION` (= action), `SOURCE`, `DESCRIPTION`, `BASIC_SET`, `STORAGE` (the only
changeable field); 463 classifiers, 444 stored. Off by default: the `COMPUTE` (PROCESS) source for
item/sub-item values, status, quality, limits, deadband, and `DATASET.NULL-ATTR.*.COMPUTE`. Not in
the manual: subject `CI-SERVER` (logins; the manual's `F/T-SYSTEM` is the old name), subject/action
`EAL OPERATION`, source `VIA-OPC-UAS` (ISS-051).

**What is actually recorded (verified):** configuration changes and DSS value writes are stored
as *dataset* events — `SUBJECT_GROUP` = dataset name (`ITEM_DF`, `ITEM_VAL`, `SECTION_DF` …),
`SUBJECT_ATTRIBUTE` = field, old and new value, user and source: `ENT-ENG-MOD` for `dssqld`
(not `QUICKLOAD`), `LOC-ENG-MOD` for the Engineering Module; every `dssqld` run also adds a
`CI-SERVER` `LOGIN`/`LOGOUT` pair. `itmval -p` writes are not audited. The item option
`AUDIT_INFO` (*Audit trailing wanted*, default 0; also on `SUB_ITEM_DF`, `EXTERNAL_ALARM_DF`) made
no difference for these tools; it switches the `ITEM.*` events of **operator writes**: a button on
display `CIENG_Tank` stored `ITEM.VALUE.MODIFY.OPER-INTERFACE` (old/new, user) with
`AUDIT_INFO` 1 and nothing with 0 (verified, ISS-049). A changed `STORAGE` flag takes effect only after the notifying process
re-reads it (`ECL_REFRESH`, up to 30 minutes, both directions; verified, ISS-050).

## 4. Setup files (§4.2)

Only `tls\sup\adtsys.sup` is installed; it documents every keyword and is the template for
per-process files named after the process (`adtsto.sup`, `adtcol01.sup`, `adtdst.sup`,
`adtlog.sup`, `adtovv.sup` for the chronological overview). Without a file, defaults apply.

| Tab / keyword | Meaning | Default |
|---|---|---|
| General `MAX_OPEN_UNITS` | Storage units open at once (2–100) | 20 |
| `PRT_DEV` | Printer for `ADTLOG` | stdout |
| `QUESIZE` | BUS queue size, kB | see below |
| `SEL_GROUP` | Selection group applied by the process | none |
| Node Numbers `COL_PROC`, `DST_PROC`, `HIS_PROC`, `STO_PROC` | `<node>, <name>` of collector, distributor, history manager, storage | local `ADTCOL01`, local `ADTSTO`, local `HIS`, `ADTSTO` on the host node |
| `NODE_ECL_FILE`, `NODE_SGP_FILE` | Node holding the classifier / selection group file | storage node |
| Layout `E_LAYOUT` | Message units and widths for the overview / log (`ACTM` time, `SBGP` subject, `SATR`, `SACT`, `SACS`, `SBID` subject id, `USER`, `TERM`, `OVAL`/`NVAL` old/new value, `REAS`, `AAI1`/`MAI1` application info, `ACND`/`ACNM`/`NOND`/`NONM`/`NOTM` node, program and notification time, `SPCE n`, `NWLN n`) | `SPCE,2,ACTM,21,SBGP,13,SATR,13,SACT,11,SACS,15,NWLN,1,SPCE,4,SBID,40,USER,16,NWLN,1,SPCE,6,OVAL,35,NVAL,35,NWLN,1` |
| `E_NOSPACE` | No automatic space between units | off |
| `TIMEFMT` | Picture for `ACTM` (`YYYY MMM DD hh mm ss ppp`) | see below |
| Events `ECL_REFRESH` | Classifier cache refresh, s | 1800 |
| `FLOWC` | Flow-control interval, timeout (s) | 30, 10 |
| `HBEAT` | Heartbeat, s | 10 |
| `TRYCON` | Reconnect interval, s | 10 |
| Header `FORM_FEED`, `HEADER` (repeatable), `HEADER_AFTER` | Log header | off / layout header / never repeated |

**Installed differences:** the `adtsys.sup` help says `QUESIZE` default 10 kB (minimum 10), the
manual says default and maximum 200 kB; the file sets `QUESIZE = 200`. The `TIMEFMT` default is
`DD/MM/YY hh:mm:ss` in the file help and `DD/MM/YY hh:mm:ss.ppp` in the manual; `ADTLOG` prints
milliseconds, so the manual is right (ISS-051). Also installed: `adtini.sup` (licence value only),
and `fmfprt.sup` assigns the printer function `AUDIT_TRAIL` to `ADTLOG`.

**Verified:** `adtlog -n <name>` run from a console prints new events with the default layout;
with a setup file `<name>.sup` holding `SEL_GROUP`, `E_LAYOUT`, `TIMEFMT`, `HEADER`,
`HEADER_AFTER` it printed only the selected events in the custom layout (sample
`examples/CI-Eng-Sample/audit/adtlogci.sup`).

## 4a. Selection groups (not described in the manual)

`AUDIT_SELGRP_DF`: `NAME`, `DESCRIPTION`, `EXPRESSION` (memo), `COMPILE`, `LISTING`,
`VALID_EXPRESSION`. The compiler listing names the language: string comparisons on `aai1 acnd
acnm actm mai1 nond nonm reas sacs sact satr sbgp sbid term user`, constant comparisons on `nval
oval`, operators `= != > < >= <=`, `and`, `or`, parentheses; no `LIKE` (prefix match with a range
`>= "X." and < "X/"`). Errors: `ADTT-E-UNKNOWN_TOK`, `ADTT-E-CMP_NO_SUCC`. Verified.

## 4b. Reading the trail

`AUDIT_TRAIL` (key `NAME` = `<action time>/<stamp>`; all fields read-only except `PROFILE` and
`APPLICATION_SUB`) is in `dssqld.sup` `NO-EXPORT`: export with `-d AUDIT_TRAIL` or a qli that
names it — the qli export returns 0 records unless `NAME` is in `@FIELDS`; `@SELECT` accepts
`LIKE "X.*"`. RQL `select … from audit_trail` works in reports (sample `CIENG_AUDIT`). `ADT`
group on the test system: lifetime 52 weeks, rollover 1 day. Task files: skill `audit-trail`.

## 5. Extending classifiers (§4.3)

New subjects/attributes/actions/sources are added in C: `#define` codes ≥ `0x80000000` in
`adt_ece.h`, names starting with `_`, rebuild `adt_ece()` (`tls\src\adt_ece.c`) and re-link AUDIT,
INTEGRATION, DATABASE Service and every program that uses it. **Installed:** `adt_ece.c`,
`tls\inc\adt_ece.h`, `audit_compile.cmd`/`.mak`, `audit_build.cmd`/`.mak` are shipped. System
integrator work; not practiced.