cliu
83af63ab53
Full manual diffs (C50, R30, C60, L20, C40, L35, R10, R20, J10, L30, L50, P30, G10, C10) and read-only checks on the shared R1.05 test server where the permission system allowed them. Skills and summaries moved to R1.05. Issues ISS-092..129 (gaps 104-107, 114-115, 130-131 unused); ISS-074 closed (manual and software agree), ISS-091 corrected by ISS-119. version-differences: unlisted manual changes and installed-only changes. r105-verification: V5-V9 and new not-tested rows. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
153 lines
11 KiB
Markdown
153 lines
11 KiB
Markdown
---
|
||
manual: IM 36K10L50-01EN
|
||
title: Data Set Service Engineering
|
||
edition: 5th Edition, Feb. 2026 (R1.05); first written from the 3rd Edition, Sep. 2023 (R1.03). Changed since: R1.04 App. 1 (OPC UA client method dataset renamed to OPCUAC_METHOD_CALL2_DF); full text diff: otherwise only §3.9 `-c` wording, same meaning
|
||
version: R1.05 (first written for R1.03)
|
||
status: R1.03 (2026-10-01): process layout, dss.sup, dssqld directives (macro, include, memo from file), dssutl read and the dataset notes checked on the test system; dssana.sup tabs from docs (covered by skill authorization); dsschk see IM36K10J10 notes. R1.05 (2026-10-08, read-only on the test server): processes, database_start.cmd, dss.sup, dssqld.sup, dssqld help text, dataset definitions and dsschk -e -v re-checked; macro/include/memo loads and dssutl not re-run
|
||
---
|
||
|
||
# Data Set Service Engineering (R1.05)
|
||
|
||
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`).
|
||
|
||
**R1.05 (installed, 2026-10-08), not in the manual:** 12 `dsssda.exe` and 7 `dssevt.exe`. The
|
||
script starts `DSSSDA00`–`03` as fixed lines (`%TLS_MAX_SDA_ID%` no longer read) plus two new
|
||
dedicated servers: `DSSSDARST` for the RESTful API server (`JRSTSRV`) and `DSSSDAPY` for pyTOOLS
|
||
(`PYDSS*`). After an upgrade (`database.new`) it runs the R1.04/R1.05 dataset conversion
|
||
programs (`*_u0104`, `*_u0105`, e.g. `opcuac_method_u0104`, `dss_ath_grp_u0104`,
|
||
`iec61850_rcb_u0105`) and keeps `database.new` when one fails so the conversion is retried at
|
||
the next start. It ends by calling `?*_database_start.cmd` extension scripts.
|
||
|
||
## 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).
|
||
|
||
**R1.05 `dss.sup`:** `DSSSDA_QUESZ = 1000` (was 252), new `DSSMAN_QUESZ = 1000`, and
|
||
`DSSSDA_SRV` lines for `JRSTSRV` → `DSSSDARST` and `PYDSS*` → `DSSSDAPY`; rest unchanged.
|
||
|
||
## 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 (identical on R1.05; it does not
|
||
cover the IEC 61850, MQTT, OPC UA client method/tag, `UASERVER_MAPPER_DF` or `API_KEYS_DF`
|
||
datasets). R1.05 `dssqld.sup` adds `NO-EXPORT=API_KEYS_DF`; `dssqld -h` text is identical to
|
||
R1.03. Exporting `OBJECT_DF` on R1.05 leaves about one 0-byte `dss_*.tmp` per object in
|
||
`tls\lst` (not removed by CI Server). 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`.
|
||
|
||
**R1.04/R1.05 datasets** (manual App. 1 and the installed `tls\src`, 2026-10-08): the OPC UA client
|
||
method dataset is now `OPCUAC_METHOD_CALL2_DF` (App. 1, R1.04; replaces
|
||
`OPCUAC_METHOD_CALL_IN_DF` and `OPCUAC_METHOD_CALL_OUT_DF`, both gone). New definitions not in
|
||
App. 1: `API_KEYS_DF` (API keys per user), `UASERVER_MAPPER_DF` (OPC UA Information Model Mapper
|
||
project), `IEC61850_RCB_DF` (IEC 61850 report control blocks), `ALARM_ATTRIBUTE_TEMP_DF` (alarm
|
||
attributes; purpose not documented). Changed definitions include `ITEM_VAL` (new fields
|
||
`ENG_UNIT`, `SCALE_HIGH_LIMIT`, `SCALE_LOW_LIMIT`), `AUTH_GROUP_DF` (`ACTION_NAME_1`…`250`
|
||
instead of …`200`), the IEC 104 / IEC 61850 datasets, several OPC UA client/PubSub
|
||
datasets, `EXTERNAL_ALARM_DF`, `AUDIT_TRAIL` and `dss_global.dss` (OPC UA node ID type
|
||
`OPAQUE`, parameter-type template for methods). Practical use: skills `data-access` and
|
||
`equipment`.
|