cliu
bf7d88a027
Full manual diffs (L15, C20, E30, L25, J40, C10 §2, L10, P10, P11, J20, C30, P20, R40, E10) and read-only checks on the shared R1.05 test server. Skills and summaries moved to R1.05; new skill pytools (IM 36K10P40) from docs (no Python on the test server). Issues ISS-132..181; corrections to version-differences (E10, E30, P11, dss_ath_grp_u0104); C10 summary lists the 3 new authorization actions; r105-verification V10-V17. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
161 lines
8.5 KiB
Markdown
161 lines
8.5 KiB
Markdown
---
|
||
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.05 (first written for R1.03)
|
||
source: IM 36K10C30-01EN §2.1, §2.3.1, §3, App. 1 (4th Edition, Feb. 2026); IM 36K10L50-01EN App. 1 (REPORT_DF, REPORT_VAL); IM 36K10P20-01EN (4th Edition, Feb. 2026); practiced on CI-Eng-Sample 2026-10-01
|
||
status: verified on R1.03 (2026-10-01, command line and Engineering Module); on R1.05 the REPORT_DF / REPORT_VAL definitions are identical to R1.03 (file hashes, 2026-10-08) and the sample's three reports loaded and were removed with 0 errors on the R1.05 test server (2026-10-08, load check only); generating, printing and deleting generated reports not tested on R1.05 (shared server)
|
||
---
|
||
|
||
# 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
|
||
"<REPORT>","<description>",0,1,1,"1 Weeks","01-01-2026 06:00:00","1 Days",1,"<DEST>","<DEST>","[ITEM:NAME like ""<Section>.*""]Item:",\
|
||
@"
|
||
select name, item_value, status from item_val where name like '<Section>.%';
|
||
if @p0 = '' then
|
||
set @item '<Section>.<Tag>';
|
||
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 <file>.qli -l <file>.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:<filter>]`, `[OBJECT:<class>:<filter>]`, `[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('<REPORT>')` |
|
||
| HTML | query writes `<HTML>…</HTML>` 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
|
||
"<REPORT>","<answer to prompt 1>",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<pid>`; the manager then logs `FSL-E-PRT_UNKUSER` and
|
||
prints nothing, even with `ADHOC_DEST` set (the report is still stored, ISS-045). To get printed
|
||
output, generate from the Engineering Module.
|
||
|
||
## 3. Read generated reports
|
||
|
||
```
|
||
@FIELDS
|
||
NAME,GENERATION_TIME,DELETION_TIME,USER_NAME,ACTION_PROCESS,CONTAINS_HTML,REPORT
|
||
@SELECT
|
||
'REPORT_NAME = "<REPORT>"'
|
||
@REPORT_VAL
|
||
```
|
||
|
||
`dssqld -e out.qlo <file>.qli` (no `-c`: the `REPORT` memo is multi-line). `NAME` is
|
||
`<REPORT>.<DD-MON-YY hh:mm:ss>`; `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
|
||
"<REPORT>.01-OCT-26 15:57:53","<DEST>",1
|
||
```
|
||
|
||
`dssqld -m`; check `PRINTER_JOB_OVV` and `umhlog.log` (`output-devices.md` §4).
|
||
|
||
## 5. Schedule and trigger behaviour (verified on R1.03)
|
||
|
||
- 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
|
||
"<REPORT>","",""
|
||
```
|
||
|
||
`dssqld -m`, then `dssqld -r` with `@FIELDS NAME` / `@REPORT_DF` / `"<REPORT>"`. This also deletes
|
||
the report's storage group, all its generated reports and its logbook file
|
||
(`%TLS_DAT_PATH%\<report>.lbk`). Remove reports before the trigger items and the destinations
|
||
they use.
|
||
|
||
## R1.05 (2026-10-08/09)
|
||
|
||
- **Verified (R1.05 test server, 2026-10-08):** the reduced CI-Eng-Sample load created the file
|
||
device and destination and the three reports with 0 errors (the sample files still say
|
||
`@VERSION 1.03.00`; R1.05 accepts them) and the sample's remove files (schedule cleared
|
||
first by `83a_stop_report_df.qli`, as in §6) removed them with 0 errors. Generation was not run.
|
||
- **Awaiting user verification:** generate, read, print and delete on R1.05. On a non-shared
|
||
R1.05 system load the sample (`examples/CI-Eng-Sample/`), then run §2 for `CIENG_TANK1` with
|
||
`PARAM_VALUE_1` = `CI-Eng-Sample.TANK1.INFLOW`, §3, §4 to `CIENG_FILE`, write 450 to
|
||
`TANK1.INFLOW` (trigger), and remove. Expected as on R1.03: `GENERATE` back to 0, a
|
||
`REPORT_VAL` record per run, the `dssqld` run not printed (`FSL-E-PRT_UNKUSER`, ISS-045), the
|
||
trigger run printed by `RPTMAN`.
|
||
- Queries may now use `ITEM_VAL.ENG_UNIT`, `SCALE_HIGH_LIMIT`, `SCALE_LOW_LIMIT`
|
||
(`rql-interactive.md` §4). Report queries written for R1.03 on `OPCUAC_METHOD_CALL_IN_DF` /
|
||
`_OUT_DF` must move to `OPCUAC_METHOD_CALL2_DF`.
|
||
|
||
## Verified on CI-Eng-Sample (R1.03, 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.
|
||
|
||
Engineering Module (checked by the user 2026-10-01): the forms show the loaded fields (General:
|
||
*Report destination* = `DEST_NAME`, no field for `ADHOC_DEST`; Query with Structure / Keywords /
|
||
Datasets panes; Time scheduling with *Correct for daylight saving*; Item triggering). Right-click ›
|
||
*Generate* opens a dialog with *Destination* (preset `<None>`, `ADHOC_DEST` is not pre-selected) and
|
||
one field per parameter prompt; an `[ITEM:<filter>]` prompt gives an item tree browser. The
|
||
filter is an `ITEM_DF` filter (DSS syntax) added with `AND` for each tree node: all sections and
|
||
objects stay visible, but only matching items (and their sub-items) appear and can be picked.
|
||
Verified by the user: `NAME like "<Section>.*"`, `NAME like "*.L*"`, `DESCRIPTION like "Tank 1*"`
|
||
work; `%` is not a wildcard and `NAME = "….*"` matches nothing (no items, no error);
|
||
`SECTION = …` is not an `ITEM_DF` field (`DSS-E-FLT_SYN_ERR` on every expand) (ISS-048). The run is made by the logged-in user (`ADMIN`, process
|
||
`JHMISET…`) and printed to the chosen destination without errors. Generated reports are listed under
|
||
the report by local time; *View* has its own *Destination* box and *Export…*; HTML reports render as
|
||
HTML.
|