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

manual	title	edition	version	status
IM 36K10L50-01EN	Data Set Service Engineering	3rd Edition, Sep. 2023	R1.03	process layout, dss.sup, dssqld directives (macro, include, memo from file), dssutl read and the dataset notes checked on the test system 2026-10-01; dssana.sup tabs from docs (covered by skill authorization); dsschk see IM36K10J10 notes

Data Set Service Engineering (R1.03)

DSS (Data Set Services) is the layer through which every CI Server tool and user interface reads and changes configuration and run-time data: items, alarms, classes, users, history, reports … all appear as datasets (tables of records with fields). dssqld, the Engineering Module, REPORT Service, ODBC and the Java/PROCESS APIs are all DSS clients. Section numbers refer to the manual; "installed" means checked on the R1.03.00 test system.

1. Building blocks (§1)

Part	Process / file	Job
API	linked into every client	Opens datasets, talks to the core over the BUS Service (DUR/MDUR)
Manager	DSSMAN (one per node)	Hands each client a DSSSDA/DSSEVT instance (the one it already uses, else the least loaded) and cleans up when clients or servers disappear
Data access	DSSSDA (several, -n <name>)	Executes read / insert / update / delete through the mapping layer
Events	DSSEVT (several, -n <name>)	Event channels (change notifications, flow control) to clients
Locks	DSSLCK (-c clears all locks)	Record locks on the dataset's primary node; frees locks of vanished processes/nodes
Watch	DSSWTH	Creates the DSS shared memory and the authorization/user files, copies dictionary changes from the host node to other nodes, cleans up after crashed clients, moves memo "file containers"
Mapping layer	PML + data access servers (dsilib:dsid_das_*)	Maps a dataset onto ISAM files or another service (ITEM, HISTORY, ALARM …)
Data dictionary	%TLS_DAT_PATH%\tlsdic_dss.dic	Description of every dataset and field; built by the DSS compiler (IM36K10P30-01EN.md) on the host node only
Tools	dssqld, dssutl, dsschk, dssxdb	Quick load/export, interactive read/modify, consistency check/repair, debugger (service use)

DSS processes start with DATABASE Service (tls\com\database_start.cmd). Installed: besides DSSWTH, DSSANA, DSSANC, DSSADB, DSSLCK, DSSMAN and the dsschk -s server, the script starts DSSSDA00–03 (count from %TLS_MAX_SDA_ID%, default 3), DSSSDAOPC00–03, DSSSDAPRC, DSSSDAOPX (and DSSSDAEEM on an enterprise engineering server) and DSSEVT00–03, DSSEVTOPC, DSSEVTPRC, DSSEVTFTE — 10 dsssda.exe and 7 dssevt.exe on the test system, more than the manual's "about 5 per node" advice. On the very first start (database.new) the script compiles all tls\src\*.dss into the dictionary (dss -d -q -u).

2. Tuning — dss.sup (§2.2)

Heartbeats and DUR queue sizes per process (DSSEVT_HBEAT, DSSSDA_QUESZ …), PML dataset cache time (DATASET_CACHE_TIME, 600 s), client event slots (EVENT_Q_SLOTS, 100), flow-control interval (FLOWC). DSSSDA_SRV = <node|-1>, "<client>", "<DSSSDA name>" ties clients to a dedicated DSSSDA (start that instance in the start script first).

Installed dss.sup: DSSEVT_QUESZ = 1000, DSSSDA_QUESZ = 252, FLOWC = 120; DSSSDA_SRV routes OPCEXE1–4, OPCACT, OPCJACT, OPCLOA, ALNMGR to DSSSDAOPC00–03, OPX* to DSSSDAOPX, PRC* to DSSSDAPRC, everything else (*) to DSSSDA00–03; DSSEVT_SRV lines do the same for events. Further undocumented keywords: EXCL_ACC_EXCEPTION_PROCESS, CLOG_EXCEPTION_PROCESS, CLOG_EXCEPTION_DATASET (a long list of run-time datasets).

3. Authentication — dssana.sup (§2.3)

DSSANA keeps the list of logged-in users and decides who may start which user interface from where. The Setup File Editor tabs: General (logout retain time 1440 min, max logged-in / logged-out users, max 5 UIs per remote client, password hashing Maximal), User Interfaces (each UI, e.g. JWUIGED = Edit Module, with the hosts/logins allowed and the authorization action needed), Clients System Trust (host/IP list, Always or Deny, top-down, <remote> / <local> last), Login control (per client and UI: Automatic, Manual CI Server, Manual OS, No, SSO, Deny; profile for No login; failed-login delay 5 s), Active Directory and Single Sign On (phase 13), Password rules (length, digits, punctuation, mixed case; all off by default), Logging (Basic/Extended/Maxima into tls\log\dssana.log, cyclic, 10 MB). Practical use: skill authorization (users-groups.md, login methods).

4. Quick load files and dssqld (§3)

File format (.qli): ! comment lines; marker lines starting with @ (@<DATASET>, @MACRO, @INCLUDE, @LANGUAGE, @SELECT, @FIELDS); data lines with comma-separated fields; \ at the end of a line continues it. Unquoted text is upper-cased, quoted text kept; "" inside a string is a quote. Escape character, separator and continuation character can be changed in dssqld.sup.

Directive	Use	Verified
@FIELDS	Field list for the next dataset block only; missing fields get defaults (dssqld -f)	yes (all phases)
@SELECT	Filter for the next dataset on export only, in single quotes, strings in double quotes	yes (ISS-003)
@MACRO	<name>,<text…>; later occurrences of the name are replaced (nesting ≤ 10); must come before the data	yes: field list as macro
@INCLUDE	One file name per line (.qli default), nesting ≤ 10	yes
@LANGUAGE	ENGLISH makes a file load on any language version	yes (all sample files)

Field types: string, number, date/time (exported as "dd-mm-yyyy hh:mm:ss", the form to load), interval ("10 Minutes", "1 Days", "1 Weeks"), memo (@""@ empty, @" … "@ inline text, or @"<file>"@ text from a file).

Installed — memo from a file: the file name is read on the server side, so a relative name fails (CRL-E-ENOENT); an absolute path works but is limited to 82 characters (DSSG-E-STRBUFSMAL). Inline memos are the safer choice (ISS-046).

Options: -i insert, -m modify, -r remove, -e <out> [<qli>] export (all datasets except the NO-EXPORT list in dssqld.sup, or what the qli names), -c CSV, -a concealed fields, -d one dataset, -f dictionary report, -l listing, -s setup file. Exports may need reordering before re-import (circular references: stations ↔ items, first-out groups, classes). %TLS_DAT_PATH%\dss_export.qli is a ready-made export list. Task files: skill system-management (export-dataset.md, load-remove-records.md).

5. dssutl (§4)

Interactive menu tool to read and modify single records via the primary index: choose a dataset (numbered list), a field set (Primary index only, All fields or a saved selection of ≤ 20 fields), then Read equal, Read sequential or Modify (change fields, Perform update). Installed: works with piped answers; values are shown raw (dates as seconds since 1970 in local time, intervals as <count>.<unit>, e.g. 10.1 = 10 minutes, 1.3 = 1 day; memos as their file path). Modifying data on a running system affects running applications — prefer dssqld -m. Task: skill system-management, dss-tools.md.

6. Consistency (dsschk, §5)

dsschk -s (server, started per node) and the client dsschk [-d <set>] [-n <node>] [-e] [-r] [-v] (extended test, repair, verbose). See IM36K10J10-01EN.md and task consistency-check.md.

7. Dataset notes (Appendix 1)

Special behaviour per dataset (only the ones not covered elsewhere): ALARM_ASA_DF compiles when COMPILE is set; ALARM_CURRENT only ACK can change; ARCHIVE_COMMAND drives the archive engine (initialise/mount/register tape, manual archive, retrieve, cancel; phase 9 notes); AUDIT_EVENT_CLAS_DF only STORAGE changes; AUTH_ACTION_DF, DATASET_*, HOST_NODE_DF, LOCAL_NODE_DF read-only; CLASS_DF COMPILE/RESET; DISPLAY_DF / SYMBOL_DF names only, insert copies a template, REBUILD; FOLDER_DF deletable only when empty; HIS_GROUP_DF only item groups can be added, FORCE_ROLLOVER; HIS_UNITS deleting a record deletes the unit; ITEM_HISTORY always needs ITEM_NAME, inserts only into Direct groups, no events; ITEM_VAL value/status/quality (BLOCKED_UPDATE for blocked items, status must be written too over ODBC); OBJECT_DF prompts via ATTR_VALUE_n, DEBUG; OPC_SERVER_DF / OPC_STATION_TAG_DF read with mandatory filter; PRINTER_* devices/destinations (written by the printer manager for _OVV and _TYPE); REPORT_DF / REPORT_VAL see IM36K10C30-01EN.md; SEQUENCE_DF COMPILE; STATION_DF REDUN_LINE.