cliu
0bff3698c2
User checked the report forms, the generate dialog and viewing text and HTML reports. The [ITEM:...] prompt filter does not limit the item browser (ISS-048). system-check: Stop-Service error while CI Server still restarts. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
146 lines
9.5 KiB
Markdown
146 lines
9.5 KiB
Markdown
---
|
||
manual: IM 36K10C30-01EN
|
||
title: Engineering Module - Reporting
|
||
edition: 3rd Edition, Sep. 2023
|
||
version: R1.03
|
||
status: report definitions (ad hoc with parameters, schedule, item trigger, HTML, logbook), generated reports, file device and destination verified by quick load on CI-Eng-Sample 2026-10-01; Engineering Module forms, generate and view checked by the user; report component in displays and hardcopy printers from docs
|
||
---
|
||
|
||
# Engineering Module - Reporting (R1.03)
|
||
|
||
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%\<report>.lbk`; read in RQL with `LOGBOOK_TEXT('<report>')` |
|
||
| 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:<filter>]`,
|
||
`[OBJECT:<class>:<filter>]`, `[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, but the filter did not limit
|
||
the tree (ISS-048). 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` (`<node>:FILE`, `<node>:HARDCOPY`, `<node>: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 `<None>`, 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` = `"<report>","<answer>",1` with
|
||
`dssqld -m`; read `REPORT_VAL` (`NAME` = `<report>.<DD-MON-YY hh:mm:ss>`, `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`; without an ad-hoc
|
||
destination `RPTMAN` then logs `FSL-E-PRT_UNKUSER, Job submitted by unknown user` (the report is
|
||
still stored; ISS-045). With `ADHOC_DEST` set the output went to the device without errors.
|
||
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 '<file>'; SET @EXPORT 1; SELECT …; SPOOL;`.
|
||
- System reports (installed, 28, all ad hoc, lifetime 1 week): `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.
|
||
|
||
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.
|