ci-server-engineer/.claude/skills/history-management/tasks/storage-groups.md

task	version	source	status
Create item storage groups (Event/Item, Scan/Time, Aggregation), add items, read history	R1.05 (first written for R1.03)	IM 36K10C40-01EN §2.1, §3, §4.2, App. 1 (5th Edition, Feb. 2026); IM 36K10L20-01EN §2.1 (4th Edition, Feb. 2026); practiced on CI-Eng-Sample 2026-10-01	verified on R1.03 (2026-10-01). R1.05 - dataset definitions (HIS_GROUP_DF, ITEM_HIS_DF, ITEM_HISTORY) and setup files (ithsag.sup, itheix.sup, itheex.sup, ithstx.sup) identical to R1.03 (compared 2026-10-08 with snapshots of the R1.05 test server); not re-tested on R1.05 (shared server; a new group needs a CI Server restart, and the reduced sample load left out the history groups)

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. From other applications (C40 §4.2, from docs): ODBC and the RESTful API (GetHistory, GetHistoryMultiTag; both also from remote PCs) in skill data-access; .NET API; pyTOOLS (dss.getItemHistory, IM 36K10P40 §3.13, no skill yet; uses its own attribute and period names). Reports: skill reporting. 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: add and INTERPOLATION = "<period>" and ATTRIBUTE = "<aggregate>". Periods (installed names, from ithdbg): Hour, Shift, Day, Week, Month, Year, 30Minutes ("30 minutes" is refused: DSSP-E-NOTRANSF … illegal value). Aggregates: Maximum, Minimum, Average, Integration, Standard deviation, Counter, Difference summation (ithdbg spelling; the manual writes Differential summation). SAMPLE_TIME is the start of the period; QUALITY 1000 = all source values online.

Source group: aggregation (and retrieval) uses the item's highest-priority storage group as its source. If the item is in several groups with the same priority, the aggregates stay empty without any message (ISS-040). Give one source group a higher PRIORITY.

Check: ithsag.log in %TLS_LOG_PATH% logs [INFO: Aggregation Completed] Group Name:<group> Period Type:<n> (8 = 30 min, 2 = hour) about 1–2 min after each period; ithdbg 20 retrieves one aggregate (<item>, attribute 100 max / 101 min / 102 avg / 103 integral / 104 std dev / 105 counter / 106 diff. sum, interpol 8 or 2, group, interval ms, start, end): 0x09 = ITM error means no value for that period.

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 (R1.03, 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	Empty while CIENG_EVENT and CIENG_SCAN10S both had priority 0; after CIENG_SCAN10S got priority 10, 13:30–14:00 gave max 77, min 33, average 52.7, quality 1000 (written values 33–77)