ci-server-engineer/.claude/skills/pytools/tasks/modify-datasets.md

task	version	source	status
Insert, update, delete and lock dataset records from a Python script	R1.05	IM 36K10P40-01EN §3.4, §3.6, §3.9, §3.14, §4 (2nd ed., Feb. 2026); sample names from `examples/CI-Eng-Sample/` (`02_item_df.qli`)	from docs, not tested (writes to the running system; no Python on the R1.05 test server)

Modify datasets (insert, update, delete, lock)

Start from setup-first-script.md. This task writes. Only on a test system or with the user's approval and in the agreed way of working (direct vs prepare only). Every change goes through DSS like an Engineering Module change: field checks apply and the audit trail records it with source PYTOOLS and the logged-on user, who needs the matching authorization actions (e.g. item insert/modify/delete, item value write; skill authorization).

For one-off bulk loads use quick load files instead (dssqld, skill system-management, load-remove-records.md); use pyTOOLS when the change depends on logic or on values read at run time.

1. Rules

• Open with the needed mode letters: i insert, u update, d delete (plus r to read back), e.g. 'riud'.
• Only fields listed in openDataset can be set; other fields get their default on insert and stay unchanged on update.
• Each record (dict) must contain the current index field (normally NAME).
• insertRecords / updateRecords take a list (one call for many records; pairs with readRecords).
• Duplicate key on insert → dss.error VIS-W-DUPLICATE; call dss.getErrorStack(conn) for the full message stack (e.g. DSS-E-RECTHERE).
• lockRecords(conn, ds, [keys]) blocks changes by other CI Server processes until unlockRecords (or disconnect); locking a record someone else holds raises dss.error.

2. Example: create, change, lock and remove a test item

Creates CI-Eng-Sample.DEMO.PY_TEST (internal real item in the sample's DEMO section), writes a value, then removes the item again.

import os, sys, getpass
sys.path.insert(0, os.path.join(os.environ['TLS_ROOT_PATH'], 'tls', 'exe'))
import dss

NAME = 'CI-Eng-Sample.DEMO.PY_TEST'          # or <Section>.<Tag> of a test section

conn = dss.connect(os.environ.get('CI_USER') or input('User: '),
                   os.environ.get('CI_PASSWORD') if 'CI_PASSWORD' in os.environ
                   else getpass.getpass('Password: '))
try:
    df = dss.openDataset(conn, 'ITEM_DF', ['NAME', 'DESCRIPTION', 'ITEM_REP'], 'riud')
    try:
        # insert
        dss.insertRecord(conn, df, {'NAME': NAME, 'DESCRIPTION': 'pyTOOLS test item',
                                    'ITEM_REP': 'Real'})
        # update one field
        rec = dss.readEqual(conn, df, NAME)
        rec['DESCRIPTION'] = 'pyTOOLS test item (updated)'
        dss.updateRecord(conn, df, rec)

        # write a value through ITEM_VAL
        iv = dss.openDataset(conn, 'ITEM_VAL', ['NAME', 'ITEM_VALUE'], 'ru')
        try:
            dss.updateRecord(conn, iv, {'NAME': NAME, 'ITEM_VALUE': 42.0})
            print(dss.readEqual(conn, iv, NAME))
        finally:
            dss.closeDataset(conn, iv)

        # lock / unlock (others cannot change the definition meanwhile)
        dss.lockRecords(conn, df, [NAME])
        dss.unlockRecords(conn, df, [NAME])

        # undo: remove the test item
        dss.deleteRecord(conn, df, NAME)
    except dss.error as e:
        print('Error:', e.args)
        for code, text in dss.getErrorStack(conn):
            print('  ', code, text)
        raise
    finally:
        dss.closeDataset(conn, df)
finally:
    dss.close(conn)

Expected: no output except the ITEM_VAL record with value 42; afterwards the item no longer exists (itmval -g CI-Eng-Sample.DEMO.PY_TEST fails) and the audit trail shows insert, modify, value change and delete with source PYTOOLS. If the script stops halfway, remove the item with the Engineering Module or a quick load remove file.

3. Not tested / to verify

On a test Core with Python (user, with approval): run §2 with a user that has the item actions; check the audit trail entries; check that ITEM_VAL accepts the value update (otherwise write values with itmval -p, skill system-management); test lockRecords by trying to change the item description in the Engineering Module while it is locked.