ci-server-engineer/.claude/skills/reporting/tasks/define-reports.md

task	version	source	status
Define reports by quick load (ad hoc with parameters, schedule, item trigger, HTML, logbook); generate, read, print and delete generated reports; remove reports	R1.05 (first written for R1.03)	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	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.