---
manual: IM 36K10L35-01EN
title: ITEM Service Engineering - ITH
edition: 3rd Edition, Sep. 2023
version: R1.03
status: from docs; installed ITH processes (item_start.cmd), setup files itheex.sup and itheix.sup checked read-only on the test system (2026-09-30); ithloahis practiced in phase 1
---

# ITEM Service Engineering - ITH (R1.03)

ITH is the item-history part of ITEM Service: it gathers item values from ITM and stores and
retrieves them for the storage (history) groups that HISTORY Service manages. Section numbers
refer to the manual. Storage groups themselves: phase 9 (IM 36K10L20, C40).

## 1. Processes and data (§1)

- **Collection/storage types** and their processes:

| Group type (collection/storage) | Store process | Retrieve process |
|---|---|---|
| SCAN / TIME | `ITHSTX` (more: `ITHST2`…, setup key `task`) | `ITHRTT` |
| SCAN / ITEM | `ITHSIX` | `ITHRTI` |
| EVENT / EVENT | `ITHEEX` | `ITHRTE` |
| EVENT / ITEM | `ITHEIX` (not described in the manual; used by CI-Eng-Sample `CIENG_EVENT`) | `ITHREI` |
| DIRECT / EVENT (values from applications, e.g. an equipment manager reading history from the field) | `ITHSDE` | `ITHRDE` |
| DIRECT / ITEM | `ITHSDI` | `ITHRDI` |

- `ITHSER`: one per node (normally the host). Group definition (with HIS) and retrieval:
  finds the item's groups, picks the **highest-priority** group, finds the first unit in the
  time window and hands the request to a retrieve process. Keeps the item directory.
- `ITHDBG` debugger, `ITHRECOVER` repair.
- Start/stop lists: `tls\com\item_start.cmd` / `item_stop.cmd`; processes for unused types can
  be removed there. **Installed R1.03 start list**: `ithser`, `itheex`, `itheix`, `ithstx`,
  `ithsde`, aggregation `ithsag` and retrieve processes in **two instances each**
  (`ithrte00/01`, `ithrei00/01`, `ithrag00/01`, `ithrtt00/01`, `ithrde00/01`). Not started:
  `ithsix`, `ithrti`, `ithsdi`, `ithrdi`.

**Files** (in the history/data folders; do not delete):
- `ith_itmdir.dat` item directory (item, id, time window, group, priority).
- Group description `hnnggg000000.dat`, unit descriptions `hnnggguuu000.dat` (a new one on
  every group change, so old compositions stay readable), unit data `hnnggguuuddd.dat` (a new
  one at each start/rollover). `nn` node, `ggg` group, `uuu` unit, `ddd` data sequence.
- Record layouts: time-based (one scan of many items per record, split into file groups),
  item-based (many scans of one item), event-based (one event per record). **Events older
  than 60 units cannot be stored.**

## 2. Setup files (§2)

Each process reads `<process name>.sup` (missing → error in `umhlog`).
- `ithser.sup`: `agg_hour_method` (hourly aggregate labelled by start or end of hour, default
  start), `his` (HIS address), `con_timeout` (group configuration lock, default 8 min),
  `his_path`, `sh_path` (default history and shadow paths), `his_mod` (allow modifying
  `ITEM_HISTORY` data via the API).
- `ithstx.sup` / `ithsix.sup`: `his`, `task`, `run_interval` (heartbeat, ≤ 1/10 of the
  shortest scan interval), `max_recsize`, `itms_a_rscan`/`itms_a_dscan` (items per ITM
  lock, ~50), `itms_a_rrun`/`itms_a_drun` (items per heartbeat, limits CPU peaks),
  overheads; ITHSIX also `max_total_buf`, `max_grp_buf` (memory in 28-byte blocks).
- `itheex.sup` (test system values): `run_interval = 600` s, `buffer_size = 10` events,
  `event_timeout = 1` s, **`gap_time = 2880` min**, `queue_size = 750` KB, optional
  `overflow_item` (counts/toggles on queue overflow).
- `itheix.sup` (not in the manual; test system): `run_interval = 60`, `buffer_size = 20`,
  `event_timeout = 1`, **`gap_time = 2880` min**, **`max_sample_delay = 14400` min**,
  `max_samples_queued = 25` (million), `max_open_files = 10`, `queue_size = 2000`.
- `ithsde.sup` / `ithsdi.sup`: `his`, `task`, `max_open_files` (10), `max_recsize` (4000),
  `gap_time` (60 min).

## 3. `ithrecover` (§3)

`ithrecover <group | "*"> [-v] [-p]` repairs the relations between item definitions, group
descriptions, the item-in-use list and the item directory (trusting item definitions and group
descriptions). Needs HISTORY Service and ITHSER running, no group configuration in progress.
`-p` extends the item directory into the past for history migration (advanced; with product
support).

## 4. `ithdbg` (§4)

Menu: 1 group contents, 2 item directory, 3 unit data file dump, 4–18 global/group info of
each ITH process, 20 retrieve history, 80 stop a process, 90 log to file, −1 exit. Group names
are case-sensitive.

## 5. `ithloahis` item history loader (§5)

`ithloahis -f <file> [-v] [-l] [-i] [-s <section>] [-t GMT|LST|LCT]` loads CSV history into
EVENT/EVENT and EVENT/ITEM groups (not SCAN). Groups and items must exist. `-i` also writes
the value to the item (e.g. to trigger alarms). Formats: `SCAN, item1, item2` header then
`time, v1, v2` rows (blank = no sample), or `EVENT` header then `time, item, value` rows.
Time as `29-Apr-14 11:48:17.452`, `29-04-2014 11:48:18.452` or UTC seconds. Practiced: skill
`system-management`, task `load-history.md`.

**Loading older history (migration)**:
1. Raise `gap_time` in `itheex.sup` (EVENT/EVENT) or `gap_time` and `max_sample_delay` in
   `itheix.sup` (EVENT/ITEM) beyond the age of the oldest sample (5 years ≈ 2,628,000 min);
   note the old values; restart CI Server.
2. Create the group, add all items, start it immediately.
3. Create earlier unit files: `hisdbg` option 3 for unit info; copy unit files to
   `%TLS_HIS_PATH%\has`, delete the unit (`hisdbg` 4), copy back, set times with
   `hisrecover <unit>.his "<start LCT>" "<end LCT>"`, create the next with `isfrename`,
   repeat until the original second unit's start time.
4. `ithrecover <group> -p`, restart CI Core.
5. `ithloahis -f <file>`.
6. Restore the setup values and restart.
This explains why samples older than the current unit were not stored in phase 1
(`knowledge/issues.md` ISS-006). From an older CI Server version use `ITHIMPORT` instead.