---
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
---

# 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.

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:…]` prompt gives an item tree browser, but the filter did
**not** limit it (whole tree shown, 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.