cliu
bf7d88a027
Full manual diffs (L15, C20, E30, L25, J40, C10 §2, L10, P10, P11, J20, C30, P20, R40, E10) and read-only checks on the shared R1.05 test server. Skills and summaries moved to R1.05; new skill pytools (IM 36K10P40) from docs (no Python on the test server). Issues ISS-132..181; corrections to version-differences (E10, E30, P11, dss_ath_grp_u0104); C10 summary lists the 3 new authorization actions; r105-verification V10-V17. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
95 lines
4.2 KiB
Markdown
95 lines
4.2 KiB
Markdown
---
|
|
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.
|