---
name: history-management
description: >-
  CI Server R1.05 HISTORY Service and item history. Use when the user wants to store item values
  in history (item storage group, storage group item, Scan/Time, Event/Item, Event/Event,
  Direct, scan interval, averaging, quality codes, priority), set rollover interval, life time
  or retention of history, use aggregation (30 minutes, hourly, shift, daily, weekly, monthly,
  yearly maximum / minimum / average / integral / standard deviation / counter / differential
  summation, ithsag.sup, completion notification), read history (ITEM_HISTORY, GROUP_NAME,
  INTERPOLATION, ATTRIBUTE; from applications via ODBC, .NET API, RESTful API or pyTOOLS),
  load history from CSV (ithloahis), force a rollover, check storage groups and units (hisdbg, his_units, history files h*.his), repair or recover history
  (hisrep, hisrecover), or archive and retrieve history (has.sup, hasman, hasdbg, tape, DVD,
  disk archive). Sources IM 36K10L20-01EN, IM 36K10C40-01EN, IM 36K10L35-01EN.
---

# History management (R1.05; first written for R1.03)

Re-checked for R1.05 on 2026-10-08 (read-only): the three manuals have no content change except
IM 36K10C40 §4.2 (R1.04), which now lists the RESTful API and pyTOOLS for reading history from
applications and drops the C API. The history setup files (`has.sup`, `his*.sup`, `ith*.sup`
incl. `ithsag.sup`) and the dataset definitions `HIS_GROUP_DF`, `ITEM_HIS_DF`, `ITEM_HISTORY`,
`HIS_UNITS` are the same as in R1.03 (compared with snapshots of the R1.05 test server; only
the C interface source `dsid_ihis_df.c` of `ITEM_HIS_DF` changed, ISS-102).
`history_start.cmd` and `item_start.cmd` (and their stop files) differ (ISS-100). Storage
groups were not re-tested on R1.05: the server is shared, and a new group needs a CI Server
restart (ISS-006).

Background: `knowledge/manuals/IM36K10C40-01EN.md` (storage group fields, types, aggregation,
archive, reading history), `IM36K10L20-01EN.md` (history manager, files, `hisdbg`, utilities,
archive administration), `IM36K10L35-01EN.md` (item history processes and setup files).

Rules:
- Run `system-check` first; follow the user's chosen way of working.
- **Deleting a storage group, a unit or unknown files deletes history for good.** Life time
  changes can delete old units at the next rollover. Only with the user's approval, and never
  on production data without a backup.
- A new storage group stores nothing until CI Server is restarted (ISS-006): plan the restart
  with the user (admin).
- `has.sup` / `ithsag.sup` / `ith*.sup` changes need admin rights and a restart: hand them to
  the user (skill `portal-setup`, task `change-setup-file.md`).

| Task | File | Status |
|---|---|---|
| Create item storage groups (Event/Item, Scan/Time, Aggregation) and add items by quick load; remove them | `tasks/storage-groups.md` | verified (R1.03); R1.05: dataset definitions and setup files identical, not re-tested (shared server, needs a restart) |
| Read history with `dssqld` (`ITEM_HISTORY`, per group); aggregates | `tasks/storage-groups.md` §4 | verified (R1.03); R1.05 not re-tested |
| Load history from CSV (`ithloahis`); which time stamps are accepted | skill `system-management`, task `load-history.md` | verified (R1.03) |
| Check groups, units, clients, rollover with `hisdbg` | `tasks/history-checks.md` | verified (R1.03); R1.05 read-only options awaiting user verification (ISS-101) |
| Archive / retrieve, `hasdbg` | C40 summary §4, L20 summary §5 | from docs (no archive device) |
| Repair and recovery (`hisrep`, `hisrecover`, `isfrename`, `hiswrn`) | L20 summary §4 | from docs |
| Reading history from classes and reports | C40 summary §5; reports: skill `reporting` | verified for reports (R1.03, `rql-interactive.md`) |
| Reading history from applications: ODBC, .NET API, RESTful API (`GetHistory`, `GetHistoryMultiTag`), pyTOOLS (`getItemHistory`) | C40 summary §5; ODBC and REST: skill `data-access` (L45 summary §1, §9); pyTOOLS: IM 36K10P40 §3.13 (no skill yet) | from docs |