From d7e30fa46e7f35d83a08ed30bb37778738e2f27c Mon Sep 17 00:00:00 2001 From: cliu Date: Thu, 1 Oct 2026 16:17:02 +1000 Subject: [PATCH] Add reporting skill and DSS tools task New skill reporting: REPORT Service checks, interactive RQL, report definitions by quick load, file output devices. New task system-management/dss-tools.md: DSS processes, dss.sup, quick load directives, dssutl, DSS compiler syntax check. Co-Authored-By: Claude Opus 5.5 --- .claude/skills/history-management/SKILL.md | 2 +- .claude/skills/reporting/SKILL.md | 45 ++++++ .../skills/reporting/tasks/define-reports.md | 132 ++++++++++++++++++ .../skills/reporting/tasks/output-devices.md | 75 ++++++++++ .../skills/reporting/tasks/report-checks.md | 68 +++++++++ .../skills/reporting/tasks/rql-interactive.md | 77 ++++++++++ .claude/skills/system-management/SKILL.md | 6 +- .../system-management/tasks/dss-tools.md | 81 +++++++++++ 8 files changed, 484 insertions(+), 2 deletions(-) create mode 100644 .claude/skills/reporting/SKILL.md create mode 100644 .claude/skills/reporting/tasks/define-reports.md create mode 100644 .claude/skills/reporting/tasks/output-devices.md create mode 100644 .claude/skills/reporting/tasks/report-checks.md create mode 100644 .claude/skills/reporting/tasks/rql-interactive.md create mode 100644 .claude/skills/system-management/tasks/dss-tools.md diff --git a/.claude/skills/history-management/SKILL.md b/.claude/skills/history-management/SKILL.md index 821a159..edb3a49 100644 --- a/.claude/skills/history-management/SKILL.md +++ b/.claude/skills/history-management/SKILL.md @@ -37,4 +37,4 @@ Rules: | Check groups, units, clients, rollover with `hisdbg` | `tasks/history-checks.md` | verified | | Archive / retrieve, `hasdbg` | C40 summary §4, L20 summary §5 | from docs (no archive device) | | Repair and recovery (`hisrep`, `hisrecover`, `isfrename`, `hiswrn`) | L20 summary §4 | from docs | -| Reading history from classes, reports, ODBC | C40 summary §5 | from docs (phases 6, 11) | +| Reading history from classes and reports; ODBC | C40 summary §5; reports: skill `reporting` | verified for reports (`rql-interactive.md`); ODBC from docs | diff --git a/.claude/skills/reporting/SKILL.md b/.claude/skills/reporting/SKILL.md new file mode 100644 index 0000000..d3b083f --- /dev/null +++ b/.claude/skills/reporting/SKILL.md @@ -0,0 +1,45 @@ +--- +name: reporting +description: >- + CI Server R1.03 REPORT Service, report definitions and RQL. Use when the user wants to create, + change, schedule or delete a report (daily / shift / hourly report, report triggered by an + item value or status, ad-hoc report with parameters such as an item, object, date or list), + write or debug an RQL query (SELECT from item_val, item_history, alarm_current, alarm_chrono, + audit_trail, unit_df …, COLUMN formats, HEADER/FOOTER, cursors DECLARE/FETCH, LOOP, GPV_VALUE, + @P0 parameters, @DATE), generate a report now (GENERATE), view, print or delete generated + reports (REPORT_VAL), output a report to a file, CSV (SPOOL, @EXPORT) or HTML, use a logbook, + set up report printers (printer device, destination, FILE / HARDCOPY output, PRINTER_DEV_DF, + PRINTER_DEST_DF), try queries in the interactive report generator (rptgen -s rptgen.rpt), stop + a hanging report (rptstp), check REPORT Service (rptman, rptge1, rptman.sup, rptge1.rpt, + report_start), use the system reports (ALARM_HISTORY, AUDIT_TRAIL, ITEM_HISTORY, SYSTEM_LOG …), + put a report component on a display, or use the Excel Add-in (DART) for reports. Sources + IM 36K10C30-01EN, IM 36K10P20-01EN, IM 36K10R40-01EN, IM 36K10E10-01EN. +--- + +# Reporting (R1.03) + +Background: `knowledge/manuals/IM36K10C30-01EN.md` (report definition fields, scheduling and +trigger behaviour, devices, generated reports, system reports), `IM36K10P20-01EN.md` (RQL), +`IM36K10R40-01EN.md` (REPORT Service processes and set-up files), `IM36K10E10-01EN.md` (Excel +Add-in), `IM36K10L50-01EN.md` (datasets, `dssqld`). + +Rules: +- Run `system-check` first; follow the user's chosen way of working. +- Report names ≤ 16 characters. Report queries only **read**, except `SPV_*` functions and + `GPV_VALUE(, )` (resets the item) — never use those without approval. +- A scheduled report runs on its own; schedule at least every 10 minutes and set a lifetime, or + generated reports pile up in history. +- Generator set-up files (`tls\sup\*.rpt`), `rptman.sup` and `report_start.cmd` need admin rights + and a restart: hand them to the user (skill `portal-setup`, `change-setup-file.md`). +- Example names come from `CI-Eng-Sample` (`CIENG_TANK1`, `CIENG_INFLOW_HI`, `CIENG_HTML`, + destination `CIENG_FILE`). + +| Task | File | Status | +|---|---|---| +| Check REPORT Service: processes, set-up files, system reports, stop a hanging report (`rptstp`) | `tasks/report-checks.md` | verified | +| Try RQL in the interactive generator (`rptgen -s rptgen.rpt`), CSV with `SPOOL` | `tasks/rql-interactive.md` | verified | +| Define reports by quick load (ad hoc with parameters, schedule, item trigger, HTML, logbook); generate, read, print, delete; remove | `tasks/define-reports.md` | verified (command line); Engineering Module forms awaiting the user's check | +| Report output to a file: printer device and destination | `tasks/output-devices.md` | verified | +| Report component on a display; Operator Interface generate/view | C30 summary §5 | from docs | +| Hardcopy printers, application devices, more generators, separate RPI servers | C30 summary §3, R40 summary §1, §3 | from docs | +| Excel Add-in (DART) | E10 summary | from docs (Excel not installed on the test system) | diff --git a/.claude/skills/reporting/tasks/define-reports.md b/.claude/skills/reporting/tasks/define-reports.md new file mode 100644 index 0000000..9f2f768 --- /dev/null +++ b/.claude/skills/reporting/tasks/define-reports.md @@ -0,0 +1,132 @@ +--- +task: Define reports by quick load (ad hoc with parameters, schedule, item trigger, HTML, logbook); generate, read, print and delete generated reports; remove reports +version: R1.03 +source: IM 36K10C30-01EN §2.1, §2.3.1, §3, App. 1; IM 36K10L50-01EN App. 1 (REPORT_DF, REPORT_VAL); IM 36K10P20-01EN; practiced on CI-Eng-Sample 2026-10-01 +status: verified (command line); Engineering Module forms awaiting the user's check +--- + +# Define and run reports + +Reports live in `REPORT_DF` (definitions) and `REPORT_VAL` (generated reports). This task uses +quick load (`dssqld`); the Engineering Module equivalent is *Configuration > Reporting > Reports* +(right-click › *Add*; tabs *General*, *Query*, *Time scheduling*, *Item triggering*). Field +meanings: `knowledge/manuals/IM36K10C30-01EN.md` §2. Test queries first in the interactive +generator (`rql-interactive.md`). Working examples: `examples/CI-Eng-Sample/18_report_df.qli`. + +## 1. Report definition file + +``` +@LANGUAGE +ENGLISH + +@FIELDS +NAME,DESCRIPTION,PRIORITY,ADHOC_ENABLED,LOGBOOK_ENABLED,LIFE_TIME,ACTIVATION_TIME,GENERATION_INTERVAL,CORRECT_DAYLIGHT,DEST_NAME,ADHOC_DEST,PARAM_PROMPT_1,QUERY + +@REPORT_DF +"","",0,1,1,"1 Weeks","01-01-2026 06:00:00","1 Days",1,"","","[ITEM:NAME like ""
.*""]Item:",\ +@" +select name, item_value, status from item_val where name like '
.%'; +if @p0 = '' then + set @item '
.'; +else + set @item @p0; +endif; +select count(item_value), avg(item_value) from item_history + where item_name = @item and sample_time > @date - 3600; +"@ +``` + +`dssqld -i .qli -l .qlo`, check `Errors` 0. Inside the query use single quotes for +strings; the memo runs from `@"` to `"@` and needs no `\` continuation. + +| Want | Fields | +|---|---| +| Ad hoc only | `ADHOC_ENABLED` 1; leave `ACTIVATION_TIME` / `GENERATION_INTERVAL` out | +| Parameters | `PARAM_PROMPT_n` (`[ITEM:]`, `[OBJECT::]`, `[DATE:TIME]`, `[LIST:a:b]` + text); the query reads `@P0`… (strings; `number(@p0)` for numbers and dates) | +| Schedule | `ACTIVATION_TIME` (first run, `dd-mm-yyyy hh:mm:ss`), `GENERATION_INTERVAL` **≥ 10 minutes** (`HIS-E-ROLLTOFAST` otherwise), `CORRECT_DAYLIGHT` 1 for a fixed local time | +| Item trigger | `TRIGGER_ITEM`, `TRIGGER_CON_1` (`Greater Than`, `Less Than`, `Equal To`, `Not Equal To`, `Greater Or Equal Than`, `Less Or Equal Than`), `TRIGGER_VAL_1`, optional second condition with `TRIGGER_COMB` `And`/`Or`, or status `TRIGGER_STAT_1/2`; `DELAY` e.g. `"5 Seconds"` | +| Output | `DEST_NAME` (scheduled and triggered runs) and `ADHOC_DEST` (ad-hoc runs): destinations from `output-devices.md` | +| Keep for | `LIFE_TIME` (also the lifetime of the report's storage group) | +| Logbook | `LOGBOOK_ENABLED` 1, text in `LOGBOOK` (memo); query: `logbook_text('')` | +| HTML | query writes `…` lines after `header ''; footer ''; set @page_size 0; set @width 512;` — `CONTAINS_HTML` becomes 1 by itself | + +Loading creates a storage group of type *Report* with the report's name (`HIS_GROUP_DF`). The page +header/footer come from `tls\sup\rptge1.rpt` (customer name, description, date, report name, page) +unless the query sets its own. + +Change a report: `dssqld -m` with `NAME` plus the fields to change. + +## 2. Generate now (ad hoc) + +``` +@FIELDS +NAME,PARAM_VALUE_1,GENERATE +@REPORT_DF +"","",1 +``` + +`dssqld -m`. `GENERATE` returns to 0 when finished (a second or two for small reports). The run is +made as user `FULL AUTHORIZATION` by `DSSQLD`; without `ADHOC_DEST` the manager then logs +`FSL-E-PRT_UNKUSER` (the report is still stored, ISS-045). + +## 3. Read generated reports + +``` +@FIELDS +NAME,GENERATION_TIME,DELETION_TIME,USER_NAME,ACTION_PROCESS,CONTAINS_HTML,REPORT +@SELECT +'REPORT_NAME = ""' +@REPORT_VAL +``` + +`dssqld -e out.qlo .qli` (no `-c`: the `REPORT` memo is multi-line). `NAME` is +`.`; `DELETION_TIME` = generation + lifetime; `ACTION_PROCESS` is +`RPTMAN` for scheduled/triggered runs. Engineering Module: expand the report, right-click a +generated report › *View*. + +## 4. Print / send a generated report to a destination + +``` +@FIELDS +NAME,DEST_NAME,PRINT +@REPORT_VAL +".01-OCT-26 15:57:53","",1 +``` + +`dssqld -m`; check `PRINTER_JOB_OVV` and `umhlog.log` (`output-devices.md` §4). + +## 5. Schedule and trigger behaviour (verified) + +- After each run `ACTIVATION_TIME` moves to the next slot. A start time in the past is moved + forward, not caught up. +- `CORRECT_DAYLIGHT` 0 counts in UTC: 06:00 set in summer time ran at 05:00 in winter time. +- An item trigger fires when the condition **becomes** true: 0 → 450 (limit 400) gave a report + after the 5 s delay; 450 → 430 did not; back to 0 and up again gave another. + +## 6. Delete generated reports and remove reports + +- One generated report: `dssqld -r` on `REPORT_VAL` with `@FIELDS NAME` and the full name (needs + `REPORT_DELETE_GENERATED_REPORT`). +- A report definition: **clear the schedule first** — a scheduled report cannot be deleted + (`RPT-E-ACTIVE`): + +``` +@FIELDS +NAME,ACTIVATION_TIME,GENERATION_INTERVAL +@REPORT_DF +"","","" +``` + + `dssqld -m`, then `dssqld -r` with `@FIELDS NAME` / `@REPORT_DF` / `""`. This also deletes + the report's storage group, all its generated reports and its logbook file + (`%TLS_DAT_PATH%\.lbk`). Remove reports before the trigger items and the destinations + they use. + +## Verified on CI-Eng-Sample (2026-10-01) + +`CIENG_TANK1` (parameter `[ITEM:…]`, daily 06:00 with `CORRECT_DAYLIGHT` 1, ad-hoc destination), +`CIENG_INFLOW_HI` (trigger `TANK1.INFLOW` > 400, delay 5 s) and `CIENG_HTML` (cursor loop, HTML, +logbook) loaded, generated (ad hoc with `@P0` = `TANK1.INFLOW`, by trigger 5 s after the write, by +schedule), read, printed to `CIENG_FILE`, deleted; full sample remove/reload with 0 errors. Not yet +checked by the user: the same reports in the Engineering Module forms (generate dialog with the +item pick list, *View* of the HTML report). diff --git a/.claude/skills/reporting/tasks/output-devices.md b/.claude/skills/reporting/tasks/output-devices.md new file mode 100644 index 0000000..c4fa3d3 --- /dev/null +++ b/.claude/skills/reporting/tasks/output-devices.md @@ -0,0 +1,75 @@ +--- +task: Send reports to a file - printer device and destination +version: R1.03 +source: IM 36K10C30-01EN §2.2; IM 36K10L50-01EN App. 1 (PRINTER_*); practiced on CI-Eng-Sample 2026-10-01 +status: verified +--- + +# Report output devices and destinations + +A report goes to a **destination** (`PRINTER_DEST_DF`), which sends it to a primary (and optional +secondary) **device** (`PRINTER_DEV_DF`). Devices: FILE, HARDCOPY (Windows printer queue), +APPLICATION. Engineering Module: *Configuration > Reporting > Printers > Device / Destinations*. +The printer manager is `FMFPRT`. + +## 1. Find the output types of this node + +``` +dssqld -e types.csv -d PRINTER_TYPE_DF -c +``` + +Names are `:FILE`, `:HARDCOPY`, `:APPLICATION` (`` = CI Server node name, +`NODE_NAME` in `LOCAL_NODE_DF`, e.g. `UNLICENCED` on an unlicensed system). A device needs the full +name; plain `FILE` is refused (`DSSP-E-NORELV`). + +## 2. File device and destination + +``` +@FIELDS +NAME,DESCRIPTION,OUTPUT_TYPE,PARAMETERS,SUSPEND +@PRINTER_DEV_DF +"","Report file",":FILE","PATH,"""",FILE,"".txt"",OVERWRITE,""Yes""",0 + +@FIELDS +NAME,DESCRIPTION,PRIMARY_DEVICE,POLICY,ALLOW_OPERATOR,PRIORITY +@PRINTER_DEST_DF +"","Report file","","None",1,0 +``` + +`dssqld -i`. `` must be a literal path that exists (no `%variables%`: `FSL-E-PRT_PAR, +Invalid device parameter` in `umhlog.log`). `OVERWRITE "Yes"` keeps one file with the latest +report (`"No"` not tried). `ALLOW_OPERATOR` 1 also lists the destination in +`PRINTER_OPER_DEST_DF` (needed for `ADHOC_DEST` and the operator's generate/print dialogs). +`CI-Eng-Sample` builds this file at load time from `17_printer_df.tpl` (node name and +`%TLS_LST_PATH%` filled in by `17_printer_df.ps1`). + +Printer instead of file: `OUTPUT_TYPE` `:HARDCOPY`, `PARAMETERS` +`TYPE,"WINDOWS",QUEUE,"\\\"` (+ `FONT`, `POINT`, `LINES`, `ORIENTATION`) — not +practiced (no printer). + +## 3. Use it + +Set `DEST_NAME` (scheduled/triggered runs) and `ADHOC_DEST` (ad-hoc runs) of the report to +``, or print a generated report (`define-reports.md` §4). + +## 4. Check + +``` +dssqld -e jobs.csv -d PRINTER_JOB_OVV -c (job, file, submitter, status, destination, device) +dssqld -e devs.csv -d PRINTER_DEV_OVV -c (device status, e.g. Ready) +``` + +A job can show *Finished* even when the device failed; also read `%TLS_LOG_PATH%\umhlog.log` +(`From: FMFPRT`, `FSL-E-…`). The output file holds the text report as generated (HTML reports as +HTML source). + +## 5. Remove + +Remove (or repoint) the reports that use the destination, then the destination, then the device +(`DSSP-E-NODEL … still in use` otherwise). The output file is not deleted. + +## Verified (2026-10-01) + +`CIENG_FILE` (`UNLICENCED:FILE`, `C:\Users\Public\Yokogawa\tls\lst\cieng_report.txt`, overwrite): +printed generated reports, scheduled, triggered and ad-hoc runs wrote the file; jobs *Finished*, +device *Ready*; `%TLS_LST_PATH%` in the path failed as above. diff --git a/.claude/skills/reporting/tasks/report-checks.md b/.claude/skills/reporting/tasks/report-checks.md new file mode 100644 index 0000000..3b66f8a --- /dev/null +++ b/.claude/skills/reporting/tasks/report-checks.md @@ -0,0 +1,68 @@ +--- +task: Check REPORT Service (processes, set-up files, system reports) and stop a hanging report +version: R1.03 +source: IM 36K10R40-01EN §1.3, §2.2, §2.3, §5; IM 36K10C30-01EN §4, App. 1.3; practiced on the test system 2026-10-01 +status: verified +--- + +# REPORT Service checks + +All read-only except `rptstp` (cancels one running report). + +## 1. Processes + +``` +durwfp -p rptman -t 0 (errorlevel 0 = running) +tasklist /FI "IMAGENAME eq rpt*" +``` + +Default: `rptman.exe` (manager) and one `rptgen.exe` attached as `RPTGE1`. The `rpi*` info servers +are linked into the generator, so they do **not** run as processes unless `report_start.cmd` was +changed. REPORT Service is started by `%TLS_ROOT_PATH%\tls\com\report_start.cmd` and only if +HISTORY Service (`his`) runs. + +## 2. Set-up files (`%TLS_ROOT_PATH%\tls\sup`) + +| File | For | What to read | +|---|---|---| +| `rptman.sup` | Manager | `his = 0, HIS, 0`, `dur_queue_size = 500` | +| `rptge1.rpt` | Background generator `RPTGE1` | Page layout (`@page_size 66`, `@width 120`, margins), default header/footer, `@workspace 500`, `dictionary rpidis.'tlsdic';`, `login rptman;` (priority 0) — every report starts with this | +| `rptgen.rpt` | Interactive generator | No `login` (= interactive), `@page_size 23`, `@formfeed 0` | +| `rptgsp.rpt` | Spare generator, priority 9 | Not started by default | + +Messages of the manager and printer manager go to `%TLS_LOG_PATH%\umhlog.log` (`--> From: +RPTMAN`, `FMFPRT`; codes `RPT-…`, `FSL-…`). + +## 3. Defined and generated reports + +``` +@FIELDS +NAME,DESCRIPTION,PRIORITY,ADHOC_ENABLED,LIFE_TIME,ACTIVATION_TIME,GENERATION_INTERVAL,DEST_NAME,ADHOC_DEST,PARAM_PROMPT_1 +@SELECT +@REPORT_DF +@FIELDS +NAME,REPORT_NAME,GENERATION_TIME,DELETION_TIME,USER_NAME,ACTION_PROCESS +@SELECT +@REPORT_VAL +``` + +`dssqld -e reports.csv .qli -c`. A fresh R1.03 system has 28 system reports (all ad hoc, +lifetime 1 week, priority 0), listed in `IM36K10C30-01EN.md` §8. Add `QUERY` to the field list +(without `-c`) to read their RQL — useful examples. + +## 4. Stop a hanging report + +A report in an endless loop keeps its generator busy (`REPORT_DF.GENERATE` stays 1). Stop it: + +``` +rptstp rptge1 +``` + +Verified: the loop stopped at once, `GENERATE` went back to 0, the generator stayed up and ran the +next report. An empty generated report remains; delete it (`define-reports.md` §6). From the +user side the manual names the *Cancel* button and `REPORT_DF.CANCEL` = 1 (not tried). + +## Verified (2026-10-01) + +`rptman` and `rptgen` running; `rpi*` lines commented out in `report_start.cmd`; set-up files as +above; 28 system reports; `rptstp rptge1` cancelled the test report `CIENG_LOOP`. diff --git a/.claude/skills/reporting/tasks/rql-interactive.md b/.claude/skills/reporting/tasks/rql-interactive.md new file mode 100644 index 0000000..ed83eec --- /dev/null +++ b/.claude/skills/reporting/tasks/rql-interactive.md @@ -0,0 +1,77 @@ +--- +task: Try RQL queries in the interactive report generator; write CSV with SPOOL +version: R1.03 +source: IM 36K10R40-01EN §4; IM 36K10P20-01EN §3–6, §9; IM 36K10C30-01EN §3.2.3; practiced on the test system and CI-Eng-Sample 2026-10-01 +status: verified +--- + +# RQL in the interactive generator + +`rptgen -s rptgen.rpt` starts a report generator in the console (prompt `RPT>`). It reads RQL, +prints results at once and needs no report definition — the quickest way to test a query or look +into a dataset. CI Server must be running. Read-only unless the query uses `SPV_*` or +`GPV_VALUE(…, )`. + +## 1. Run a query file + +Put the statements in a file (each ends with `;`) and pipe it in; end with `QUIT;`: + +``` +set @next 0; +set @width 132; +column t as 'DD-MMM-YYYY hh:mm:ss' heading 'Time'; +select name, item_value, status from item_val where name like 'CI-Eng-Sample.TANK1.%'; +select sample_time t, item_value, quality from item_history + where item_name = 'CI-Eng-Sample.TANK1.LEVEL' and group_name = 'CIENG_SCAN10S' + and sample_time > @date - 600 order by sample_time; +select count(item_value), min(item_value), max(item_value), avg(item_value) from item_history + where item_name = 'CI-Eng-Sample.TANK1.LEVEL' and sample_time > @date - 3600; +select gpv_value('CI-Eng-Sample.TANK1.LEVEL', 0), gpv_status('CI-Eng-Sample.TANK1.LEVEL'); +quit; +``` + +``` +rptgen -s rptgen.rpt < query.rql > query.out +``` + +(Git Bash: `timeout 60 rptgen -s rptgen.rpt < query.rql`; PowerShell does not support `<`, use +`cmd /c "rptgen -s rptgen.rpt < query.rql"`.) + +- `set @next 0;` first, otherwise output stops after each page (`Press to continue`). +- `rptgen.rpt` has `@page_size 23`, so headings repeat every 23 lines; `set @page_size 0;` for one + long list. +- Errors show the code and a caret under the position, e.g. `RPT-E-ALIASSEL` (an alias used twice + in one SELECT), `RPT-E-UNKFLDSPC` (unknown field). Field names: `dssqld -f -d `. +- `LOOP` does not work here (`RPT-E-LPNOTAL`); test loops and cursors in a report definition + (`define-reports.md`). +- `@P0`…`@P7` and `@NAME` do not exist here; `SET` them to test a report query. + +## 2. Dates + +RQL dates are seconds since 1970 in **local time**. `@date` is now; constants like +`01-Oct-2026 15:00` or `12:00` (today) need no quotes; `number('01-Oct-2026 15:00')` converts text. +Show them with a date format (`column t as 'DD-MMM-YYYY hh:mm:ss'`). `to_gmt(@date)` gives real +Unix time (10 h less on a UTC+10 system) — use it only when another program needs UTC. + +## 3. CSV file with SPOOL + +``` +spool 'C:\Users\Public\Yokogawa\tls\lst\cieng_levels.csv'; +set @export 1; +select name, item_value, status from item_val where name like 'CI-Eng-Sample.TANK1.%'; +spool; +set @export 0; +``` + +Result: one line per row, strings quoted (`"CI-Eng-Sample.TANK1.LEVEL",61,"NORMAL"`), no headings. +File name ≤ 79 characters, literal (no `%variables%`), overwritten each time, never cleaned up by +CI Server — delete it when done. The same statements work inside a report definition. + +## Verified (2026-10-01) + +Current values, history of `CIENG_EVENT` / `CIENG_SCAN10S` (count 299 in an hour at 10 s), group +functions, `GROUP BY` on `unit_df`, `GPV_VALUE`/`GPV_STATUS`/`GPV_QUALITY` (61, 9, 0), string and +date functions (`SUBSTR`, `DECODE`, `NUMBER`, `DRAW`, `LINE`, `MONTH_DAYS`, `TO_GMT`), integer vs +real arithmetic (`12/5+10.0` = 12), CSV via `SPOOL` (file removed afterwards). Aggregated history +(`interpolation = '30Minutes'`) returned no rows because the test system had no completed +aggregation periods (also empty through `dssqld`). diff --git a/.claude/skills/system-management/SKILL.md b/.claude/skills/system-management/SKILL.md index 9f1df69..28f6c51 100644 --- a/.claude/skills/system-management/SKILL.md +++ b/.claude/skills/system-management/SKILL.md @@ -8,7 +8,10 @@ description: >- a system, tune or debug CI Server, or plan a system layout (standalone, separate portal, HAC, host-to-host, enterprise) or time synchronization, check whether a CI Server process is running (durwfp), stop a single process (durstp), read the message log (umhlog), or check - BUS Service queues (adaptive queues, dur.sup). Sources IM 36K10J10-01EN, IM 36K10L30-01EN. + BUS Service queues (adaptive queues, dur.sup), or work with DSS / Data Set Services (dsssda, + dssevt, dssman, dss.sup, quick load macros and includes, memo fields from a file, dssutl, + DSS compiler dss, .dss files, data dictionary tlsdic_dss.dic). Sources IM 36K10J10-01EN, + IM 36K10L30-01EN, IM 36K10L50-01EN, IM 36K10P30-01EN. --- # System management (R1.03) @@ -34,3 +37,4 @@ Rules for every task: | Database consistency check (`dsschk`) | `tasks/consistency-check.md` | verified (check only) | | Tuning checks: limits and health snapshots | `tasks/tuning-checks.md` | verified (read-only) | | BUS Service utilities: is a process attached (`durwfp`), stop one process (`durstp`), message tools, adaptive queues | `tasks/bus-utilities.md` | verified (`durwfp`, read-only checks); message tools fail (ISS-030) | +| DSS checks and tools: DSS processes, `dss.sup`, quick load macros/includes/memo files, `dssutl`, DSS compiler syntax check | `tasks/dss-tools.md` | verified | diff --git a/.claude/skills/system-management/tasks/dss-tools.md b/.claude/skills/system-management/tasks/dss-tools.md new file mode 100644 index 0000000..b3b14a5 --- /dev/null +++ b/.claude/skills/system-management/tasks/dss-tools.md @@ -0,0 +1,81 @@ +--- +task: DSS (Data Set Services) checks and tools - processes, dss.sup, quick load directives, dssutl, DSS compiler syntax check +version: R1.03 +source: IM 36K10L50-01EN §1, §2.1, §2.2, §3, §4; IM 36K10P30-01EN §2, §3; practiced on the test system 2026-10-01 +status: verified +--- + +# DSS tools + +Everything here is read-only except where marked. Background: +`knowledge/manuals/IM36K10L50-01EN.md`, `IM36K10P30-01EN.md`. + +## 1. DSS processes and `dss.sup` + +`tasklist /FI "IMAGENAME eq dss*"` — expect `dsswth`, `dssana`, `dssanc`, `dssadb`, `dsslck`, +`dssman`, `dsschk` (server) and several `dsssda` / `dssevt` (10 and 7 on a default R1.03 node). +`durwfp -p dssman -t 0` tests one by its BUS Service name (`DSSSDA00`…, `DSSSDAOPC00`…, +`DSSEVT00`…). Started by `tls\com\database_start.cmd`; the number of general `DSSSDA` comes from +`%TLS_MAX_SDA_ID%` (default 3 → `DSSSDA00`–`03`). + +`%TLS_ROOT_PATH%\tls\sup\dss.sup` (Setup File Editor or text): queue sizes, heartbeats, `FLOWC`, +and `DSSSDA_SRV` / `DSSEVT_SRV` lines `, "", ""` that tie +clients to server instances (`*` = all others). Changing it needs admin rights and a restart. + +## 2. Quick load directives (`dssqld`) + +Besides `@FIELDS`, `@SELECT`, `@LANGUAGE` and `@` (tasks `export-dataset.md`, +`load-remove-records.md`): + +``` +@LANGUAGE +ENGLISH +@MACRO +RPT_FIELDS,NAME,DESCRIPTION,ADHOC_ENABLED,LIFE_TIME,QUERY +@INCLUDE +"part2" +``` + +with `part2.qli` in the current folder starting `@FIELDS` / `RPT_FIELDS` / `@` … — +macros must come before any data; includes and macros nest up to 10 deep. + +Memo fields (class methods, report queries, logbooks): inline `@"` … `"@` (preferred), empty +`@""@`, or `@""@`. The file form is read by the server side: use an **absolute path of at +most 82 characters** (relative names fail with `CRL-E-ENOENT`, longer ones with +`DSSG-E-STRBUFSMAL`; ISS-046). + +## 3. `dssutl` - read one record interactively + +Menu tool on the primary index. Pipe the answers (Git Bash): + +``` +printf '1\n\n2\n2\n1\n1\n\n-1\n-1\n-1\n-1\n-1\n-1\n' | timeout 30 dssutl +``` + += choose a data set › number from the list (first run `printf '1\n-1\n-1\n'` to see the +numbered list, e.g. `REPORT_DF` was 209) › choose a field set › all fields › read equal › enter +the key. Values are raw: dates in seconds since 1970 (local time), intervals as +`.` (`10.1` = 10 minutes, `1.3` = 1 day, `1.4` = 1 week), memos as the path of +their container file. The *Modify* menu writes to the running system — use `dssqld -m` instead +unless the user asks for `dssutl`. + +## 4. DSS compiler as a syntax checker + +To check a `.dss` file (custom dataset or an edited copy) without touching the dictionary: + +``` +mkdir \dss ; copy "%TLS_ROOT_PATH%\tls\src\*.dss" \dss (or only your file + dss_global.dss) +cd \dss +dss -l -w +``` + +Without `-d` the compiler only checks; results are in `tlsdic_dss.lst` (` (,): +` and ` errors found.`). **Never run `dss -d` without the user's approval**: it rewrites +`%TLS_DAT_PATH%\tlsdic_dss.dic` (host node only) and needs a restart. + +## Verified (2026-10-01) + +17 DSS processes as listed; installed `dss.sup` routing read; macro + include load of a report; +memo from file (relative fails, 125-character path fails, short absolute path works); `dssutl` +read of `REPORT_DF` record `CIENG_TANK1`; compiler check of all 253 installed files (0 errors, +dictionary unchanged) and of a test file with a missing `>` (1 error, line/column shown).