ci-server-engineer/.claude/skills/system-management/tasks/load-remove-records.md

task	version	source	status
Load and remove dataset records with dssqld (quick load)	R1.05 (first written for R1.03)	IM 36K10J10-01EN §2.9.2, §5.6; IM 36K10L50-01EN §3 (5th ed., Feb. 2026); IM 36K10L45-01EN §10.12–10.13 (5th ed.; §9.10–9.11 in the R1.03 edition); practiced with CI-Eng-Sample 2026-09-30	verified on R1.03 (2026-09-30); on R1.05 `dssqld -i` / `-r` used in the reduced CI-Eng-Sample load on the R1.05 test server (2026-10-08, 0 errors, `@VERSION 1.03.00` files accepted); `dssqld` help text identical to R1.03; `-m` and the storage-group steps not re-run on R1.05

Load and remove dataset records (dssqld quick load)

Writes to the CI Server database. Needs CI Server running. Follow the user's chosen way of working: in prepare only mode, write the .qli files and a .cmd script for the user to run. Test on a test system first.

Quick load file format (.qli)

@LANGUAGE
ENGLISH

@VERSION
1.03.00

! comment
@FIELDS
NAME,SECTION_PATH,SECTION_NAME,DESCRIPTION

@SECTION_DF
"CI-Eng-Sample","","CI-Eng-Sample","CI-Eng-Sample project"
"CI-Eng-Sample.TANK1","CI-Eng-Sample","TANK1","Sample tank 1"

• @VERSION names the release the file was written for; R1.05 loads files marked 1.03.00 without complaint (CI-Eng-Sample test, 2026-10-08).
• @FIELDS lists the fields in the records that follow; the next @<DATASET> line names the dataset. A file can hold several @FIELDS / @<DATASET> blocks.
• One record per line, strings in double quotes, numbers bare, comma-separated. End a line with \ to continue the record on the next line (long @FIELDS lists can also wrap).
• Only the listed fields are set; the rest take their defaults. Required fields are marked "Is required on import" in the data dictionary (dssqld -f -l dict.lst).
• Easiest way to get a correct template: export an existing dataset without -c (dssqld -e template.qli -d <DATASET>); the output is already in this format.

Load (insert)

dssqld -i <file>.qli -l <file>.qlo

Summary per dataset: Recognized, Imported, Exists (already present, left unchanged), Errors. Check Errors is 0; the .qlo listing holds the same result.

File names: the whole path must be ≤ 79 characters (verified; longer input paths fail with DSSQ-E-Q_QLIEXT or CRL-E-ENOENT). Run dssqld from the file's folder with relative names. ISS-020.

Update (modify)

dssqld -m <file>.qli -l <file>.qlo

Changes the listed fields of existing records (the key field plus the fields to change). Summary: Modified, Not found, Errors. Verified by setting a storage group's STOP_TIME.

Remove (delete)

dssqld -r <file>.qli -l <file>.qlo

The file only needs the key field (@FIELDS NAME). Summary: Removed, Not found, Errors.

Storage groups (HIS_GROUP_DF) cannot be deleted while they have an active storage unit (HIS-E-GROUPHASUNT, Group still has an active unit connected). First remove the items from the group (ITEM_HIS_DF), then set the group's STOP_TIME a minute ahead with -m, wait until it has passed, then delete the group. Deleting a group deletes its history.

Order matters

• Load parents before children: sections (parent before child) → template items → classes (compiled) → objects → other items (IM 36K10J10 §5.6) → storage groups → items in storage groups (ITEM_HIS_DF, record name <group>:<item>).
• Remove in reverse: items from storage groups, storage groups (stop first), items, sections (children before parents).
• A new storage group stores nothing until CI Server is restarted.
• Linking items to a group straight after creating it failed once with 2 errors; a 5 s pause in between has been reliable (knowledge/issues.md ISS-005).
• Put each step in a .cmd script so the order is repeatable. Run scripts by full path (cmd /c "<path>\load.cmd"); a bare name may not be found from the current folder.

Clean up after loading (R1.05)

dssqld leaves 0-byte dss_<n>_<id>.tmp files in %TLS_LST_PATH% (tls\lst), and loading a class left one holding the class source (34 files after the CI-Eng-Sample load and remove on the R1.05 test server, ISS-091). The read-only re-check of 2026-10-08 found that of the exports only OBJECT_DF creates them (about one per object, ISS-119); which load/remove steps create them was not narrowed down. CI Server does not delete them. After a test session, delete the files written since it started that are empty or hold only your own test data: examples/CI-Eng-Sample/shared/clean_dss_tmp.ps1 -Since <start time> (note the server time before the first dssqld run). Not checked on R1.03.

Verified example

examples/CI-Eng-Sample/ (01_section_df.qli, 02_item_df.qli, load.cmd, remove.cmd): sections, items, a storage group and its item links loaded, removed and loaded again with 0 errors. remove.cmd shows how to set the storage group stop time from a script (PowerShell writes the .qli, then Start-Sleep; timeout fails when there is no console). Items need only NAME and ITEM_REP (Real, Integer, Boolean, String); the sample also sets DESCRIPTION, VALUE_FORMAT, limits and scale.