cliu
d7e30fa46e
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 <noreply@anthropic.com>
132 lines
5.9 KiB
Markdown
132 lines
5.9 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.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
|
||
"<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>`; 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>"'
|
||
@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)
|
||
|
||
- 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.
|
||
|
||
## 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).
|