cliu/ci-server-engineer
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Phase 9: History Management Engineering, Engineering Module - Historical #9

Merged
cliu merged 5 commits from docs/phase-9-history into main 2026-10-01 14:09:34 +10:00
Conversation 0 Commits 5 Files changed 14 +425 -2
6 changed files with 425 additions and 2 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files
Showing only changes of commit 37c91eeac7 - Show all commits

40
.claude/skills/history-management/SKILL.md Normal file
View file

@ -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) |

46
.claude/skills/history-management/tasks/history-checks.md Normal file
View file

@ -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<GROUP>\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 `<name>` | 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<node><group><unit><data>.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.

104
.claude/skills/history-management/tasks/storage-groups.md Normal file
View file

@ -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
"<GROUP>","<description>","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
"<GROUP>","<description>","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
"<GROUP>","<description>","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
"<GROUP>:<Section>.<Tag>","<Section>.<Tag>","<GROUP>",1,1
@FIELDS
NAME,ITEM_NAME,GROUP_NAME
@ITEM_HIS_DF
"<SCANGROUP>:<Section>.<Tag>","<Section>.<Tag>","<SCANGROUP>"
@FIELDS
NAME,ITEM_NAME,GROUP_NAME,STORE_AGG_MAX,STORE_AGG_MIN,STORE_AGG_AVG
@ITEM_HIS_DF
"<AGGGROUP>:<Section>.<Tag>","<Section>.<Tag>","<AGGGROUP>",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 = "<Section>.<Tag>" and GROUP_NAME = "<GROUP>" and SAMPLE_TIME > "<dd-mm-yyyy hh:mm:ss>" and SAMPLE_TIME < "<dd-mm-yyyy hh:mm:ss>"'
@ITEM_HISTORY
```
`dssqld -e <out>.qli <filter>.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) |

11
.claude/skills/system-management/tasks/load-history.md
View file

@ -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

122
knowledge/manuals/IM36K10C40-01EN.md Normal file
View file

@ -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
`<group>:<item>`). 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 `"<GMT seconds>,<period>,<group>"`; 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 = "<group>"` 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 <csv> [-v] [-l] [-i] [-s <section>] [-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).

104
knowledge/manuals/IM36K10L20-01EN.md Normal file
View file

@ -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`): `h<nn><ggg>000000.his` group description,
`h<nn><ggg><uuu>000.his` unit description, `h<nn><ggg><uuu><ddd>.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 <file> <start> <stop>` | 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.