ci-server-engineer/.claude/skills/portal-setup/tasks/change-setup-file.md

task	version	source	status
Change a setup file safely	R1.03	IM 36K10R20-01EN §1–2; IM 36K10R10-01EN §4	verified on the test system 2026-09-30 (jwuiisg.sup HTTP port 8080 → 8081 and back; wfla_display.sup queue size via the editor and Reset Field)

Change a setup file safely

Setup files are read only at startup, so every change needs a CI Server restart and should be reversible. Follow the user's way of working: in prepare only mode do steps 1–3 in the user's chosen folder and hand over steps 4–6.

1. Read the current state

Task read-setup-file.md: active lines and the keyword's !KEYWORD block (kind, unit, limits). Check the value the user wants is allowed (!OPTIONS: pos, min, max, list choices).

2. Back up

Copy the file before changing it, e.g. to <name>.sup.<yyyymmdd>.bak in a folder outside tls\sup (or keep the copy in the prepare folder). Writing to tls\sup needs administrator rights.

3. Change the value

Either way works:

• Setup File Editor (Start menu CI Server → Setup File Editor): double-click the file, change the field on its tab and click OK: the file is written at once (R1.03), so back up before clicking OK. The changed field's label turns blue and the file's Status becomes Changed (differs from its !DEFAULT block). Toggle Read Only must be off. Keywords placed before the file's first !TAB line are on the General tab. To go back to the default: cursor in the field, Reset Field, OK.

• Text edit: change only the active line KEYWORD = value; keep the ! lines, the keyword spelling and the CRLF line endings. Add a line if the keyword is not active yet, using the syntax in its !KEYWORD block. The !DEFAULT block holds a copy of each line prefixed with ! : do not change it, or the editor loses the real defaults. Keep double quotes around string values (the editor shows them without quotes). Elevated PowerShell example (active line only, file stays ASCII/CRLF):

  $f = Join-Path $env:TLS_ROOT_PATH 'tls\sup\jwuiisg.sup'
  $t = [IO.File]::ReadAllText($f)
  $n = [regex]::Replace($t, '(?m)^NON_SECURE_PORT_NUMBER = \d+(?=\r?$)', 'NON_SECURE_PORT_NUMBER = 8081')
  [IO.File]::WriteAllText($f, $n)
  

  From a non-elevated shell the write fails with "Access to the path … is denied".

4. Restart CI Server

Stop and start CI Server (skill system-check, needs administrator rights). Confirm with the user first: operator stations and data collection stop during the restart.

5. Verify

Check the new behaviour, not just the file (e.g. for a port change: task check-web-access.md). Check %TLS_LOG_PATH%\ci_start.log and umhlog.log for errors from the program that reads the file.

6. Restore (if needed)

Copy the backup back (or set the old value the same way) and restart again. Compare with the backup (Get-FileHash) to confirm the file is exactly as before.

Test system (2026-09-30)

• NON_SECURE_PORT_NUMBER 8080 → 8081 by text edit, CI Service restarted (elevated): 8081 listening, http://localhost:8081/ returned 200, 8080 refused, no new errors in ci_start.log. Restored to 8080 the same way; file hash identical to the backup.
• wfla_display.sup DUR_QUEUE_SIZE 1000 → 2000 in the Setup File Editor: OK wrote the file at once, Status Changed, label blue. Reset Field + OK wrote 1000 back. Not restarted in between, so never applied.
• Stop-Service/Start-Service StartCIServer from a non-elevated shell fails with "Cannot open StartCIServer service".