---
task: Read and write item values with itmval
version: R1.03
source: IM 36K10J10-01EN §2.9.2; practiced on the test system and CI-Eng-Sample 2026-09-30
status: verified
---

# 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, e.g. `ack` (acknowledged),
  `off` (item's station not communicating). `uoff` also appears on station items after a write;
  its meaning is not yet known (see `knowledge/issues.md` ISS-001).

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

## 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)

| 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 |