--- manual: IM 36K10L50-01EN title: Data Set Service Engineering edition: 3rd Edition, Sep. 2023 version: R1.03 status: 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 `) | Executes read / insert / update / delete through the mapping layer | | Events | `DSSEVT` (several, `-n `) | 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 = , "", ""` 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, `` / `` 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 `@` (`@`, `@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` | `,`; 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 `@""@` 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 []` 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 `.`, 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 ] [-n ] [-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`.