ci-server-engineer/knowledge/manuals/IM36K10J10-01EN.md

manual	title	edition	version	status
IM 36K10J10-01EN	CI Server System Design/Management	3rd Edition, Sep. 2023	R1.03	from docs

System Design / Management (R1.03)

How CI Server is built, how to choose a system layout, and how to run, back up, monitor, tune and migrate it. Section numbers refer to the manual.

1. Fundamentals

Three tiers (1.1)

• CI View: the client HMI (Java or HTML5), on Windows PCs, tablets and phones.
• CI Portal: web server that sits between CI View and CI Core.
• CI Core: data server. Talks to field devices (EQUIPMENT drivers), processes real-time data, manages alarms, stores history, exposes external interfaces.

Node, services, processes (1.2)

• One CI Server per machine; each is a node. The license is tied to the node.
• A node runs services (DATABASE, ITEM, ALARM, EQUIPMENT, REPORT, …). Which services start depends on the license.
• Each service is made of processes; a process can have several instances (e.g. several report generators, requests shared out by priority).
• Processes talk by DUR messages; each has a named queue, visible in Performance Monitor.

Data model (1.3)

• Item: the basic data point. Receives acquired values, sends operator/application writes to the RTU, drives alarms, serves as class I/O and as dynamic properties of displays/symbols.
• Section: hierarchical folder for items (item full name Section1.Section2.Tag).
• Object: a set of items managed together; used by processing and linked to graphics.
• External alarm (EAL): alarm from an external system received via the OPC UA client; EAL settings are kept in sections.
• Dataset: table (rows/fields, like an RDB table) holding configuration, current data and history. Users can add their own. Read by displays, symbols, classes, objects, reports and external applications.

Two layers (1.4): CI Portal services and CI Core services, on the same or separate machines.

Service	CI Core	CI Portal
BUS	✓	✓
DATABASE	✓	✓
HISTORY, AUDIT, ITEM, EQUIPMENT, ALARM, PROCESS, REPORT, ACCESS	✓
USER		✓
INTEGRATION	✓	✓

2. Inside CI Server

Function	Service(s)	Summary
Data acquisition (2.1)	EQUIPMENT	Drivers for STARDOM FCX, Vnet/IP, Modbus, DNP3 and others.
Alarming (2.2)	ALARM	Detection (by CI Server or the RTU/PCS, with filters against chattering); notification to display, report, OPC AE/UA, sound, e-mail, printer; state and acknowledgement; stored in ALARM_CURRENT (current) and ALARM_CHRONO (history); analysis with ASPA.
Historization (2.3)	HISTORY	Storage groups made of storage units, one kind per data type: items (ITEM_HISTORY), alarms (ALARM_CHRONO), audit (AUDIT_TRAIL), system log (SYS_LOG), reports.
Symbol and processing (2.4)	PROCESS	Class → object → symbol (below).
Display (2.5)	USER	Displays contain symbols; appearance comes from layouts in an XML layouts file. User definitions set the initial display/layout; Open display actions name a display/layout. Defaults: display main, layout default.
Reporting (2.6)	REPORT	Configure in the Engineering module (query, schedule, trigger item, destination) → generate by schedule, trigger item or ad hoc → output via spool statement or destination (file, printer, application) → stored in history with a lifetime set by the storage group.
User authorization (2.7)	USER	Users belong to authorization groups; groups grant actions. Can be managed through a Windows domain (see Active Directory Integration, IM 36K10J40).
Multi-node (2.8)	BUS	DURM protocol between nodes: dynamic routing, best-line selection, auto-connect to the active HAC server, encryption and server certificates.
External interface (2.9)	ACCESS	ODBC (Simba server on the Core; optional license; the only route for non-Windows clients), OPC classic DA/AE/HDA (local network), OPC UA, remote database copy (mirror to external tables for complex queries; watch export size), Excel Add-in, command-line tools.

Class, object, symbol (2.4)

• A class defines items, template items and processing; written in the traditional language or Java. Traditional has no loops; Java classes cannot access datasets (no DSS).
• Class structure: PROLOG (local variables VAR, parameters ATTRIBUTE/PROMPT, items SIGNAL ... FROM <template> MAKE ...) and BODY (METHODs with ENTRYCONDITIONs).
• An object is created from a class with parameter values; its items are created or removed with it. Objects are triggered by the scheduler, trigger groups (intervals) or changes of trigger signals. Traditional COMPUTE/FAST classes can also read/write datasets.
• A symbol can be linked to an object so item attributes drive colour, blinking, etc. Symbols with no dynamic attributes need no object.
• Details: Class Description Language (IM 36K10P10 traditional, IM 36K10P11 Java).

Command-line tools (2.3.1, 2.9.2)

Tool	Purpose	Key usage
dssqld	Export / import / update / delete dataset contents; dump data dictionary	-e <out> [<qli filter>] -d <dataset> export (-c comma separated, -a include hidden fields); -i <qli> insert; -m <qli> update; -r <qli> delete; -f dump dictionary; -l [<listing>] log result; -s <setup> (default dssqld.sup).
itmval	Read/write current item data	-g -n <item> [-a <attr>] get (attr 1 deadband, 2 low, 3 high, 4 lowlow, 5 highhigh); -p -n <item> [-v <value>] [-s <status>] [-q <quality>] [-o overwrite blocked] [-t [<date>] <time> [GMT|LST]] set; -e write to event history only (host node); -f <file> <opts> save a command file; -l use local node.
ithloahis	Load history from CSV into event-item / event-event storage groups	-f <file> [-s <section prefix>] [-t GMT|LST|LCT] [-i update current value too] [-v] [-l]. File is either SCAN,<item1>,<item2>,... then <time>,<v1>,<v2>,... (max 100 items), or EVENT then <time>,<item>,<value>. Times as date text or seconds since 1970.
ithimport	Import item history from another CI Server	-l list groups; -s -g <from> [<to>] show; -i -g <from> [<to>] [-f <from time>] [-t <to time>] [-c <rename file>] import. Rename file lines: <old name>, <new name>.
alhimport / adtimport	Import alarm / audit history from another CI Server	-s show, -i import, optional -f / -t time range.

3. System design

Standards to consider (3.1): ANSI/ISA-101 (HMI), EEMUA 191 and ISA 18.2 (alarms), ISA-99 / IEC 62443 and ISO/IEC 17799 (security).

Configurations (3.2)

Layout	When to use	Watch out for
Simple: one CI Core does everything	Local RTUs, a few tens of clients at most	Above ~10 clients, add a separate CI Portal
Separate CI Portal (Portal ↔ Core via DURM)	Many clients / load balancing; clients on untrusted networks; redundant Cores	Deploy display files to the Portals
HAC (high availability): ACTIVE + STANDBY Cores	Continuous operation required; large history that needs a live copy	Stable (ideally redundant) link between servers and to the island-detection network device; license Audit log if it is monitored
Host to Host: a client Core collects from server Cores via DURM	Reuse data at another site/level; RGS on Vnet/IP forwarding upward	Storage on the client Core can grow large
Enterprise operation/engineering	Share data and displays across Cores; standardize engineering (EES deploys configurations)	Needs deep knowledge of dataset dependencies

• HAC: modes MANUAL / AUTO; functions monitoring (restart processes/server), watchdog (shuts itself down if isolated), mirroring; options journaling (recommended on small systems) and debug logging. Portals and OPC clients (via OPC tunneller) follow the active server. Dual redundancy is standard; triple/quad need a special order (Tokuchu).
• Redundant networks: DNP3, Modbus, STARDOM FCX, Host-Host (DURM).
• Buffering and catch-up fill history gaps after outages: STARDOM FCX, DNP3, Host-Host.

Sizing (3.4): estimate history disk size (storage group types and lifetimes) with the sizing tool, and network load with the bandwidth sheets; include Vnet/IP load if connected.

Long distance (3.5): advise on the WAN, but the network provider (or the client's own fibre) owns its design.

Time synchronization (3.6)

• Why: Kerberos fails beyond 5 min skew; protocol timestamps; historians rejecting future data; correlating events; cross-system scheduling.
• Terms: UTC/GMT; LST (local standard, no DST); LCT (local civil, with DST). CI Server tools default to LCT unless noted.
• Adjust gently (slew, not step backwards). Forward jumps make aggregates too small, backward jumps too large.
• Topologies: simple, cascade, star, tree (segment large/wide systems).
• Mechanisms:
  • (S)NTP / Windows Time: domain members sync to the domain controller automatically; workgroup machines need configuring. Registry HKLM\SYSTEM\CurrentControlSet\Services\W32Time\Parameters\Type = NT5DS (domain), NTP (use NtpServer, DNS name), NOSYNC. Poll interval via Config\MinPollInterval / MaxPollInterval (2^n seconds), or NtpClient\SpecialPollInterval when NtpServer ends with ,0x1.
  • DURECS: external clock on a Core serial port (Wharton 482, Trimble GPS, Arbiter 1092/1093), set in durecs.sup.
  • DURUTL: distributes the time master Core's clock to other nodes over DURM (durutl.sup: interval, three deviation limits, two adjust steps, slave node list). Resolution ~2 s; cannot sync a HAC standby.
  • DNP3: CI Server as master writes time to outstations (STARDOM: set TIM_SYNC_REQ on SD_CDNP_*_OPEN; CI side: station Options › time synchronization interval).
  • STARDOM FCX: CI Server writes FT_STime at the station's interval (needs the FCX extension).
  • Vnet/IP: the CENTUM domain master distributes network time; add an SNTP server to the time group on BUS-1. On Vnet/IP stations Windows Time must be stopped/NOSYNC.
  • Others with time sync: IEC 60870-5-101/102/103/104, FA-M3, MELSEC, Omron FINS, Allen Bradley CIP, Bristol Babcock, Fisher ROC, TIE 870-5; ProSafe-PLC via start-up command file.
• Rules: one time master per machine; Vnet/IP overrides everything else; sync everything that shares timestamped data; keep masters close; aim for under a few seconds deviation; plan for time master failure.
• History event buffering: keep Gap time (default 2 days) and Maximum sample delay (default 10 days) in itheix.sup / itheex.sup well above any expected time correction.
• Checks: w32tm /query /configuration, w32tm /query /status, w32tm /resync /rediscover; net time (SMB, not NTP); tmtime on Vnet/IP stations.

Hardening (3.7)

• Windows Firewall on, with the exceptions CI Server needs; remove unused applications and services.
• Install on a fixed, tested patch level; no automatic Windows updates; apply only Yokogawa-evaluated patches.
• Antivirus with real-time scanning; exclude C:\Users\Public\Yokogawa\tls\dat, …\tls\sav, …\tls\his.
• Recommended user groups: Administrators (everything), Maintenance (users, logs, datasets), Engineers (engineering module: alarms, reports, graphics), Operators (operator screens), InternalProcess (internal accounts, non-expiring passwords). The manual's table maps each authorization (e.g. ITEM_MODIFY_VALUE, REPORT_GENERATE_ADHOC, USER_INSERT) to these groups; in short, read rights go to all, engineering changes to Administrators and Engineers, user management to Administrators and Maintenance.

4. Operation and maintenance

Backup and recovery (4.1.1)

• What to back up: the OS (~10 GB), CI Server software and setup files %TLS_ROOT_PATH%\tls (~2 GB), database and display files %TLS_ALLUSERS_PATH% (~700 MB without history), and history.
• Plan for RTO/RPO, off-site copies, labelled and rotated media, and backup result reporting. Recommended: disk first tier, tape second tier; centralized backup server; never back up over the control network.
• Suggested schedule: full offline backup at version upgrades and periodic maintenance; full after OS patches; weekly full; daily full or differential of the tls folder; archive history weekly; export key datasets daily with dssqld.
• Don't change configuration during a backup. Use VSS for consistent online copies.
• Consistency tools: ismchk <file> / ismkfr [-c] [-r] [-s] [-d] <file> for ISAM files; dsschk [-d <dataset>] [-n <node>] [-e] [-r] [-v] for replicated/duplicated datasets. Repair: repeat dsschk -r until clean, then dsschk -e, then dsschk -e -r (maybe twice).
• Disaster recovery: restore system backup (or reinstall OS + CI Server + patches) → restore tls configuration and database → verify.
• Retrieve archived history from the Engineering module (you can set its lifetime).
• Restore lost records: back up current data, build a .qli from the daily dssqld export, import.

Routine (4.1.2–4.1.5): OS patches, antivirus updates, user account housekeeping; watch Windows and CI Server Performance Monitor, Windows event log, CI Server system log report and audit trail report.

Monitoring processes (4.1.6) — INTEGRATION Service tools, each configured in its .sup file and reporting status into items:

Process	Monitors	How to start
intmon	process running; DURM node and channel status (can set slave items OFFLINE)	Uncomment its line in %TLS_ROOT_PATH%\tls\com\integration_start.cmd
intcpumon	CPU load (any perf counter)	start /B /NORMAL %TLS_ROOT_PATH%\tls\exe\intcpumon -n intcpumon then durwfp -p intcpumon -t 10
intdskmon	disk free space	same pattern with intdskmon
inttcpmon	TCP reachability (ping) of hosts	same pattern with inttcpmon
intadtnot	writes an AUDIT event from a script	intadtnot -e A.B.C.D [-u user] [-t terminal] [-o old] [-v new]
intspawn	runs a command on item value/status/option change, timer or node up/down (max 64 triggers)	intspawn -n intspawn, triggers in intspawn.sup

Problem handling (4.2): identify → investigate (performance monitors, logs, debug mode, debug tools) → fix (memory size, queue size, load balancing, patch).

5. Implementation

Engineering tools (5.1): License Request / Authorization wizards, Setup File Editor (changes apply after the process restarts), Engineering module (Enterprise version for enterprise systems), Edit module (displays and symbols), CI Exchange (import CENTUM VP projects), Performance Monitor, Message log, ASPA, Excel Add-in, hacw_hmi (HAC management).

CENTUM VP import (5.2): CI Exchange reads the VP project → produces import files and an import command → run it → review scan times against Vnet/IP load.

Designing classes and symbols (5.3)

1. Create template items (analogue, digital, string…) in a common system section.
2. Group devices of the same type, define their inputs/outputs and common behavior in a class.
3. Decide which items the class creates; creating an object fails if its items already exist.
4. Group equipment with the same look into one symbol.
5. Sections in a class are relative to the object's section. Template items must exist before objects are created (matters for migration scripts).
6. For performance, prioritize objects.

Testing checklist (5.4): input validation (valid/invalid, boundaries, combinations, defaults), outputs (destination, value, format, messages), interfaces (including offline partners), scheduled tasks, UI (initial values, invalid/quick/concurrent operations, usability), administrator tasks (backup, accounts, monitoring), performance and long-run (leaks, disk), security (privileges), localization, regulations.

Tuning (5.5.1)

• Common memory: max processes 250 by default (dur.sup); keep free common memory above 10 % and usage below 75 % (item pool size in itm.sup).
• Queues must not hold waiting requests; enlarge in each process's setup file. Objects running too often: fix triggers/schedules, or add instances and priorities.
• Database: collisions under 250/s; entries under 80 % of max users (default 2K); max files 1,200. Set -u / -f in database_start.cmd; check with ismdbg.

Debugging (5.5.2)

• Enable debug/log per process in its setup file (<process>.sup, level 1–3, log size); e.g. alnmgr, eqp* (eqpfcx.sup, eqpmdc.sup, or eqpdbg until restart), hac, opc (PRINT statements to UMHLOG, on by default in opc.sup), opxdac (opxsys.sup), opxuac_mon. Turn debug off afterwards (performance).
• Debug-mode launchers: jwuipoi_debug (operator interface), jhmiset_debug (Engineering module), jwuiged_debug (Edit module), fsuedit_debug (Setup File Editor), ftmoni_debug (Performance Monitor), jwuitrd_debug (Trend), jwuiaan_debug (ASPA), jtoolslic_debug / jtoolslicreq_debug (license wizards).
• Debuggers: dssxdb, dsschk, ismdbg (DATABASE); hisdbg, hasdbg (HISTORY); itmdbg, ithdbg, ithrecover (ITEM); opxxdb (ACCESS); rptgen interactive (REPORT); opcdbg (PROCESS); almdbg (ALARM); eqpdbg (EQUIPMENT).

Migration (5.6), e.g. from a demo-license system to the target system

1. Export master datasets with dssqld -e, using .qli filter files (@<DATASET>, @FIELD, @SELECT) where needed: AUTH_GROUP_DF, USER_DF, PRINTER_*_DF, STATUS_DF, ALARM_ACK_DF, ALARM_AOI_DF, communication *_LINE_DF / *_STATION_DF / *_POINT_DF, INSTALL_DF, UNIT_DF, ITEM_DF, HIS_GROUP_DF (item storage groups only), CLASS_DF, OBJECT_DF, REPORT_DF. Drop fields removed in the new release.
2. Re-apply setup file changes on the new system (setup file contents can change between releases).
3. Edit exports (e.g. node names in PRINTER_TYPE_DF, *_LINE_DF, ITEM_DF; set the COMPILE flag to 1 in CLASS_DF), then import in dependency order: template items → classes (compiled) → objects that create items → remaining items → objects that create none. Check each .qlo listing for errors; reorder on relation errors.
4. History: copy %TLS_HIS_PATH% (except has) and his_group.* / his_units.* from %TLS_DAT_PATH%; create the same item storage groups; ithimport -g <group> -c <rename file>; alhimport -i. Alarm tag names cannot be renamed.