---
task: Insert, update, delete and lock dataset records from a Python script
version: R1.05
source: 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`)
status: 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.

```python
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.