84 lines
3 KiB
Markdown
84 lines
3 KiB
Markdown
---
|
||
task: Load item history from CSV (ithloahis) and read history back (dssqld)
|
||
version: R1.03
|
||
source: IM 36K10J10-01EN §2.9.2; IM 36K10L50-01EN §3.6; practiced with CI-Eng-Sample 2026-09-30
|
||
status: verified
|
||
---
|
||
|
||
# Load item history (ithloahis) and read it back
|
||
|
||
**Writes to the history database.** Needs CI Server running and the items linked to an
|
||
item storage group of type *Event/Item* or *Event/Event*. The sample project provides
|
||
`CIENG_EVENT` with `CI-Eng-Sample.TANK1.LEVEL` and `.INFLOW`.
|
||
|
||
## Before loading
|
||
|
||
- A **new** storage group stores nothing until CI Server has been restarted (stop, then start
|
||
the CI Service). Restart after creating a group.
|
||
- Samples are stored into the active unit **or an earlier unit opened by the storage process
|
||
since the last restart** (e.g. one closed by a forced rollover). Samples older than the first
|
||
unit opened after the restart are **dropped without any message**, even with `-l`, and even
|
||
when an older unit's time range covers them (verified 2026-10-01, ISS-006). A restart closes
|
||
the active unit and starts a new one, so load old data **before** restarting, or not at all.
|
||
Check the unit times first: skill `history-management`, task `history-checks.md`.
|
||
- A dropped sample can still become the initial value of the next unit at the next rollover
|
||
(ISS-038): check the result after loading.
|
||
- Loaded samples appear in `ITEM_HISTORY` a few seconds after `ithloahis` returns.
|
||
|
||
## Input files
|
||
|
||
Event file: one sample per line.
|
||
|
||
```
|
||
EVENT
|
||
<time>,<item>,<value>
|
||
1790739700,CI-Eng-Sample.TANK1.LEVEL,47
|
||
```
|
||
|
||
Scan file: several items per line (max 100), one line per timestamp.
|
||
|
||
```
|
||
SCAN,CI-Eng-Sample.TANK1.LEVEL,CI-Eng-Sample.TANK1.INFLOW
|
||
1790739715,61,101
|
||
1790739720,62,102
|
||
```
|
||
|
||
Time is seconds since 1970 (UTC), optionally with a fraction, or a date text such as
|
||
`29-Apr-14 11:48:17.452`. Quotes and spaces around fields are optional. A blank value in a
|
||
scan line is skipped.
|
||
|
||
## Load
|
||
|
||
```
|
||
ithloahis -f <file>.csv -v
|
||
```
|
||
|
||
- `-v` shows progress (`Handle event based table`, `item … on column n`).
|
||
- `-t GMT|LST|LCT` sets how text times are read (default GMT).
|
||
- `-s <section>` puts a section in front of every item name.
|
||
- `-i` also updates the item's current value (can raise alarms and trigger objects; loads the
|
||
system). Without it, only history is written.
|
||
|
||
## Read history back
|
||
|
||
`ITEM_HISTORY` is not exported by default; use a filter file that names the item **and** a
|
||
time range, otherwise nothing is returned:
|
||
|
||
```
|
||
@SELECT
|
||
'ITEM_NAME = "CI-Eng-Sample.TANK1.LEVEL" and SAMPLE_TIME > "30-09-2026 00:00:00" and SAMPLE_TIME < "01-10-2026 00:00:00"'
|
||
@ITEM_HISTORY
|
||
```
|
||
|
||
```
|
||
dssqld -e history.qli <filter>.qli -c -l history.qlo
|
||
```
|
||
|
||
Result columns include `NAME` (`<group>:<item>/<time>/Value`), `SAMPLE_TIME`, `ITEM_VALUE`,
|
||
`QUALITY`. Values written live (e.g. with `itmval -p`) and the value at CI Server start also
|
||
appear.
|
||
|
||
## Verified (CI-Eng-Sample, 2026-09-30)
|
||
|
||
SCAN load of LEVEL 61–63 / INFLOW 101–103 and EVENT load of LEVEL 47, 48 were all read back
|
||
with the filter above.
|