--- manual: IM 36K10C30-01EN title: Engineering Module - Reporting edition: 4th Edition, Feb. 2026 (R1.05); content unchanged since the 3rd Edition, Sep. 2023 (R1.03): the revision table lists contact information only and a full text diff found only title spacing version: R1.05 (first written for R1.03) status: verified on R1.03 (2026-10-01): report definitions (ad hoc with parameters, schedule, item trigger, HTML, logbook), generated reports, file device and destination by quick load on CI-Eng-Sample; Engineering Module forms, generate and view checked by the user. R1.05 test server: REPORT_DF / REPORT_VAL / PRINTER_* definitions identical to R1.03 (2026-10-08), sample reports and file device loaded and removed with 0 errors (2026-10-08), system reports and factory destinations checked read-only (2026-10-09); generation not tested on R1.05. Report component in displays and hardcopy printers from docs --- # Engineering Module - Reporting (R1.05) Defining, generating and viewing reports. Language: `IM36K10P20-01EN.md`; REPORT Service processes: `IM36K10R40-01EN.md`. Section numbers refer to the manual; dataset fields were read with `dssqld -f` on the installed system. ## 1. Flow (§1) Define (Engineering Module *Configuration > Reporting > Reports*, or quick load `REPORT_DF`) → generate (schedule, item trigger, or ad hoc from the Engineering Module, a display or `REPORT_DF.GENERATE`) → output (destination device: file, printer, application; or `SPOOL` in the query) → kept as a generated report (`REPORT_VAL`) in the report's own storage group for its lifetime. ## 2. Report definition (§2.1, dataset `REPORT_DF`) | Form field | `REPORT_DF` field | Notes (installed) | |---|---|---| | Name | `NAME` | max 16 characters | | Description | `DESCRIPTION` | max 80; printed in the default header | | Report destination | `DEST_NAME` | a `PRINTER_DEST_DF` name; used by scheduled/triggered runs | | Ad-hoc destination | `ADHOC_DEST` | a `PRINTER_OPER_DEST_DF` name; used by ad-hoc runs | | Priority | `PRIORITY` | 0–9, higher first; generators only take reports ≥ their login priority | | Lifetime | `LIFE_TIME` | interval, e.g. `"1 Weeks"`; empty = keep forever (manual); also the storage group's lifetime | | Logbook information | `LOGBOOK_ENABLED`, `LOGBOOK` (memo) | operator memo stored in `%TLS_DAT_PATH%\.lbk`; read in RQL with `LOGBOOK_TEXT('')` | | Process area | `PROCESS_LIST` | e.g. `3 5 8 10-19`; empty = everyone | | Ad-hoc generation | `ADHOC_ENABLED` | | | Ad-hoc parameters | `PARAM_PROMPT_1`–`8`, answers `PARAM_VALUE_1`–`8` | prompts → `@P0`–`@P7` (strings) | | Query | `QUERY` (memo) | RQL | | Time scheduling | `ACTIVATION_TIME`, `GENERATION_INTERVAL`, `CORRECT_DAYLIGHT` | see below | | Item triggering | `TRIGGER_ITEM`, `TRIGGER_CON_1/2`, `TRIGGER_VAL_1/2`, `TRIGGER_COMB` (`And`/`Or`), `TRIGGER_STAT_1/2` (status names), `DELAY` | | | — | `GENERATE`, `CANCEL` | set 1 to generate / cancel; back to 0 when done | | — | `CONTAINS_HTML` | read-only, set automatically when the query writes HTML (verified) | | — | `DESTINATION` (hidden) | old field: `File Only`, `Printer 1`, `Message`, `Printer mgmnt` | Parameter prompt meta-information (makes a pick list in the generate dialog): `[ITEM:]`, `[OBJECT::]`, `[DATE]`, `[TIME]`, `[DATE:TIME]`, `[LIST:a:b:c]`, followed by the prompt text, e.g. `[ITEM:NAME like "CI-Eng-Sample.TANK1.*"]Item for statistics:`. **Installed:** the `[ITEM:…]` prompt opens an item tree browser in the generate dialog; the filter (an `ITEM_DF` filter, `*` wildcard, `like`) limits the **items** shown, while sections and objects always stay in the tree (ISS-048, verified). The installed system reports use lower case (`[item]`, `[date:time]`, `[list:Days:Hours:Minutes]`). Query editor: *Ctrl+Space* lists keywords, datasets and fields. Basics of RQL (§2.1) are summarised in `IM36K10P20-01EN.md`. ### Scheduling — verified behaviour (not in the manual) - `GENERATION_INTERVAL` is also the rollover interval of the report's storage group, so it must be at least **10 minutes** (`HIS-E-ROLLTOFAST`). - `ACTIVATION_TIME` is the first run; after each run CI Server moves it on by the interval. An activation time in the past is moved to the next future slot (no catch-up). One test (past time within the lifetime, set by modify) generated a single report labelled with the old time; at insert with a time older than the lifetime nothing was generated. - `CORRECT_DAYLIGHT 0` counts intervals in UTC: a daily 06:00 set for January (summer time) ran at 05:00 in October. Use `1` for fixed local times. - **A scheduled report cannot be deleted** (`RPT-E-ACTIVE`): clear `ACTIVATION_TIME` and `GENERATION_INTERVAL` first (`dssqld -m`), then delete. ### Item triggering — verified behaviour The report is generated `DELAY` after the condition **becomes** true (edge): writing 420 then 430 above a limit of 400 gave one report; going below and above again gave a second one. ## 3. Devices and destinations (§2.2) | Dataset | Form | Fields (installed) | |---|---|---| | `PRINTER_DEV_DF` | *Reporting > Printers > Device* | `NAME`, `DESCRIPTION`, `OUTPUT_TYPE` (`:FILE`, `:HARDCOPY`, `:APPLICATION` from `PRINTER_TYPE_DF`), `PARAMETERS`, `STATUS_ITEM` (0 initial, 1 ready, 2 busy, 3 warning, 4 unavailable), `SUSPEND` | | `PRINTER_DEST_DF` | *Reporting > Printers > Destinations* | `NAME`, `PRIMARY_DEVICE`, `SECONDARY_DEVICE`, `POLICY` (`None` primary only, `Both`, `Automatic` = secondary when primary unavailable), `ALLOW_OPERATOR` (appears in `PRINTER_OPER_DEST_DF`), `PRIORITY` (high) | Parameters, written `NAME,"value",NAME,"value"`: FILE `PATH`, `FILE`, `OVERWRITE` (`Yes`/`No`); HARDCOPY `TYPE` (`WINDOWS` on Windows), `QUEUE` (e.g. `\\PrintServer\prt001`), `FONT`, `POINT`, `LINES` (76), `ORIENTATION`, `N-UP`; APPLICATION `PROGRAM`, `ARGUMENTS`. **Installed:** `OUTPUT_TYPE` must include the node name (plain `FILE` is refused, `DSSP-E-NORELV`); the path must be literal (`%TLS_LST_PATH%` gave `FSL-E-PRT_PAR` in the log while the job still showed *Finished*). Factory destinations `ALARMS`, `AUDIT_TRAIL`, `DEFAULT`, `MESSAGES`, `PRINTER_1`, `SCREEN_CAPTURE` exist with no device. Job and device status: `PRINTER_JOB_OVV`, `PRINTER_DEV_OVV` (printer manager `FMFPRT`). ## 4. Report storage groups (§2.3.1) Creating a report creates a storage group of type *Report* with the same name (*Historisation > Other storage groups*); its lifetime is linked to the report's lifetime; *Exclude from archive* is available. **Installed:** deleting the report deletes the group, its generated reports and its `.lbk` file. Generated reports are stored in `tls\his\h…*.his` unit files. ## 5. Report component in displays (§2.3.2) The Edit Module report component has a report list, a generated-report list, a *Generate* form (report, destination, logbook text, parameters) and a *View* form (report, generated report, printer). Properties: show/hide and enable/disable each part; *Advanced*: a variable that starts generation (back to false when done), logbook variable (string), report and selection filter. Logbook on a display needs *Logbook Enabled* and *Visible* in the report. Not practiced. ## 6. Generating and viewing (§3) - Engineering Module: right-click a report › *Generate* (choose destination - preset ``, the report's `ADHOC_DEST` is not pre-selected - and answer parameters) › right-click a generated report › *View* (*Scroll Form-Feeds* for multi-page). - Operator interface: display with the report component (*Generate* / *View* tabs, print). - Command line: `REPORT_DF` `NAME,PARAM_VALUE_1,GENERATE` = `"","",1` with `dssqld -m`; read `REPORT_VAL` (`NAME` = `.`, `REPORT` memo, `USER_NAME`, `ACTION_PROCESS`, `DELETION_TIME`); print with `NAME,DEST_NAME,PRINT`; delete with `dssqld -r` (needs `REPORT_DELETE_GENERATED_REPORT`; users only delete their own ad-hoc ones). - `rptgen -s rptgen.rpt` for trying RQL (`IM36K10R40-01EN.md` §6). **Verified:** ad-hoc runs from `dssqld` are made by user `FULL AUTHORIZATION`; `RPTMAN` then logs `FSL-E-PRT_UNKUSER, Job submitted by unknown user` and prints nothing, with or without `ADHOC_DEST` (the report is still stored; ISS-045, corrected in phase 12). Scheduled and triggered runs are made by `RPTMAN` and print to `DEST_NAME`. Generated from the Engineering Module the run is made by the logged-in user (`ADMIN`, process `JHMISET…`) and printed to the chosen destination without errors; *View* lists generated reports by local time and has a *Destination* box and *Export…*. ## 7. Tuning (§4) `rptman.sup`, generator `.rpt` files and `report_start.cmd` as in `IM36K10R40-01EN.md`; one generator `RPTGE1` by default; add generators for priorities, large reports or load; restart CI Server after changes. Query tip: filter on the primary key `NAME` (e.g. `NAME > (@obj || ':') AND NAME < (@obj || ';')` on `object_attr_val`) instead of other fields. ## 8. Formats and system reports (Appendix 1) - HTML: write the HTML with `SELECT '…';` lines, `HEADER ''; FOOTER ''; SET @PAGE_SIZE 0; SET @WIDTH 512;`. The Engineering Module and displays render it; a destination receives the HTML source. - CSV: `SPOOL ''; SET @EXPORT 1; SELECT …; SPOOL;`. - System reports (installed, 28, all ad hoc, lifetime 1 week; same list on R1.05, verified 2026-10-09): `ALARM_COUNT`, `ALARM_CURRENT`, `ALARM_EXT_CURR`, `ALARM_HISTORY`, `ALARM_SHELVE`, `ALM_ATTRS_CUR`, `ALM_ATTRS_HIS` (manual: `ALM_ATTS_CUR`, `ALM_ATRS_HIS`, ISS-043), `AUDIT_TRAIL`, `AUTH_GROUP`, `ITEM_ACK`, `ITEM_ALM`, `ITEM_EQP`, `ITEM_FO`, `ITEM_HISTORY`, `ITEM_HISTORY_AG`, `ITEM_ID`, `ITEM_ITM`, `ITEM_OTH`, `ITEM_TYPE`, `ITEM_VAL_STA`, `ITM_VAL_CSV`, `STATION`, `STATION_STATS`, `SYSTEM_LOG`, `SYSTEM_LOG_HTML`, `UA_SERVER_AUDIT`, `USER`, `USER_VAL`. Their queries are good RQL examples (`dssqld -e` on `REPORT_DF` with `QUERY`). Enterprise engineering servers add `EES_*` reports. ## 9. R1.05 notes (not in the manual) - `ITEM_VAL` has `ENG_UNIT`, `SCALE_HIGH_LIMIT`, `SCALE_LOW_LIMIT` (ISS-126), usable in report queries; see skill `reporting`, `rql-interactive.md` §4. - New datasets since R1.03 are readable in report queries; `API_KEYS_DF` holds API keys and must never be used in a report (ISS-168). - `report_start.cmd` / `report_stop.cmd` call `?*_report_start.cmd` / `?*_report_stop.cmd` extension scripts (ISS-121). Known issues (IM 36K01A50): with Active Directory and printer management, generation can fail looking for the user's default printer (use a destination without device as the user's default); report features of schemes need an Engineering Module restart.