ci-server-engineer/.claude/skills/reporting/tasks/rql-interactive.md

---

task: Try RQL queries in the interactive report generator; write CSV with SPOOL version: R1.05 (first written for R1.03) source: IM 36K10R40-01EN §4; IM 36K10P20-01EN §3–6, §9; IM 36K10C30-01EN §3.2.3 (all 4th Edition, Feb. 2026); R1.05 data dictionary (ITEM_VAL); practiced on the test system and CI-Eng-Sample 2026-10-01 status: verified on R1.03 (2026-10-01); on the R1.05 test server piped query files, cursors (DECLARE/OPEN/FETCH), group functions, @VERSION and the new ITEM_VAL fields verified read-only (2026-10-09); SPOOL/CSV, history queries and the CI-Eng-Sample examples not re-run on R1.05 (sample not loaded on the shared server) Re-tested on R1.05 2026-10-09 on the shared test server with the user's approval (temporary sample records, everything removed, before/after snapshot identical): SPOOL with @EXPORT wrote the quoted CSV lines to %TLS_LST_PATH% (file deleted) (V12).

RQL in the interactive generator

rptgen -s rptgen.rpt starts a report generator in the console (prompt RPT>). It reads RQL, prints results at once and needs no report definition — the quickest way to test a query or look into a dataset. CI Server must be running. Read-only unless the query uses SPV_* or GPV_VALUE(…, <non-zero>).

1. Run a query file

Put the statements in a file (each ends with ;) and pipe it in; end with QUIT;:

set @next 0;
set @width 132;
column t as 'DD-MMM-YYYY hh:mm:ss' heading 'Time';
select name, item_value, status from item_val where name like 'CI-Eng-Sample.TANK1.%';
select sample_time t, item_value, quality from item_history
  where item_name = 'CI-Eng-Sample.TANK1.LEVEL' and group_name = 'CIENG_SCAN10S'
  and sample_time > @date - 600 order by sample_time;
select count(item_value), min(item_value), max(item_value), avg(item_value) from item_history
  where item_name = 'CI-Eng-Sample.TANK1.LEVEL' and sample_time > @date - 3600;
select gpv_value('CI-Eng-Sample.TANK1.LEVEL', 0), gpv_status('CI-Eng-Sample.TANK1.LEVEL');
quit;

rptgen -s rptgen.rpt < query.rql > query.out

(Git Bash: timeout 60 rptgen -s rptgen.rpt < query.rql; PowerShell does not support <, use cmd /c "rptgen -s rptgen.rpt < query.rql".)

• set @next 0; first, otherwise output stops after each page (Press <RETURN> to continue).
• rptgen.rpt has @page_size 23, so headings repeat every 23 lines; set @page_size 0; for one long list.
• Errors show the code and a caret under the position, e.g. RPT-E-ALIASSEL (an alias used twice in one SELECT), RPT-E-UNKFLDSPC (unknown field). Field names: dssqld -f -d <DATASET>.
• LOOP does not work here (RPT-E-LPNOTAL); test loops and cursors in a report definition (define-reports.md).
• @P0…@P7 and @NAME do not exist here; SET them to test a report query.
• A literal next to a group function counts as a plain column: select 'n', count(name) from … gives RPT-E-MIXAGGFNC (verified R1.05). Select the group function alone.
• DECLARE / OPEN / one FETCH / CLOSE work here without a loop (verified R1.05) — handy to pick one record and reuse its fields in the next query (where name = @n).

2. Dates

RQL dates are seconds since 1970 in local time. @date is now; constants like 01-Oct-2026 15:00 or 12:00 (today) need no quotes; number('01-Oct-2026 15:00') converts text. Show them with a date format (column t as 'DD-MMM-YYYY hh:mm:ss'). to_gmt(@date) gives real Unix time (10 h less on a UTC+10 system) — use it only when another program needs UTC.

3. CSV file with SPOOL

Use the real TLS_LST_PATH (set TLS): R1.03 default C:\Users\Public\Yokogawa\tls\lst, on the R1.05 test server under C:\Yokogawa\CIServer\tls.

spool 'C:\Users\Public\Yokogawa\tls\lst\cieng_levels.csv';
set @export 1;
select name, item_value, status from item_val where name like 'CI-Eng-Sample.TANK1.%';
spool;
set @export 0;

Result: one line per row, strings quoted ("CI-Eng-Sample.TANK1.LEVEL",61,"NORMAL"), no headings. File name ≤ 79 characters, literal (no %variables%), overwritten each time, never cleaned up by CI Server — delete it when done. The same statements work inside a report definition.

4. New in R1.05: item units and scale limits in ITEM_VAL

ITEM_VAL has three new fields (not in any manual; ISS-126): ENG_UNIT (char 8, engineering units), SCALE_HIGH_LIMIT and SCALE_LOW_LIMIT (double). Before R1.05 a report had to join ITEM_DF for the unit; now one query on current values is enough:

column u heading 'Unit';
select name, item_value, eng_unit u, scale_low_limit, scale_high_limit
  from item_val where name like '<Section>.%';

Verified (R1.05 test server, 2026-10-09, read-only): the fields are accepted by RQL. For an item with a unit, ITEM_VAL.ENG_UNIT held the same unit text as ITEM_DF.ENG_UNIT. The scale fields gave 0 / 0 where the item defines no scale; for one item without a unit ITEM_VAL gave scale high 1 while ITEM_DF had 0, so how ITEM_VAL fills the scale limits is not clear yet (ISS-167). Until then take scale limits from ITEM_DF when they matter. R1.03 ITEM_VAL has no such fields, so a report using them fails there (unknown field).

Other datasets new since R1.03 can be queried like any other (checked read-only with count(name) on R1.05: ALARM_ATTRIBUTE_TEMP_DF, UASERVER_MAPPER_DF, IEC61850_RCB_DF, OPCUAC_METHOD_CALL2_DF). Never query API_KEYS_DF (it holds users' API keys; ISS-168).

@VERSION returns 1.05.00 on R1.05 (1.03.00 on R1.03).

Verified (R1.03, 2026-10-01)

Current values, history of CIENG_EVENT / CIENG_SCAN10S (count 299 in an hour at 10 s), group functions, GROUP BY on unit_df, GPV_VALUE/GPV_STATUS/GPV_QUALITY (61, 9, 0), string and date functions (SUBSTR, DECODE, NUMBER, DRAW, LINE, MONTH_DAYS, TO_GMT), integer vs real arithmetic (12/5+10.0 = 12), CSV via SPOOL (file removed afterwards). Aggregated history (interpolation = '30Minutes') returned no rows because the test system had no completed aggregation periods (also empty through dssqld).