---
name: reporting
description: >-
  CI Server R1.05 REPORT Service, report definitions and RQL. Use when the user wants to create,
  change, schedule or delete a report (daily / shift / hourly report, report triggered by an
  item value or status, ad-hoc report with parameters such as an item, object, date or list),
  write or debug an RQL query (SELECT from item_val, item_history, alarm_current, alarm_chrono,
  audit_trail, unit_df …, item units and scale limits ENG_UNIT / SCALE_HIGH_LIMIT /
  SCALE_LOW_LIMIT, COLUMN formats, HEADER/FOOTER, cursors DECLARE/FETCH, LOOP, GPV_VALUE,
  @P0 parameters, @DATE), generate a report now (GENERATE), view, print or delete generated
  reports (REPORT_VAL), output a report to a file, CSV (SPOOL, @EXPORT) or HTML, use a logbook,
  set up report printers (printer device, destination, FILE / HARDCOPY output, PRINTER_DEV_DF,
  PRINTER_DEST_DF), try queries in the interactive report generator (rptgen -s rptgen.rpt), stop
  a hanging report (rptstp), check REPORT Service (rptman, rptge1, rptman.sup, rptge1.rpt,
  report_start), use the system reports (ALARM_HISTORY, AUDIT_TRAIL, ITEM_HISTORY, SYSTEM_LOG …),
  put a report component on a display, or use the Excel Add-in (DART) for reports. Sources
  IM 36K10C30-01EN, IM 36K10P20-01EN, IM 36K10R40-01EN, IM 36K10E10-01EN.
---

# Reporting (R1.05)

Re-checked on R1.05 on 2026-10-09 (read-only): the four manuals changed only in wording; the
REPORT datasets (`REPORT_DF`, `REPORT_VAL`, `PRINTER_*`), `rptman.sup` and the generator set-up
files (`rptge1.rpt`, `rptgen.rpt`, `rptgsp.rpt`) are identical to R1.03; the 28 system reports
and the 6 factory destinations are the same. New on R1.05: `ITEM_VAL` fields `ENG_UNIT`,
`SCALE_HIGH_LIMIT`, `SCALE_LOW_LIMIT` (readable in RQL), new datasets (see below), and
`report_start.cmd` / `report_stop.cmd` call extension scripts `?*_report_start.cmd` /
`?*_report_stop.cmd` in `tls\com`. Report generation was **not** re-tested on R1.05 (shared
test server): the sample's file device, destination and three reports loaded with 0 errors
(2026-10-08) and were removed again.

Background: `knowledge/manuals/IM36K10C30-01EN.md` (report definition fields, scheduling and
trigger behaviour, devices, generated reports, system reports), `IM36K10P20-01EN.md` (RQL),
`IM36K10R40-01EN.md` (REPORT Service processes and set-up files), `IM36K10E10-01EN.md` (Excel
Add-in), `IM36K10L50-01EN.md` (datasets, `dssqld`).

Rules:
- Run `system-check` first; follow the user's chosen way of working.
- Report names ≤ 16 characters. Report queries only **read**, except `SPV_*` functions and
  `GPV_VALUE(<item>, <non-zero>)` (resets the item) — never use those without approval.
- A scheduled report runs on its own; schedule at least every 10 minutes and set a lifetime, or
  generated reports pile up in history.
- Generator set-up files (`tls\sup\*.rpt`), `rptman.sup` and `report_start.cmd` need admin rights
  and a restart: hand them to the user (skill `portal-setup`, `change-setup-file.md`).
- Example names come from `CI-Eng-Sample` (`CIENG_TANK1`, `CIENG_INFLOW_HI`, `CIENG_HTML`,
  destination `CIENG_FILE`).
- Paths: read `set TLS` first. R1.03 default data root `C:\Users\Public\Yokogawa\tls`; on the
  R1.05 test server program and data share `C:\Yokogawa\CIServer\tls`. `SPOOL` and FILE device
  paths must be literal, so write the real path of the system.
- RQL can read every dataset. **Never query `API_KEYS_DF`** (it holds users' API keys) and do
  not put it in a report. Other datasets new since R1.03 (names only): `ALARM_ATTRIBUTE_TEMP_DF`,
  `UASERVER_MAPPER_DF`, `IEC61850_RCB_DF`, `OPCUAC_METHOD_CALL2_DF` (replaces
  `OPCUAC_METHOD_CALL_IN_DF` / `_OUT_DF`; old report queries on those names fail).

| Task | File | Status |
|---|---|---|
| Check REPORT Service: processes, set-up files, system reports, stop a hanging report (`rptstp`) | `tasks/report-checks.md` | verified (R1.03); on R1.05 processes, files and system reports checked read-only (2026-10-09); `rptstp` not re-tested |
| Try RQL in the interactive generator (`rptgen -s rptgen.rpt`), CSV with `SPOOL` | `tasks/rql-interactive.md` | verified (R1.03); queries re-run read-only on R1.05 (2026-10-09), `SPOOL` not re-tested |
| Define reports by quick load (ad hoc with parameters, schedule, item trigger, HTML, logbook); generate, read, print, delete; remove | `tasks/define-reports.md` | verified (R1.03, command line and Engineering Module); on R1.05 load and remove only (2026-10-08), generation not tested |
| Report output to a file: printer device and destination | `tasks/output-devices.md` | verified (R1.03); on R1.05 load and remove only (2026-10-08) |
| Report component on a display; Operator Interface generate/view | C30 summary §5 | from docs |
| Hardcopy printers, application devices, more generators, separate RPI servers | C30 summary §3, R40 summary §1, §3 | from docs |
| Excel Add-in (DART) | E10 summary | from docs (Excel not installed on either test system) |