ci-server-engineer/.claude/skills/pytools/tasks/setup-first-script.md

---

task: Set up Python and pyTOOLS, check the server side, run a first read-only script version: R1.05 source: IM 36K10P40-01EN §1, §2, §3.2, §3.4, §3.5, §3.12, §3.14, §4 (2nd ed., Feb. 2026); IM 36K01C10-01EN §1.3.3 (5th ed., Feb. 2026, Python 3.12); IM 36K10J10-01EN §2.9.1 (5th ed., Feb. 2026, login method); installed files on the R1.05 test server (2026-10-09) status: from docs, not tested (no Python on the R1.05 test server). Verified read-only on the R1.05 test server 2026-10-09 - tls\exe\dss.pyd (module 3.6.1), DSSSDAPY started by database_start.cmd, dss.sup routing, dssana.sup Python Interface lines; no Python installed there (only the 0-byte Microsoft Store aliases). R1.03 (development machine 2026-10-09): R1.03 dss.pyd imports under Python 3.12.10, version() and busGetDirs() work without CI Server running

Set up pyTOOLS and run a first script

1. Check the server side (read-only)

Check	Command	Expected (R1.05)
Module present	dir "%TLS_ROOT_PATH%\tls\exe\dss.pyd"	137,728 bytes, Jun. 2026 (R1.03: 124,928 bytes, Aug. 2023)
Dedicated DSS server running	durwfp -p DSSSDAPY -t 0 then echo %ERRORLEVEL% (separate commands)	0
Started by	findstr /i dsssdapy "%TLS_ROOT_PATH%\tls\com\database_start.cmd"	start /B /NORMAL ...\dsssda -n dsssdapy
Client routing	findstr /i PYDSS "%TLS_ROOT_PATH%\tls\sup\dss.sup"	DSSSDA_SRV = -1, "PYDSS*", "DSSSDAPY"
Allowed as user interface + login method	findstr /c:"Python Interface" "%TLS_ROOT_PATH%\tls\sup\dssana.sup"	USER_INTERFACE = "Python Interface", "PYDSS", 18, ... and LOGIN_METHOD = "<local>" / "<remote>", "Python Interface", Manual CI Server, NO,
Python	where python and py -0p	a real python.exe (a 0-byte file under ...\WindowsApps is only the Store alias = no Python)

If the Python Interface lines are missing (e.g. after a merge of an old dssana.sup during an upgrade), pyTOOLS cannot log on: compare with tls\sup\dssana.sup of a clean R1.05 install (skill portal-setup, setup-file merge).

2. Install Python and the environment (user, administrator)

Action needed (administrator, on the CI Core / CI Portal):

1. Install 64-bit Python 3.12 from python.org (right-click the installer › Run as administrator; tick Add python.exe to PATH or use the py launcher). Python 3.12 is the version listed as allowed coexisting software in IM 36K01C10.
2. Add the system variable PYTHONPATH = %TLS_ROOT_PATH%\tls\exe with the real path (e.g. C:\Yokogawa\CIServer\tls\exe; the manual's C:\Program Files (x86)\... is only the default). PowerShell (admin): [Environment]::SetEnvironmentVariable('PYTHONPATH', "$env:TLS_ROOT_PATH\tls\exe", 'Machine')
3. Open a new command prompt and run python -c "import dss; print(dss.version())". Expected on R1.05: pyTOOLS DSSmodule 3.6.1 r11609M [Jun 10 2026, ...].

Without changing the system variable, a script can add the folder itself (used in the examples below): sys.path.insert(0, os.path.join(os.environ['TLS_ROOT_PATH'], 'tls', 'exe')). TLS_ROOT_PATH is set by the CI Server installation. The module finds its CI Server DLLs (buslib64.dll, databaselib64.dll) in the same folder.

3. First read-only script

Needs a CI Server user (any authorization group that may read items; e.g. the sample's CIENG user, which has no password). Save as first_read.py in a scratch folder.

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

ITEM = 'CI-Eng-Sample.TANK1.LEVEL'            # or <Section>.<Tag>

print(dss.version())                          # works without a connection
user = os.environ.get('CI_USER') or input('CI Server user: ')
pwd = os.environ.get('CI_PASSWORD')
if pwd is None:
    pwd = getpass.getpass('Password: ')

conn = dss.connect(user, pwd)                 # connect + logon (Manual CI Server)
try:
    ds = dss.openDataset(conn, 'LOCAL_NODE_DF',
                         ['NAME', 'NODE_NUMBER', 'VERSION_MAJOR', 'VERSION_MINOR',
                          'VERSION_PACK', 'STARTUP_TIME'], 'r')
    try:
        node = dss.readNext(conn, ds)
        print('Node %s (%d), CI Server R%d.%02d.%02d, started %s' % (
            node['NAME'], node['NODE_NUMBER'], node['VERSION_MAJOR'],
            node['VERSION_MINOR'], node['VERSION_PACK'],
            dss.dateString(conn, node['STARTUP_TIME'], 'GENERAL')))
    finally:
        dss.closeDataset(conn, ds)

    ds = dss.openDataset(conn, 'ITEM_VAL',
                         ['NAME', 'ITEM_VALUE', 'STATUS', 'UPDATE_TIME'], 'r')
    try:
        rec = dss.readEqual(conn, ds, ITEM)
        print('%s = %s (%s) at %s' % (rec['NAME'], rec['ITEM_VALUE'], rec['STATUS'],
                                     dss.dateString(conn, rec['UPDATE_TIME'], 'GENERAL')))
    except dss.error as e:
        code, text = e.args
        print('Cannot read %s: %s %s' % (ITEM, code, text))
    finally:
        dss.closeDataset(conn, ds)
finally:
    dss.close(conn)                           # also logs out

Run: python first_read.py (with CI_USER=CIENG and CI_PASSWORD= set, or answer the prompts). Expected: the module version, one line for the local node (version matching the system-check result) and the current value of the item. An unknown item gives a dss.error from DSS (record not found) instead of a crash.

4. Typical first errors

Symptom	Cause
ModuleNotFoundError: No module named 'dss'	PYTHONPATH / sys.path does not point to tls\exe, or an old prompt without the new variable
ImportError: DLL load failed / not a valid Win32 application	32-bit Python, or CI Server DLLs missing (not a CI Core / Portal)
PY_DSS_NOT_LOGGED_IN	dss.connect() without user/password, then a dataset call: DSS gives no data without a logon
PY_DSS_ALREADY_CONN	a second dss.connect() in the same script
Logon refused	wrong password, user unknown, or the Python Interface login method is not Manual CI Server / missing (§1)
DSS-E-EOS	end of dataset in a readNext loop: normal, catch it (task read-items-history.md)

Check afterwards: the audit trail shows the logon/logout with source PYTOOLS (skill audit-trail).

5. User verification (R1.05, not yet done)

1. §1 checks (all read-only) → expected values as in the table.
2. §2 on a test Core with Python 3.12 64-bit → version string as above.
3. §3 with a read-only user → node line + item value; then confirm in the audit trail that the logon and logout were recorded with source PYTOOLS.
4. Also try dss.connect() without user followed by openDataset → expect PY_DSS_NOT_LOGGED_IN (ISS-178).