cliu
83af63ab53
Full manual diffs (C50, R30, C60, L20, C40, L35, R10, R20, J10, L30, L50, P30, G10, C10) and read-only checks on the shared R1.05 test server where the permission system allowed them. Skills and summaries moved to R1.05. Issues ISS-092..129 (gaps 104-107, 114-115, 130-131 unused); ISS-074 closed (manual and software agree), ISS-091 corrected by ISS-119. version-differences: unlisted manual changes and installed-only changes. r105-verification: V5-V9 and new not-tested rows. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
79 lines
3.3 KiB
Markdown
79 lines
3.3 KiB
Markdown
---
|
|
task: Read and write item values with itmval
|
|
version: R1.05 (first written for R1.03)
|
|
source: IM 36K10J10-01EN §2.9.2 (5th ed., Feb. 2026); practiced on the test system and CI-Eng-Sample 2026-09-30 (R1.03)
|
|
status: verified on R1.03 (2026-09-30, all examples below); itmval -p/-g used on R1.05 in the CI-Eng-Sample test, 2026-10-08; read output format, limit read and error messages re-checked read-only on the R1.05 test server 2026-10-08
|
|
---
|
|
|
|
# Read and write item values (itmval)
|
|
|
|
Needs CI Server running. Reading is read-only. **Writing changes live data**: follow the
|
|
user's chosen way of working (direct vs prepare only) and never write to an item that drives
|
|
real equipment without explicit approval.
|
|
|
|
Item names are full paths: `<Section>.<Sub-section>.<Tag>`, e.g.
|
|
`CI-Eng-Sample.TANK1.INFLOW` from the sample project.
|
|
|
|
## Read the current value
|
|
|
|
```
|
|
itmval -g -n <Section>.<Tag>
|
|
```
|
|
|
|
Output:
|
|
|
|
```
|
|
Value = 130
|
|
Status = 9
|
|
Options = 0xffffff88.00 ack
|
|
Quality = 0
|
|
```
|
|
|
|
- **Status** is a number from `STATUS_DF` (export it with `dssqld -e status_df.qli -d STATUS_DF -c`
|
|
to look numbers up). Common ones: 9 `NORMAL`, 13 `NOT INIT` (never written; new items start
|
|
here), 4 / 5 `BOOLEAN 0` / `BOOLEAN 1`, 11 `HIGH HIGH`.
|
|
- **Options** lists item flags as words after the hex value (option bits, IM 36K10C10 §3.5):
|
|
`blk` 1 blocked, `off` 2 offline (station not communicating), `uoff` 4 **updated offline**
|
|
(written by an application such as `itmval` while offline), `ack` 8 acknowledged, `ublk` 16
|
|
**updated blocked** (written while blocked, e.g. with `-o`); 32/64 direct/delayed alarm.
|
|
So writing a station item whose station is down adds `uoff` (0x…8a → 0x…8e); internal items
|
|
(no station) never get it.
|
|
|
|
## Read limits
|
|
|
|
```
|
|
itmval -g -n <Section>.<Tag> -a <n>
|
|
```
|
|
|
|
`<n>`: 1 deadband, 2 low, 3 high, 4 low-low, 5 high-high. The limit is returned in `Value`.
|
|
Items with no limits configured return `ITM-E-WRONG_ATT, Wrong attribute number used`
|
|
(same on R1.05). An item name that does not exist gives `VIS-W-NOTFOUND, Record not found`
|
|
followed by `ISF-E-NOREC` / `GIN-E-GET` lines (R1.05, 2026-10-08).
|
|
|
|
On R1.05 `ITEM_VAL` also has the fields `ENG_UNIT`, `SCALE_HIGH_LIMIT` and `SCALE_LOW_LIMIT`
|
|
(installed `item_val.dss`); `itmval` itself has no option for them.
|
|
|
|
## Write a value
|
|
|
|
```
|
|
itmval -p -n <Section>.<Tag> -v <value> [-s <status>] [-q <quality>]
|
|
```
|
|
|
|
- Read the item first and note its value, so it can be restored.
|
|
- Booleans take `-v 0` / `-v 1`; the status follows automatically (4 / 5).
|
|
- `-s` sets the status explicitly (e.g. `-s 9` NORMAL). Without it, a numeric write gives 9.
|
|
- `-o` overwrites a blocked item; `-t [<date>] <time> [GMT|LST]` sets the timestamp
|
|
(default local civil time); `-e` writes to event history only, not the current value.
|
|
- Read it back to confirm.
|
|
|
|
## Verified examples (CI-Eng-Sample, R1.03)
|
|
|
|
On R1.05 the CI-Eng-Sample test (2026-10-08) used `itmval -p` and `-g` on the sample items in
|
|
the same way, with the same output format (`Value` / `Status` / `Options` / `Quality`).
|
|
|
|
| Command | Result |
|
|
|---|---|
|
|
| `itmval -p -n CI-Eng-Sample.TANK1.INFLOW -v 120.5` | Value 120.5, status 9 |
|
|
| `itmval -p -n CI-Eng-Sample.TANK1.INFLOW -v 130 -s 9` | Value 130, status 9 |
|
|
| `itmval -p -n CI-Eng-Sample.PUMP1.RUNNING -v 1` | Value 1, status 5 (BOOLEAN 1) |
|
|
| `itmval -g -n CI-Eng-Sample.TANK1.LEVEL -a 2` / `-a 3` / `-a 4` / `-a 5` | 20 / 80 / 10 / 90 |
|