diff --git a/.claude/skills/history-management/SKILL.md b/.claude/skills/history-management/SKILL.md new file mode 100644 index 0000000..370bd94 --- /dev/null +++ b/.claude/skills/history-management/SKILL.md @@ -0,0 +1,40 @@ +--- +name: history-management +description: >- + CI Server R1.03 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), 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.03) + +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 (aggregation values not yet seen, ISS-040) | +| Read history with `dssqld` (`ITEM_HISTORY`, per group); aggregates | `tasks/storage-groups.md` §4 | verified (aggregates from docs, ISS-040) | +| Load history from CSV (`ithloahis`); which time stamps are accepted | skill `system-management`, task `load-history.md` | verified | +| Check groups, units, clients, rollover with `hisdbg` | `tasks/history-checks.md` | verified | +| 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, reports, ODBC | C40 summary §5 | from docs (phases 6, 11) | diff --git a/.claude/skills/history-management/tasks/history-checks.md b/.claude/skills/history-management/tasks/history-checks.md new file mode 100644 index 0000000..1c97066 --- /dev/null +++ b/.claude/skills/history-management/tasks/history-checks.md @@ -0,0 +1,46 @@ +--- +task: Check storage groups, units and history clients with hisdbg; force a rollover +version: R1.03 +source: IM 36K10L20-01EN §2.1, §3.1; IM 36K10C40-01EN §5.1; practiced on the test system and CI-Eng-Sample 2026-10-01 +status: verified +--- + +# History checks (`hisdbg`) + +Interactive; pipe the answers from bash with a timeout. The first answer is the node (blank = +local), the last `-1` exits. Never send blank lines at the action prompt blindly (a blank repeats +the previous action). + +``` +printf '\n1\n20\n6\n-1\n' | timeout 20 hisdbg +printf '\n21\n\n3\n\n-1\n' | timeout 20 hisdbg +``` + +| Option | Shows | Safe | +|---|---|---| +| 1 | Statistics: group count, logged-in clients, unit starts / stops / rollovers / deletions since start | yes | +| 20 | All groups: name, node,group number, history type (24 item, 21 alarm, 6 audit, 1058 report, 36 system log, 4 station statistics) | yes | +| 21 `` | Group info: path, next unit and file name, opt_type (`1 1` Scan/Time, `2 2` Event/Item, `4 4` Aggregation), start, stop, first rollover, interval, life time (all GMT), GMT/LCT rollover, archiving | yes | +| 3 (then blank = this group) | Units: unit, data, file, start, stop or `--- active ---`, delete time | yes | +| 6 | Clients logged in at the history manager | yes | +| 11 | Unknown history files | yes | +| 5 | Force rollover of the current group (closes the active unit, starts the next) | changes files — with approval | +| 4, 8, 10, 12, 9 | Delete unit / group, restore unit, delete unknown files, change schedule | **no — never without explicit approval** | + +History files are in `%TLS_ALLUSERS_PATH%\tls\his\` (path shown by option 21): +`h.his` with base-32 digits, e.g. group 1,54 → `h0101m…`. + +## What to look for + +- New group but no history: no active unit after loading → restart CI Server (ISS-006). +- Unit start dates: the first unit of an Event/Item or Aggregation group is dated 2 days back + (`gap_time`); history loaded before the first unit opened after the restart is dropped + (see `storage-groups.md` §5). +- After a CI Server restart the unit sequence increases (the start script runs `hisrep`). +- Delete times = stop time + life time. + +## Verified (2026-10-01) + +45 groups, 30 clients; `CIENG_EVENT` group 1,54, opt_type `2 2`, daily GMT rollover, life 7 +days; units 1,1 (created at load) → 3,1 after restart → forced rollover closed 3,1 at 12:05:26 +and opened 3,2. `CIENG_SCAN10S` 1,55 `1 1`; `CIENG_AGG` 1,56 `4 4` with extra `h0101ozzz…` files. diff --git a/.claude/skills/history-management/tasks/storage-groups.md b/.claude/skills/history-management/tasks/storage-groups.md new file mode 100644 index 0000000..5a8cfa0 --- /dev/null +++ b/.claude/skills/history-management/tasks/storage-groups.md @@ -0,0 +1,104 @@ +--- +task: Create item storage groups (Event/Item, Scan/Time, Aggregation), add items, read history +version: R1.03 +source: IM 36K10C40-01EN §2.1, §3, App. 1; IM 36K10L20-01EN §2.1; practiced on CI-Eng-Sample 2026-10-01 +status: verified for Event/Item and Scan/Time; Aggregation loads but values not yet seen (ISS-040) +--- + +# Item storage groups (quick load) + +Sample files: `examples/CI-Eng-Sample/03_his_group_df.qli` (groups) and `04_item_his_df.qli` +(items in groups); removal `89_…`, `90a` (generated by `remove.cmd`), `90_…`. Commands as in +skill `system-management` (`dssqld -i` / `-m` / `-r`); `dssqld` exits 0 even on errors — read the +summary table. + +## 1. Groups (`HIS_GROUP_DF`) + +``` +@FIELDS +NAME,DESCRIPTION,TYPE,COL_STOR_TYPE,LIFE_TIME,ROLLOVER_INT +@HIS_GROUP_DF +"","","Item","Event/Item","1 weeks","1 days" + +@FIELDS +NAME,DESCRIPTION,TYPE,COL_STOR_TYPE,SCAN_INTERVAL,STORE_QUALITY,LIFE_TIME,ROLLOVER_INT +@HIS_GROUP_DF +"","","Item","Scan/Time",10,1,"1 days","1 hours" + +@FIELDS +NAME,DESCRIPTION,TYPE,COL_STOR_TYPE,STORE_QUALITY,LIFE_TIME,ROLLOVER_INT,AGG_PERIOD_HOUR,AGG_PERIOD_30MIN +@HIS_GROUP_DF +"","","Item","Aggregation",1,"4 weeks","1 weeks",1,1 +``` + +- Name ≤ 16 characters. `COL_STOR_TYPE`: `Scan/Time`, `Event/Item`, `Event/Event`, + `Direct/Event`, `Direct/Item`, `Aggregation`. Other fields: C40 summary §2 (priority, data + compression, averaging, samples per record, shift/day/week settings, completion item). +- Defaults filled in by the system: first rollover at the next interval boundary, aggregation + shift 8 h from 00:00, week from Monday. +- Size the life time to the disk: every unit older than the life time is deleted at rollover. + +## 2. Items in a group (`ITEM_HIS_DF`) + +``` +@FIELDS +NAME,ITEM_NAME,GROUP_NAME,ON_VALUE_CHANGE,ON_STATUS_CHANGE +@ITEM_HIS_DF +":
.","
.","",1,1 + +@FIELDS +NAME,ITEM_NAME,GROUP_NAME +@ITEM_HIS_DF +":
.","
.","" + +@FIELDS +NAME,ITEM_NAME,GROUP_NAME,STORE_AGG_MAX,STORE_AGG_MIN,STORE_AGG_AVG +@ITEM_HIS_DF +":
.","
.","",1,1,1 +``` + +Event triggers (`ON_*`) matter for event groups; aggregates (`STORE_AGG_MAX`, `_MIN`, `_AVG`, +`_INTG` + `AGG_INTG_PERIOD`, `_STDV`, `_CNT`, `_DIFF_SUM` + range/percentage) for aggregation +groups. Load the group first; a short pause before linking items avoids a failure seen once +(`load.cmd` waits 5 s). + +## 3. Restart + +**A new group stores nothing until CI Server is restarted** (verified: groups loaded at 11:32 +and 11:54 started storing only after the 12:00 restart). Ask the user to restart the CI Service +(admin) and check the active unit with `history-checks.md`. + +## 4. Read history + +``` +@SELECT +'ITEM_NAME = "
." and GROUP_NAME = "" and SAMPLE_TIME > "" and SAMPLE_TIME < ""' +@ITEM_HISTORY +``` + +`dssqld -e .qli .qli -c`. Item name and a time range are required; times are local. +`GROUP_NAME` picks one group (otherwise every group with the item answers). Columns: +`SAMPLE_TIME`, `SAMPLE_END_TIME`, `INTERVAL_TIME`, `ITEM_VALUE`, `QUALITY`, `INITIAL_VALUE` +(1 = value at unit start), `STATUS`, `INTERPOLATION`, `ATTRIBUTE`, `GROUP_NAME`, … + +Aggregates (from docs; **not yet seen on the test system**, ISS-040): add +`and INTERPOLATION = "Hour" and ATTRIBUTE = "Maximum"` (also `Minimum`, `Average`, +`Integration`, `Standard deviation`, `Counter`, `Differential summation`; periods `Hour`, `Day`, +`Month`, `Year`, …). `INTERPOLATION = "Hour"` is accepted by `dssqld`; `"30 minutes"`, +`"30 Minutes"` and `"Half hour"` are refused (`DSSP-E-NOTRANSF … illegal value`), so the +30-minute period name is still unknown. + +## 5. Remove + +Items first (`ITEM_HIS_DF` names), then give each group a `STOP_TIME` in the future with +`dssqld -m`, wait until it has passed, then `dssqld -r` the groups (an active unit blocks the +delete: `HIS-E-GROUPHASUNT`, ISS-005). `remove.cmd` does this for all three sample groups. +Removing a group deletes its history. + +## Verified (CI-Eng-Sample, 2026-10-01) + +| Group | Type | Result | +|---|---|---| +| `CIENG_EVENT` | Event/Item, 1 week / 1 day | Live writes stored (12:04:56 = 112); `ithloahis` into active and closed units stored | +| `CIENG_SCAN10S` | Scan/Time 10 s, quality, 1 day / 1 hour | `TANK1.LEVEL` and `INFLOW` every 10 s after the restart | +| `CIENG_AGG` | Aggregation 30 min + hour, 4 weeks / 1 week | Group, items and units created (extra `…zzz…` files); after the restart no 30-minute aggregate was written by 13:00 (ISS-040) | diff --git a/.claude/skills/system-management/tasks/load-history.md b/.claude/skills/system-management/tasks/load-history.md index dfce558..7942cd8 100644 --- a/.claude/skills/system-management/tasks/load-history.md +++ b/.claude/skills/system-management/tasks/load-history.md @@ -15,8 +15,15 @@ item storage group of type *Event/Item* or *Event/Event*. The sample project pro - A **new** storage group stores nothing until CI Server has been restarted (stop, then start the CI Service). Restart after creating a group. -- Only samples dated **after the start of the current storage unit** were stored; older ones - were silently skipped (see `knowledge/issues.md` ISS-006). A restart starts a new unit. +- 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 diff --git a/knowledge/manuals/IM36K10C40-01EN.md b/knowledge/manuals/IM36K10C40-01EN.md new file mode 100644 index 0000000..0b9a758 --- /dev/null +++ b/knowledge/manuals/IM36K10C40-01EN.md @@ -0,0 +1,122 @@ +--- +manual: IM 36K10C40-01EN +title: Engineering Module - Historical +edition: 3rd Edition, Sep. 2023 +version: R1.03 +status: Event/Item and Scan/Time storage groups verified by quick load (Aggregation loads, values not yet seen — ISS-040) on CI-Eng-Sample 2026-10-01; ithloahis loading rules verified; Engineering Module forms, archive and retrieve from docs +--- + +# Engineering Module - Historical (R1.03) + +Item storage groups (*Configuration > Historisation > Item storage groups*), aggregation and +archive in the Engineering Module, plus how history is read. History manager internals: +`IM36K10L20-01EN.md`; storage processes: `IM36K10L35-01EN.md`. Section numbers refer to the +manual; dataset fields were checked on the installed system. + +## 1. Historical database (§1) + +| Storage group kind | Dataset | Created by | +|---|---|---| +| Item storage groups | `ITEM_HISTORY` | the engineer, one per collection/storage type and schedule | +| Alarm (`ALH`) | `ALARM_CHRONO` | system | +| Audit (`ADT`) | `AUDIT_TRAIL` | system | +| System log (`SYS_LOG`) | `SYS_LOG` | system | +| Reports | report storage | system | + +Items are only stored after they are added to an item storage group (`ITEM_HIS_DF`, name +`:`). Displays read history through the trend, alarm overview and report +components. + +## 2. Item storage group (§2.1, dataset `HIS_GROUP_DF`) + +| Tab / field | `HIS_GROUP_DF` | Notes | +|---|---|---| +| Name | `NAME` | max 16 characters | +| Type | `TYPE` | `Item` | +| Node | `NODE` | cannot be changed later | +| Exclude from archive | `EXCLUDE_ARCHIVE` | | +| Activation / deactivation time | `START_TIME`, `STOP_TIME` | `STOP_TIME` in the future = stop then (used by `remove.cmd`, ISS-005) | +| First rollover, interval | `FIRST_ROLLOVER`, `ROLLOVER_INT` (`"1 hours"`, `"1 days"`, `"1 weeks"`) | | +| Correct for daylight saving | `CORRECT_DAYLIGHT` | data is stored in UTC | +| Life time, warning time | `LIFE_TIME`, `WARN_TIME` | units older than the life time are deleted at rollover; warning if not archived | +| Collection/storage type | `COL_STOR_TYPE` | `Scan/Time`, `Event/Event`, `Event/Item`, `Direct/Event`, `Direct/Item`, `Aggregation` | +| Priority | `PRIORITY` | which group answers when an item is in several groups (highest wins; also source for aggregation) | +| Data compression | `DATA_COMP` | doubles stored as singles (15 → 7 digits) | +| Store quality code | `STORE_QUALITY` | | +| Scan interval, averaging | `SCAN_INTERVAL` (s), `AVERAGING_METHOD` (None / Normal / Difference), `AVERAGING_INTERVAL` | Scan/Time only | +| Samples per record | `SAMPLES_RECORD` (default 100) | Event/Item, Direct/* | +| Fill old record | `FILL_OLD` | Direct/* only | +| Aggregation periods | `AGG_PERIOD_30MIN`, `_HOUR` (always on), `_SHIFT`, `_DAY`, `_WEEK`, `_MONTH`, `_YEAR`; `AGG_SHIFT_START`, `AGG_SHIFT_LENGTH`, `AGG_DAY_START`, `AGG_WEEK_START`, `AGG_CORRECT_*_DST` | Aggregation only | +| Completion notification item | `AGG_COMP_NOT_ITEM` | string item set to `",,"`; period 2 hour, 3 shift, 4 day, 5 week, 6 month, 7 year, 8 30 min | + +Collection types: **Scan** (fixed interval, no buffering), **Event** (on change; needed for +buffering and for migrating history to a CI Core), **Direct** (written by tools/applications). +Storage types: **Time** (one record per scan time, predictable size), **Item** (one record per +item with many samples), **Event** (one record per event; slow for many samples of one item). + +Item in a group (`ITEM_HIS_DF`): `NAME`, `ITEM_NAME`, `GROUP_NAME`; event triggers +`ON_VALUE_CHANGE`, `ON_STATUS_CHANGE`, `ON_QUALITY_CHANGE`, `ON_OPTION_CHANGE`, `ON_EACH_UPDATE`, +`ON_FIRST_UPDATE`, `ON_PASS_PIT`; extra values `STORE_VALUE`, `STORE_*_LIMIT`, `STORE_DEADBAND`; +aggregates `STORE_AGG_MAX`, `_MIN`, `_AVG`, `_INTG` (+ `AGG_INTG_PERIOD` second/minute/hour/day), +`_STDV`, `_CNT` (Boolean: times True), `_DIFF_SUM` (+ `AGG_DIFF_SUM_RANGE` rollover count, +`AGG_DIFF_SUM_PERC` leap detection; for counters, more accurate than the integral). +Typical: Real/Integer max, min, average, standard deviation, integral; Boolean counter; +Integer counter totals differential summation. + +Aggregation quality (with *Store quality code*): 1000 × share of source values that were not +offline (other bad statuses do not count). Weekly/monthly/yearly are built from daily values. + +`ithsag.sup` (aggregation process): `run_interval` (manual: *Heartbeat*, spreads the work, +600 s), `buffer_size` 20, `event_timeout` 1 s, `gap_time` 2880 min, `max_sample_delay` 14400 +min, `max_open_files` 10, `queue_size` (installed **500** KB, manual default 200), `dif_sum_noise`. + +## 3. Verified behaviour (CI-Eng-Sample, 2026-10-01) + +- Loaded `CIENG_SCAN10S` (Scan/Time, 10 s) and `CIENG_AGG` (Aggregation, 30 min + hour) with + `dssqld -i`, 0 errors. **They stored nothing until CI Server was restarted** (ISS-006); after + the restart `TANK1.LEVEL` appeared every 10 s (`SAMPLE_TIME` 12:00:10, 12:00:20, …, status 9). +- The first unit of a new Event/Item or Aggregation group is dated 2 days back (= `gap_time`); + a Scan/Time group's first unit starts at creation. +- Reading one group: add `GROUP_NAME = ""` to the `ITEM_HISTORY` filter. Without it the + rows of all groups holding the item are returned. +- `ithloahis` into an Event/Item group: samples dated inside the active unit or a unit closed by a + rollover were stored (a few seconds later); samples older than the first unit the storage + process opened after the restart were dropped **without any message** (also with `-l`). The + next unit's initial value then came from the dropped sample (ISS-038). + +- Aggregation: `CIENG_AGG` (30 min + hour, LEVEL max/min/avg) loaded, units and extra + `…zzz…` files created, but no aggregate appeared in `ITEM_HISTORY` between the 12:00 restart + and 13:00 (level varied 40–70 from 12:06 to 12:11; `ithsag` running, no message) — ISS-040. + `INTERPOLATION = "Hour"` is a valid filter value; `"30 minutes"` is refused. +- Full sample remove/reload with all three groups: 0 errors. + +## 4. Archive (§2.2) + +1. Define the device in `has.sup` (tape, or a CD/DVD/disk path) and restart. +2. *Historisation > Archive > Initialize storage medium* (label, e.g. the first date) — writes an + ID file. +3. *Archive > Automatic archive*: daily time; unarchived data is written then. Big archives + need a scratch folder (`TEMPORARY-PATH` in `has.sup`). +4. *Archive > Retrieve from archive*: period (whole archive runs only), group, keep-free disk + space, life time of the restored data; mount the requested media. Restored data is used by + reports and trends until its life time ends. (Known issue: alarm attribute databases are not + restored, IM 36K01A50.) + +## 5. Reading history (§4) + +- Classes (`DSS_OPEN_ALL("ITEM_HISTORY", "r", r)`, `DSS_SET_FILTER`, `DSS_READ_NEXT`, + `DSS_GET_FLOAT(…,"ITEM_VALUE",…)`), reports (`SELECT … FROM ITEM_HISTORY WHERE ITEM_NAME = … + and INTERPOLATION = 'Hour' and ATTRIBUTE = 'Maximum' …`), ODBC (only remote way), C / .NET API, + `dssqld`, and `ithloahis` for writing. +- Aggregates are selected with `INTERPOLATION` (`Hour`, `Day`, `Month`, `Year`, …) and + `ATTRIBUTE` (`Maximum`, `Minimum`, `Average`, `Integration`, `Standard deviation`, + `Counter`, `Differential summation`). +- `ithloahis -f [-v] [-l] [-i] [-s
] [-t GMT|LST|LCT]`: SCAN or EVENT files + (skill `system-management`, task `load-history.md`). + +## 6. Troubleshooting (§5) + +`hisdbg` (3 unit info, 20 all groups, 21 group by name), `hisrep`, `hisrecover`, `isfrename`; +archive: the `has.sup` status item and `hasdbg` (11 media, 8 overview, 10 delete a medium). +Backup example (App. 1.4): `xcopy /E` of `%TLS_ROOT_PATH%\tls` and `%TLS_ALLUSERS_PATH%` into +a dated folder (the manual does not say; stopping CI Server first gives a consistent copy). diff --git a/knowledge/manuals/IM36K10L20-01EN.md b/knowledge/manuals/IM36K10L20-01EN.md new file mode 100644 index 0000000..9c992ff --- /dev/null +++ b/knowledge/manuals/IM36K10L20-01EN.md @@ -0,0 +1,104 @@ +--- +manual: IM 36K10L20-01EN +title: History Management Engineering +edition: 3rd Edition, Sep. 2023 (text marked Sep. 2022) +version: R1.03 +status: hisdbg read-only options, rollover and history file layout verified on the test system 2026-10-01; archive (hasman/hasexe/hasdbg), hisrecover, hisrep, hiswrn from docs; setup files checked read-only +--- + +# History Management Engineering (R1.03) + +HISTORY Service schedules and administers **history groups** (storage groups) and their +**units** (files) for all services that keep history: item history (ITEM Service), the +chronological alarm overview (`ALH`), the audit trail, the system log and report definitions. +It does not know the contents of the files; the client services write and read them. Section +numbers refer to the manual. Engineering Module forms and item storage group types: +`IM36K10C40-01EN.md`; item history processes (ITH*): `IM36K10L35-01EN.md`. + +## 1. Processes and data (§1) + +| Process | Role | +|---|---| +| `HIS` | History manager: schedules start / stop / rollover / delete commands, keeps the administration, serves the message interface. No setup file, no arguments | +| `HASMAN` | Archive manager (automatic daily archive, manual archive, retrieve); `has.sup` | +| `HASEXE` | Archive executor: accesses the archive device; `has.sup` | +| `LGHUMH` | Copies message log entries into the `SYS_LOG` group (started by `history_start.cmd` on the host node) | + +Installed `tls\com\history_start.cmd`: creates `%TLS_HIS_PATH%\has`, runs **`hisrep` +automatically at every start** when `his_units.dat` exists, then starts `his`, `lghumh`, +`hasexe`, `hasman`. + +Administration (DATABASE Service files in `tls\dat`): `his_proc.dat` (every client that ever +logged in; they get *history manager up* at start), `his_groups.dat` (group definitions and +schedule), `his_units.dat` (all units with start, stop, delete and warning times). + +Archive status item (`has.sup` `STATUS_ITEM`): statuses `ARCHIVE_A`, `ARCHIVE_M`, `ARCHIVE_R`, +`MOUNT_TAPE`, `INIT_TAPE`, `REG_TAPE`, `SKIP_TAPE`, `CANCEL`, `READY` (value 1, normal) and +`FAILED` (value 0, Alarm 1). A storage group can be excluded from archiving +(`HIS_GROUP_DF` `EXCLUDE_ARCHIVE`). + +## 2. History files (§2.1) + +- Group number = node + sequence; unit number = *unit* sequence (incremented when the group + is modified) + *data* sequence (incremented at each rollover). +- File names use base-32 digits (`0`–`9`, `a`–`v`): `h000000.his` group description, + `h000.his` unit description, `h.his` unit data; reports also + `…000000.rpt`. Each is a DATABASE Service file with `.d01` / `.k01` / `.k02` companions. +- **Verified** (`%TLS_ALLUSERS_PATH%\tls\his\`, `hisdbg`): `CIENG_EVENT` = group 1,54 → + `h0101m…`; `CIENG_SCAN10S` 1,55 → `h0101n…`; `CIENG_AGG` 1,56 → `h0101o…` plus extra + `h0101ozzz…` files for the aggregates. After a CI Server restart the unit sequence jumped from + 1 to 3 (consistent with `hisrep` at start, which increases unit sequences by 1). + +## 3. Debugger `hisdbg` (§3.1) + +Starts by asking for the node (blank = local). Menu (installed: `-1` … `22`): + +| No. | Action | Use | +|---|---|---| +| 1 | Statistics (groups, logged-in clients, commands, unit starts/stops/rollovers/deletions) | read-only | +| 2 / 21 / 22 | Group info (last group / by name / by number): path, group number, next unit and file, his_type, opt_type, start, stop, first rollover, interval, life time, warn time, GMT/LCT rollover, archiving flag, lock state | read-only | +| 3 | Unit info of the current group: unit, data, file, start, stop, delete (GMT) | read-only | +| 6 / 7 | Logged-in clients / command interests of one client | read-only | +| 11 | Show unknown history files | read-only | +| 20 | All groups: name, number, type | read-only | +| 4 / 8 / 10 / 12 | Delete unit / delete group (no active unit) / restore unit (file must exist) / delete unknown files | **changes history — never without approval** | +| 5 | Force rollover (same as Engineering Module *Force rollover*; not within 2 min of the last one) | changes files | +| 9 | Change schedule (start, stop, next rollover, interval, life time, GMT rollover, warn time) | changes the group | + +History types: 21 alarm (`ALH`), 24 item, 6 audit (`ADT`), 1058 report definitions; on the test +system also 4 (`STATION_STAT`) and 36 (`SYS_LOG`), not listed in the manual (ISS-039). +opt_type shows the item collection/storage type (the manual's table is garbled in the PDF); +**verified**: Scan/Time `1 1` (`CIENG_SCAN10S`), Event/Item `2 2` (`CIENG_EVENT`), +Aggregation `4 4` (`CIENG_AGG`). Times are shown in GMT. + +**Verified on the test system (2026-10-01):** 45 groups, 30 logged-in clients (ITH*, ALH, +ADTSTO, DSSSDA/DSSEVT, LGHUMH, EQPIOSTAT, RPTMAN, HIS); group info of `CIENG_EVENT` (path +`C:\Users\Public\Yokogawa\tls\his\`, rollover daily at 00:00 GMT, life 7 days, GMT rollover, +included in archiving); force rollover of `CIENG_EVENT` closed unit 3,1 and started 3,2. + +## 4. Other utilities (§3.2–§3.5) + +| Utility | Use | +|---|---| +| `hisrecover ` | Make an unknown unit data file known again (start/stop LCT `dd-mmm-yy hh:mm:ss`); group and unit description must be known | +| `hiswrn` | Reset deletion warning times of units saved with a backup prefix | +| `hisrep` | Repair unit administration after crashes or full disks: increase unit sequences, close units with stop time 0 using the last time-control record. Runs at every CI Server start | +| `hasdbg` | Archive debugger: 1 initialise, 2 mount, 3 register medium, 4/5 get/set automatic archive time, 6 manual archive, 7 retrieve, 8 overview, 9 cancel, 10 delete a medium from the administration, 11 list media, 20 dump medium | + +## 5. Archive (§2.2) + +- `HASMAN` decides what to archive (daily automatic archive or on request), `HASEXE` writes it. + Devices: tape (`TAPE-DRIVE`, Windows default `//./TAPE0`) or a disk path (`CD-DRIVE`: local + disk, network share, USB, UDF-formatted CD/DVD). One device at a time; restart after + changing `has.sup`. Archive size ≈ 20 % of the history data. +- Administration: `has_idx_act.dat` (initialise / archive actions) and `has_idx_grp.dat` + (groups and units per medium), also copied to each medium. If corrupt: stop CI Server, + delete both from `tls\dat`, start, register the latest initialised medium (and the latest + used one). Remove damaged media with `hasdbg` 10. +- **Installed `has.sup`:** no drive configured (archiving not set up), `COMPRESSION-RATIO 6`, + `SH_EOT` / `SH_NO_TAPE` shell signals. Other keywords: `TAPE-SIZE`, `STATUS_ITEM`, + `HISTORY-PATH`, `TEMPORARY-PATH` (scratch folder for big archives), `HIS`, `SH_WRITE_PROT`, + `SH_IGNORE`, `SH_KILL`, `DEBUG`. + +Not practiced: archiving and retrieve (no archive device; would write to disk and change the +archive administration), `hisrecover`, `hiswrn`, running `hisrep` by hand.