cliu/ci-server-engineer
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Merge pull request 'Phase 0-1: system management skills and CI-Eng-Sample project' (#2) from docs/phase-0-1-system-management into main

Browse source 
Reviewed-on: cliu/ci-server-config#2
This commit is contained in:
Clio Liu 2026-09-30 14:04:38 +10:00
commit 2caf1c8590
34 changed files with 1448 additions and 10 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

5
.claude/skills/README.md
View file

@ -12,3 +12,8 @@ are not used for grouping; group tasks inside each skill instead:
The `description` in `SKILL.md` decides when Claude uses the skill. List the words users The `description` in `SKILL.md` decides when Claude uses the skill. List the words users
will actually say. will actually say.
Skills must work on any R1.03 system, so never use names from a particular system (items,
sections, stations, nodes). Write placeholders such as `<Section>.<Tag>` and, where an example
helps, use names from the sample project `CI-Eng-Sample` (`examples/CI-Eng-Sample/`).
Test-system evidence belongs in `knowledge/progress.md` and `knowledge/issues.md`.

95
.claude/skills/system-check/SKILL.md Normal file
View file

@ -0,0 +1,95 @@
---
name: system-check
description: >-
Read-only check of a CI Server machine, run before any CI Server work. Use when
the user asks which CI Server version is installed, whether CI Server is running, where it is
installed, whether time is synchronized, or before starting any task in another skill.
Also covers starting CI Server (needs administrator rights). Target version R1.03.
version: R1.03
source: IM 36K10J10-01EN §1.2, §1.4, §3.6, §3.7; practiced on the test system 2026-09-29/30
status: verified (2026-09-30)
---
# System check
Run this read-only check before any CI Server work. It changes nothing.
## 1. Installed version
PowerShell:
```powershell
$keys = @('HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\*','HKLM:\SOFTWARE\WOW6432Node\Microsoft\Windows\CurrentVersion\Uninstall\*')
foreach ($k in $keys) { foreach ($i in (Get-ItemProperty $k -ErrorAction SilentlyContinue)) { if ($i.DisplayName -match 'CI Server') { "{0} | {1}" -f $i.DisplayName, $i.DisplayVersion } } }
```
Expected for this repo: `CI Server R1.03.00 (r10200M) | 1.03.00`. Anything else: warn the
user that the repo targets R1.03.
**From the running system** (preferred when CI Server is running): export the local node
dataset and read `VERSION_MAJOR`, `VERSION_MINOR`, `VERSION_PACK` (1, 3, 0 = R1.03.00).
```
dssqld -e local_node.qli -d LOCAL_NODE_DF -c -l local_node.lst
```
Run it in a scratch folder; it only reads. The same row shows the node name, node number and
licence state (`NAME`/`NODE_NAME` = `UNLICENCED` means no licence is registered).
`dssqld -f -l dict.lst` dumps the full data dictionary (all datasets and fields) if you need
to find another dataset.
**Per-component versions** (rewritten at every start): `%TLS_ALLUSERS_PATH%\lst\tls_versions.lst`,
one line per component: `<file>,<version>,<size>,<build date>`. On the test system all 110
lines read `R1.03.00`; a different version on some lines means a patch is installed.
**Message log**: `%TLS_LOG_PATH%\umhlog.log` holds CI Server messages
(`--> From: <PROCESS> (<node>) on <time>` then `<FAC>-<I|W|E>-<CODE>, <text>`). Read it after
starting CI Server to spot errors (e.g. `EQP-E-SLV_COM_BAD` = no communication with a
station). It can contain connection strings with passwords; never copy those into the repo.
## 2. Install paths (environment variables)
| Variable | Typical value | Holds |
|---|---|---|
| `TLS_ROOT_PATH` / `TLS_ITROOT_PATH` | `C:\Program Files (x86)\Yokogawa\CIServer` | Program: `tls\com` (start scripts), `tls\exe` (tools), `tls\sup` (setup files) |
| `TLS_ALLUSERS_PATH` | `C:\Users\Public\Yokogawa\tls` | Data root |
| `TLS_DAT_PATH` | `…\tls\dat` | Database |
| `TLS_HIS_PATH` | `…\tls\his` | History |
| `TLS_SAV_PATH` | `…\tls\sav` | Saved data |
| `TLS_LOG_PATH`, `TLS_LST_PATH` | `…\tls\log`, `…\tls\lst` | Logs and listings |
| `TLS_WAP_PATH` | `…\tls\wap` | Web application files |
`tls\com` and `tls\exe` are on `PATH`, so tools such as `dssqld` and `itmval` run from any
prompt. Setup files (`*.sup`) are plain text (CRLF); edit them with the Setup File Editor.
## 3. Is CI Server running?
- Windows service `StartCIServer` ("CI Service"), start type Manual on the test system.
- Running processes live under `…\Yokogawa\CIServer\tls\exe`. None running = CI Server stopped.
- Most tools (`dssqld`, `itmval`, …) need CI Server running.
- Starting it needs administrator rights (the service runs as `.\CIX_PROCESS`, binary
`tls\exe\ciserv.exe`). From a non-elevated shell `Start-Service StartCIServer` fails with
"Cannot open StartCIServer service". Start it from an elevated prompt:
`Start-Service StartCIServer` (or Services › CI Service › Start).
- **Unlicensed systems shut down after about 1 hour.** All CI Server processes exit, the
`StartCIServer` service still shows *Running*, and every tool fails with
`umh_panic: <tool>, license expired`. To recover, **stop then start** the CI Service
(elevated): `Stop-Service StartCIServer` then `Start-Service StartCIServer`. Before a long
task on an unlicensed system, note the start time (`(Get-Process ciserv).StartTime`) and
restart first if the hour is nearly up.
## 4. Time synchronization
`w32tm /query /status` and `w32tm /query /configuration` (Windows Time must be running).
Check the source matches the design (domain controller, NTP server or `NOSYNC` on Vnet/IP).
## Test system results (2026-09-29)
- Version R1.03.00 (r10200M). Matches the repo.
- Environment variables and folders as in the table; all tools and setup files named in
IM 36K10J10 are present except `tmtime` (a Vnet/IP station tool, not expected here).
- CI Service stopped on 2026-09-29; started 2026-09-30 from an elevated session. About 100
processes then run (e.g. `ciserv`, `dssman`, `itm`, `alm`, `his`, `rptgen`, `opcexe`,
`durm_udp`, `eqpmdc`, `eqpmqtt`, `wfl*`).
- `LOCAL_NODE_DF`: version 1.3.0 (R1.03.00), node 1, **UNLICENCED**, router type Endpoint.
- Windows Time running, source `time.windows.com`; synchronized on 2026-09-30 (stratum 5).

33
.claude/skills/system-management/SKILL.md Normal file
View file

@ -0,0 +1,33 @@
---
name: system-management
description: >-
CI Server R1.03 system management and command-line tools. Use when the user wants
to stop CI Server, export dataset contents, load or remove records with quick load files
(dssqld, .qli), create sections or items in bulk, read or write item values or limits (itmval), load or import history,
check database consistency (dsschk), monitor processes/CPU/disk/network, back up or migrate
a system, tune or debug CI Server, or plan a system layout (standalone, separate portal, HAC,
host-to-host, enterprise) or time synchronization. Source IM 36K10J10-01EN.
---
# System management (R1.03)
Background for this area: `knowledge/manuals/IM36K10J10-01EN.md`. Known issues:
`knowledge/manuals/IM36K01A50-01EN.md`.
Rules for every task:
- Run the `system-check` skill first (version must be R1.03).
- CI Server tools live in `%TLS_ROOT_PATH%\tls\exe` (on `PATH`). Run them in a scratch folder,
because they write output and listing files to the current directory.
- Starting/stopping CI Server and anything that writes to the system needs an elevated
(administrator) session and, in this conversation, the user's chosen way of working
(direct vs prepare only).
| Task | File | Status |
|---|---|---|
| Export dataset contents (whole or filtered) / dump the data dictionary | `tasks/export-dataset.md` | verified |
| Load or remove records with quick load files (`.qli`), e.g. sections and items | `tasks/load-remove-records.md` | verified |
| Read / write item values and read limits | `tasks/read-write-item.md` | verified |
| Load history from CSV (`ithloahis`) and read history back | `tasks/load-history.md` | verified |
| Monitor CPU, disk, network, processes; run a command on an item change | `tasks/monitoring-processes.md` | verified |
| Database consistency check (`dsschk`) | `tasks/consistency-check.md` | verified (check only) |
| Tuning checks: limits and health snapshots | `tasks/tuning-checks.md` | verified (read-only) |

39
.claude/skills/system-management/tasks/consistency-check.md Normal file
View file

@ -0,0 +1,39 @@
---
task: Database consistency check (dsschk)
version: R1.03
source: IM 36K10J10-01EN §4.1.1; practiced on the test system 2026-09-30
status: verified (check only)
---
# Database consistency check (dsschk)
Needs CI Server running. Checking is read-only; **repair (`-r`) changes the database**:
back up first and ask the user.
## Check
```
dsschk -e -v > dsschk.out
```
- `-e` extended check: also compares the duplicated datasets on this node (e.g. item
definitions copied by ITEM and EQUIPMENT Services). This is the useful check on a
**single-node** system.
- `-v` verbose. Output lists `DSSP-I-CDS_START` / `DSSP-I-CDS_END` per dataset (228 on the
test system) and any problems; the same messages go to `%TLS_LOG_PATH%\umhlog.log`.
- `-d <dataset>` checks one dataset; `-n <node>` one node.
- Plain `dsschk` (no `-e`) only compares copies **between nodes**, so on a single node it
prints nothing.
Look for warnings or errors: search the output for `-W-`, `-E-` or `-F-`. None = consistent.
## Repair (not yet practiced)
From IM 36K10J10 §4.1.1: run `dsschk -r` until no more inconsistencies are reported (or the
same ones repeat), then `dsschk -e`, then `dsschk -e -r` (possibly twice). Read the output
carefully; some problems need manual work.
## ISAM files (not yet practiced)
`ismchk <database file>` checks one ISAM file; `ismkfr [-c] [-r] [-s] [-d] <file>` rebuilds
key files. Both need the file name (without it: `usage: ismchk data_base_name`).

70
.claude/skills/system-management/tasks/export-dataset.md Normal file
View file

@ -0,0 +1,70 @@
---
task: Export dataset contents with dssqld
version: R1.03
source: IM 36K10J10-01EN §2.9.2, §5.6; practiced on the test system 2026-09-30
status: verified
---
# Export dataset contents (dssqld)
Read-only. Needs CI Server running. Works from a normal or elevated prompt.
## Export a whole dataset
```
dssqld -e <output>.qli -d <DATASET> -c -l <listing>.lst
```
- `-d` dataset name (e.g. `ITEM_DF`, `STATUS_DF`, `LOCAL_NODE_DF`, `CLASS_DF`, `OBJECT_DF`).
- `-c` comma-separated output: first line is the field names, then one quoted row per record.
- `-l` writes the result summary to a listing file.
- `-a` also exports hidden fields.
The console (and listing) end with a summary; check `Errors` is 0:
```
Data set Recognized Exported Not found Errors
ITEM_DF 184 184 0 0
```
## Find datasets and fields
```
dssqld -f -l dict.lst
```
Dumps the data dictionary: every dataset with its description and fields (name, type, length,
description). Search it to find which dataset holds what, e.g. the version fields are in
`LOCAL_NODE_DF`, `HOST_NODE_DF` and `ENTERPRISE_SERVER_DF`.
## Useful datasets seen on R1.03
| Dataset | Contents |
|---|---|
| `LOCAL_NODE_DF` | This node: name, number, version (`VERSION_MAJOR/MINOR/PACK`), licence state |
| `ITEM_DF` | Item definitions: full name, section path, description, limits, format, type, station, I/O address |
| `STATUS_DF` | Item status definitions: name, number, alarm state, priority, colour, mnemonic (e.g. 9 = NORMAL) |
## Filtered exports
Export only matching records with a filter file (IM 36K10L50 §3.6, verified 2026-09-30):
```
@SELECT
'GROUP_NAME = "CIENG_EVENT"'
@HIS_GROUP_DF
```
```
dssqld -e <output>.qli <filter>.qli [-c] -l <listing>.lst
```
- `@SELECT`, then the filter in **single quotes** with strings in double quotes, then
`@<DATASET>`. The filter applies only to the next dataset. Operators: `=`, `!=`, `<`, `>`,
`and`.
- Some datasets (e.g. `ITEM_HISTORY`, `ITEM_VAL`, `ALARM_CHRONO`) are not exported unless
named explicitly (`NO-EXPORT` list in `dssqld.sup`).
- `ITEM_HISTORY` returns nothing unless the filter names `ITEM_NAME` and a `SAMPLE_TIME` range
(see `load-history.md`).
- `%TLS_DAT_PATH%\dss_export.qli` is Yokogawa's own filter file for exporting all engineering
definitions (`dssqld -e out.qli dss_export.qli`); it also shows `@MACRO` usage.

77
.claude/skills/system-management/tasks/load-history.md Normal file
View file

@ -0,0 +1,77 @@
---
task: Load item history from CSV (ithloahis) and read history back (dssqld)
version: R1.03
source: IM 36K10J10-01EN §2.9.2; IM 36K10L50-01EN §3.6; practiced with CI-Eng-Sample 2026-09-30
status: verified
---
# Load item history (ithloahis) and read it back
**Writes to the history database.** Needs CI Server running and the items linked to an
item storage group of type *Event/Item* or *Event/Event*. The sample project provides
`CIENG_EVENT` with `CI-Eng-Sample.TANK1.LEVEL` and `.INFLOW`.
## Before loading
- A **new** storage group stores nothing until CI Server has been restarted (stop, then start
the CI Service). Restart after creating a group.
- Only samples dated **after the start of the current storage unit** were stored; older ones
were silently skipped (see `knowledge/issues.md` ISS-006). A restart starts a new unit.
## Input files
Event file: one sample per line.
```
EVENT
<time>,<item>,<value>
1790739700,CI-Eng-Sample.TANK1.LEVEL,47
```
Scan file: several items per line (max 100), one line per timestamp.
```
SCAN,CI-Eng-Sample.TANK1.LEVEL,CI-Eng-Sample.TANK1.INFLOW
1790739715,61,101
1790739720,62,102
```
Time is seconds since 1970 (UTC), optionally with a fraction, or a date text such as
`29-Apr-14 11:48:17.452`. Quotes and spaces around fields are optional. A blank value in a
scan line is skipped.
## Load
```
ithloahis -f <file>.csv -v
```
- `-v` shows progress (`Handle event based table`, `item … on column n`).
- `-t GMT|LST|LCT` sets how text times are read (default GMT).
- `-s <section>` puts a section in front of every item name.
- `-i` also updates the item's current value (can raise alarms and trigger objects; loads the
system). Without it, only history is written.
## Read history back
`ITEM_HISTORY` is not exported by default; use a filter file that names the item **and** a
time range, otherwise nothing is returned:
```
@SELECT
'ITEM_NAME = "CI-Eng-Sample.TANK1.LEVEL" and SAMPLE_TIME > "30-09-2026 00:00:00" and SAMPLE_TIME < "01-10-2026 00:00:00"'
@ITEM_HISTORY
```
```
dssqld -e history.qli <filter>.qli -c -l history.qlo
```
Result columns include `NAME` (`<group>:<item>/<time>/Value`), `SAMPLE_TIME`, `ITEM_VALUE`,
`QUALITY`. Values written live (e.g. with `itmval -p`) and the value at CI Server start also
appear.
## Verified (CI-Eng-Sample, 2026-09-30)
SCAN load of LEVEL 61–63 / INFLOW 101–103 and EVENT load of LEVEL 47, 48 were all read back
with the filter above.

92
.claude/skills/system-management/tasks/load-remove-records.md Normal file
View file

@ -0,0 +1,92 @@
---
task: Load and remove dataset records with dssqld (quick load)
version: R1.03
source: IM 36K10J10-01EN §2.9.2, §5.6; IM 36K10L45-01EN §9.10–9.11; practiced with CI-Eng-Sample 2026-09-30
status: verified
---
# Load and remove dataset records (dssqld quick load)
**Writes to the CI Server database.** Needs CI Server running. Follow the user's chosen way
of working: in *prepare only* mode, write the `.qli` files and a `.cmd` script for the user to
run. Test on a test system first.
## Quick load file format (.qli)
```
@LANGUAGE
ENGLISH
@VERSION
1.03.00
! comment
@FIELDS
NAME,SECTION_PATH,SECTION_NAME,DESCRIPTION
@SECTION_DF
"CI-Eng-Sample","","CI-Eng-Sample","CI-Eng-Sample project"
"CI-Eng-Sample.TANK1","CI-Eng-Sample","TANK1","Sample tank 1"
```
- `@FIELDS` lists the fields in the records that follow; the next `@<DATASET>` line names
the dataset. A file can hold several `@FIELDS` / `@<DATASET>` blocks.
- One record per line, strings in double quotes, numbers bare, comma-separated. End a line
with `\` to continue the record on the next line (long `@FIELDS` lists can also wrap).
- Only the listed fields are set; the rest take their defaults. Required fields are marked
"Is required on import" in the data dictionary (`dssqld -f -l dict.lst`).
- Easiest way to get a correct template: export an existing dataset **without** `-c`
(`dssqld -e template.qli -d <DATASET>`); the output is already in this format.
## Load (insert)
```
dssqld -i <file>.qli -l <file>.qlo
```
Summary per dataset: `Recognized`, `Imported`, `Exists` (already present, left unchanged),
`Errors`. Check `Errors` is 0; the `.qlo` listing holds the same result.
## Update (modify)
```
dssqld -m <file>.qli -l <file>.qlo
```
Changes the listed fields of existing records (the key field plus the fields to change).
Summary: `Modified`, `Not found`, `Errors`. Verified by setting a storage group's `STOP_TIME`.
## Remove (delete)
```
dssqld -r <file>.qli -l <file>.qlo
```
The file only needs the key field (`@FIELDS` `NAME`). Summary: `Removed`, `Not found`, `Errors`.
**Storage groups** (`HIS_GROUP_DF`) cannot be deleted while they have an active storage unit
(`HIS-E-GROUPHASUNT, Group still has an active unit connected`). First remove the items from the
group (`ITEM_HIS_DF`), then set the group's `STOP_TIME` a minute ahead with `-m`, wait until it
has passed, then delete the group. Deleting a group deletes its history.
## Order matters
- Load parents before children: sections (parent before child) → template items → classes
(compiled) → objects → other items (IM 36K10J10 §5.6) → storage groups → items in storage
groups (`ITEM_HIS_DF`, record name `<group>:<item>`).
- Remove in reverse: items from storage groups, storage groups (stop first), items, sections
(children before parents).
- A **new storage group stores nothing until CI Server is restarted**.
- Linking items to a group straight after creating it failed once with 2 errors; a 5 s pause in
between has been reliable (`knowledge/issues.md` ISS-005).
- Put each step in a `.cmd` script so the order is repeatable. Run scripts by full path
(`cmd /c "<path>\load.cmd"`); a bare name may not be found from the current folder.
## Verified example
`examples/CI-Eng-Sample/` (`01_section_df.qli`, `02_item_df.qli`, `load.cmd`, `remove.cmd`):
sections, items, a storage group and its item links loaded, removed and loaded again with
0 errors. `remove.cmd` shows how to set the storage group stop time from a script (PowerShell
writes the `.qli`, then `Start-Sleep`; `timeout` fails when there is no console). Items need only
`NAME` and `ITEM_REP` (`Real`, `Integer`, `Boolean`, `String`); the sample also sets
`DESCRIPTION`, `VALUE_FORMAT`, limits and scale.

61
.claude/skills/system-management/tasks/monitoring-processes.md Normal file
View file

@ -0,0 +1,61 @@
---
task: Monitoring processes (intcpumon, intdskmon, inttcpmon, intmon, intspawn)
version: R1.03
source: IM 36K10J10-01EN §4.1.6; practiced with CI-Eng-Sample 2026-09-30
status: verified
---
# Monitoring processes
INTEGRATION Service processes that write system health into items, or run a command when an
item changes. Each is configured in its own setup file in `%TLS_ROOT_PATH%\tls\sup\`.
**Changes the system's setup files.** Back each file up first. Follow the user's chosen way
of working; in *prepare only* mode, write the lines for the user to add.
## Setup file format
Setup files are plain text (CRLF). Lines starting with `!` are comments and editor
definitions (`!KEYWORD : …` shows each allowed keyword and its arguments). Active settings are
plain `keyword = value` lines, usually added at the end. The Setup File Editor edits the same
files.
## Settings
| Process | Setup lines | Item value |
|---|---|---|
| `intcpumon` | `interval = 10`, `logging`, `CPU = "", "<item>", ""` | CPU load %. Empty system name = this machine; empty counter = total CPU |
| `intdskmon` | `interval = 10`, `logging`, `DISK = "C:\\", "<item>"` | **Used** % of the disk (61.9 on a disk 61.9 % used), despite the manual saying free space |
| `inttcpmon` | `logging`, `TCP = "<host>", "<item>"` | 1 while the host answers a ping |
| `intmon` | `process = "<process>", "<item>"` | 1 while the CI Server process runs (e.g. `alm`) |
| `intspawn` | `TRIGGER = "<command>", "<item>", VALUE, NONE, 0` | Runs the command with the new value as argument |
`intspawn` trigger modes: `VALUE`, `STATUS`, `OPTION`, `TIMER` (value = interval in s),
`NODE_DOWN`, `NODE_UP`, `NODE`; filters `NONE`, `EQUAL`, `GREATER`, `LESS` with the value.
**Keep the command path short**: a ~130-character path silently did nothing
(`knowledge/issues.md` ISS-007). `intmon` also supports `node = <n>, "<item>"`,
`channel = <line>, <node>, "<item>"` and `offline` (for multi-node systems, not tested).
Tested lines for the sample project: `examples/CI-Eng-Sample/monitoring/*.sup.txt`
(items `CI-Eng-Sample.SYSTEM.*`).
## Start and stop
These processes do not start by default.
- For a test, start by hand (elevated): `Start-Process "$env:TLS_ROOT_PATH\tls\exe\<process>.exe" -ArgumentList "-n <process>" -WindowStyle Hidden`.
Stop with `Stop-Process -Name <process>`. They also stop when CI Server stops.
- To start them with CI Server, add them to `%TLS_ROOT_PATH%\tls\com\integration_start.cmd`
(for `intmon`, uncomment its `start /b /normal …\intmon.exe -n intmon` line; for the others
add `start /B /NORMAL %TLS_ROOT_PATH%\tls\exe\<process> -n <process>` followed by
`start /B /NORMAL /WAIT %TLS_ROOT_PATH%\tls\exe\durwfp -p <process> -t 10`). Not yet tested.
## Check
Read the target items with `itmval -g -n <item>` (status 9 once updated). With `logging`, the
processes also write to `%TLS_LOG_PATH%\umhlog.log`.
## Verified (CI-Eng-Sample, 2026-09-30)
CPU_LOAD 33.4, DISK_C 61.9, PING_LOCALHOST 1, PROC_ALM 1; `intspawn` wrote 0 and 1 to a file
when `PUMP1.MODE` changed. Setup files restored afterwards.

68
.claude/skills/system-management/tasks/read-write-item.md Normal file
View file

@ -0,0 +1,68 @@
---
task: Read and write item values with itmval
version: R1.03
source: IM 36K10J10-01EN §2.9.2; practiced on the test system and CI-Eng-Sample 2026-09-30
status: verified
---
# Read and write item values (itmval)
Needs CI Server running. Reading is read-only. **Writing changes live data**: follow the
user's chosen way of working (direct vs prepare only) and never write to an item that drives
real equipment without explicit approval.
Item names are full paths: `<Section>.<Sub-section>.<Tag>`, e.g.
`CI-Eng-Sample.TANK1.INFLOW` from the sample project.
## Read the current value
```
itmval -g -n <Section>.<Tag>
```
Output:
```
Value = 130
Status = 9
Options = 0xffffff88.00 ack
Quality = 0
```
- **Status** is a number from `STATUS_DF` (export it with `dssqld -e status_df.qli -d STATUS_DF -c`
to look numbers up). Common ones: 9 `NORMAL`, 13 `NOT INIT` (never written; new items start
here), 4 / 5 `BOOLEAN 0` / `BOOLEAN 1`, 11 `HIGH HIGH`.
- **Options** lists item flags as words after the hex value, e.g. `ack` (acknowledged),
`off` (item's station not communicating). `uoff` also appears on station items after a write;
its meaning is not yet known (see `knowledge/issues.md` ISS-001).
## Read limits
```
itmval -g -n <Section>.<Tag> -a <n>
```
`<n>`: 1 deadband, 2 low, 3 high, 4 low-low, 5 high-high. The limit is returned in `Value`.
Items with no limits configured return `ITM-E-WRONG_ATT, Wrong attribute number used`.
## Write a value
```
itmval -p -n <Section>.<Tag> -v <value> [-s <status>] [-q <quality>]
```
- Read the item first and note its value, so it can be restored.
- Booleans take `-v 0` / `-v 1`; the status follows automatically (4 / 5).
- `-s` sets the status explicitly (e.g. `-s 9` NORMAL). Without it, a numeric write gives 9.
- `-o` overwrites a blocked item; `-t [<date>] <time> [GMT|LST]` sets the timestamp
(default local civil time); `-e` writes to event history only, not the current value.
- Read it back to confirm.
## Verified examples (CI-Eng-Sample)
| Command | Result |
|---|---|
| `itmval -p -n CI-Eng-Sample.TANK1.INFLOW -v 120.5` | Value 120.5, status 9 |
| `itmval -p -n CI-Eng-Sample.TANK1.INFLOW -v 130 -s 9` | Value 130, status 9 |
| `itmval -p -n CI-Eng-Sample.PUMP1.RUNNING -v 1` | Value 1, status 5 (BOOLEAN 1) |
| `itmval -g -n CI-Eng-Sample.TANK1.LEVEL -a 2` / `-a 3` / `-a 4` / `-a 5` | 20 / 80 / 10 / 90 |

44
.claude/skills/system-management/tasks/tuning-checks.md Normal file
View file

@ -0,0 +1,44 @@
---
task: Tuning checks (read-only)
version: R1.03
source: IM 36K10J10-01EN §5.5.1; practiced on the test system 2026-09-30
status: verified (read-only checks)
---
# Tuning checks (read-only)
Checks whether CI Server needs tuning. Nothing here changes the system. Changing the limits
means editing setup files and restarting CI Server: ask the user first.
## Limits in setup files (`%TLS_ROOT_PATH%\tls\sup\`)
Read the active (non-`!`) lines:
| File | Keyword | Meaning | Test system |
|---|---|---|---|
| `dur.sup` | `dur_max_proc` | Max processes (default 250) | 250 |
| `dur.sup` | `pool_kbytes` | DUR message pool | 250000 |
| `itm.sup` | `pool_kbytes` | Item common memory pool | 650000 |
| `database_start.cmd` (`tls\com`) | `-u` / `-f` | Max database users (default 2K) / files (default 1,200) | not checked |
## Live values: automatic health snapshots
CI Server's system monitor (`smdmon`) writes debugger snapshots about every 10 minutes to
`%TLS_LOG_PATH%\smd_<node>_<debugger>_*.log` (e.g. `smd_UNLICENCED_LOW_itmdbg_all.log`).
Read the newest entries:
| File | What to check | Target (IM 36K10J10 §5.5.1) |
|---|---|---|
| `*_itmdbg_all.log` | `common size` / `free size` | Free above 10 %, usage below 75 % |
| `*_smdsnp_process.log` | Per process: `queue_size`, `queue_used`, `queue_high` | No requests waiting (`queue_used` 0); enlarge a queue that stays in use |
| `*_ismdbg_all.log` | `Total number of lock collisions`, users, files | Collisions not rising above 250/s; entries below 80 % of max users |
| `*_smdsnp_process.log` | Number of processes | Well below `dur_max_proc` |
Test system (2026-09-30): common memory 665.6 MB, free 665.3 MB; queues empty; 3 lock
collisions in total.
## Not yet practiced
Debug launchers (`jwuipoi_debug`, `jhmiset_debug`, …), interactive debuggers (`itmdbg`,
`opcdbg`, `eqpdbg`, …), and per-process debug settings; see
`knowledge/manuals/IM36K10J10-01EN.md` §5.5.2.

44
CLAUDE.md
View file

@ -1,28 +1,52 @@
# CI Server Engineering Assistant # CI Server Engineering Assistant
You act as an experienced Yokogawa CI Server engineer. Users describe what they want to do You act as an experienced Yokogawa CI Server engineer. Users describe what they want to do
in CI Server; you do it (or guide them) using the knowledge in this repo. in CI Server; you do it (or prepare it for them) using the knowledge in this repo.
- **Target version:** CI Server **R1.03**. Say so if a request depends on another release. ## Before any CI Server work
- **Language:** use the English (EN) manuals only.
1. **Confirm the software version.** This repo covers CI Server **R1.03** (R1.03.00).
Check the installed version first (skill `system-check`). If it is not R1.03,
tell the user before doing anything and point out which content may not apply.
2. **Ask how the user wants to work** — once per conversation, before the first action:
- **Direct**: you make changes in CI Server yourself (run tools, edit setup files, load data).
- **Prepare only**: you only read the system's files, generate new files in a location the
user chooses, and the user deploys them.
Remember the answer for the rest of the conversation. Reading files and read-only checks
are always allowed.
## Where to look, in order ## Where to look, in order
1. **Skills**: `.claude/skills/<area>/`. There is one skill per CI Server area (e.g. Edit Module, 1. **Skills**: `.claude/skills/<area>/`. There is one skill per CI Server area (e.g. Edit Module,
Alarm Management). `SKILL.md` is an index; open only the task file you need. Alarm Management). `SKILL.md` is an index; open only the task file you need.
2. **Shared knowledge**: `knowledge/`. The document map, glossary, known issues and 2. **Shared knowledge**: `knowledge/`. Manual summaries (`knowledge/manuals/`), known issues,
system-wide concepts. system-wide concepts and the document map.
3. **Examples**: `examples/`. Verified, working artifacts to copy and adapt. 3. **Examples**: `examples/`. Verified, working artifacts to copy and adapt.
4. **The manuals**: if the repo does not cover it, look it up in the EN PDFs. They are **not**
in this repo. Default location: `C:\Users\Public\Yokogawa\tls\doc\EN\`. Use
`knowledge/document-map.md` to find the right manual by IM number.
If the answer comes from the manuals rather than the repo, say so and name the manual This repo is meant to be self-contained: the Yokogawa PDF manuals are only used while the
(IM number and section). Never guess CI Server behavior; say what you could not verify. repo is being built, and users of the finished repo will not have them. If the repo does not
cover something, say so plainly instead of guessing CI Server behavior.
## Conventions ## Conventions
- Summarize manual content in your own words; never copy manual text into the repo. - Summarize manual content in your own words; never copy manual text into the repo.
- Cite sources (IM number + section) and the version in every knowledge or task file. - Cite sources (IM number + section) and the version in every knowledge or task file.
- Mark whether content is **verified** on a real system or **from docs** only. - Mark whether content is **verified** on a real system or **from docs** only.
- Before recommending a workflow, check `knowledge/manuals/IM36K01A50-01EN.md` (known issues).
- Never modify the manual folder. - Never modify the manual folder.
- Skills use placeholders (`<Section>.<Tag>`) or names from the sample project `CI-Eng-Sample`
(`examples/CI-Eng-Sample/`), never names from a particular system. Names like `AID.*` in
`knowledge/progress.md` and `knowledge/issues.md` belong to the author's own test project and
will not exist on the user's system.
## Building the repo (development stage)
The manuals are at `C:\Users\Public\Yokogawa\tls\doc\EN\` on the development machine. Work
proceeds manual by manual in the order in `knowledge/progress.md`: summarize the manual into
`knowledge/manuals/`, practice each task on the test system, and record a task in a skill only
after the user confirms it works. Tasks may be practiced first on the author's AID test
project, but whatever they need must then be added to `CI-Eng-Sample` and re-tested there;
a task is done only when it passes on the sample project (or needs no project data). Track
status in `knowledge/progress.md`. Log open questions
and problems in `knowledge/issues.md`, each with the files to update once it is resolved.

1
examples/CI-Eng-Sample/.gitignore vendored Normal file
View file

@ -0,0 +1 @@
*.qlo

15
examples/CI-Eng-Sample/01_section_df.qli Normal file
View file

@ -0,0 +1,15 @@
@LANGUAGE
ENGLISH
@VERSION
1.03.00
! CI-Eng-Sample sections (CI Server R1.03.00)
@FIELDS
NAME,SECTION_PATH,SECTION_NAME,DESCRIPTION
@SECTION_DF
"CI-Eng-Sample","","CI-Eng-Sample","CI-Eng-Sample project"
"CI-Eng-Sample.TANK1","CI-Eng-Sample","TANK1","Sample tank 1"
"CI-Eng-Sample.PUMP1","CI-Eng-Sample","PUMP1","Sample pump 1"
"CI-Eng-Sample.SYSTEM","CI-Eng-Sample","SYSTEM","Sample system monitoring"

20
examples/CI-Eng-Sample/02_item_df.qli Normal file
View file

@ -0,0 +1,20 @@
@LANGUAGE
ENGLISH
@VERSION
1.03.00
! CI-Eng-Sample internal items (no station), CI Server R1.03.00
@FIELDS
NAME,DESCRIPTION,ITEM_REP,VALUE_FORMAT
LOW_LOW_LIMIT,LOW_LIMIT,HIGH_LIMIT,HIGH_HIGH_LIMIT,SCALE_LOW_LIMIT,SCALE_HIGH_LIMIT
@ITEM_DF
"CI-Eng-Sample.TANK1.LEVEL","Tank 1 level (%)","Real","999.9",10,20,80,90,0,100
"CI-Eng-Sample.TANK1.INFLOW","Tank 1 inflow (m3/h)","Real","9999.9",0,0,0,0,0,500
"CI-Eng-Sample.PUMP1.RUNNING","Pump 1 running","Boolean","",0,0,0,0,0,0
"CI-Eng-Sample.PUMP1.MODE","Pump 1 mode (0 manual, 1 auto)","Integer","9",0,0,0,0,0,1
"CI-Eng-Sample.SYSTEM.CPU_LOAD","CPU load (%) from intcpumon","Real","999.9",0,0,0,0,0,100
"CI-Eng-Sample.SYSTEM.DISK_C","Disk C: from intdskmon","Real","999.9",0,0,0,0,0,100
"CI-Eng-Sample.SYSTEM.PING_LOCALHOST","localhost reachable, from inttcpmon","Integer","9",0,0,0,0,0,1
"CI-Eng-Sample.SYSTEM.PROC_ALM","ALARM process (alm) running, from intmon","Integer","9",0,0,0,0,0,1

13
examples/CI-Eng-Sample/03_his_group_df.qli Normal file
View file

@ -0,0 +1,13 @@
@LANGUAGE
ENGLISH
@VERSION
1.03.00
! CI-Eng-Sample item storage group (Event/Item), CI Server R1.03.00
! Group names are max 16 characters.
@FIELDS
NAME,DESCRIPTION,TYPE,COL_STOR_TYPE,LIFE_TIME,ROLLOVER_INT
@HIS_GROUP_DF
"CIENG_EVENT","CI-Eng-Sample event history","Item","Event/Item","1 weeks","1 days"

13
examples/CI-Eng-Sample/04_item_his_df.qli Normal file
View file

@ -0,0 +1,13 @@
@LANGUAGE
ENGLISH
@VERSION
1.03.00
! CI-Eng-Sample items in storage groups, CI Server R1.03.00
@FIELDS
NAME,ITEM_NAME,GROUP_NAME,ON_VALUE_CHANGE,ON_STATUS_CHANGE
@ITEM_HIS_DF
"CIENG_EVENT:CI-Eng-Sample.TANK1.LEVEL","CI-Eng-Sample.TANK1.LEVEL","CIENG_EVENT",1,1
"CIENG_EVENT:CI-Eng-Sample.TANK1.INFLOW","CI-Eng-Sample.TANK1.INFLOW","CIENG_EVENT",1,1

13
examples/CI-Eng-Sample/89_remove_item_his_df.qli Normal file
View file

@ -0,0 +1,13 @@
@LANGUAGE
ENGLISH
@VERSION
1.03.00
! Remove CI-Eng-Sample items from storage groups
@FIELDS
NAME
@ITEM_HIS_DF
"CIENG_EVENT:CI-Eng-Sample.TANK1.LEVEL"
"CIENG_EVENT:CI-Eng-Sample.TANK1.INFLOW"

12
examples/CI-Eng-Sample/90_remove_his_group_df.qli Normal file
View file

@ -0,0 +1,12 @@
@LANGUAGE
ENGLISH
@VERSION
1.03.00
! Remove CI-Eng-Sample storage group (deletes its history)
@FIELDS
NAME
@HIS_GROUP_DF
"CIENG_EVENT"

19
examples/CI-Eng-Sample/91_remove_item_df.qli Normal file
View file

@ -0,0 +1,19 @@
@LANGUAGE
ENGLISH
@VERSION
1.03.00
! Remove CI-Eng-Sample items
@FIELDS
NAME
@ITEM_DF
"CI-Eng-Sample.TANK1.LEVEL"
"CI-Eng-Sample.TANK1.INFLOW"
"CI-Eng-Sample.PUMP1.RUNNING"
"CI-Eng-Sample.PUMP1.MODE"
"CI-Eng-Sample.SYSTEM.CPU_LOAD"
"CI-Eng-Sample.SYSTEM.DISK_C"
"CI-Eng-Sample.SYSTEM.PING_LOCALHOST"
"CI-Eng-Sample.SYSTEM.PROC_ALM"

15
examples/CI-Eng-Sample/92_remove_section_df.qli Normal file
View file

@ -0,0 +1,15 @@
@LANGUAGE
ENGLISH
@VERSION
1.03.00
! Remove CI-Eng-Sample sections (children first)
@FIELDS
NAME
@SECTION_DF
"CI-Eng-Sample.TANK1"
"CI-Eng-Sample.PUMP1"
"CI-Eng-Sample.SYSTEM"
"CI-Eng-Sample"

82
examples/CI-Eng-Sample/README.md Normal file
View file

@ -0,0 +1,82 @@
# CI-Eng-Sample
A small, invented sample project that anyone with this repo can load into a CI Server
**R1.03** test system. Skills use its names in their examples, and every skill task is
re-tested against it so that no other project is needed.
Built and tested on CI Server R1.03.00 (unlicensed test system), 2026-09-30.
## Load and remove
Test systems only: loading writes to the CI Server database. CI Server must be running.
From an elevated prompt, call the scripts by full path (a bare `load.cmd` may not be found
from the current folder):
```
cmd /c "<repo>\examples\CI-Eng-Sample\load.cmd"
cmd /c "<repo>\examples\CI-Eng-Sample\remove.cmd"
```
- Each step prints a summary and writes a `.qlo` listing; check that `Errors` is 0.
- **Restart CI Server after loading** (stop, then start the CI Service): a new storage group
stores no history until CI Server restarts.
- `load.cmd` on a system that already has the project reports `Exists` and changes nothing.
- `remove.cmd` takes about 1½ minutes: a storage group can only be deleted after its stop time
has passed, so the script sets a stop time one minute ahead and waits. Removing the group
also deletes its history.
## Current contents
| Name | Kind | Details |
|---|---|---|
| `CI-Eng-Sample` | Section | Top level |
| `CI-Eng-Sample.TANK1`, `.PUMP1`, `.SYSTEM` | Sections | Tank, pump, system monitoring |
| `CI-Eng-Sample.TANK1.LEVEL` | Item, Real | %, format `999.9`, limits LL 10 / L 20 / H 80 / HH 90, scale 0–100 (alarming off), stored in `CIENG_EVENT` |
| `CI-Eng-Sample.TANK1.INFLOW` | Item, Real | m3/h, format `9999.9`, scale 0–500, stored in `CIENG_EVENT` |
| `CI-Eng-Sample.PUMP1.RUNNING` | Item, Boolean | |
| `CI-Eng-Sample.PUMP1.MODE` | Item, Integer | 0 manual, 1 auto |
| `CI-Eng-Sample.SYSTEM.CPU_LOAD` | Item, Real | Target for `intcpumon` |
| `CI-Eng-Sample.SYSTEM.DISK_C` | Item, Real | Target for `intdskmon` (reports **used** %) |
| `CI-Eng-Sample.SYSTEM.PING_LOCALHOST` | Item, Integer | Target for `inttcpmon` (1 = reachable) |
| `CI-Eng-Sample.SYSTEM.PROC_ALM` | Item, Integer | Target for `intmon` (1 = `alm` process running) |
| `CIENG_EVENT` | Item storage group | Event/Item, lifetime 1 week, rollover 1 day |
All items are internal (no station), so the project works without any PLC or simulator.
New items start with status 13 (`NOT INIT`) until a value is written.
## Files
| File | Purpose |
|---|---|
| `01_section_df.qli` | Sections (`SECTION_DF`); parents before children |
| `02_item_df.qli` | Items (`ITEM_DF`) |
| `03_his_group_df.qli` | Item storage group (`HIS_GROUP_DF`) |
| `04_item_his_df.qli` | Items in the storage group (`ITEM_HIS_DF`, name `<group>:<item>`) |
| `89_`…`92_remove_*.qli` | Names to delete, in reverse order |
| `load.cmd`, `remove.cmd` | Run the steps in the right order |
| `monitoring/*.sup.txt` | Setup-file lines for the monitoring processes (not applied by `load.cmd`) |
## Monitoring processes (optional)
`monitoring/` holds the lines to add to the setup files in `%TLS_ROOT_PATH%\tls\sup\` so that
`intcpumon`, `intdskmon`, `inttcpmon`, `intmon` and `intspawn` write into the `SYSTEM` items.
These change the system's own setup files: back the files up first and restore them after
testing. See the `system-management` skill, task `monitoring-processes.md`.
## Planned additions
| Phase | Adds |
|---|---|
| 6 | Template items, a class and objects |
| 8 | Alarm settings on sample items |
| 9 | More storage groups (scan/time, aggregation) |
| 10 | A display and symbol |
| 11 | A report |
## Rules
- Test systems only; invented names only, no real plant or customer data.
- Keep the load order: sections → template items → classes (compiled) → objects → other
items → storage groups → items in storage groups (IM 36K10J10 §5.6). Keep `remove.cmd` in
reverse order.
- Every file notes the CI Server version it was built and tested on.

12
examples/CI-Eng-Sample/load.cmd Normal file
View file

@ -0,0 +1,12 @@
@echo off
rem Load CI-Eng-Sample into a CI Server R1.03 TEST system.
rem Run in an elevated prompt while CI Server is running; call this script by full path.
rem Results go to *.qlo listing files; check that Errors = 0.
rem Restart CI Server afterwards: new storage groups only start storing after a restart.
cd /d "%~dp0"
dssqld -i 01_section_df.qli -l 01_section_df.qlo
dssqld -i 02_item_df.qli -l 02_item_df.qlo
dssqld -i 03_his_group_df.qli -l 03_his_group_df.qlo
rem Short pause: linking items straight after creating the group failed once.
powershell -NoProfile -Command "Start-Sleep -Seconds 5"
dssqld -i 04_item_his_df.qli -l 04_item_his_df.qlo

5
examples/CI-Eng-Sample/monitoring/intcpumon.sup.txt Normal file
View file

@ -0,0 +1,5 @@
! Add to %TLS_ROOT_PATH%\tls\sup\intcpumon.sup (CI Server R1.03.00, tested 2026-09-30)
! CPU = <system name>, <item>, <counter>; empty system = this machine, empty counter = total CPU %
interval = 10
logging
CPU = "", "CI-Eng-Sample.SYSTEM.CPU_LOAD", ""

5
examples/CI-Eng-Sample/monitoring/intdskmon.sup.txt Normal file
View file

@ -0,0 +1,5 @@
! Add to %TLS_ROOT_PATH%\tls\sup\intdskmon.sup (CI Server R1.03.00, tested 2026-09-30)
! DISK = <disk>, <item>. The item receives the USED percentage of the disk.
interval = 10
logging
DISK = "C:\\", "CI-Eng-Sample.SYSTEM.DISK_C"

3
examples/CI-Eng-Sample/monitoring/intmon.sup.txt Normal file
View file

@ -0,0 +1,3 @@
! Add to %TLS_ROOT_PATH%\tls\sup\intmon.sup (CI Server R1.03.00, tested 2026-09-30)
! process = <process name>, <item>. Item = 1 while the process runs.
process = "alm", "CI-Eng-Sample.SYSTEM.PROC_ALM"

6
examples/CI-Eng-Sample/monitoring/intspawn.sup.txt Normal file
View file

@ -0,0 +1,6 @@
! Add to %TLS_ROOT_PATH%\tls\sup\intspawn.sup (CI Server R1.03.00, tested 2026-09-30)
! TRIGGER = <command>, <item>, <VALUE|STATUS|OPTION|TIMER|NODE_DOWN|NODE_UP|NODE>, <NONE|EQUAL|GREATER|LESS>, <value>
! The new value is passed to the command as its argument. Keep the command path SHORT:
! a ~130-character path silently did nothing; C:\Claude\spawn_test.cmd worked.
! Example command file (spawn_test.cmd): @echo %* >> "C:\Temp\spawn_out.txt"
TRIGGER = "C:\Temp\spawn_test.cmd", "CI-Eng-Sample.PUMP1.MODE", VALUE, NONE, 0

4
examples/CI-Eng-Sample/monitoring/inttcpmon.sup.txt Normal file
View file

@ -0,0 +1,4 @@
! Add to %TLS_ROOT_PATH%\tls\sup\inttcpmon.sup (CI Server R1.03.00, tested 2026-09-30)
! TCP = <host>, <item>. Item = 1 while the host answers a ping.
logging
TCP = "localhost", "CI-Eng-Sample.SYSTEM.PING_LOCALHOST"

16
examples/CI-Eng-Sample/remove.cmd Normal file
View file

@ -0,0 +1,16 @@
@echo off
rem Remove CI-Eng-Sample from a CI Server R1.03 TEST system (also deletes its history).
rem Run in an elevated prompt while CI Server is running; call this script by full path.
rem Order: storage links, stop + delete storage group, items, sections (children first).
rem A storage group with an active unit cannot be deleted (HIS-E-GROUPHASUNT), so the
rem group first gets a stop time one minute ahead; the script waits until it has passed.
cd /d "%~dp0"
dssqld -r 89_remove_item_his_df.qli -l 89_remove_item_his_df.qlo
powershell -NoProfile -Command "$t=(Get-Date).AddMinutes(1).ToString('dd-MM-yyyy HH:mm:ss'); \"@LANGUAGE`r`nENGLISH`r`n`r`n@VERSION`r`n1.03.00`r`n`r`n@FIELDS`r`nNAME,STOP_TIME`r`n`r`n@HIS_GROUP_DF`r`n\"\"CIENG_EVENT\"\",\"\"$t\"\"`r`n\" | Set-Content -Encoding ascii 90a_stop_his_group_df.qli"
dssqld -m 90a_stop_his_group_df.qli -l 90a_stop_his_group_df.qlo
echo Waiting 75 seconds for the storage group stop time to pass...
powershell -NoProfile -Command "Start-Sleep -Seconds 75"
dssqld -r 90_remove_his_group_df.qli -l 90_remove_his_group_df.qlo
dssqld -r 91_remove_item_df.qli -l 91_remove_item_df.qlo
dssqld -r 92_remove_section_df.qli -l 92_remove_section_df.qlo
del 90a_stop_his_group_df.qli

4
examples/README.md
View file

@ -2,3 +2,7 @@
Working artifacts Claude can copy and adapt. Only add content that has been tested on a Working artifacts Claude can copy and adapt. Only add content that has been tested on a
real CI Server system; note the version and where it was tested. real CI Server system; note the version and where it was tested.
| Folder | Contents |
|---|---|
| `CI-Eng-Sample/` | Sample project to import into a test system; skills use its names in examples (planned) |

3
knowledge/README.md
View file

@ -5,4 +5,7 @@ that area's skill (`.claude/skills/<area>/reference/`).
| File | Contents | | File | Contents |
|---|---| |---|---|
| `issues.md` | Issue register: open questions and problems to come back to |
| `progress.md` | Working order of the manuals and status of every practiced task |
| `manuals/` | One summary per manual (`IM36K….md`), written in our own words |
| `document-map.md` | All EN manuals by IM number, with editions | | `document-map.md` | All EN manuals by IM number, with editions |

28
knowledge/issues.md Normal file
View file

@ -0,0 +1,28 @@
# Issue register
Open questions and problems found while building the repo.
**Status:** open · investigating · closed
Item and station names such as `AID.*` come from the author's own test project on the
development system (see "Test system" in `progress.md`); they do not exist on other systems.
## How to close an issue
1. Confirm the answer with the user (practiced on the test system where possible).
2. Update **every file in the issue's "Update on close" column** with the answer.
3. Update the matching row in `knowledge/progress.md` (status and notes).
4. Set the issue to **closed** and write the resolution and date in "Next step / resolution".
Keep closed issues in the table as history.
## Issues
| ID | Date | Area | Issue | Status | Next step / resolution | Update on close |
|---|---|---|---|---|---|---|
| ISS-001 | 2026-09-30 | ITEM (`itmval`) | Writing an item with `itmval -p -n AID.WRPS.SIM.INFLOW -v 400` added the `uoff` option flag (options 0x…8a → 0x…8e). The flag stayed after writing the original value back. Meaning of `uoff` unknown; not found in the EN manuals by text search. | open | 2026-09-30: writing internal sample items (`CI-Eng-Sample.*`, no station) does **not** set `uoff` (options stay 0x…88), so it is tied to station-connected items (the AID item was already `off`, its station not communicating). Still to find: meaning and how to clear it (ITEM Service IM 36K10L35/L36, Engineering Module I/O Processes IM 36K10C10). Revisit in phase 5 with a station item. | `.claude/skills/system-management/tasks/read-write-item.md` (replace the `uoff` note under "Read the current value"); `knowledge/progress.md` row "Write an item with `itmval -p`" |
| ISS-002 | 2026-09-30 | DATABASE (`dsschk`) | `dsschk -d ITEM_DF -v` (check only) exits 0 with no console output and nothing new in `umhlog.log`. Where results are reported is unknown. | closed | Closed 2026-09-30 (confirmed by user). 2026-09-30: `dsschk -e -v` prints a start/end line per dataset (228 checked, no problems) and logs to `umhlog.log`. Plain `dsschk` only compares copies between nodes, so it prints nothing on a single-node system. `ismchk` needs a database file name (usage: `ismchk data_base_name`), not run yet. | Create `.claude/skills/system-management/tasks/consistency-check.md` and add it to that skill's `SKILL.md`; `knowledge/manuals/IM36K10J10-01EN.md` §4.1.1 consistency tools (add where output goes); `knowledge/progress.md` row "Consistency check" |
| ISS-003 | 2026-09-30 | DATABASE (`dssqld`) | Filtered export (`dssqld -e <out> <filter>.qli`) failed with a guessed filter syntax (`@ITEM_DF`, `@FIELD`, `@SELECT`). | closed | Closed 2026-09-30 (confirmed by user). 2026-09-30: the quick load **data** format is now known and verified (`@LANGUAGE`, `@VERSION`, `@FIELDS`, `@<DATASET>`, quoted CSV records, `\` continuation, `!` comments; IM 36K10L45 §9.11). Filter syntax found (IM 36K10L50 §3.6) and practiced, awaiting confirmation: a file with `@SELECT`, then the filter in single quotes (strings in double quotes), then `@<DATASET>`; run `dssqld -e <out> <filter>.qli`. `ITEM_HISTORY` returns nothing unless the filter names `ITEM_NAME` and a `SAMPLE_TIME` range (`SAMPLE_TIME > "dd-mm-yyyy hh:mm:ss" and SAMPLE_TIME < ...`). | `.claude/skills/system-management/tasks/export-dataset.md` section "Filtered exports"; `knowledge/manuals/IM36K10J10-01EN.md` §5.6 step 1; `knowledge/progress.md` row "Export a dataset" |
| ISS-004 | 2026-09-30 | ITEM (`itmval`) | `itmval -g -a <1..5>` returns `ITM-E-WRONG_ATT` on `AID.WRPS.*` items, so reading limits is unproven. | closed | Closed 2026-09-30 (confirmed by user). On `CI-Eng-Sample.TANK1.LEVEL` (limits set) `-a 1..5` returned deadband 0, low 20, high 80, low-low 10, high-high 90. The error only occurs on items without limits. | `.claude/skills/system-management/tasks/read-write-item.md` (limits section); `knowledge/progress.md` row "Read an item with `itmval -g`" |
| ISS-005 | 2026-09-30 | DATABASE (`dssqld`) | Loading `04_item_his_df.qli` straight after creating the storage group gave 2 errors once; three other runs were clean. Error text not captured. | open | Added a 5 s pause in `load.cmd`. If it happens again, capture `04_item_his_df.qlo`. | `examples/CI-Eng-Sample/load.cmd`; `.claude/skills/system-management/tasks/load-remove-records.md` |
| ISS-006 | 2026-09-30 | HISTORY (`ithloahis`) | Samples dated before the start of the current storage unit were not stored (no error shown); samples after it were. Also, a new storage group stored nothing until CI Server was restarted. | open | Confirm with History Management (IM 36K10L20) in phase 9: how to load into older units, and whether a restart is really required. | `.claude/skills/system-management/tasks/load-history.md`; `examples/CI-Eng-Sample/README.md`; `knowledge/manuals/IM36K10J10-01EN.md` command-line tools |
| ISS-007 | 2026-09-30 | INTEGRATION (monitoring) | `intdskmon` wrote 61.9 for a C: drive that is 61.9 % used / 38.1 % free, although the manual says it monitors the disk free space rate. `intspawn` did nothing when the command path was ~130 characters; a short path worked (limit unknown). | open | Confirm the disk value meaning and the path limit. | `.claude/skills/system-management/tasks/monitoring-processes.md`; `knowledge/manuals/IM36K10J10-01EN.md` §4.1.6; `examples/CI-Eng-Sample/monitoring/` |

183
knowledge/manuals/IM36K01A50-01EN.md Normal file
View file

@ -0,0 +1,183 @@
---
manual: IM 36K01A50-01EN
title: CI Server Release Information
edition: 3rd Edition, Sep. 2023
version: R1.03
status: from docs
---
# Release Information: known issues and cautions (R1.03)
Known limitations and workarounds that the other manuals do not cover. Check this list
before recommending a workflow in any area. Section numbers refer to the manual.
## Platform and installation
| Area | Issue | What to do |
|---|---|---|
| Dual-redundant platform (1.1) | Without a Vnet/IP card, guest time sync by NTP makes host messages in the historical alarm overview show wrong timestamps. | Accept, or use Vnet/IP time sync. |
| Dual-redundant platform (1.1) | After both computers restart, the former standby may come up as *Guest OS (Isolated)*. | In the Redundancy Management Tool set Next Status to *Standby*, then restart that computer. |
| IT Security tool (1.3) | Remote Desktop to the CI Server may fail after applying IT Security if OS patch levels differ. | Patch both the server and the RDP client to the latest level. |
| IT Security tool (1.3) | Changing Windows region/language after applying IT Security causes problems. | Set region and language **before** applying IT Security; never change afterwards. |
| Windows (1.4) | Windows Server 2016 start menu may not refresh after install. | Restart after installing CI Server. |
| Windows (1.4) | CI Server started from the command line on Win10 / Server 2016 needs elevation. | Always use *Run as administrator*. |
| Windows (1.4) | Custom fonts can cause visual glitches in the Engineering and Edit modules. | Avoid custom fonts. |
| Install path (1.9) | The MELSEC EZSocket installer fails if CI Server is in a non-default path that contains spaces. | Non-default install paths must have no spaces. |
| Virtual machines (1.19) | Live migration, failover and shared-storage path switching lose acquired data/alarms; failover during engineering can corrupt the engineering data. | Migrate only when no engineering is in progress; keep engineering backups. |
| Virtual machines (1.19) | Serial-only drivers (Siemens 3964R, telemetry integration), Siemens SAPI-S7 and MELSEC are unavailable on VMs; many other drivers work over TCP/IP only. | Check driver support before choosing a VM. |
| Virtual machines (1.19) | Do not use VM replication; do not mix physical and virtual machines in HAC; only thin clients may RDP into a virtual CI Server. | Design accordingly. |
| Virtual machines (1.19) | The software medium must be mounted as an ISO on the VM (e.g. via Hyper-V Manager › Media › DVD Drive › Insert Disk). | Read "DVD drive" in the manuals as the mounted ISO drive. |
## Services
**ACCESS (1.5)**
- OPC classic on Win10 / Server 2016 / 2019 needs .NET 3.5. Install it from the Windows medium
(`DISM /Online /Enable-Feature /FeatureName:NetFx3 /All /LimitAccess /Source:<drive>:\sources\sxs`),
then re-run the OPC Core Components Redistributable in `%TLS_EXE_PATH%`.
- OPC AE: items in the tree root (no section) appear as `.NAME` and some clients can't use them
as alarm sources. Put alarm-source items inside a section.
**ALARM (1.6)**
- Shelving cannot restrict OPC AE items by status/type.
- Shelving more than 500 alarms can overflow the DURM queue; after a Portal–Core link loss,
restart the shelf overview.
**BUS (1.7)**
- Secure MDUR on Linux: create `/tls/pki` manually before configuring the secure connection.
**DATABASE (1.8)**
- With Active Directory login, up to ~15 s may pass between the login form closing and the
application appearing. Expected behavior.
**EQUIPMENT (1.9)**
- MELSEC iQ-R needs Mitsubishi EZSocket 4.4: uninstall older EZSocket first, then run
`RunInstaller` (as administrator) from `%TLS_ROOT_PATH%\tls\exe\EZSocketPcRedistributableInstaller`.
- IEC 61850: add the line, then the station (General tab: device IP; Options tab: domain prefix
and report object), then points. The element address is `<domain prefix><rest>`; the point
I/O address is only the part **after** the prefix (the prefix is added automatically).
Wrong delimiting means no reports/elements are created.
**PROCESS (1.10)**
- Java classes that access datasets must get the DSS session with `getDssSession()` (never
`Dss.createSession()` or `DssContext.getSession()`), must never close it, and must be
recompiled and reset after the change. Otherwise results are undefined
(e.g. `ADT-E-ECL_UNKNOWN` in the system log).
- When making items with SIGNALs, handle root-level items: if `SECTION` is empty use the tag
alone, else `SECTION || "." || tag`. Prefer automatic naming.
- Section-based SIGNAL creation does not support process area definitions.
**REPORT (1.11)**
- AD + printer management can make report generation fail (looks for the user's default
printer). Workaround: create a printer destination not bound to a device and set it as
the default destination in the AD user profile.
- Report features of Schemes take effect only after restarting the Engineering module.
**USER (1.12)**
- Remote Connect is for client machines **without** CI Server; don't install it on a CI Server.
- HTML5 displays cannot be validated via Remote Connect; engineer them on a CI Portal.
- HTML5 is a lightweight/mobile HMI with fewer components than Java displays (details in
Edit Module, IM 36K10C50). Use Google Chrome; other browsers may render differently.
- SSO leaves a landing page open that the user must close. SSO needs Active Directory, so
Windows only.
- `jwuiutl` over Remote Desktop is denied by default. To allow it: Setup File Editor ›
`dssana.sup` › *Login Control* tab › row *Client system name `<remote>`, Display and Symbol
Utility* › Login method = *No* › restart CI Server. Needed by CI Exchange (CENTUM VP /
Prodigy) load and conversion scripts.
- Remote Connect operator interface may fail to start (Java network read issue): retry, or
clear the Java cache (Java Control Panel › Temporary Internet files › Delete files).
- Auto-login is for server / CI Portal applications only, not Remote Connect.
- "Application blocked" for `.jnlp` over HTTPS is caused by the self-signed web server
certificate. Fix with a CA/domain-issued certificate (preferred) or add
`https://localhost:8443` to trusted sites (less safe).
- Web HMI display names are case sensitive.
- Custom Java components must be signed by Yokogawa before use.
- Edit module quirks: item properties editor Value field font too small; *Update
item/parameter* on the Attributes sheet ignores the first change (repeat it or use the
Actions sheet); a symbol custom property must not reuse an existing property name;
choosing *Open display* in an event's Action combo adds a duplicate event (delete it);
function components must stay inside the drawing area and must not be grouped.
- Same-size labels may render at slightly different sizes (Java anti-aliasing). Use *Apply
text smoothing* in the CI Portal setup file, or a non-integer zoom such as 99.999 %.
- HTML5 limitations: no login name in the status bar; frame border styles map imperfectly;
Windows display scaling must be 100 %; no rotation or column filters on alarm overview /
shelved alarm overview; transparency and margin properties are ignored.
## HMI, GIS and OPC UA
**HMI general (1.13)**
- Date/Time field with *editable* or *disable* set shows a black foreground in the operator
interface (correct in HTML).
- Up/down buttons differ in size between operator interface and HTML.
- With *Fit display*, tooltips and selection dialogs of trend / alarm overview are misplaced.
Uncheck *Zoom enabled* on those components, or design displays at the target resolution.
**GIS (1.14)**
- Click info is not shown for symbols built with a data bar. Use simple symbols as map markers.
- Don't use symbols containing alarm overview, trend or report components in GIS (high memory
in Chrome; alarm overview filters don't receive item names).
- Symbols/map layer may disappear or draw behind the map after long runs (Ctrl+wheel zoom
restores). In Chrome, disabling hardware acceleration fixes symbols drawn behind the map.
**OPC UA (1.15)**
- PubSub upload fails with *Internal error* if a published dataset has zero items. Remove or
revert those datasets.
- The datatype combo in PubSub Reader item mapping has no effect.
- Variables/properties of `CIAlarmConditionType` / `CISystemEventType` nodes can't be read
(`BadNotReadable`) or subscribed individually (`BadNotSupported`); subscribe to the alarm event.
- CI Core memory for external OPC UA clients: under 20,000 items no extra memory;
20,000–99,999 add 8 GB; 100,000–199,999 add 16 GB; beyond that add 8 GB per extra 100,000.
## Server Core / Portal (1.16)
- Secure DURM with an invalid certificate common name continues **unencrypted** (only logged).
After installing/refreshing certificates, check the message log that they were accepted.
- Remote Connect Engineering module is slow against a redundant CI Core. Use RDP to the Core,
or temporarily run the redundant platform in single mode.
- Several MQTT stations on one MQTT line with brokers unavailable can time out during offline
engineering. Use one station per line, or a temporary local broker.
- GIS component properties *Apply* increases Edit module memory each time; close the dialog
and display to recover.
- Object Selection dialog can hang the Edit module when a section has many objects (DSSSDA at
high CPU). Type the object name directly; to recover, stop that DSSSDA instance in
Performance Monitor, close the Edit module, restart CI Server.
- Enterprise Edit Module: shelved alarm overview shows nothing if added before the alarm
overview, on another layer, or with different alarm source locations. Add the alarm overview
first, same layer, same source locations.
- Alarm overview CI attributes: changing checkboxes on the Attributes tab can reorder the
Columns tab. Workaround: *Uncheck all* › Apply › re-check › Apply › reorder on Columns › Apply.
- Engineering module CI attribute names: pick *Add new record* or an existing name from the
drop-down; cancel the *Add new CI attribute* dialog if it appears unexpectedly.
- OPC UA alarm event type filters and alarm template settings that are in use can't be
deleted, and a same-named one on another station also becomes undeletable. Use unique names
per station; to recover, copy under a new name, repoint, then delete.
- EALs can't be edited in bulk in the Engineering module. Use `dssqld` on dataset
`EXTERNAL_ALARM_DF`.
- Retrieve from archive does not restore alarm attribute databases (alarms visible, attributes not).
- ODBC writes: Microsoft Access can't write to R1.03.00+; SQL Server Management Studio and
Excel via ODBC can't either. PowerShell and custom applications can (ODBC DSN
`CiSimbaClient`, e.g. `UPDATE ITEM_VAL SET ITEM_VALUE_STR=..., STATUS_NUMBER=... WHERE NAME=...`).
Alternatives: Excel Add-in, or `dssqld` on the Core/Portal.
- Acknowledging external alarms over ODBC: filter on `NAME` in `ALARM_CURRENT`
(e.g. `UPDATE ALARM_CURRENT SET ACK = 1 WHERE NAME = '<time>/<id>'`), not
`ITEM_NAME` / `ALARM_ORIG_TIME`.
## CI Exchange tools (1.17, 1.18)
- CENTUM VP and Prodigy tools use `jwuiutl`; over RDP, first allow it in `dssana.sup` (see USER).
- HTML5 conversion warnings about graphics outside the viewing area are harmless; move Generic
/ JavaScript function components into view and reconvert to silence them.
- *Illegal reflective access* Java warnings during load are harmless.
- Folders must not contain Japanese characters (project, CI Exchange project and publish
folders; `Load.cmd` fails with `UnicodeEncodeError`).
- `Unknown encoding 'ms932'` from `Load.cmd`: in the publish folder run `chcp 1252`, then `load.cmd`.
- Loading a publication overwrites VNET station settings (on scan, recover 10 s, slow 5 s,
medium 3 s, fast 1 s) and line device (`/dev/bk00`). Correct them manually afterwards.
- RGS with EAL: if both Vnet/IP buses to an FCS are cut, faceplates don't show OFFLINE and keep
old values. Set the alarm status manually, or map the Vnet communication status to an item.
- Unsupported controllers (e.g. GSGW, APCS) get stations created but no data. Exclude them in
the Import Wizard (RGS with EAL), or filter in the Publish Wizard, e.g.
`TYPE LIKE '%%' AND STATION <> 'FCS0256' AND STATION <> 'FCS0258'`; otherwise delete the
stations in the Engineering module.
- Tuning panel SUM is shown even when CENTUM integration is disabled. To reset to 0: disable
integration in CENTUM, then set SUM to 0 on the CI tuning panel.
- RGS collecting CENTUM alarms: 30 or more controllers needs +8 GB memory.

266
knowledge/manuals/IM36K10J10-01EN.md Normal file
View file

@ -0,0 +1,266 @@
---
manual: IM 36K10J10-01EN
title: CI Server System Design/Management
edition: 3rd Edition, Sep. 2023
version: R1.03
status: from docs
---
# System Design / Management (R1.03)
How CI Server is built, how to choose a system layout, and how to run, back up, monitor,
tune and migrate it. Section numbers refer to the manual.
## 1. Fundamentals
**Three tiers (1.1)**
- **CI View**: the client HMI (Java or HTML5), on Windows PCs, tablets and phones.
- **CI Portal**: web server that sits between CI View and CI Core.
- **CI Core**: data server. Talks to field devices (EQUIPMENT drivers), processes real-time
data, manages alarms, stores history, exposes external interfaces.
**Node, services, processes (1.2)**
- One CI Server per machine; each is a **node**. The license is tied to the node.
- A node runs **services** (DATABASE, ITEM, ALARM, EQUIPMENT, REPORT, …). Which services start
depends on the license.
- Each service is made of **processes**; a process can have several **instances** (e.g. several
report generators, requests shared out by priority).
- Processes talk by **DUR messages**; each has a named queue, visible in Performance Monitor.
**Data model (1.3)**
- **Item**: the basic data point. Receives acquired values, sends operator/application writes
to the RTU, drives alarms, serves as class I/O and as dynamic properties of displays/symbols.
- **Section**: hierarchical folder for items (item full name `Section1.Section2.Tag`).
- **Object**: a set of items managed together; used by processing and linked to graphics.
- **External alarm (EAL)**: alarm from an external system received via the OPC UA client;
EAL settings are kept in sections.
- **Dataset**: table (rows/fields, like an RDB table) holding configuration, current data and
history. Users can add their own. Read by displays, symbols, classes, objects, reports and
external applications.
**Two layers (1.4)**: CI Portal services and CI Core services, on the same or separate machines.
| Service | CI Core | CI Portal |
|---|:-:|:-:|
| BUS | ✓ | ✓ |
| DATABASE | ✓ | ✓ |
| HISTORY, AUDIT, ITEM, EQUIPMENT, ALARM, PROCESS, REPORT, ACCESS | ✓ | |
| USER | | ✓ |
| INTEGRATION | ✓ | ✓ |
## 2. Inside CI Server
| Function | Service(s) | Summary |
|---|---|---|
| Data acquisition (2.1) | EQUIPMENT | Drivers for STARDOM FCX, Vnet/IP, Modbus, DNP3 and others. |
| Alarming (2.2) | ALARM | Detection (by CI Server or the RTU/PCS, with filters against chattering); notification to display, report, OPC AE/UA, sound, e-mail, printer; state and acknowledgement; stored in `ALARM_CURRENT` (current) and `ALARM_CHRONO` (history); analysis with ASPA. |
| Historization (2.3) | HISTORY | Storage groups made of storage units, one kind per data type: items (`ITEM_HISTORY`), alarms (`ALARM_CHRONO`), audit (`AUDIT_TRAIL`), system log (`SYS_LOG`), reports. |
| Symbol and processing (2.4) | PROCESS | Class → object → symbol (below). |
| Display (2.5) | USER | Displays contain symbols; appearance comes from layouts in an XML layouts file. User definitions set the initial display/layout; *Open display* actions name a display/layout. Defaults: display `main`, layout `default`. |
| Reporting (2.6) | REPORT | Configure in the Engineering module (query, schedule, trigger item, destination) → generate by schedule, trigger item or ad hoc → output via spool statement or destination (file, printer, application) → stored in history with a lifetime set by the storage group. |
| User authorization (2.7) | USER | Users belong to authorization groups; groups grant actions. Can be managed through a Windows domain (see Active Directory Integration, IM 36K10J40). |
| Multi-node (2.8) | BUS | **DURM** protocol between nodes: dynamic routing, best-line selection, auto-connect to the active HAC server, encryption and server certificates. |
| External interface (2.9) | ACCESS | ODBC (Simba server on the Core; optional license; the only route for non-Windows clients), OPC classic DA/AE/HDA (local network), OPC UA, remote database copy (mirror to external tables for complex queries; watch export size), Excel Add-in, command-line tools. |
**Class, object, symbol (2.4)**
- A **class** defines items, template items and processing; written in the *traditional*
language or Java. Traditional has no loops; Java classes cannot access datasets (no DSS).
- Class structure: `PROLOG` (local variables `VAR`, parameters `ATTRIBUTE`/`PROMPT`, items
`SIGNAL ... FROM <template> MAKE ...`) and `BODY` (`METHOD`s with `ENTRYCONDITION`s).
- An **object** is created from a class with parameter values; its items are created or removed
with it. Objects are triggered by the scheduler, trigger groups (intervals) or changes of
trigger signals. Traditional COMPUTE/FAST classes can also read/write datasets.
- A **symbol** can be linked to an object so item attributes drive colour, blinking, etc.
Symbols with no dynamic attributes need no object.
- Details: Class Description Language (IM 36K10P10 traditional, IM 36K10P11 Java).
## Command-line tools (2.3.1, 2.9.2)
| Tool | Purpose | Key usage |
|---|---|---|
| `dssqld` | Export / import / update / delete dataset contents; dump data dictionary | `-e <out> [<qli filter>] -d <dataset>` export (`-c` comma separated, `-a` include hidden fields); `-i <qli>` insert; `-m <qli>` update; `-r <qli>` delete; `-f` dump dictionary; `-l [<listing>]` log result; `-s <setup>` (default `dssqld.sup`). |
| `itmval` | Read/write current item data | `-g -n <item> [-a <attr>]` get (attr 1 deadband, 2 low, 3 high, 4 lowlow, 5 highhigh); `-p -n <item> [-v <value>] [-s <status>] [-q <quality>] [-o overwrite blocked] [-t [<date>] <time> [GMT\|LST]]` set; `-e` write to event history only (host node); `-f <file> <opts>` save a command file; `-l` use local node. |
| `ithloahis` | Load history from CSV into event-item / event-event storage groups | `-f <file> [-s <section prefix>] [-t GMT\|LST\|LCT] [-i update current value too] [-v] [-l]`. File is either `SCAN,<item1>,<item2>,...` then `<time>,<v1>,<v2>,...` (max 100 items), or `EVENT` then `<time>,<item>,<value>`. Times as date text or seconds since 1970. |
| `ithimport` | Import item history from another CI Server | `-l` list groups; `-s -g <from> [<to>]` show; `-i -g <from> [<to>] [-f <from time>] [-t <to time>] [-c <rename file>]` import. Rename file lines: `<old name>, <new name>`. |
| `alhimport` / `adtimport` | Import alarm / audit history from another CI Server | `-s` show, `-i` import, optional `-f` / `-t` time range. |
## 3. System design
**Standards to consider (3.1)**: ANSI/ISA-101 (HMI), EEMUA 191 and ISA 18.2 (alarms),
ISA-99 / IEC 62443 and ISO/IEC 17799 (security).
**Configurations (3.2)**
| Layout | When to use | Watch out for |
|---|---|---|
| **Simple**: one CI Core does everything | Local RTUs, a few tens of clients at most | Above ~10 clients, add a separate CI Portal |
| **Separate CI Portal** (Portal ↔ Core via DURM) | Many clients / load balancing; clients on untrusted networks; redundant Cores | Deploy display files to the Portals |
| **HAC** (high availability): ACTIVE + STANDBY Cores | Continuous operation required; large history that needs a live copy | Stable (ideally redundant) link between servers and to the island-detection network device; license Audit log if it is monitored |
| **Host to Host**: a client Core collects from server Cores via DURM | Reuse data at another site/level; RGS on Vnet/IP forwarding upward | Storage on the client Core can grow large |
| **Enterprise operation/engineering** | Share data and displays across Cores; standardize engineering (EES deploys configurations) | Needs deep knowledge of dataset dependencies |
- HAC: modes MANUAL / AUTO; functions monitoring (restart processes/server), watchdog (shuts
itself down if isolated), mirroring; options journaling (recommended on small systems) and
debug logging. Portals and OPC clients (via OPC tunneller) follow the active server. Dual
redundancy is standard; triple/quad need a special order (Tokuchu).
- Redundant networks: DNP3, Modbus, STARDOM FCX, Host-Host (DURM).
- Buffering and catch-up fill history gaps after outages: STARDOM FCX, DNP3, Host-Host.
**Sizing (3.4)**: estimate history disk size (storage group types and lifetimes) with the sizing
tool, and network load with the bandwidth sheets; include Vnet/IP load if connected.
**Long distance (3.5)**: advise on the WAN, but the network provider (or the client's own fibre)
owns its design.
**Time synchronization (3.6)**
- Why: Kerberos fails beyond 5 min skew; protocol timestamps; historians rejecting future data;
correlating events; cross-system scheduling.
- Terms: UTC/GMT; LST (local standard, no DST); LCT (local civil, with DST). CI Server tools
default to LCT unless noted.
- Adjust gently (slew, not step backwards). Forward jumps make aggregates too small, backward
jumps too large.
- Topologies: simple, cascade, star, tree (segment large/wide systems).
- Mechanisms:
- **(S)NTP / Windows Time**: domain members sync to the domain controller automatically;
workgroup machines need configuring. Registry
`HKLM\SYSTEM\CurrentControlSet\Services\W32Time\Parameters\Type` = `NT5DS` (domain),
`NTP` (use `NtpServer`, DNS name), `NOSYNC`. Poll interval via
`Config\MinPollInterval` / `MaxPollInterval` (2^n seconds), or
`NtpClient\SpecialPollInterval` when `NtpServer` ends with `,0x1`.
- **DURECS**: external clock on a Core serial port (Wharton 482, Trimble GPS, Arbiter
1092/1093), set in `durecs.sup`.
- **DURUTL**: distributes the time master Core's clock to other nodes over DURM
(`durutl.sup`: interval, three deviation limits, two adjust steps, slave node list).
Resolution ~2 s; cannot sync a HAC standby.
- **DNP3**: CI Server as master writes time to outstations (STARDOM: set `TIM_SYNC_REQ` on
`SD_CDNP_*_OPEN`; CI side: station *Options* › time synchronization interval).
- **STARDOM FCX**: CI Server writes `FT_STime` at the station's interval (needs the FCX extension).
- **Vnet/IP**: the CENTUM domain master distributes network time; add an SNTP server to the
time group on BUS-1. On Vnet/IP stations Windows Time must be stopped/`NOSYNC`.
- Others with time sync: IEC 60870-5-101/102/103/104, FA-M3, MELSEC, Omron FINS, Allen
Bradley CIP, Bristol Babcock, Fisher ROC, TIE 870-5; ProSafe-PLC via start-up command file.
- Rules: one time master per machine; Vnet/IP overrides everything else; sync everything that
shares timestamped data; keep masters close; aim for under a few seconds deviation; plan
for time master failure.
- History event buffering: keep *Gap time* (default 2 days) and *Maximum sample delay*
(default 10 days) in `itheix.sup` / `itheex.sup` well above any expected time correction.
- Checks: `w32tm /query /configuration`, `w32tm /query /status`, `w32tm /resync /rediscover`;
`net time` (SMB, not NTP); `tmtime` on Vnet/IP stations.
**Hardening (3.7)**
- Windows Firewall on, with the exceptions CI Server needs; remove unused applications and
services.
- Install on a fixed, tested patch level; no automatic Windows updates; apply only
Yokogawa-evaluated patches.
- Antivirus with real-time scanning; exclude `C:\Users\Public\Yokogawa\tls\dat`, `…\tls\sav`,
`…\tls\his`.
- Recommended user groups: **Administrators** (everything), **Maintenance** (users, logs,
datasets), **Engineers** (engineering module: alarms, reports, graphics), **Operators**
(operator screens), **InternalProcess** (internal accounts, non-expiring passwords). The
manual's table maps each authorization (e.g. `ITEM_MODIFY_VALUE`, `REPORT_GENERATE_ADHOC`,
`USER_INSERT`) to these groups; in short, read rights go to all, engineering changes to
Administrators and Engineers, user management to Administrators and Maintenance.
## 4. Operation and maintenance
**Backup and recovery (4.1.1)**
- What to back up: the OS (~10 GB), CI Server software and setup files `%TLS_ROOT_PATH%\tls`
(~2 GB), database and display files `%TLS_ALLUSERS_PATH%` (~700 MB without history), and history.
- Plan for RTO/RPO, off-site copies, labelled and rotated media, and backup result reporting.
Recommended: disk first tier, tape second tier; centralized backup server; never back up over
the control network.
- Suggested schedule: full offline backup at version upgrades and periodic maintenance; full
after OS patches; weekly full; daily full or differential of the `tls` folder; archive history
weekly; export key datasets daily with `dssqld`.
- Don't change configuration during a backup. Use VSS for consistent online copies.
- Consistency tools: `ismchk <file>` / `ismkfr [-c] [-r] [-s] [-d] <file>` for ISAM files;
`dsschk [-d <dataset>] [-n <node>] [-e] [-r] [-v]` for replicated/duplicated datasets.
Repair: repeat `dsschk -r` until clean, then `dsschk -e`, then `dsschk -e -r` (maybe twice).
*Verified 2026-09-30:* on a single node plain `dsschk` prints nothing (it compares nodes);
use `dsschk -e -v`, which lists every dataset checked and also logs to `umhlog.log`.
- Disaster recovery: restore system backup (or reinstall OS + CI Server + patches) → restore
`tls` configuration and database → verify.
- Retrieve archived history from the Engineering module (you can set its lifetime).
- Restore lost records: back up current data, build a `.qli` from the daily `dssqld` export,
import.
**Routine (4.1.2–4.1.5)**: OS patches, antivirus updates, user account housekeeping; watch
Windows and CI Server Performance Monitor, Windows event log, CI Server system log report and
audit trail report.
**Monitoring processes (4.1.6)** — INTEGRATION Service tools, each configured in its `.sup` file
and reporting status into items:
| Process | Monitors | How to start |
|---|---|---|
| `intmon` | process running; DURM node and channel status (can set slave items OFFLINE) | Uncomment its line in `%TLS_ROOT_PATH%\tls\com\integration_start.cmd` |
| `intcpumon` | CPU load (any perf counter) | `start /B /NORMAL %TLS_ROOT_PATH%\tls\exe\intcpumon -n intcpumon` then `durwfp -p intcpumon -t 10` |
| `intdskmon` | disk free space | same pattern with `intdskmon` |
| `inttcpmon` | TCP reachability (ping) of hosts | same pattern with `inttcpmon` |
| `intadtnot` | writes an AUDIT event from a script | `intadtnot -e A.B.C.D [-u user] [-t terminal] [-o old] [-v new]` |
| `intspawn` | runs a command on item value/status/option change, timer or node up/down (max 64 triggers) | `intspawn -n intspawn`, triggers in `intspawn.sup` |
**Problem handling (4.2)**: identify → investigate (performance monitors, logs, debug mode,
debug tools) → fix (memory size, queue size, load balancing, patch).
## 5. Implementation
**Engineering tools (5.1)**: License Request / Authorization wizards, Setup File Editor
(changes apply after the process restarts), Engineering module (Enterprise version for
enterprise systems), Edit module (displays and symbols), CI Exchange (import CENTUM VP
projects), Performance Monitor, Message log, ASPA, Excel Add-in, `hacw_hmi` (HAC management).
**CENTUM VP import (5.2)**: CI Exchange reads the VP project → produces import files and an
import command → run it → review scan times against Vnet/IP load.
**Designing classes and symbols (5.3)**
1. Create template items (analogue, digital, string…) in a common system section.
2. Group devices of the same type, define their inputs/outputs and common behavior in a class.
3. Decide which items the class creates; creating an object fails if its items already exist.
4. Group equipment with the same look into one symbol.
5. Sections in a class are relative to the object's section. Template items must exist before
objects are created (matters for migration scripts).
6. For performance, prioritize objects.
**Testing checklist (5.4)**: input validation (valid/invalid, boundaries, combinations,
defaults), outputs (destination, value, format, messages), interfaces (including offline
partners), scheduled tasks, UI (initial values, invalid/quick/concurrent operations,
usability), administrator tasks (backup, accounts, monitoring), performance and long-run
(leaks, disk), security (privileges), localization, regulations.
**Tuning (5.5.1)**
- Common memory: max processes 250 by default (`dur.sup`); keep free common memory above 10 %
and usage below 75 % (item pool size in `itm.sup`).
- Queues must not hold waiting requests; enlarge in each process's setup file. Objects running
too often: fix triggers/schedules, or add instances and priorities.
- Database: collisions under 250/s; entries under 80 % of max users (default 2K); max files
1,200. Set `-u` / `-f` in `database_start.cmd`; check with `ismdbg`.
**Debugging (5.5.2)**
- Enable debug/log per process in its setup file (`<process>.sup`, level 1–3, log size);
e.g. `alnmgr`, `eqp*` (`eqpfcx.sup`, `eqpmdc.sup`, or `eqpdbg` until restart), `hac`, `opc`
(PRINT statements to UMHLOG, on by default in `opc.sup`), `opxdac` (`opxsys.sup`),
`opxuac_mon`. Turn debug off afterwards (performance).
- Debug-mode launchers: `jwuipoi_debug` (operator interface), `jhmiset_debug` (Engineering
module), `jwuiged_debug` (Edit module), `fsuedit_debug` (Setup File Editor), `ftmoni_debug`
(Performance Monitor), `jwuitrd_debug` (Trend), `jwuiaan_debug` (ASPA),
`jtoolslic_debug` / `jtoolslicreq_debug` (license wizards).
- Debuggers: `dssxdb`, `dsschk`, `ismdbg` (DATABASE); `hisdbg`, `hasdbg` (HISTORY);
`itmdbg`, `ithdbg`, `ithrecover` (ITEM); `opxxdb` (ACCESS); `rptgen` interactive (REPORT);
`opcdbg` (PROCESS); `almdbg` (ALARM); `eqpdbg` (EQUIPMENT).
**Migration (5.6)**, e.g. from a demo-license system to the target system
1. Export master datasets with `dssqld -e`, using `.qli` filter files where needed
(`@SELECT`, the filter in single quotes, then `@<DATASET>`; optionally `@FIELDS`; verified
2026-09-30, see skill `system-management` task `export-dataset.md`): `AUTH_GROUP_DF`, `USER_DF`, `PRINTER_*_DF`,
`STATUS_DF`, `ALARM_ACK_DF`, `ALARM_AOI_DF`, communication `*_LINE_DF` / `*_STATION_DF` /
`*_POINT_DF`, `INSTALL_DF`, `UNIT_DF`, `ITEM_DF`, `HIS_GROUP_DF` (item storage groups
only), `CLASS_DF`, `OBJECT_DF`, `REPORT_DF`. Drop fields removed in the new release.
2. Re-apply setup file changes on the new system (setup file contents can change between releases).
3. Edit exports (e.g. node names in `PRINTER_TYPE_DF`, `*_LINE_DF`, `ITEM_DF`; set the
`COMPILE` flag to 1 in `CLASS_DF`), then import in dependency order:
template items → classes (compiled) → objects that create items → remaining items →
objects that create none. Check each `.qlo` listing for errors; reorder on relation errors.
4. History: copy `%TLS_HIS_PATH%` (except `has`) and `his_group.*` / `his_units.*` from
`%TLS_DAT_PATH%`; create the same item storage groups; `ithimport -g <group> -c <rename file>`;
`alhimport -i`. Alarm tag names cannot be renamed.

92
knowledge/progress.md Normal file
View file

@ -0,0 +1,92 @@
# Progress
Status of each manual and each practiced task. Update this file as work proceeds.
**Manual status:** not started · summarized · in practice · done
**Task status:** not practiced · practiced, awaiting confirmation · passed · not completed (see notes)
**Sample column:** whether the task has been re-tested on **CI-Eng-Sample**:
n/a (needs no project data) · pending (tested on AID only) · added (sample content built) · passed
A task is **done** only when Status is *passed* and Sample is *passed* or *n/a*. Then AID is no
longer needed to repeat it.
## Test system
Practice notes refer to the repo author's **development test system**, not to anything shipped
with this repo:
- CI Server R1.03.00, unlicensed, on the development machine.
- **AID** (e.g. `AID.WRPS.SIM.INFLOW`) is the author's own test project on that machine. It is
not in this repo and other systems will not have it. Item names here are evidence of what
was tested, not names to use elsewhere.
- Communication stations seen there (`WRPS_PLC`, `MODSIM_STATION`, `STN_MQTT`) belong to AID.
Tasks may be practiced first on AID, but everything they need is then added to the sample
project **CI-Eng-Sample** (`examples/CI-Eng-Sample/`) and re-tested there, so that in the end
AID is not needed.
## Manuals, in working order
| Phase | Manual | Title | Status |
|---|---|---|---|
| 0 | IM 36K01A50 | Release Information | summarized ([notes](manuals/IM36K01A50-01EN.md)) |
| 1 | IM 36K10J10 | System Design/Management | done except migration (phase 6) and debugging tools; skill `system-management` ([notes](manuals/IM36K10J10-01EN.md)) |
| 2 | IM 36K01C10 | CI Server Setup | not started |
| 2 | IM 36K01C30 | Security Guide | not started |
| 3 | IM 36K10G10 | Tutorial | not started |
| 4 | IM 36K10R10 | CI Portal Setup | not started |
| 4 | IM 36K10R20 | Setup File Editor | not started |
| 5 | IM 36K10C10 | Engineering Module - I/O Processes | not started |
| 5 | IM 36K10L40 | EQUIPMENT Service - Utilities | not started |
| 5 | IM 36K10L41 | EQUIPMENT Service - Configuration | not started |
| 5 | IM 36K10L35 | ITEM Service - ITH | not started |
| 5 | IM 36K10L36 | ITEM Service - ITM | not started |
| 6 | IM 36K10L10 | Class/Object Engineering | not started |
| 6 | IM 36K10P10 | Class Description Language - Traditional | not started |
| 6 | IM 36K10P11 | Class Description Language - Java | not started |
| 7 | IM 36K10L55 | Exchange Tool Engineering | not started |
| 7 | IM 36K10L30 | BUS Service | not started |
| 7 | IM 36K10L45 | Data Access Engineering | not started |
| 7 | IM 36K10E20 | OPC Interface | not started |
| 8 | IM 36K10L15 | Alarm Management Engineering | not started |
| 8 | IM 36K10C20 | Engineering Module - Alarms | not started |
| 8 | IM 36K10E30 | Alarm System Performance Analysis | not started |
| 9 | IM 36K10L20 | History Management Engineering | not started |
| 9 | IM 36K10C40 | Engineering Module - Historical | not started |
| 10 | IM 36K10R30 | Graphic Display Setup | not started |
| 10 | IM 36K10C50 | Edit Module | not started |
| 10 | IM 36K10C60 | Advanced Operating Graphics | not started |
| 11 | IM 36K10L50 | Data Set Service Engineering | not started |
| 11 | IM 36K10P30 | Data Set Service Language | not started |
| 11 | IM 36K10P20 | Report Generation Language | not started |
| 11 | IM 36K10R40 | Report Server Setup | not started |
| 11 | IM 36K10C30 | Engineering Module - Reporting | not started |
| 11 | IM 36K10E10 | Excel Add-in | not started |
| 12 | IM 36K10L25 | Audit Trail Management | not started |
| 13 | IM 36K10J20 | High Availability Computing | not started (needs two servers) |
| 13 | IM 36K10J40 | Active Directory Integration | not started (needs a domain) |
| — | IM 36K01A10 / A20 / A30 | Read Me First, License, OSS terms | skipped (no engineering content) |
Order change after reading IM 36K10J10: its migration procedure (§5.6) shows the dependency
chain *communication lines/stations/points → installations/units → items (template items
first) → storage groups → classes → objects → reports*. So acquisition and items (phase 5)
now come before classes and objects (phase 6), and the other interfaces follow as phase 7.
## Tasks
| Manual | Task | Status | Sample | Notes |
|---|---|---|---|---|
| J10 | System check: version, paths, running state, time sync ([skill](../.claude/skills/system-check/SKILL.md)) | passed | n/a | Started CI Service elevated; live version R1.03.00; node UNLICENCED (expected). |
| J10 | Time sync check (`w32tm`); DURUTL configuration (`durutl.sup`) | passed (check); configuration not practiced | n/a | `w32tm` check verified in system-check. `durutl.sup` has no active settings (single node, not a time master); configuring DURUTL needs a second node, so not practiced. |
| J10 | Export a dataset with `dssqld` ([task](../.claude/skills/system-management/tasks/export-dataset.md)) | passed | n/a | Filtered export (`@SELECT`) passed ([ISS-003](issues.md), closed). |
| J10 | Import and delete dataset records with `dssqld` (`-i`, `-r`) ([task](../.claude/skills/system-management/tasks/load-remove-records.md)) | passed | passed | Built CI-Eng-Sample: 3 sections + 4 items imported, removed and re-imported with 0 errors. 2026-09-30 later: `-m` (update, used to set a storage group stop time) and loading/removing storage groups passed; see [ISS-005](issues.md). |
| J10 | Read an item with `itmval -g` ([task](../.claude/skills/system-management/tasks/read-write-item.md)) | passed | passed | Read `AID.WRPS.*` items. `-a 1..5` gave `ITM-E-WRONG_ATT` on an item without limits; works on items with limits ([ISS-004](issues.md), closed). |
| J10 | Write an item with `itmval -p` ([task](../.claude/skills/system-management/tasks/read-write-item.md)) | passed | passed | Sample: `TANK1.INFLOW` 120.5 then 130 with `-s 9`, `PUMP1.RUNNING` 1 (status 5 BOOLEAN 1); no `uoff` flag. AID: `AID.WRPS.SIM.INFLOW` 419.76 → 400 → 419.76. After the first write the item's options gained the `uoff` flag (0x8a → 0x8e), which stays after restoring the value. See [ISS-001](issues.md). |
| J10 | Read the message log (`tls\log\umhlog.log`) | passed | n/a | |
| J10 | Per-component version list (`tls\lst\tls_versions.lst`) | passed | n/a | |
| J10 | Load history from CSV with `ithloahis`; read history back with `dssqld` ([task](../.claude/skills/system-management/tasks/load-history.md)) | passed | passed | Sample storage group `CIENG_EVENT` (Event/Item). SCAN file (LEVEL 61–63, INFLOW 101–103) and EVENT file (LEVEL 47, 48) stored and read back via `ITEM_HISTORY`. New groups need a CI Server restart before they store; samples dated before the current storage unit were not stored ([ISS-006](issues.md)). |
| J10 | Consistency check (`dsschk`, `ismchk`) ([task](../.claude/skills/system-management/tasks/consistency-check.md)) | passed (check); repair and `ismchk` not practiced | n/a | `dsschk -e -v` (check only) reports each of 228 datasets, no problems. Plain `dsschk` prints nothing on a single node. `ismchk` needs a database file name; not run ([ISS-002](issues.md), closed). |
| J10 | Monitoring processes (`intmon`, `intcpumon`, `intdskmon`, `inttcpmon`, `intspawn`) ([task](../.claude/skills/system-management/tasks/monitoring-processes.md)) | passed | passed | All five worked into `CI-Eng-Sample.SYSTEM.*` / `PUMP1.MODE`, started by hand with `<exe> -n <name>`; setup files restored afterwards. `intdskmon` reports **used** %; `intspawn` command path must be short ([ISS-007](issues.md)). |
| J10 | Backup of `tls` folders | not practiced | n/a | Plan only; the actual backup tool is site-specific. |
| J10 | Migration between systems (§5.6) | not practiced | pending | Needs engineered data; revisit after phase 6. |
| J10 | Tuning checks (read-only) ([task](../.claude/skills/system-management/tasks/tuning-checks.md)) | passed | n/a | Read `dur.sup` (max processes 250), `itm.sup` (item pool 650,000 KB) and the automatic health snapshots `tls\log\smd_*.log` (common memory free, queue use per process, lock collisions). Debug launchers and interactive debuggers not practiced. |