---
name: reporting
description: >-
  CI Server R1.03 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 …, 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.03)

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`).

| Task | File | Status |
|---|---|---|
| Check REPORT Service: processes, set-up files, system reports, stop a hanging report (`rptstp`) | `tasks/report-checks.md` | verified |
| Try RQL in the interactive generator (`rptgen -s rptgen.rpt`), CSV with `SPOOL` | `tasks/rql-interactive.md` | verified |
| Define reports by quick load (ad hoc with parameters, schedule, item trigger, HTML, logbook); generate, read, print, delete; remove | `tasks/define-reports.md` | verified (command line and Engineering Module) |
| Report output to a file: printer device and destination | `tasks/output-devices.md` | verified |
| 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 the test system) |