cliu
48426a0a14
With the user's approval: item blocking and string length, alarm raise / acknowledge / delay / repeat and INFO event, report generate / print / item trigger / rptstp / SPOOL, class change and reset and attribute change. All results match R1.03 (ISS-028 still holds). Everything was removed again; before/after snapshot identical. ISS-129 and ISS-158 closed. Test package saved in examples/CI-Eng-Sample/shared/write_test; snapshot.ps1 now removes the dss_*.tmp files its own exports leave. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
109 lines
6 KiB
Markdown
109 lines
6 KiB
Markdown
---
|
||
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`).
|