ci-server-engineer/knowledge/manuals/IM36K10L25-01EN.md

manual	title	edition	version	status
IM 36K10L25-01EN	Audit Trail Management Engineering	3rd Edition, Sep. 2023	R1.03	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; the same events from Manual / Auto on CIENG_Control, 2026-10-06). 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.