ci-server-engineer/knowledge/manuals/IM36K10C30-01EN.md

manual	title	edition	version	status
IM 36K10C30-01EN	Engineering Module - Reporting	3rd Edition, Sep. 2023	R1.03	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 awaiting the user's check; 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:. 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, 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.

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.