ci-server-engineer/knowledge/manuals/IM36K10L35-01EN.md

manual	title	edition	version	status
IM 36K10L35-01EN	ITEM Service Engineering - ITH	3rd Edition, Sep. 2023	R1.03	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.