Citect for Windows, Version 5.xx
TONS driver, User information and design
Citect for Windows, V5.xx
TONS driver
Driver version history
Version
1.00
1.01
1.02
2.00
2.01
Modified By
Andrew Peterson
Andrew Peterson
Andrew Peterson
Andrew Peterson
Andrew Peterson
2.02
Greg Roberts
Details
Original, including accreditation testing
Added Release 1.0.01.09 testing section
Updated after CiT Review
Driver modified to support ONS Messages
Updated to support S3 PLC. Added documentation
for message support.
15-Nov-01 - Update for Polyline support and
blocking support. Updated to v2.03.02.13 of the
driver.
© Copyright 2000 Ci Technologies
Page: 2
Citect for Windows, V5.xx
TONS driver
Contents
1. GENERAL .........................................................................................................6
1.1
1.2
1.3
ABBREVIATIONS.............................................................................................6
OVERVIEW .....................................................................................................6
DRIVER DESCRIPTION .....................................................................................6
2. USER INFORMATION ....................................................................................8
2.1 APPLICATION NOTES FOR DEVICE VETHX1....................................................8
2.1.1 Overview.................................................................................................8
2.1.2 Communication Configuration – VETHX1 ..............................................8
2.1.3 Hints, Tips, and Frequently asked Questions.........................................11
2.2 APPLICATION NOTES FOR TOSHIBA ONS SERVICE ........................................13
2.2.1 ONS Installation Guide.........................................................................13
2.2.2 ONS Verification Guide ........................................................................14
2.2.3 ONS Architecture..................................................................................14
2.3 DRIVER REFERENCE .....................................................................................15
2.3.1 Description ...........................................................................................15
2.3.2 Installation Requirements .....................................................................16
2.3.3 Driver Methodology..............................................................................17
2.3.4 ONS API Access....................................................................................17
2.3.5 Reference: Required Components .........................................................18
2.3.6 Reference: Communications forms........................................................18
2.3.7 Citect Tag Address Format ...................................................................19
2.3.8 Reference: Supported Data Types .........................................................20
2.3.9 Parameters, Options, and Settings ....................................................2321
2.3.10 Advanced ..........................................................................................2421
3. ANALYSIS...................................................................................................2825
3.1 OVERVIEW ...............................................................................................2825
3.2 PROGRAMMING REFERENCE .....................................................................2825
3.2.1 ONS API Functions Reference ..........................................................2825
3.2.2 ONS API Usage Reference ................................................................2825
3.2.3 Required Build Settings.....................................................................2926
3.3 CITECT TAG ADDRESS FORMAT CONVENTION...........................................3128
3.4 SYSTEM TAG TYPES .................................................................................3128
3.4.1 General Tag Format .........................................................................3128
3.4.2 Tag Bases .........................................................................................3128
3.5 PARAMETER TAG TYPES...........................................................................3229
3.5.1 General Tag Format .........................................................................3229
3.5.2 Tag Bases .........................................................................................3330
3.6 PROCESS TAG TYPES ................................................................................3330
3.6.1 General Tag Format .........................................................................3330
3.6.2 Process Tag Types ............................................................................3330
3.7 MESSAGE TAG TYPES...............................................................................3431
3.7.1 Message Tag Format ........................................................................3431
3.7.2 Message.Cache.Reset Tag Format ....................................................3431
3.7.3 Message Tag Types...........................................................................3532
3.7.4 msgPRO_ALARM_CHANGE Message Class ....................................3532
© Copyright 2000 Ci Technologies
Page: 3
Citect for Windows, V5.xx
TONS driver
3.7.5 msgSYS_ALARM_CHANGE..............................................................3633
3.7.6 msgPRM_ALARM_CHANGE............................................................3835
3.7.7 msgEVT_SYSTEM_EVENT ...............................................................3936
3.8 TAG ADDRESS FORMAT SPECIFICATION ....................................................3936
3.8.1 Compiler File Specification...............................................................3936
3.8.2 Include Projects ................................................................................4138
3.8.3 ONS Array Support ...........................................................................4239
3.9 DRIVER SPECIFIC ERRORS ........................................................................4239
3.10 DRIVER ERROR HELP ...............................................................................4239
3.11 DRIVER IMPLEMENTATION NOTES ............................................................4340
3.11.1 OIS TCP/IP Configuration for Redundancy ......................................4340
3.11.2 Online / Offline conditions ................................................................4340
3.11.3 Watchdog Timeout ............................................................................4441
3.11.4 Thread Synchronisation ....................................................................4441
3.11.5 Data Type Mapping and Precedence.................................................4441
3.11.6 PROTDIR.DBF.................................................................................4643
3.11.7 TONS.DBF .......................................................................................4643
3.11.8 Distribution Files..............................................................................4643
3.12 DEVELOPMENT RESOURCES ......................................................................4643
3.12.1 Contacts............................................................................................4643
Ian Emmett ....................................................................................................4643
Michael Preston.............................................................................................4744
3.12.2 Documents ........................................................................................4744
3.13 RISK AREAS .............................................................................................4744
3.14 DEVELOPMENT PLAN ................................................................................4845
4. TESTING RELEASE 1.0.00.26...................................................................4946
4.1 PROCEDURE .............................................................................................4946
4.2 RESULTS ..................................................................................................4946
4.2.1 Test Conditions .................................................................................4946
4.2.2 Citect Startup Testing........................................................................5148
4.2.3 Communication Failure Testing........................................................5148
4.2.4 Redundancy Testing ..........................................................................5249
4.2.5 Error Reporting Testing ....................................................................5249
4.2.6 Data Type Read / Write Testing ........................................................5350
4.2.7 Data Type Matching Testing .............................................................5350
4.2.8 Soak Testing......................................................................................5552
4.2.9 Multiple Unit Tests............................................................................5552
4.3 PERFORMANCE TESTING ...........................................................................5552
4.3.1 Introduction ......................................................................................5552
4.3.2 Calculating the Blocking Constant ....................................................5552
4.3.3 Max Pending Calculation..................................................................5653
5. TESTING RELEASE 1.0.01.09...................................................................5653
5.1 PROCEDURE .............................................................................................5653
5.2 RESULTS ..................................................................................................5653
5.2.1 Test Conditions .................................................................................5653
5.2.2 Citect Startup Testing........................................................................5754
5.2.3 Communication Failure Testing........................................................5754
5.2.4 Soak Testing......................................................................................5754
© Copyright 2000 Ci Technologies
Page: 4
Citect for Windows, V5.xx
TONS driver
5.3 PERFORMANCE TESTING ...........................................................................5754
5.3.1 Introduction ......................................................................................5754
5.3.2 Max Pending Calculation..................................................................5754
© Copyright 2000 Ci Technologies
Page: 5
Citect for Windows, V5.xx
TONS driver
1. General
1.1 Abbreviations
API
DCB
DDK
DLL
DPCS
LAN
MFC
NIC
OIS
ONS
PCMP
TONS
WAN
Application Programming Interface
Driver Control Block. The internal data structure used by a Citect
I/O server when communicating with drivers.
Driver Development Kit
Dynamic Link Library
Distributed Process Control Station
Local Area Network
Microsoft Foundation Class libraries (Win32 C++ object libraries)
Network Interface Card
Operator Interface Station
Toshiba’s Open Network Service
Toshiba’s Process Control Message Protocol
The Citect driver (DLL and compiler files) for Toshiba’s ONS
Wide Area Network
1.2 Overview
The TONS driver supports communication with any ONS protocol-compatible device.
The VETHX1 is the ONS-compatible communication control card of the Toshiba
DPCS system and is the interface card between an ethernet LAN and the internal MC
bus of the Toshiba Integrated Control System TOSDIC-CIE DS.
A similar range of communication control cards are available for other systems,
including the S3 PLC, however this specification refers primarily to DPCS systems
for clarity.
The Toshiba Open Network Service is both a protocol and a suite of NT services
implementing the protocol, for communication via TCP/IP ethernet with the VETHX1
card, and thereby with the DPCS MC bus, or individual cards in the DPCS system.
A development interface, the ONS API, is available for accessing the ONS services
from third party software. The TONS driver uses the ONS API to request information
from and send information to ONS systems, such as the DPCS VETHX1 card.
The ONS API and ONS services require a correctly configured NT ethernet card in
the Citect IO server, running the TCP/IP protocol, as well as a small amount of
configuration of the ONS NT services and ONS systems themselves. The
configuration procedures for the Windows NT components are included in this
specification.
1.3 Driver Description
The TONS driver is a Citect board driver for communicating with ONS-compatible
communication cards (the I/O devices) via the ONS API under Windows NT. The
TONS driver does not physically communicate with the I/O devices themselves, and
does not directly generate channel traffic in the same way a serial driver does, but
© Copyright 2000 Ci Technologies
Page: 6
Citect for Windows, V5.xx
TONS driver
rather re-formats requests from Citect and passes them through to the ONS API. The
ONS API is the access point for the ONS service, which in turn contains the code to
format API requests as physical TCP/IP packets and send them to the I/O devices.
The TONS driver itself is structured as a front-end / back-end driver with a separate
back-end thread launched to service requests for each online unit. A multithreaded
approach is required since all ONS API functions are blocking functions, and calling
them in the foreground driver thread would unacceptably block the Citect process.
© Copyright 2000 Ci Technologies
Page: 7
Citect for Windows, V5.xx
TONS driver
2. User information
2.1 Application notes for Device VETHX1
Property
Manufacturer
Device name
Comms method
Detail
Toshiba Corporation
Communication Control Card VETHX1 for TOSDIC-CIE DS
TCP/IP via 10base5, 10baseT or 100baseT ethernet, or Serial1
Please note that the TONS driver supports communication with any ONS-compatible
communication device.
2.1.1 Overview
This section details the communication configuration for one type of ONS-compatible
device, the DPCS VETHX1 Communication Control Card, and demonstrates
configurations supporting full (4-channel) redundancy.
Please refer to the manufacturer’s documentation for configuration procedures for
other devices.
2.1.2 Communication Configuration – VETHX1
Each VETHX1 card supports redundant communication paths via two separate
ethernet ports on each card, known as Bus A and Bus B. The address of the primary
ethernet port (Bus A) is set via the rotary switches on the front of the card in the range
172.16.64.1 to 172.16.64.32. If the address of the primary port is 172.16.64.x, the
address of the secondary ethernet port (Bus B) is then automatically fixed at
172.16.128.x. Note that the two addresses are on different TCP/IP subnets if the
recommended subnet mask of 255.255.192.0 is used. The ONS API will
automatically attempt to communicate with the secondary port of a VETHX1 card if
communication through the primary port fails.
In addition to the redundancy provided by a single VETHX1 card, two VETHX1
cards can be installed in a single DPCS chassis, providing up to 4 separate
communication paths to a single station. The IP address of the second VETHX1 card
should always be set at 172.16.64.(x+32) where x is the IP address of the primary
VETHX1 card. If the redundant card address is not set to the primary address + 32,
the cards will not operate as a redundant pair.
Although the rotary switches can be used to set IP addresses contrary to the rules and
address ranges specified above, the ONS system will not operate correctly unless the
IP addresses are set correctly.
Example: The following table illustrates the correct IP address configuration for a
DPCS station assigned station number 14, with two VETHX1 cards, each using both
Bus A and Bus B. (NB The configuration will of course change accordingly for other
station numbers):
1
For information on configuring serial communication, please refer to the VETHX1
installation manual 6F8C0789. Serial communication configuration does not form
part of this specification since the TONS driver is independent of the communications
layer, which is entirely abstracted behind the ONS API.
© Copyright 2000 Ci Technologies
Page: 8
Citect for Windows, V5.xx
TONS driver
DPCS Station number
Slot 11 VETHX1 Bus A
Slot 11 VETHX1 Bus B
Slot 13 VETHX1 Bus A
Slot 13 VETHX1 Bus B
14
172.16.64.14
172.16.128.14
172.16.64.46
172.16.128.46
2.1.2.1 Primary VETHX1 Card Mode
The primary VETHX1 card in a DPCS chassis can be set to one of two modes via DIP
switches on the card’s main circuit board. Via jumper W5, the VETHX1 card can be
set to halt (HLT) or retry (RTY) communications when the comms watchdog timer
detects a break in the network connection. For a pair of VETHX1 cards to operate in
a redundant manner, the primary VETHX1 card should be set to HLT to allow the
secondary VETHX1 card to take over communication when the primary comms fails.
2.1.2.2 Single Controller, Multiple DPCS Stations, No Redundancy
The ethernet links shown can be assumed to represent either a single or a double
ethernet connection to the VETHX1 cards (primary and redundant ethernet sockets
per card). Where two links are shown to a single chassis, two VETHX1 cards must be
installed in that chassis.
Standard Ethernet
Card supporting
TCP/IP
:
10bT or 100bT
ethernet LAN
Hub
DPCS stations
(1 VETHX1 card per station)
2.1.2.3 Single Controller, Multiple DPCS Stations, Ethernet Redundancy
The ethernet links shown can be assumed to represent either a single or a double
ethernet connection to the VETHX1 cards (primary and redundant ethernet sockets
per card). Where two links are shown to a single chassis, two VETHX1 cards must be
installed in that chassis.
© Copyright 2000 Ci Technologies
Page: 9
Citect for Windows, V5.xx
TONS driver
Standard Ethernet
Cards supporting
TCP/IP
:
10bT or 100bT
ONS LAN 1
Hub 1
Hub 2
10bT or 100bT
ONS LAN 2
DPCS stations
(2 VETHX1 cards per station)
2.1.2.4 Multiple Controllers, Multiple DPCS Stations, Full Redundancy
The ethernet links shown can be assumed to represent either a single or a double
ethernet connection to the VETHX1 cards (primary and redundant ethernet sockets
per card). Where two links are shown to a single chassis, two VETHX1 cards must be
installed in that chassis.
Hub 3
OIS
LAN
:
10bT or 100bT
ONS LAN 1
OIS 1 10bT or 100bT
ONS LAN 2
:
10bT or 100bT
ONS LAN 1
Hub 1
Hub 2
OIS 2 10bT or 100bT
ONS LAN 2
DPCS stations
(2 VETHX1 cards per station)
2.1.2.5 Redundancy Example
This section describes the action of the redundancy system given the following
hardware configuration:
• Two ONS LAN segments, A and B configured on networks 172.16.64.0 subnet
255.255.192.0 and 172.16.128.0 subnet 255.255.192.0
• OIS PC with 2 ethernet cards configured at IP Addresses 172.16.64.1 subnet
255.255.192.0 on LAN A and 172.16.128.1 subnet 255.255.192.0 on LAN B
respectively
• DPCS chassis with 2 VETHX1 cards configured redundantly at IP Addresses
172.16.64.10 on LAN A / 172.16.128.10 on LAN B and 172.16.64.42 on LAN A /
172.16.128.42 on LAN B respectively.
• DPCS Station configured using the Engineering Tool to use dual VETHX1 cards
at addresses 172.16.64.10 and 172.16.128.42.
• The configuration is illustrated in the expanded system diagram below:
© Copyright 2000 Ci Technologies
Page: 10
Citect for Windows, V5.xx
TONS driver
Hub A
:
172.16.64.1
ONS LAN A
172.16.128.1
ONS LAN B
Hub B
172.16.64.10 172.16.64.42
172.16.128.10 172.16.128.42
VETHX1 VETHX1
Slot 13
Slot 11
(Primary) (Standby)
DPCS Station
With all four communication paths connected, a request for “$C0A.SST” defaults to
communication with 172.16.64.10 (VETHX1 in slot 11 primary port) via OIS card
172.16.64.1. All other channels remain in standby mode.
With Hub A link to 172.16.64.10 broken, a request for “$C0A.SST” switches to
communication with 172.16.128.10 (VETHX1 in slot 11 standby port) via OIS card
172.16.128.1. All other channels remain in standby mode.
With Hub B link to 172.16.128.10 broken, the primary VETHX1 card automatically
switches out of RUN mode, and a request for “$C0A.SST” switches to
communication with 172.16.64.42 (VETHX1 in slot 13 primary port) via OIS card
172.16.64.1. The remaining channel is in standby mode.
With Hub B link to 172.16.64.42 broken, a request for “$C0A.SST” defaults to
communication with 172.16.128.42 (VETHX1 in slot 13 standby port) via OIS card
172.16.128.1.
With all links broken, communication to the DPCS station is lost.
Restoring either of the network links to the secondary VETHX1 card will restore
communications.
Once the primary VETHX1 card has left RUN mode, it must be reset, and the network
links reconnected before it will pick up communications again.
It must be noted that although the IP address of the secondary VETHX1 card
corresponds to DPCS station number 42 (0x2A), the tag $C2A.SST is not available.
When redundancy is properly configured, $C0A.SST is an automatic alias for
$C2A.SST, and in general station N is an alias for station N+0x20.
2.1.3 Hints, Tips, and Frequently asked Questions
2.1.3.1 Duplexing VETHX1
The VETHX1 card can be duplexed by inserting two cards in a single VMCUX1
DPCS chassis, one in slot 11 and one in slot 13. The VETHX1 in slot 11 is always
the primary communication device and the VETHX1 in slot 13 is always the standby
communication device.
© Copyright 2000 Ci Technologies
Page: 11
Citect for Windows, V5.xx
TONS driver
2.1.3.2 DbaAccess Console Application
Toshiba’s DBAACCESS.EXE console application is the recommended diagnostic and
fault-finding tool for the TONS driver and ONS systems. DBAACCESS is installed
automatically during the ONS service installation process, and commonly resides in
C:\ONS.
DBAACCESS makes use of the same API employed by the TONS driver and should
behave identically to the TONS driver. In particular, errors reported by the TONS
driver should also be repeatable using the DBAACCESS utility.
DBAACCESS can assist in determining whether a fault lies in the ONS system
configuration or in the Citect configuration.
• If both DBAACCESS and the TONS driver report the same error the fault will lie
in the ONS system configuration, independent of the TONS / Citect system.
• If the TONS driver reports an error that cannot be reproduced using
DBAACCESS, the fault is likely to lie in the Citect system configuration. Verify
all Board, Port, IO Device and Variable Tag parameters, and CITECT.INI
configuration in Citect.
• If the Citect system configuration is correct, the fault may lie in the ONS API or
TONS driver. Contact Citect Support for more information.
© Copyright 2000 Ci Technologies
Page: 12
Citect for Windows, V5.xx
TONS driver
2.2 Application Notes for Toshiba ONS Service
2.2.1 ONS Installation Guide
The following sections describe the installation process for the ONS service.
2.2.1.1 System Configuration
The ONS service is available under Windows NT only. The system configuration of
the computer running the service should match the following template:
Platform
Microsoft Windows NT Server or
Microsoft Windows NT Workstation 4.0
(Both with service pack 5 or higher)
Hardware
FDD required for PCMP driver installation
Around 4Mb of HDD space available for installation
Around 4Mb of RAM reserved for the ONS service
Network
At least one Windows-compatible ethernet card installed
Microsoft TCP/IP installed
IP Address
172.16.64.x / 172.16.128.x
Multihomed configurations are allowed.
DHCP should not be used since the PCMP/IRPC system
must be manually configured with the current IP address.
Firewall
Ensure that ports 50001, 50011 and 50101 are not blocked
2.2.1.2 PCMP Service Installation
• To install the PCMP driver V1.21, copy the installation files to a 1.44Mb floppy
disk and run SETUP.EXE from A:.
• Note the PCMP service will not install from hard disk or CD.
• You must be logged on as Administrator to install the driver.
• Enter the installation directory, or accept the default directory shown.
• When prompted, install the service as a Single system at the IP address configured
in step 1.
• Restart the computer.
• The PCMP service should be listed as startpmd under the Control Panel
Services applet.
2.2.1.3 ONS Driver Installation
• Run SETUP.EXE from the install directory (on CD or HDD)
• Enter the installation directory, or accept the default directory shown.
• Select an ONS station number (the first node installed should be chosen as node
ONS1).
• Restart the computer.
• The should be 8 services listed under the Control Panel services applet:
- Toshiba ONS Broadcast Message Receiver
- Toshiba ONS Create NWK Region
- Toshiba ONS Database Access
- Toshiba ONS Message
- Toshiba ONS Network Communication
- Toshiba ONS Network Routing
- Toshiba ONS System Control
© Copyright 2000 Ci Technologies
Page: 13
Citect for Windows, V5.xx
-
TONS driver
Toshiba ONS Version Read
2.2.2 ONS Verification Guide
The following steps are for debugging and testing purposes and apply to DPCS
systems only. These steps do not need to be performed as part of a standard ONS,
Citect and TONS driver installation.
Similar procedures may be implemented for other PLC families as required.
2.2.2.1 PCS-DS Engineering Tool Installation
• Run SETUP.EXE from the install directory (on CD or HDD)
• Enter the installation directories, or accept the default directories as shown.
• There is no need to restart the system after installation
2.2.2.2 DPCS Package Installation
• To avoid potential PCS-DS Engineering Tool database corruption it is
recommended that the user run the Engineering Tool at least once after
installation, and before applying the DPCS pack, and create at least one system
with one station.
• Run SETUP.EXE from the install directory (on CD or HDD)
• There is no need to restart the system after installation
2.2.2.3 Communication Test
• Run the PDS-DS Engineering Menu program from the Start Menu
• Select Open System List under the File menu
• Select system type TOSDIC-CIE-DS (… )
• Select LAN form single or double as appropriate (usually single)
• Enter a System Name (e.g. Test System)
• Save the system and overwrite any existing system config if appropriate.
• Select the new system from the Engineering Menu System No. combo box
• Click the System Config button
• Make sure the top level System01 node is selected in the tree view
• Select Add Component under the Edit menu
• Add a DPCS single station (e.g. as Station02)
• Select the new system from the tree view
• Configure the rack as per the physical hardware (by default a VETHX1 card is
shown in slot 11)
2.2.3 ONS Architecture
All information in an ONS system is accessed through string tag names. Some tag
names are predefined (System and Parameter tags), and others can be user-defined
(Process tags, using the Signal List editor in Toshiba’s PCS-DS Engineering Tool for
DPCS systems).
A tag name encapsulates a set of values, not just a single IO point. The values within
a tag are known as atoms, and the object type that corresponds to a tag (e.g. Analog
Input) determines the list of atoms available within the tag.
Accessing information in a tag invariably requires both the tag name and an atom
name to be specified, separated by a period ‘.’.
© Copyright 2000 Ci Technologies
Page: 14
Citect for Windows, V5.xx
TONS driver
There are three classes of tag names defined in the ONS protocol: System Tags,
Parameter Tags and Process Tags.
• System tags provide direct access to information in the DPCS hardware, and the
tag name uniquely identifies a station number, and / or a slot number and / or a
data point. System tag names and atoms always resolve to exactly one data point
(and always the same data point). The naming convention for DPCS systems is
set by the ONS protocol in the document 9B8C0661.
• Parameter tags provide access to user parameter tables, and are also accessed by
formatting a tag name that identifies a station number and / or slot number and /or
I/O point. Parameter tables are generally used within a DPCS program as lookup
tables for conversion processes or as general user memory. The tag and atom
naming convention for DPCS systems is set by the ONS protocol in the document
9B8C0662.
• Process tags provide access to physical I/O values, and are addressed by a userconfigured tag name. The ONS API allows any tag name to be used, and the
Signal List editor of the PCS-DS Engineering Tool can be used to relate a tag
name with a DPCS station, slot and I/O point type. The ONS system allows
arbitrary tag names, however the tag atoms for each tag type are generally fixed.
The allowable tag atoms for DPCS systems are listed in the document 9B8C0604.
A fourth class of tags known as Message Tags are implemented by the TONS driver
itself and are described in section ???.
The tag names referred to above should not be confused with Citect tag names, which
have scope only within the Citect project development environment. The TONS
driver does not have access to the Citect tag names, only to the Citect tag address;
Citect tag names do not form part of the discussion in this specification.
2.3 Driver Reference
2.3.1 Description
The TONS driver for Citect 5.21 is used to communicate with ONS-compatible
devices such as the VETHX1 communications card via the ONS API under Windows
NT
Property
Driver name
Maximum array size2
Detail
TONS
1024 bits
A maximum array size of 1024 bits is chosen to allow Citect to retrieve strings of up
to 128 characters from the driver. Although an ONS string is limited to 16 characters
(128 bits) in length, the ONS data type D_TIME can be retrieved as either an integer
or as a string, and when retrieved as a string, 16 characters is insufficient to hold the
formatted date/time information.
The maximum array size does not affect Citect blocking since the TONS driver
disables all blocking features by means of the %R compiler option (in TONS.DBF).
2
Equivalent to ‘Maximum Request Length’
© Copyright 2000 Ci Technologies
Page: 15
Citect for Windows, V5.xx
TONS driver
2.3.2 Installation Requirements
The TONS driver has been written with Citect DDK version 5.0, and includes support
for C++, multithreading and MFC.
2.3.2.1 CTREGION.DLL
In order to use the driver with Citect version 5.21 and above, the version of
CTREGION.DLL that normally resides in the \CITECT\BIN directory must be
updated with the CTREGION.DLL version from the DDK.
The correct version information for CTREGION.DLL is shown below:
2.3.2.2 DB3UTILS.DLL
The TONS driver makes use of an updated version of the Dbase III file access
routines in DB3UTILS.DLL. In order to use the driver with Citect version 5.21 and
above, DB3UTILS.DLL must be copied to the \CITECT\BIN directory.
The correct version information for DB3UTILS.DLL is shown below:
© Copyright 2000 Ci Technologies
Page: 16
Citect for Windows, V5.xx
TONS driver
2.3.3 Driver Methodology
The ONS API operates in the same manner as the back-end portion of a frontend/back-end driver, and all physical communication, including communication path
redundancy to the I/O devices3, is abstracted behind the API. The API takes on the
full responsibility of acquiring and maintaining the process values of all required
points, as well as online diagnostic and system information for individual stations.
The ONS API must be installed and configured independently of Citect, and the
installation procedure for this is detailed in section 2.1.2.
The TONS driver itself also operates as its own front-end/back-end driver, where the
front end marshals requests from Citect and queues them for servicing by separate 32bit back end threads. The back end must run as a thread since requests to the ONS
API block the calling process, which is unacceptable in the foreground Citect process.
2.3.4 ONS API Access
Tag values are accessed through the ONS API by specifying the string tag name only.
Resolving the string tag name to an IP address / system number, slot number and data
point type is handled behind the API, as is determining whether to use the primary or
redundant network path, or primary and redundant ethernet port in each VETHX1
3
The ONS API offers quadruple-path redundancy with DPCS systems as described in
section 2.1.1 and double-path redundancy with S3 PLC systems, with no additional
configuration required via the API.
© Copyright 2000 Ci Technologies
Page: 17
Citect for Windows, V5.xx
TONS driver
card4. The use of string tag names presents particular problems for the TONS driver,
which is normally provided only with integer UnitType and UnitAddress information
by the Citect compiler (parsed from a Citect tag’s Address field using the definitions
in DRIVER.DBF). To accommodate the arbitrary tag names allowed by the API, the
TONS driver uses the %N+ format option in TONS.DBF to bypass the compiler
translation stage and instead force Citect to provide the driver with a logical record
index into VARIABLE.DBF at runtime. When the driver receives a read or write
request from Citect at runtime, the numerical record index is stored in UnitAddress is
resolved into a string tag name by reading VARIABLE.DBF (or any included
VARIABLE.DBF files) directly, and extracting the string address field.
To assist the driver performance, variable tag information is pre-processed and cached
to memory by the driver during channel initialisation5. This process is invisible to the
user, and is only performed once per Citect IO Server.
• The particular responsibility of loading, caching and querying
VARIABLE.DBF data based on logical record indexes is handled by the
TONS driver front end.
• The responsibility of ensuring full data type compatibility, communicating
with the ONS API and returning data to Citect is handled by the TONS driver
back end.
2.3.5 Reference: Required Components
2.3.5.1 Software
• Windows NT 4.0 Server or Workstation
• Windows NT Service Pack 5 or above
• Toshiba PCMP/IRCP Support Software 1.21 (previous PCMP versions do not
properly support redundancy).
• Toshiba ONS Support Software, Jan 2001 (specific version information not
available)
2.3.5.2 Hardware
• VETHX1 communication card or similar
• RJ45 UTP ethernet crossover cable
or
• RJ45 UTP ethernet straight-through cables x 2 + 10bT / 100bT ethernet hub
2.3.6 Reference: Communications forms
Boards form
Field
Default
Allowable values
4
Obviously the procedure for resolving tag names to DPCS stations is simplified for
System and Parameter tags where system number and slot number is explicit.
5
The cache is initialised during the call to InitChannel() to allow for initialisation
retries if a VARIABLE.DBF file is temporarily locked by another process, and to
minimise the number of tests for whether the cache is initialised or not, per IO Server.
© Copyright 2000 Ci Technologies
Page: 18
Citect for Windows, V5.xx
Board Name
Board Type
Address
I/O Port
Interrupt
Special Opt
Comment
This field is user defined, and is not used by the driver.
TONS
TONS
0
0
Blank
Not used, any value
Blank
Not used, any value
Blank
Not used, any value
This field is user defined and is not used by the driver.
Ports form
Field
Port Name
Port number
Board name
Baud rate
Data bits
Stop bits
Parity
Special Opt
Comment
Default
Allowable values
This field is user defined and is not used by the driver.
User defined
Any value
Refers to the board previously defined in ‘boards’form.
Blank
Not used, any value
Blank
Not used, any value
Blank
Not used, any value
Blank
Not used, any value
Blank
Not used, any value
This field is user defined and is not used by the driver.
TONS driver
NB: This driver has a maximum port support count of 32.
I/O Devices form
Field
Default
Allowable values
Name
This field is user defined, and is not used by the driver.
Number
Must be unique, but is not used by the driver.
Address
<ONS Tag Address>
The address of an ONS System or Parameter
tag (as a string) that can be queried by the
driver to verify whether the unit should be
regarded as online or offline. The numerical
DPCS station number is also extracted from
the tag name.
Protocol
TONS
TONS
Port name
Refers to the port previously defined in the ‘ports’form.
Comment
This field is user defined and is not used by the driver.
2.3.7 Citect Tag Address Format
The TONS driver supports standard Citect redundancy features via automatic
generation of the DPCS station number in the ONS tag.
Initially, the ONS station number is extracted from the tag name specified in the
Citect IO Devices form Address field, which must be a system or parameter tag.
All variable tags addresses that start with $ or % (indicating system or parameter tag)
are automatically formatted to replace the specified station ID numbers or characters
with the station number extracted previously.
© Copyright 2000 Ci Technologies
Page: 19
Citect for Windows, V5.xx
TONS driver
For example, if the IO Device Address field specifies $C13.SST[0], the decimal
station number 19 (= 0x13) will be extracted. For a tag specified in the Citect
VARIABLE.DBF file as $C__.SST[2], the characters in positions 3 and 4 (the __
characters) will be replaced is “13” to form the tag name $C13.SST[2].
The characters specified in VARIABLE.DBF in positions 3 and 4 are not important,
and will always be replaced.
2.3.8 Reference: Supported Data Types
The ONS system supports a number of distinct data types for different I/O points that
must be mapped to appropriate Citect data types in order to be read or written. The
following table details the Citect data types that should be used for each ONS data
type. Where applicable, any alternative Citect data types that can be used to read the
same ONS data type are also listed, in italics.
ONS Data Type
D_NOTYPE
UNDEFINED
D_BIT
D_BITS
D_BYTE
D_BYTES
D_U_BYTE
D_U_BYTES
D_SHORT
D_SHORTS
D_U_SHORT
D_U_SHORTS
D_LONG
D_LONGS
D_U_LONG
D_U_LONGS
D_FLOAT
D_FLOATS
D_DOUBLE
D_DOUBLES
D_TEXT
© Copyright 2000 Ci Technologies
Equivalent Citect Data Type
(NONE)
RDT_DIGITAL
RDT_BYTE
RDT_INTEGER
RDT_LONG
RDT_DIGITAL[]
RDT_BYTE[]
RDT_INTEGER[]
RDT_LONG[]
RDT_BYTE
RDT_INTEGER
RDT_LONG
RDT_BYTE[]
RDT_INTEGER[]
RDT_LONG[]
RDT_BYTE
RDT_INTEGER
RDT_LONG
RDT_BYTE[]
RDT_INTEGER[]
RDT_LONG[]
RDT_INTEGER
RDT_LONG
RDT_INTEGER[]
RDT_LONG[]
RDT_INTEGER
RDT_LONG
RDT_INTEGER[]
RDT_LONG[]
RDT_LONG
RDT_LONG[]
RDT_LONG
RDT_LONG[]
RDT_REAL
RDT_REAL[]
RDT_REAL
RDT_REAL[]
RDT_STRING
Page: 20
Citect for Windows, V5.xx
TONS driver
D_TEXTS
D_STRING
D_STRINGS
D_BIT8
RDT_STRING[]
RDT_STRING
RDT_STRING[]
RDT_BYTE
RDT_INTEGER
RDT_LONG
RDT_BYTE[]
RDT_INTEGER
RDT_LONG
RDT_INTEGER[]
RDT_LONG
RDT_LONG[]
RDT_LONG
RDT_STRING6
RDT_LONG[]
RDT_STRING[]6
D_BIT8S
D_BIT16
D_BIT16S
D_BIT32
D_BIT32S
D_TIME
D_TIMES
Special Polynomial Line Support Tags
Device Data
Description
Citect Address
Format
Citect
Data
Types
Supported
R/W
Description/Special
Usage/Limitations
Name of basethe
polyline tag used
for the block read
POLYTAG
STRING
RW
Must specify a complete,
valid ONS tag/atom.
Polyline operation
POLYOP
INT
RW
W: -1 read data, 0 set all
reals to 0.0, 1 write data
R: 0 no error, otherwise
an error in last operation
Polyline real data
from 0 to 25 (26
items)
POLYVARx
REAL
RW
A POLYOP read
operation is needed
before this data can be
read, and a POLYOP
write operation is needed
to set data
POLYOP Read / Write Values Summary
Operation
Write
Write
Write
Write
Read
Read
Read
Read
Value
-1
0
1
<other>
0
1
2
3
Description
Read polyline data (from POLYTAG into POLVARx vars)
Reset local polyline data (POLYVARx) to 0.0
Write polyline data (from POLYVARx vars to POLYTAG)
Error. POLYOP read value will be set to 1.
No error / Success
An invalid value was written to POLYOP
A polyline read operation failed
A polyline write operation failed
6
When retrieving a D_TIME or D_TIMES type as a string (or array of strings), the
data is returned in the format “Friday, 24th March 2000 16:00:00”
© Copyright 2000 Ci Technologies
Page: 21
Citect for Windows, V5.xx
Read
4
TONS driver
An invalid POLYVARx tag was accessed (e.g. POLYVAR99)
Polynomial lines are special data sets in the ONS system that are logically grouped
together, e.g. used to linearise analog inputs in thermocouples . thermocouples. Find
more info in Toshiba document 6F8C0802 .6F8C0802.
Although it is possible to define many of these (variable name to address) and have
mutiliple units, only ONE memory set of variables exist. Thus the user must ensure
parallel operations/use does not occur if multiple clients use the same ioserver.
CICODE example
To guarantee correct read and write values the Cicode ReRead function should be
used as in the examples below to refresh data.
// Setting
POLYTAG = "%C09ply1401_.tbl" ; // Set basetag string name
POLYOP = 0;
// Clear values
POLYVAR00 = 1.2;
// Set values
....
POLYVAR25 = 0.0;
POLYOP = 1;
// Write values out
ReRead(1)
// Refresh the value of POLYOP
if (POLYOP <> 0) then error
// Reading
POLYTAG = "%C09ply1401_.tbl" ; // Set basetag string name
POLYOP = -1;
// Read values into POLYVARxx
ReRead(1)
// Refresh the value of POLYOP
if (POLYOP <> 0) then error
Message.Reset.Cache Tag
A tag with this ADDRESS name when written to will clear the TONS drivers cache of
alarm statuses. This will force fresh reads of all tags as they are requested from Citect.
2.3.9 Blocking
TONS, being a tag based driver, has unique issues when it comes to blocking data
together for more effeciency. The user must ensure that tags are logically grouped
together because Citect uses the TONS variable.dbf record number as the tags
ADDRESS to the driver.
A special “^” operator has been used in the tags ADDRESS field to group like tags
together. Any data item can be grouped, it should use a unique UNIT TYPE number
in the 0x09000000 range.
tons.dbf file format :
TEMPLATE
¦UNIT_TYPE
¦RA¦BIT_¦LOW
¦HIGH
¦COMMENT
¦
------------------------------ ¦------------¦--¦----¦--------¦--------¦-------------------- ¦
MESSAGE.CACHE.RESET
¦0x0F000000 ¦ 1¦ 16¦
¦
¦Special write only ¦
© Copyright 2000 Ci Technologies
Page: 22
Citect for Windows, V5.xx
TONS driver
POLYTAG
POLYOP
POLYVAR%U(0,0,25)%*64
%N+%R%*16%!%!%!
^^%N+%!%!%!
^^%N+%!%!%!
%N+%R%!%!%!
%N+%R%!%!%!
%N+%R%!%!%!
%N+%R%!%!%!
%N+%R%!%!%!
¦0x0F000001
¦0x0F000002
¦0x0F000003
¦0x00000000
¦0x09000000
¦0x09000001
¦0x0A000000
¦0x0B000000
¦0x0C000000
¦0x0D000000
¦0x0E000000
¦
¦
¦
¦
¦
¦
¦
¦
¦
¦
¦
7¦1024¦
1 ¦ 16¦
2¦ 32¦
0¦
1¦
4¦ 32¦
1¦ 16¦
7¦1024¦
8¦
8¦
1¦ 16¦
4¦ 32¦
2¦ 32¦
¦
¦
¦
¦
¦
¦
¦
¦
¦
¦
¦
¦Basename of polytag
¦Operation
¦Special write only
¦RDT_DIGITAL
¦RDT_LONG, alarms
¦RDT_INTEGER,alarms
¦RDT_STRING
¦RDT_BYTE
¦RDT_INTEGER
¦RDT_LONG
¦RDT_REAL
2.3.10 Alarm Tags
For efficient handling of alarm tags, all tags with “^abcdef” ADDRESSes, should be
placed at the beginning of the VARIABLE.DBF database. This is so that the driver
can quickly match an ONS alarm tag, when it comes in from the ONS system, to the
Citect tag.
2.3.92.3.11 Parameters, Options, and Settings
Standard Parameters
Parameter
Default
Block (bytes)
2
Delay (mS)
0
MaxPending
32
Polltime (mS)
0
Timeout (mS)
1000
Retry
1
WatchTime (Sec) 30
Allowable values
2 (don’t change)
0 (not used)
1 to 32
0 (not used)
1000 (not used)
1 (not used)
30
When using a project with many units and a MaxPending of 32, it may be possible to
run out of Citect data queues. The solution is to add
[Code]queue=1000
to your citect.ini. This will resolve the problem.
Driver Specific Parameters
Parameter
Default
Allowable values
There are currently no driver-specific parameters.
Other Parameters
Parameter
[LAN]Timeout
[TONS]Checkallt
ags
[TONS]Trace
[TONS]
Batchsleeptime
Default
40000
0
Allowable values
40000
0 or 1
0
10
0, 1 or 2
10 to 999 ms
© Copyright 2000 Ci Technologies
Page: 23
¦
¦
¦
¦
¦
¦
¦
¦
¦
¦
¦
Citect for Windows, V5.xx
[TONS]
Pollmsgsleeptime
[TONS]
Onsbatchcount
[TONS]Offlinech
eck
TONS driver
200
10 to 9999 ms
32
1 to 256
10000
100 to 100000 ms
The increased [LAN]Timeout parameter is required to prevent “Request timeout from
PLC I/O Server” hardware alarms during 30 second ONS API timeouts. This
parameter must be set in CITECT.INI.
It is recommended none of the other driver parameters are changed unless there is a
specific reason to do so.
CHECKALLTAGS – If set will check all tags at startup to see if they can be read
from the ONS system. NB: Tags starting with % or $ will fail. For projects with a
large TAG set, this will take a LONG time. TRACE=1 needs to be set for the results
to be seen. This option should only be used at project setup as a check. The other
option is to use the “TagReadKit” which is available from Citect’s WEB site under
“Citect Toolbox” .
TRACE – This should only be used when asked for by Citect Support. It provides
extra traces in the code to a file called “tons_trace.txt” under citect\bin .
BATCHSLEEPTIME – This is the time each thread (one per unit) waits for ONS
requests to be collected. Thus is needed for 2 reasons, to give other units access to
ONS, and to allow requests to “batch” together.
POLLMSGSLEEPTIME – This time is the wait period to check on alarms coming
into the driver from ONS. If set too low, then CPU time will increase to the detriment
of normal driver operation.
ONSBATCHCOUNT – This is the value of the maximum count of ONS points to be
batched and sent to ONS. Experiments have shown that 32 or 64 are good values for
efficiency. NB: If TAG blocking is being used of INT data types, this value MUST
be a min. of 64.
OFFLINECHECKTIME – This is the time used to determine that a unit is the standby
unit. The logic uses the fact that no data requests have occurred in this time period.
This value can be made lower to improve the detection time of being the offline unit.
This is required to ensure correct handling of alarms. e.g. the active unit stores alarm
events and these are removed on a regular period by the alarm scan system. The
standby unit, is also storing these events. Once we know that the standby unit is a
standby unit, we can discard these events, because we don’t want repeats of events to
occur when the active unit switches to the standby unit.
2.3.102.3.12 Advanced
2.3.10.12.3.12.1 Driver generated statistics
Number
Label
© Copyright 2000 Ci Technologies
Description
Page: 24
Citect for Windows, V5.xx
1
2
3
4
API_THREADS
API_READ_COUNT
API_WRITE_COUNT
API_READ_FAIL
5
API_WRITE_FAIL
6
API_READ_MISMATCH
7
API_WRITE_MISMATCH
8
MSG_THREADS
9
MSG_RECEIVE_COUNT
10
MSG_RECEIVE_TIMEOUT
11
MSG_RECEIVE_ERROR
12
13
MSG_CACHE_SIZE
MSG_IMMEDIATE_READS
14
MSG_TTL_EXPIRED
15
MSG_CACHE_READ_COUNT
16
MSG_CACHE_RESET_COUNT
TONS driver
The number of threads launched to support Citect units
The number of read requests to the ONS API
The number of write requests to the ONS API
The number of read requests returned as errors by the
ONS API
The number of write requests returned as errors by the
ONS API
The number of read requests with bad data type
matches
The number of write requests with bad data type
matches
The number of threads launched to support message
processing
The number of messages successfully returned by the
ONS syste,.
The number of messages returned by the ONS system
as having timed out.
The number of messages returned by the ONS system
as having an error.
The number of IO points currently being cached.
The number of immediate reads issued by the driver
due to no valid data in the cache at that point.
The number of messages discarded after not being read
within the normal time-to-live.
The number of read requests serviced from the
message cache.
The number of writes to Message.Cache.Reset
received
Note that the statistics on the number of requests to the ONS API is based on the
number of DCB requests sent by Citect since a single DCB always translates to a
single batch command in the API.
2.3.12.2 Tag Error Handling
Because TONS can block (from Citect) as well as batch (to the API), this poses issues
for reporting problems. The logic is as follows :
- Report the first "point" (equivalent to Citect TAG) error to the user. When the block count is
one then no issue exists, if a block had 10 items , then the first errored item in the block is
reported. NB: Other errors may exist after this item.
- Report a ONS Batch error only if NO ONS point errors have occured previously. This will
occur for the last TAG of the batch,
- Both batch & point errors are reported in the tons_trace.txt file IF enabled. NB:
tons_trace.txt is a diagnostic tool, not an operational tool.
© Copyright 2000 Ci Technologies
Page: 25
Citect for Windows, V5.xx
TONS driver
2.3.10.22.3.12.3 Debug Messages Explained
The TONS driver does not generate physical channel traffic in the same way as serial
or TCP/IP drivers. Consequently, the debug messages generated by the driver relate
to the information passed to and received from the ONS API only.
Debug messages are enabled via the kernel using the debug <portname>
[all|error|write] command
The format of a debug message is as follows:
Ddd Mmm dd hh:nn:ss yyyy hh:nn:ss.uuu [READ|WRITE]
t:[D|I|R|L|S|B|?] a:xxxxxx c:xxxxxx w:xx e:xx [xxxxxx] ‘’
Length nn
<’tttt’ = vvvv>[…]
where
Ddd
Mmm
Dd
hh:mm:ss
Yyyy
hh:nn:ss.uuu
is the day of the week as a string
is the month of the year as a string
is the numerical day of the month
is the current time in hours:minutes:seconds
is the year in numeric format
is the uptime of the IO Server in
hours:minutes:seconds:msec
[READ|WRITE]
is the operation: read or write
t:[D|I|R|L|S|B|?] is the data type: Digital, Integer, Real, Long, String,
Byte or Unknown.
a:xxxxxx
is the UnitAddress in 6 digit hex format
c:xxxxxx
is the UnitCount in 6 digit hex format
w:xx
is the BitWidth in 2 digit hex format
e:xx
is the Element count
(BitWidth*UnitCount/RawBitWidth)
[xxxxxx]
is the index into the variable.dbf cache in 6 digit
hex format
‘tttt’
is the ONS tag name as a string
Nn
is the length of the ASCII debug data that follows
Vvvv
is the value being read or written
An example of a debug message is as follows:
Thu Apr 13 21:34:39 2000 53:29:44.924 READ
c:000010 w:01 e:01 [000008] ‘’ Length 22
<’PV1501.SCN’ = 0>
t:D a:000090
If the Citect request involves a blocked command, then several <’tttt’ = vvvv>
blocks will be displayed, as per the calculated Element count.
2.3.10.32.3.12.4 Error Messages Explained
The error message reporting system is used to format any errors detected by the
TONS driver into human-readable format.
© Copyright 2000 Ci Technologies
Page: 26
Citect for Windows, V5.xx
TONS driver
The format of an error message is as follows:
Ddd Mmm dd hh:nn:ss yyyy hh:nn:s s.uuu Error: Ssss
READ
nnnn
pppppp
uuuuuu
t:[D|I|R|L|S|B|?] a:xxxxxx c:xxxxxx w:xx e:xx [xxxxxx]
‘tttt’
Generic gggggg Driver dddddd (0xDDDDDDDD)
where
Ddd
Mmm
dd
hh:mm:ss
yyyy
hh:nn:ss.uuu
is the day of the week as a string
is the month of the year as a string
is the numerical day of the month
is the current time in hours:minutes:seconds
is the year in numeric format
is the uptime of the IO Server in
hours:minutes:seconds:msec
Ssss
is the error description as a string
nnnn
is the ???
pppppp
is the port name as a string
uuuuuu
is the unit name as a string
t:[D|I|R|L|S|B|?] is the data type: Digital, Integer, Real, Long, String,
Byte or Unknown.
a:xxxxxx
is the UnitAddress in 6 digit hex format
c:xxxxxx
is the UnitCount in 6 digit hex format
w:xx
is the BitWidth in 2 digit hex format
e:xx
is the Element count
(BitWidth*UnitCount/RawBitWidth)
[xxxxxx]
is the index into the variable.dbf cache in 6 digit
hex format
‘tttt’
is the ONS tag name as a string
gggggg
is the generic error value
dddddd
is the driver-specific error value in decimal format
DDDDDD
is the driver-specific value in 8 digit hex format
An example of a debug message is as follows:
Thu Apr 13 21:34:39 2000 53:29:44.924 Error: Unknown data
type
READ
0003
ONSAPIP
ONSAPI t:I a:000001
c:000002 w:08 e:0 [000001] ‘PV102.PV’
Generic 000003 Driver 00000258 (0x00000102)
Individual points within blocked command are not displayed in the error message,
however the driver-specific error code will indicate the cause of the error.
© Copyright 2000 Ci Technologies
Page: 27
Citect for Windows, V5.xx
TONS driver
3. Analysis
3.1 Overview
This section provides extended information on the ONS system, including a
breakdown of API anomalies encountered, expected usage and configuration
examples, and information on the TONS driver implementation.
3.2 Programming Reference
3.2.1 ONS API Functions Reference
3.2.1.1 dbaOpen(char* name)
• The function input parameter name should be a unique string identifying the
process requesting an ONS API handle. In the case of the TONS driver, the string
identifier is the concatenation of the IO server name and the unit name, e.g.
MYSERVER.MYUNIT.
• The dbaOpen() function must be called before any other ONS functions.
• The scope of the handle returned by the dbaOpen() function is valid within a
single thread only. The ONS API does not support multithreaded calls, and an
API handle should be used only within a single thread.
3.2.1.2 dbaPntFillEx(dbaPoint *dbapoint, char *tag_atom)
• The dbaPntFillEx() function is used in preference to the dbaPntFill()
function since it passes the responsibility of determining the element count and
starting element number to the ONS API. The Citect tag string address is passed
through directly as the tag_atom function input.
3.2.1.3 dbaCnt(dbaDesc dbaDesc, int action, char *name)
• The dbaCnt() function is used to control queuing of batch requests for the ONS
API. After calling dbaCnt(dbaDesc, dbaBATCH_START, name) , the
TONS driver will call dbaGet() or dbaPut() up to 32 times to queue a
number of individual requests as a single batch. Once all requests for that batch
have been queued, dbaCnt(dbaDesc, dbaBATCH_END, name) is called
to initiate processing of the batch. DbaCnt() returns only when the batch has
been completed.
• The status of the batch (return value from dbaCnt()) is examined in preference
to the status of any individual data points within the batch.
3.2.2 ONS API Usage Reference
3.2.2.1 Case Sensitivity
All ONS tag names are case sensitive, and may be a combination of both upper and
lower case characters.
Case must be preserved throughout the TONS driver, and the user must specify the
correct case in the Citect Tag Address field when configuring the Citect project, and
throughout any VARIABLE.DBF files.
© Copyright 2000 Ci Technologies
Page: 28
Citect for Windows, V5.xx
TONS driver
For example, if DPCS station 05 is available, the tag $C05.SST exists, as does
$C05.mod, however $C05.MOD will return the error D_ILLEGAL_ATOM.
3.2.2.2 Batch Requests and Citect Blocking
The ONS API supports batching of read or write requests, up to approximately 100
tag atoms (or 30kb of data). Mixing of read and write requests within the same batch
is not supported, and if a batch does contain both reads and writes, only the write
requests will be serviced.
The TONS driver supports blocked requests from Citect, however the blocking
facility has been currently disabled due to conflicts with the use of the %N compiler
option. Blocking is disabled by using the %R compiler option in TONS.DBF which
assigns a unique UnitType to each address.
Currently, if blocking is enabled, the use of the %N option causes Citect to make
incorrect BitWidth and UnitCount requests of the driver, leading to stability issues
and garbage read values. Once this issue is resolved, the %R option may be removed
from TONS.DBF and driver blocking safely re-enabled.
3.2.2.3 API Mutual Exclusivity
The ONS API does not support multithreaded access, but does support multiple
sessions from a single thread. To ensure that only one TONS driver thread at a time
accesses any ONS API function, a global critical section object is used to control
mutual exclusivity throughout the TONS DLL. Before any ONS API call, the critical
section is entered, and after the call, it is left. The overhead in using the critical
section is negligible.
The critical section must be initialised by the first CiAPIThread object created (in the
constructor) and deleted by the last CiAPIThread object destroyed (in the destructor).
A global reference counter is used to track the number of CiAPIThread objects
currently using the ONS API critical section.
3.2.3 Required Build Settings
These build settings apply to Microsoft Visual C++ 5.0 Service Pack 3 and 6.0
Service Pack 3.
3.2.3.1 C/C++ Issues
Although the ONS API supports C++, it is designed for use primarily under the C
language. The following requirements must be met when using the API under the
C++ environment.
• ONS.H forces the C++ operator class to be undefined, hence all C++ class
declarations must be included before the inclusion of ONS.H.
• In general, the include structure would look like the following:
#include “stdafx.h”
// Standard MFC class and helper fn declarations
#include “MyClasses.h”
// Include any common user-defined classes
#include “Project.h”
// Include any C++ declarations local to this project
#include <ONS.H>
// Include the ONS API header.
// Additional C++ declarations will be rejected from this point on.
#include “MyCDefs.h”
// Inclusion of any other C declarations is allowed
•
The __STDC__ preprocessor definition must be defined for the scope of the
ONS.H include file. __STDC__ is assigned the fixed value 1. The following
© Copyright 2000 Ci Technologies
Page: 29
Citect for Windows, V5.xx
TONS driver
text should appear around the #include <ons.h> statement:
// BEGIN ONS INCLUDES
#ifndef __STDC__
#define __STDC__ 1
#define TONS_STDC_UNDEF
#endif
#include <ons.h>
#ifdef TONS_STDC_UNDEF
#undef __STDC__
#endif
// END ONS INCLUDES
// The actual ONS.H header file include
3.2.3.2 Project Directories
The main ONS API header file ONS.H will look for the other API header files in the
standard include paths (i.e. using the #include <> notation as opposed to the
#include “” notation). The directory containing the ONS header files should be
added to the list of standard Visual C++ header paths.
The include directories can be set under the Tools | Options | Directories tab.
3.2.3.3 Library Includes
The following libraries should be specified under the Project | Settings | Link tab in
the Object/library modules field (replace release build libraries with debug libraries as
required for debug builds):
Library
Scanner.lib
Ctregion.lib
DB3UTILS.lib
RegChk32.lib
MFC42.LIB
MFCS42.LIB
MSVCRT.LIB
OLDNAMES.LIB
Libdba.lib
Libuti.lib
Libint.lib
Librep.lib
Libmem.lib
Libons.lib
Description
DDK 5.0 standard library
DDK 5.0 standard library
DDK 5.0 standard library
DDK 5.0 registration library
MFC 4.2 library
Static helper library
Multithread DLL link for MSVCRT.DLL
C Library Backward Compatibility
ONS API standard library
ONS API standard library
ONS API standard library
ONS API standard library
ONS API standard library
ONS API standard library
3.2.3.4 ONS.H Modifications
To eliminate a conflicting linkage specification problem under C++, Toshiba have
advised the following: “NWKSTD.H needs to be modified: comment out the 148th
line of NWKSTD.H 'int unlink(const char *f);' to resolve the problem.”
The function name ‘unlink’is declared in STDIO.H as
_CRTIMP int __cdecl unlink(const char *);
and in the ONS API as above, however using the ONS API under C++ requires all C
functions to be declared as extern “C”, thereby causing a linkage conflict.
The above modification has been performed for the TONS driver.
© Copyright 2000 Ci Technologies
Page: 30
Citect for Windows, V5.xx
TONS driver
3.3 Citect Tag Address Format Convention
The tag address specified in the Citect Variable Tag form corresponds to the string tag
name used by the ONS API. The possible formats of the string ONS tag are detailed
in the next section, and the Citect tag address should correspond to these formats.
Since the TONS driver supports standard Citect redundancy by automatically
updating the DPCS station number for System and Parameter tags, all System or
Parameter tag addresses declared in Citect should used a generic string, such as ‘xx’
in place of a physical station number, to indicate that the value will automatically be
overwritten by the driver.
For example, instead of specifying the System tag address $C05.SST[2],
VARIABLE.DBF should contain the generic form, $Cxx.SST[2]. The TONS driver
will always replace the characters in positions 3 and 4 (in this case “xx”) with the
station number extracted from the system or parameter tag specified in the IO Devices
form Address field.
3.4 System Tag Types
System tags provide direct access to information in ONS hardware, and tag names
uniquely identify a station number, a slot number and a data point. System tag names
always resolve to exactly one data point (and always the same data point), and the
naming convention for DPCS systems is set in the document 9B8C0661.
System tags do not need to be configured using the PCS-DS Engineering Tool (or
similar) before use, however attempting to access a tag that does not exist (e.g.
because the hardware does not exist) will return a “Tag Not Found” error.
3.4.1 General Tag Format
A system tag has the following fixed structure:
$C xx aaa bbb ccc ddd . atom [ m – n ]
Where
xx is the system number:
01 to 20 for the online system
81 to A0 for the standby system
aaa is the first class module name
bbb is the second class module name
ccc is the third class module name
ddd is the fourth class module name
atom is the atom name
m is the starting element for array access
n is the ending element for array access
A module name is always 3 characters long, including the “-“ character where
applicable.
3.4.2 Tag Bases
The following table lists the available system tag bases for DPCS systems and the
information they relate to.
Tag Base
© Copyright 2000 Ci Technologies
Relates to
Page: 31
Citect for Windows, V5.xx
$Cxx
$Cxxm11, $Cxxm13
$Cxxm18
$Cxxm11 to $Cxxm6a
$Cxxlcp
$Cxxecl
$Cxxegr
$Cxxmer
TONS driver
DPCS Status
Ethernet Interface Type
VSVPX1 Card Type
VSCPX2 Card Type
VACPX2 Card Type
VLCPXn Card Type
Digital I/O Card Type
Analog I/O Card Type
VBMPX1 Card Type
Power Supply Unit Card Type
VPCPX2 Card Type
One Loop Card Type
One Loop 213 Card Type
VLCPXn Backup Status
Client Communication Status
Controller Communication Status
MC Bus Error Counter
The list of corresponding tag atoms for these tag bases is defined in the document
9B8C0661, and is not repeated here.
3.5 Parameter Tag Types
Parameter tags provide access to user parameter tables, and are also accessed by
formatting a tag name that identifies an ONS station number, slot number and a data
point. Parameter tables are generally used as lookup tables for conversion processes
or as general user memory. The tag naming convention for DPCS systems is set by
the ONS protocol, in the document 9B8C0662.
System tags do not need to be configured using the PCS-DS Engineering Tool before
use, however attempting to access a tag that does not exist (e.g. because the hardware
does not exist) will return a “Tag Not Found” error.
3.5.1 General Tag Format
A parameter tag has the following fixed structure:
%c xx ppp ss ccc ddd . atom [ m – n ]
Where
c is a single-character type idenfitier (commonly capital “C”)
xx is the system number:
01 to 20 for the online system
81 to A0 for the standby system
ppp is the parameter type
ss is the slot number
ccc provides additional slot and card type information
ddd provides additional slot and card type information
atom is the atom name
m is the starting element for array access
n is the ending element for array access
© Copyright 2000 Ci Technologies
Page: 32
Citect for Windows, V5.xx
TONS driver
3.5.2 Tag Bases
The following table lists the available parameter tag bases for DPCS systems and the
information they relate to.
Tag Base
%Cxxrawnn
%Cxxdpcnn
%Cxxplymmn
%Cxxsadnn
%Cxxstmnn
%Cxxsctnn
%Cxxsifnn
%Cxxstbmmnn
%Cxxstbmmnnoopp
%Cxxanynn
Relates to
General raw data
DPCS data
Polynomial Line
Sensor Adjust
Sequence Timer
Sequence Counter
Sequence Internal Flag
Sequence Table
Sequence Table
Other general (free format) data
The list of corresponding tag atoms for these tag bases is defined in the document
9B8C0662, and is not repeated here.
3.6 Process Tag Types
Process tags provide access to physical I/O values, and are addressed by a userconfigured tag name. The ONS API allows any tag name to be used, and the Signal
List editor of the PCS-DS Engineering Tool (or similar) can be used to relate a tag
name with an ONS station, slot and I/O point. Although the ONS protocol allows
arbitrary tag names, the set of allowed tag atoms is fixed, as listed in the document
9B8C0604.
3.6.1 General Tag Format
A process tag has the following fixed structure:
xxxxxxxxxxxxxxxx . atom [ m – n ]
Where
xxxxxxxxxxxxxxxx is the tag base as defined in the PCS-DS Engineeing Tool
atom is the atom name
m is the starting element for array access
n is the ending element for array access
3.6.2 Process Tag Types
There are 12 distinct types of process tags, as per the table below:
Type number
210
211
212
220
221
222
240
230
231
Type name
INDd
PAd
PINd
PIDd
SPId
AOd
SQd
LP1d
LP2d
Type
Analog
Analog
Analog
Analog
Analog
Analog
Sequence
Digital
Digital
© Copyright 2000 Ci Technologies
Direction
Input
Input
Input
Output
Output
Output
Description
Interface Data
PID Loop
Sample PID Loop
Page: 33
Citect for Windows, V5.xx
232
233
234
DI7d
PB3d
PB5d
TONS driver
Digital
Digital
Digital
3.7 Message Tag Types
Message tags provide access to the information returned to the TONS driver through
unsolicited ONS message generated by hardware I/O devices.
Message tags are not recognised by the ONS protocol and are implemented only
within the TONS driver.
Because of the unsolicited nature of messages from ONS hardware, information about
a given message tag may not always have been received before a request for that tag’s
value is received from Citect. To overcome this, the format specification for message
tags allows the name of a normal ONS tag to be declared, as the tag to query for the
‘current’value of the message tag in this case.
Any normal ONS tags specified are queried at most once during a Citect session, and
the returned values are then held in the cache as the current message tag value. The
message tag value will then be updated by any new values received in messages for
that tag.
The TONS driver also implements a specific write-only tag at address
“Message.Cache.Reset” (case insensitive) that allows the entire message cache to be
flushed, thereby forcing all data to be re-requested from the field.
3.7.1 Message Tag Format
A message tag has the following structure:
^ xxxxxxxxxxxxxxxx . class . type . ext = tag . atom
Where
xxxxxxxxxxxxxxxx is a tag base
class is the ONS message class to query
type is the ONS message type to query
ext is a Process Tag atom or TONS-defined extension
tag.atom is any System, Parameter or Process tag + atom.
The combined ^xxxxxxxxxxxxxxxx.class.type.ext identifier is known as an alias for the
tag <tag_name>.
3.7.2 Message.Cache.Reset Tag Format
The special tag identifier Message.Cache.Reset represents a write-only tag
implemented by the TONS driver that allows the contents of the message cache to be
reset. Resetting the cache normally then forces data to be re-requested from the field
using the normal ONS tag specified as part of the message tag address.
The value written to this tag is not used.
The tag has the following structure:
Message.Cache.Reset
The tag name is not case sensitive.
© Copyright 2000 Ci Technologies
Page: 34
Citect for Windows, V5.xx
TONS driver
3.7.3 Message Tag Types
The following sections list the available TONS-defined message type identifiers and
the corresponding list of available atom names for each message class / type in the
ONS system. This information is mainly compiled from Toshiba document
8M8C0404 as applied to DPCS systems.
For example, section 3.7.4.1 indicates that the alias PV1501.PRO.CHG.ALIT[20] is
generated from ONS message class msgPRO_ALARM_CHANGE and ONS message
type msgPRO_CHANGE, from a change of state of bit number 20.
3.7.4 msgPRO_ALARM_CHANGE Message Class
Process Tag Alarm Change
3.7.4.1 msgPRO_CHANGE Message Type
TONS class.type:
PRO.CHG
The msgPRO_CHANGE message contains one or more bit change records.
ALIT[<bit#>] records are parsed for as many bit numbers as are in the message.
<bit#> is an integer between 0 and 31.
Msg Element Name
Msg Start Bytes
ALIT
STIT
FLIT
Bit change data
52
56
60
68+<bit#>*10
Msg
Byte
Count
4
4
4
2
TONS Ext
ONS Data
Type
Citect
Data Type
Common
Alias
ALIT
STIT
FLIT
ALIT[<bit#>]
D_LONG
D_LONG
D_LONG
D_BIT
LONG
LONG
LONG
DIGITAL
ALIT
STIT
FLIT
TONS Ext
ONS Data
Type
Citect
Data Type
Common
Alias
ALIT
STIT
FLIT
D_LONG
D_LONG
D_LONG
LONG
LONG
LONG
ALIT
STIT
FLIT
TONS Ext
ONS Data
Type
Citect
Data Type
Common
Alias
ALIT
STIT
FLIT
D_LONG
D_LONG
D_LONG
LONG
LONG
LONG
ALIT
STIT
FLIT
3.7.4.2 msgPRO_CNF Message Type
TONS class.type:
PRO.CNF
Msg Element Name
Msg Start Bytes
ALIT
STIT
FLIT
52
56
60
Msg
Byte
Count
4
4
4
3.7.4.3 msgPRO_LO Message Type
TONS class.type:
PRO.LO
Msg Element Name
Msg Start Bytes
ALIT
STIT
FLIT
52
56
60
Msg
Byte
Count
4
4
4
3.7.4.4 msgPRO_TAG_PARAM Message Type
TONS class.type:
PRO.PRMPRE
This message contains a variable byte count, as required by the data type associated
with the tag atom ‘<atom>’.
Msg Element Name
Before
Msg Start Bytes
Msg
Byte
Count
1
© Copyright 2000 Ci Technologies
TONS Ext
ONS Data
Type
Citect
Data Type
<atom>
D_BYTE
INT
Common
Alias
Page: 35
Citect for Windows, V5.xx
TONS driver
1
2
2
4
4
8
TONS class.type:
<atom>[<bit#>]
<atom>
<atom>[<bit#>]
<atom>
<atom>[<bit#>]
<atom>
D_BIT
D_SHORT
D_BIT
D_LONG
D_BIT
D_FLOAT
DIGITAL
INT
DIGITAL
INT
DIGITAL
REAL
PRO.PRMPOST
This message contains a variable byte count, as required by the data type associated
with the tag atom ‘<atom>’.
Msg Element Name
Msg Start Bytes
After
Msg
Byte
Count
1
1
2
2
4
4
8
TONS Ext
ONS Data
Type
Citect
Data Type
<atom>
<atom>[<bit#>]
<atom>
<atom>[<bit#>]
<atom>
<atom>[<bit#>]
<atom>
D_BYTE
D_BIT
D_SHORT
D_BIT
D_LONG
D_BIT
D_FLOAT
INT
DIGITAL
INT
DIGITAL
INT
DIGITAL
REAL
TONS Ext
ONS Data
Type
Citect
Data Type
DIPRE
DIPOST
DOPRE
DOPOST
D_SHORT
D_SHORT
D_SHORT
D_SHORT
INT
INT
INT
INT
Common
Alias
3.7.4.5 msgPRO_DI_DO Message Type
TONS class.type:
PRO.DIO
Msg Element Name
Msg Start Bytes
DI before
DI after
DO before
DO after
52
54
56
58
Msg
Byte
Count
2
2
2
2
Common
Alias
3.7.4.6 msgPRO_COND_CHANGE Message Type
TONS class.type:
PRO.CC
Msg Element Name
Msg Start Bytes
ALIT
STIT
FLIT
52
56
60
Msg
Byte
Count
4
4
4
TONS Ext
ONS Data
Type
Citect
Data Type
ALIT
STIT
FLIT
D_LONG
D_LONG
D_LONG
LONG
LONG
LONG
TONS Ext
ONS Data
Type
Citect
Data Type
FO[<FO#>]
D_BYTE
INT
Common
Alias
3.7.4.7 msgPRO_FO_REQ Message Type
TONS class.type:
PRO.FO
<FO#> is an integer between 0 and 7
Msg Element Name
Msg Start Bytes
FO[<FO#>]
52+<FO#>
Msg
Byte
Count
1
Common
Alias
3.7.5 msgSYS_ALARM_CHANGE
System Tag Alarm Change
3.7.5.1 msgSYS_CHANGE Message Type
TONS class.type:
SYS.CHG
© Copyright 2000 Ci Technologies
Page: 36
Citect for Windows, V5.xx
TONS driver
Msg Element Name
Msg Start Bytes
ALIT
STIT
FLIT
Bit change data
52
56
60
68+<bit#>*24
Msg
Byte
Count
4
4
4
2
TONS Ext
ONS Data
Type
Citect
Data Type
ALIT
STIT
FLIT
ALIT[<bit#>]
D_LONG
D_LONG
D_LONG
D_BIT
LONG
LONG
LONG
DIGITAL
ONS Data
Type
Citect
Data Type
Common
Alias
3.7.5.2 msgSYS_CNF Message Type
TONS class.type:
SYS.CNF
Not implemented.
Msg Element Name
Msg Start Bytes
Msg
Byte
Count
TONS Ext
Common
Alias
3.7.5.3 msgSYS_TAG_PARAM Message Type
TONS class.type:
SYS.PRMPRE
This message contains a variable byte count, as required by the data type associated
with the tag atom ‘<atom>’.
Msg Element Name
Msg Start Bytes
Before
TONS class.type:
Msg
Byte
Count
1
1
2
2
4
4
8
TONS Ext
ONS Data
Type
Citect
Data Type
<atom>
<atom>[<bit#>]
<atom>
<atom>[<bit#>]
<atom>
<atom>[<bit#>]
<atom>
D_BYTE
D_BIT
D_SHORT
D_BIT
D_LONG
D_BIT
D_FLOAT
INT
DIGITAL
INT
DIGITAL
INT
DIGITAL
REAL
Common
Alias
SYS.PRMPOST
This message contains a variable byte count, as required by the data type associated
with the tag atom ‘<atom>’.
Msg Element Name
Msg Start Bytes
After
Msg
Byte
Count
1
1
2
2
4
4
8
TONS Ext
ONS Data
Type
Citect
Data Type
<atom>
<atom>[<bit#>]
<atom>
<atom>[<bit#>]
<atom>
<atom>[<bit#>]
<atom>
D_BYTE
D_BIT
D_SHORT
D_BIT
D_LONG
D_BIT
D_FLOAT
INT
DIGITAL
INT
DIGITAL
INT
DIGITAL
REAL
Common
Alias
3.7.5.4 msgSYS_COND_CHANGE Message Type
TONS class.type:
SYS.CC
Not implemented.
Msg Element Name
Msg Start Bytes
Msg
Byte
Count
© Copyright 2000 Ci Technologies
TONS Ext
ONS Data
Type
Citect
Data Type
Common
Alias
Page: 37
Citect for Windows, V5.xx
TONS driver
3.7.5.5 msgSYS_DO_REQ Message Type
TONS class.type:
SYS.DOR
Not implemented.
Msg Element Name
Msg Start Bytes
Msg
Byte
Count
TONS Ext
ONS Data
Type
Citect
Data Type
Common
Alias
ONS Data
Type
Citect
Data Type
Common
Alias
ONS Data
Type
Citect
Data Type
Common
Alias
Citect
Data Type
Common
Alias
Citect
Data Type
Common
Alias
3.7.5.6 msgSYS_DI_CHANGE Message Type
TONS class.type:
SYS.DIC
Not implemented.
Msg Element Name
Msg Start Bytes
Msg
Byte
Count
TONS Ext
3.7.5.7 msgSYS_DI_DO Message Type
TONS class.type:
SYS.DIO
Not implemented.
Msg Element Name
Msg Start Bytes
Msg
Byte
Count
TONS Ext
3.7.5.8 msgSYS_DUP_ALARM Message Type
TONS class.type:
SYS.DUP
Not implemented.
Msg Element Name
Msg Start Bytes
Msg
Byte
Count
TONS Ext
ONS Data
Type
3.7.5.9 msgSYS_STATUS_CHANGE Message Type
TONS class.type:
SYS.SS
Not implemented.
Msg Element Name
Msg Start Bytes
Msg
Byte
Count
TONS Ext
ONS Data
Type
3.7.6 msgPRM_ALARM_CHANGE
Parameter Tag Alarm Change
3.7.6.1 msgPRM_TAG_PARAM Message Type
TONS class.type:
PRM.PRMPRE
© Copyright 2000 Ci Technologies
Page: 38
Citect for Windows, V5.xx
TONS driver
Not implemented.
Msg Element Name
Msg Start Bytes
TONS class.type:
Msg
Byte
Count
TONS Ext
ONS Data
Type
Citect
Data Type
Common
Alias
ONS Data
Type
Citect
Data Type
Common
Alias
Citect
Data Type
Common
Alias
Citect
Data Type
Common
Alias
PRM.PRMPOST
Not implemented.
Msg Element Name
Msg Start Bytes
Msg
Byte
Count
TONS Ext
3.7.7 msgEVT_SYSTEM_EVENT
3.7.7.1 msgEVT_SE_NODE_DOWN Message Type
TONS class.type:
EVT_ND
Not implemented.
Msg Element Name
Msg Start Bytes
Msg
Byte
Count
TONS Ext
ONS Data
Type
3.7.7.2 msgEVT_SE_NODE_UP Message Type
TONS class.type:
EVT_NU
Not implemented.
Msg Element Name
Msg Start Bytes
Msg
Byte
Count
TONS Ext
ONS Data
Type
3.8 Tag Address Format Specification
3.8.1 Compiler File Specification
The Citect compiler file TONS.DBF file (also known generically as ‘DRIVER’.DBF)
indicates to the compiler how to convert Citect tag string addresses into the integer
UnitAddress and UnitType values that will be sent to the TONS driver at runtime.
Normally a target device, such as a PLC has a well-defined memory map, often with
many elements of the same type arranged consecutively in a block of memory. In this
case UnitType would be used to indicate which block of memory is being referred to,
and UnitAddress would serve as an index into that block.
In the case of the TONS driver, the tag addresses used with the ONS API are in string
format, hence it is not appropriate to encode string information from
VARIABLE.DBF into integer UnitType and UnitAddress values. Instead, the %N
compiler option is used to provide the TONS driver with a logical index into
VARIABLE.DBF at runtime, via UnitAddress, which the driver then uses to retrieve
the original string tag address specified by the user.
© Copyright 2000 Ci Technologies
Page: 39
Citect for Windows, V5.xx
TONS driver
3.8.1.1 Compiler Data Type Conversion
When the %N compiler option is used, all Citect tag addresses are compiled in the
same way, and if TONS.DBF contained only one record, all Citect tags would have to
compile to the same raw Citect data type. To overcome this, the Citect compiler
provides a degree of type matching during compilation, where the Citect tag data type
is best-fit matched against the list of available driver formats (given that all
TONS.DBF tag address formats are identical).
For this conversion, the TONS.DBF file must define the list of supported data types in
the order (first record to last record) that gives the desired type matching order during
compilation. In general, TONS.DBF specifies types in ascending order of data size,
with the exception that STRING appears before BYTE to avoid being compiled as an
array of bytes.
The data type order has been established as RDT_DIGITAL, RDT_STRING,
RDT_BYTE, RDT_INTEGER, RDT_LONG and RDT_REAL.
3.8.1.2 Citect Blocking
Based on the assumption that most PLCs uses memory maps that have contiguous
blocks of same-type data, Citect blocks read and write requests based on UnitType
similarity. For example UnitAddresses 1 and 10 for UnitType 1 would best be read in
a block of 16, starting from the 0th element. Citect would translate this as a UnitType
of 1, a UnitAddress of 0 and a UnitCount of 16.
Digital tag type blocking also presents an additional problem, since Citect will never
request (under any circumstances!) just a single bit of data, and will generally block
digital types together in groups of 16. To solve this problem, all digital
UnitAddresses are multiplied by 16 so that each digital request lies on a 16-bit
boundary. To retrieve the original digital address, the UnitAddress is divided by 16.
To service a blocked request the driver translates the number of IO points requested
by Citect into a list of dbaPoint structures which will be sent to the ONS API using
the dbaCnt() and dbaPut() or dbaGet() functions.
The actual number of IO points requested can be calculated as:
IO Points = BitWidth * Un itCount / RawBitWidth
where RawBitWidth is determined by the RawType value, and represents the
number of bits in the raw data type.
All requests queued for servicing by the driver’s back-end threads are packaged into a
single ONSDCB structure. The ONSDCB structure encapsulates the original CTDCB,
an array of dbaPoint structures representing the batched request, a write data buffer
and various other status values.
Because the memory map of each UnitType is not contiguous7, a Citect request for
3 consecutive addresses may translate into only two dbaPoint requests, if the data
type of the tag at the middle address does not match the raw data type of the original
Citect request.
7
To put this another way, the %N compiler option means that the UnitAddress
determines the UnitType. Even if addresses 0x0002 and 0x0004 are INTEGERs,
address 0x0003 is not necessarily an integer, since UnitAddresses are only indexes
into VARIABLE.DBF.
© Copyright 2000 Ci Technologies
Page: 40
Citect for Windows, V5.xx
TONS driver
For example, if the first and third tags declared in a Citect project are of type LONG,
and the second is of type DIGITAL, then if blocking is enabled, Citect would request
both LONG addresses in a single blocked request by setting RawType = RDT_LONG,
BitWidth = 16 and UnitCount = 6 (equivalent to 3 LONGs). In preparing the
ONSDCB structure with its linked list of dbaPoint structures, the TONS driver would
verify that the type of each ONS tag address retrieved from the VARIABLE.DBF
cache matched the RawType value specified by Citect. If the types did not match,
then the corresponding dbaPoint structure would be marked as invalid by setting the
tag name to "". The driver back end would then skip over any invalid dbaPoints,
and would consequently make only 2 requests to the ONS API. The value returned to
Citect in place of any invalid addresses is always 0.
This strategy is safe since, as in the above example, the LONG value returned for
address 2 would never be used. If the tag at address 2 is used on a Citect graphics
page, it would be requested in a separate block of DIGITALs starting at address 2.
3.8.1.3 Data Type Matching Examples
Reading a BYTE as a BYTE:
• For an ONS tag called “TEST” configured as an INDd type (process tag), the tag
atom “SNO” (slot number) could have a value of 14.
• “TEST.SNO” would therefore be read using the ONS API as atom type
D_U_BYTE (unsigned byte), atom size 1 and atom array length 1. The value read
would be 14.
• A Citect tag could be configured to read this data by specifying data type BYTE
and Citect tag address “TEST.SNO”.
• If this were the 6th tag declared in the project, the Citect compiler would then
compile it as UnitType 0x08000006, UnitAddress 0x00000006 and UnitCount 1.
• The data type matching table indicates a D_U_BYTE can be read as an
RDT_BYTE, and the read request would succeed.
Reading a DIGITAL as a LONG:
• For an ONS tag called “TEST” configured as an INDd type (process tag), the tag
atom “PVI” could have a value of 1.
• “TEST.PVI” would therefor be read using the ONS API as atom type D_BIT
(digital), atom size 1 and atom array length 1. The value read would be 1.
• A Citect tag could be configured to read this data by specifying data type LONG
and Citect tag address “TEST.PVI”.
• If this was the 23rd tag declared in the project, the Citect compiler would then
compile it as UnitType 0x04000017, UnitAddress 0x00000017 and UnitCount 1.
• The data type matching table indicates a D_BIT can be read as an RDT_LONG,
and the read request would succeed.
3.8.2 Include Projects
The TONS driver makes provision for Citect INCLUDE projects when caching
VARIABLE.DBF information, and caches tags sequentially, starting with the current
project, and then processing any included projects recursively.
© Copyright 2000 Ci Technologies
Page: 41
Citect for Windows, V5.xx
TONS driver
Include projects should not be used with the TONS driver however, since the %N
compiler option does not provide unique UnitAddress values across Include projects,
and the first tag in each project is always currently assigned UnitAddress 1.
This issue is currently under review, and support for Include projects will be available
once it is resolved.
All TONS driver tags should currently be placed in a single Citect project, and always
in the top-level Citect project.
3.8.3 ONS Array Support
A single ONS tag/atom can actually stand for an array of values. For example,
$C01.SST actually returns 3 elements, for the 3 realtime clocks in the VETHX1 card.
To access arrays in the ONS system, the ‘[]’ operator is used. For example,
$C01.SST[0] stands for the first clock value, and $C01.SST[1-2] stands for the last
two clock values.
The TONS driver does not currently support retrieval of ONS arrays, and each Citect
tag should resolve to a single ONS datapoint. If the tag does resolve to an array, the
TONS driver will return the value of the first element in the array only.
3.9 Driver Specific Errors
Driver Driver Error Label
Error
0x100 DRIVER_API_UNAVAILABLE
0x101
0x102
0x200
0x201
0x202
0x203
0x204
0x205
0x206
0x207
0x300
0x400
Mapped to
(Generic Error label)
GENERIC_SOFTWARE_ERROR
Meaning of Error Code
The Toshiba ONS API is not installed or is
unavailable.
Check the ONS driver
configuration.
DRIVER_CANNOT_READ_VARIABLE_DBF GENERIC_GENERAL_ERROR
One or more VARIABLE.DBF files could
not be read. Check that all files exist and
that no files are locked.
DRIVER_DATA_TYPE_MISMATCH
GENERIC_INVALID_DATA_TYPE
A data type mismatch was detected
between the Citect tag data type and the
data type of the ONS tag specified in the
address field.
DRIVER_TAG_NOT_FOUND
GENERIC_ADDRESS_RANGE_ERROR The ONS tag specified in the Citect tag
address field does not exist. Check for
mismatched case.
DRIVER_ILLEGAL_ATOM
GENERIC_ADDRESS_RANGE_ERROR The ONS atom specified in the Citect tag
address field does not exist for the
specified tag.
DRIVER_SECURITY_VIOLATION
GENERIC_ACCESS_VIOLATION
The ONS tag specified in the Citect tag
address field has already been deleted.
DRIVER_ILLEGAL_TAG_ATOM
GENERIC_INVALID_DATA_FORMAT
The ONS atom specified in the Citect tag
address field is badly formatted.
DRIVER_BAD_ACCESS_VERSION
GENERIC_ACCESS_VOILATION
Dualised switching occurred during
processing of the ONS request.
DRIVER_MODULE_NOT_FOUND
GENERIC_ADDRESS_RANGE_ERROR The specified tag has been deleted
DRIVER_BATCH_FAIL
GENERIC_GENERAL_ERROR
Abnormal batch termination
DRIVER_BATCH_PARTIAL_FAIL
GENERIC_GENERAL_ERROR
Abnormal batch termination with tag
DRIVER_POINT_ERROR
GENERIC_GENERAL_ERROR
Base value for other (undocumented)
point errors
DRIVER_BATCH_ERROR
GENERIC_GENERAL_ERROR
Base value for other (undocumented)
batch errors
3.10 Driver Error Help
[Contents of the PROTERR.DBF file.
completed, after testing.]
© Copyright 2000 Ci Technologies
To be defined after the table above is
Page: 42
Citect for Windows, V5.xx
TONS driver
3.11 Driver Implementation Notes
3.11.1 OIS TCP/IP Configuration for Redundancy
TCP/IP configuration of the Citect IO server with redundant VETHX1 cards has
proven problematic. This section details some of the problems encountered and their
solution.
To communicate successfully with a pair of VETHX1 cards in the same chassis, the
Citect IO server must have two separate ethernet cards installed. A single ethernet
card with a multihomed configuration has proven unsuccessful for communication on
the 172.16.128.0 network. The issue appears to arise out of a requirement that the
ONS API transmit on both the 172.16.64.0 and 172.16.128.0 networks simultaneously
for systems utilising both the A and B bus (hence the requirement that both ports on a
VETHX1 card operate at the same speed, such that the EM1 and EM2 LEDs do not
flicker).
Furthermore, if one card does have a multihomed configuration (say on the 10.0.0.0
and 172.16.64.0 networks), the binding order of the IP addresses is of importance, and
the 172.16.64.0 network (or 172.16.128.0) must appear first.
The following checklist should assist in configuring a redundant OIS:
• The OIS must have two separate network cards installed. The cards must be
configured to operate at the same speed (10 or 100 mbit).
• Each card must be bound to the 172.16.64.0 or 172.16.128.0 network IP
addresses first, in cases where the cards are multihomed.
• Both ethernet ports on each VETHX1 card must be connected, and configured
to operate at the same speed (10 or 100 mbit).
• The primary VETHX1 card must be configured to HLT on comms failure via
the jumper pins. The standby VETHX1 card must be configured to RTY on
comms failure via the jumper pins.
• The primary and standby VETHX1 cards must be configured as DUAL cards
via the jumper pins.
• The OIS PCMP service must be configured as a Dual station, specifying the
OIS IP address on the 172.16.64.0 network.
• The TOSDIC-CIE DS system must be configured to use Ethernet Double (A,
B bus) LAN form, under the Engineering Menu application File | Open
System List menu.
• The System Configuration must specify Station Type (CTYP) DPCS Duplex,
and must specify both primary and secondary IP addresses (IPPR and IPSD)
3.11.2 Online / Offline conditions
The selection of appropriate conditions to place an IO device online or offline is
critical to the success of Citect’s redundancy changeover.
The following methodology is used:
1. An IO device is initially put online if the tag specified in the Citect IO Devices
form Address field can be successfully retrieved. This tag is known as the
‘online test’tag.
2. An error returned through a single ONS tag is not considered sufficient to
place an IO device offline.
3. If an error is encountered in a batched ONS operation, the online test tag must
be immediately tested.
© Copyright 2000 Ci Technologies
Page: 43
Citect for Windows, V5.xx
TONS driver
4. If the online test tag can be retrieved, then the Citect request is returned with
an appropriate error code, but the unit remains online.
5. If the online test tag cannot be retrieved, then the unit is immediately placed
offline.
3.11.3 Watchdog Timeout
The standard watchdog timeout of 30000ms is increased to 40000ms since the ONS
API timeout is 30s on communications failure.
Since all calls to the ONS API are blocking functions, the driver cannot control or
detect timeouts occurring behind the API. On communication failure, a call to
dbaGet(), dbaPut() or dbaCnt() will block for up to 30 seconds. The
increased Citect watchdog timer timeout of 40s will correctly prevent “PLC Server
Request timeout from I/O Server” hardware alarms.
3.11.4 Thread Synchronisation
A FIFO queue paradigm is used for passing information from the driver’s front-end
thread to the back-end thread, with all access to the queue structures synchronised by
a critical section object. The critical section synchronisation ensures the integrity of
the queue pointers at all times.
An important feature of Citect’s design that is exploited by the driver is that the
Reply() function can be safely called from within any thread. Any DCB requests
requiring calls to the ONS API will be replied-to from within the back-end thread.
All other DCB requests will be replied-to immediately from within the front-end
thread.
3.11.5 Data Type Mapping and Precedence
The ONS system supports a number of distinct data types for different I/O points that
must be mapped to appropriate Citect data types in order to be read or written. For
each ONS data type, the following table lists both the Win 32 C data type (used for
internal storage in the driver), and the smallest Citect data type that can be used to
represent the data.
The table also lists all data type precedence supported by the TONS driver. Data type
precedence allows the same ONS data type to be retrieved through several Citect data
types, providing that the cast type (Citect type) is larger than the ONS type.
For example, a BIT type can be retrieved as a DIGITAL, BYTE, SHORT, INTEGER
or LONG data type, however a LONG data type cannot be retrieved as a BYTE
without unacceptable loss of information. In the above, a DIGITAL type precedes a
BYTE type, and the BYTE, SHORT, INTEGER and LONG types are known as
antecedent types.
Data type precedence is not supported between array and non-array types. For
example, a BIT[] type cannot be retrieved as BIT, and a STRING type cannot be
retrieved as a LONG, etc.
Data type precedence is a function of the TONS driver, and cannot be pre-determined
since the Citect tag address fields are not parsed in advance. A decision on data type
precedence is made by the driver only after the Citect tag string address is retrieved
and the ONS API queried for type information on the tag. Once this has been done,
the ONS data type can be compared with the Citect data type, and a precedence
decision made.
© Copyright 2000 Ci Technologies
Page: 44
Citect for Windows, V5.xx
TONS driver
The first Citect data type shown below is the best-fit data type and any antecedent
types are shown after in italics.
ONS Data Type
Win32 C Type Cast
D_NOTYPE
UNDEFINED
D_BIT
char
D_BITS
char*
D_BYTE
char
D_BYTES
char*
D_U_BYTE
unsigned char
D_U_BYTES
unsigned char*
D_SHORT
short
D_SHORTS
short*
D_U_SHORT
unsigned short
D_U_SHORTS
unsigned short*
D_LONG
D_LONGS
D_U_LONG
D_U_LONGS
D_FLOAT
D_FLOATS
D_DOUBLE
D_DOUBLES
D_TEXT
D_TEXTS
D_STRING
D_STRINGS
D_BIT8
int
int*
unsigned int
unsigned int*
float
float*
double
double*
char*
char**
char*
char**
unsigned char
D_BIT8S
D_BIT16
unsigned char*
unsigned short
D_BIT16S
D_BIT32
unsigned short*
unsigned long
© Copyright 2000 Ci Technologies
Citect Data Type
(Antecedent Type)
RDT_DIGITAL
RDT_BYTE
RDT_INTEGER
RDT_LONG
RDT_DIGITAL[]
RDT_BYTE[]
RDT_INTEGER[]
RDT_LONG[]
RDT_BYTE
RDT_INTEGER
RDT_LONG
RDT_BYTE[]
RDT_INTEGER[]
RDT_LONG[]
RDT_BYTE
RDT_INTEGER
RDT_LONG
RDT_BYTE[]
RDT_INTEGER[]
RDT_LONG[]
RDT_INTEGER
RDT_LONG
RDT_INTEGER[]
RDT_LONG[]
RDT_INTEGER
RDT_LONG
RDT_INTEGER[]
RDT_LONG[]
RDT_LONG
RDT_LONG[]
RDT_LONG
RDT_LONG[]
RDT_REAL
RDT_REAL[]
RDT_REAL
RDT_REAL[]
RDT_STRING
RDT_STRING[]
RDT_STRING
RDT_STRING[]
RDT_BYTE
RDT_INTEGER
RDT_LONG
RDT_BYTE[]
RDT_INTEGER
RDT_LONG
RDT_INTEGER[]
RDT_LONG
Description / Special Usage /
Limitations / Valid Ranges
Caution: Loss of sign
Caution: Loss of sign
Page: 45
Citect for Windows, V5.xx
TONS driver
D_BIT32S
D_TIME
unsigned long*
unsigned long
D_TIMES
unsigned long*
RDT_LONG[]
RDT_LONG
RDT_STRING8
RDT_LONG[]
RDT_STRING[]6
As seconds elapsed since 1/1/70
As a formatted string
As seconds elapsed since 1/1/70
As a formatted string
3.11.6 PROTDIR.DBF
TAG
FILE
BIT_BLOCK MAX_LENGTH OPTIONS
TONS TONS 1024
1024
0x0cf
Options 0x0cF indicates:
OPT_DIGITAL
OPT_INTEGER
OPT_STRING
OPT_LONG
OPT_REAL
OPT_BYTE
0x0001
0x0002
0x0004
0x0008
0x0040
0x0080
3.11.7 TONS.DBF
The %! compiler option indicates that the rest of the address field should be ignored.
This is added as a safety precaution to prevent the Citect compiler from matching any
characters after the %N%R specifiers.
TEMPLATE
%N%R%!%!%!
%N%R%!%!%!
%N%R%!%!%!
%N%R%!%!%!
%N%R%!%!%!
%N%R%!%!%!
UNIT_TYPE
0x07000000
0x08000000
0x10000000
0x01000000
0x04000000
0x02000000
RAW_TYPE
7
8
10
1
4
2
BIT_WIDTH LOW HIGH COMMENT
1024
RDT_STRING[16]
8
RDT_BYTE
16
RDT_UINTEGER
16
RDT_INTEGER
32
RDT_LONG
32
RDT_REAL
3.11.8 Distribution Files
The following table lists the distribution files for the TONS driver:
Filename
TONS.DLL
DB3UTILS.DLL
TONS.DBF
PROTDIR.DBF
CTREGION.DLL
Description
The Toshiba ONS Driver
DBaseIII Access Routines
TONS Driver Compiler Specification
Modified PROTDIR.DBF Protocol Listing
Standard Citect Library
3.12 Development resources
3.12.1 Contacts
Ian Emmett
Senior Engineer
Process Control Department
8
When retrieving a D_TIME or D_TIMES type as a string (or array of strings), the
data is returned in the format “Friday, 24th March 2000 16:00:00”
© Copyright 2000 Ci Technologies
Page: 46
Citect for Windows, V5.xx
TONS driver
Toshiba International Corp. Pty. Ltd.
2 Morton St
Parramatta NSW 2150
Ph (02) 9768-6612
Fax (02) 9890-7542
Mobile 0419 414 066
Email [email protected]
Michael Preston
Manager
Automation Division
Toshiba International Corp. Pty. Ltd.
2 Morton St
Parramatta NSW 2150
Ph (02) 9768-6633
Fax (02) 9890-7542
Mobile 0419 296 846
Email [email protected]
3.12.2 Documents
1. Toshiba Integrated Control System TOSDIC-CIE DS Communication Control
Card VETHX1 Instruction Manual 6F8C0789, First Edition, June 1999
2.
Toshiba Integrated Control System TOSDIC-CIE DS Open Network Service
Support Package for PC Instruction Manual 6F8C0793, First Edition, July
1999
3.
CIEMAC-DS DPCS Parameter Tag Data
9B8C0662, Rev 2, 24/6/98 (Japanese version)
4.
CIEMAC-DS DPCS System Tag Data Structure Specification, 9B8C0661,
Rev 7, 14/7/99 (Japanese version)
5.
CIEMAC-DS DPCS Process Tag Data Structure Specification, 9B8C0604,
Rev 8, 7/9/99 (Japanese version)
Structure
Specification
3.13 Risk areas
The development of the TONS driver has been staged, with the initial phase used to
identify any potential risk areas, and resolve them before designing or implementing
the driver. The primary tool for investigating and resolving risk areas has been a
console application known as TAGREAD, developed jointly between Toshiba and
CiT. The built version, TR.EXE, wrappers calls to the ONS API and allows the
tag_atom parameter sent to the dbaPntFillEx() function to be specified via a
command line. The values returned by the API are then output to the standard output.
Array types are supported. This utility has been used to eliminate the risk associated
with most development areas by resolving issues up front.
The remaining areas of risk have been identified as:
• Driver performance. The current methodology of no blocking and no batching
may incur performance issues in large systems. Current testing has indicated
© Copyright 2000 Ci Technologies
Page: 47
Citect for Windows, V5.xx
TONS driver
however that the approach has little impact on network bandwidth or CPU usage
on a Citect I/O server.
• Citect Include projects. The implications of Citect include projects on retrieving
Citect tag string addresses has not been fully resolved, however no particular
problems are anticipated.
3.14 Development plan
Description
Target
Completion
Date9
Person
Date
Completed
0.1
The ONS API software drivers and development kit are obtained from Toshiba
10/12/99
AP
10/12/99
0.2
The ONS API documentation is obtained from Toshiba
10/12/99
AP
10/12/99
0.2
Download to a target device via the Engineering Tool is successfully tested
13/12/99
IE/AP
24/1/00
0.3
Communication with a target device via the API is successfully tested
13/12/00
IE/AP
27/1/00
At this checkpoint the driver development is ready to be commenced
1.1
The setup procedure, target device, driver operation and development schedule are
defined in the driver spec.
10/2/00
AP
6/2/00
1.2
The tag format specification is defined in the driver spec
25/3/00
AP
25/3/00
1.3
The Citect interface and setup is defined in the driver spec
13/3/00
AP
24/3/00
1.4
The testing procedures are defined in the driver spec
20/3/00
AP
27/3/00
1.5
Hold point for customer review
20/3/00
AP
24/3/00
1.6
The specification is reviewed and accepted by CiT Driver Development
27/3/00
SJ
7/4/00
At this checkpoint the driver coding is ready to be commenced
2.1
The driver framework is written with the Citect DDK 5.0
23/2/00
AP
29/2/00
2.2
Communication with a target device via the driver is successfully tested
29/2/00
AP
2/3/00
2.3
The Citect compiler files are completed
27/3/00
AP
25/3/00
2.4
Driver coding is completed
3/4/00
AP
26/4/00
2.5
Hold point for customer review
5/5/00
IE
21/6/00
2.6
Code and specification reviewed and accepted by CiT Driver Development
10/5/00
SJ, PG, BL,
AM, MP, AP
21/6/00
At this checkpoint the driver is completed and testing may be commenced
3.1
Accreditation testing is completed
24/5/00
AP
21/6/00
3.2
Specification and documentation updated from testing results
26/5/00
AP
21/6/00
The driver is now finished and fully accredited
9
The target completion dates shown are guidelines only and may change subject to
approval.
© Copyright 2000 Ci Technologies
Page: 48
Citect for Windows, V5.xx
TONS driver
4. Testing Release 1.0.00.26
The programmer will perform a minimum level of testing that is outlined here.
A sample Project is available which can be used as a starting point for the
programmer’s test Project. When the programmer has completed basic testing and
debugging this Project should be backed up and supplied to the Citect Testing
department.
4.1 Procedure
The following are points that should be covered by basic testing.
• On startup the IO Device comes online without errors.
• The driver reports the IO Device offline when the IO Device is a) powered down,
b) disconnected. Redundant comms path testing must be included.
• The driver will re-establish communication with the IO Device after a) power
•
•
•
•
•
•
•
cycle, b) disconnection/ reconnection. Redundant comms path testing should be
included.
Confirm that retries (if supported) and error reporting operate correctly.
Confirm errors reported by the ONS API are reported correctly to Citect
Confirm that data type mismatches are reported correctly to Citect
The driver reads all the device data types documented as readable in this
specification.
The driver writes to all the device data types documented as write-able in this
specification.
Let the driver run over night and check that no retries or other errors have
occurred.
If hardware is available then the protocol should be tested with more than one IO
Device connected.
4.2 Results
The following tests were performed in accordance with the testing procedure
documented in section 4.1.
4.2.1 Test Conditions
The test equipment used was as follows:
• Windows NT Server 4.0 Service Pack 6a
2x 10/100bT ethernet cards
Citect 5.21 Rev. 00 Service Pack D Release 1
TONS Driver 1.00.00 Build 26, based on:
CTREGION.DLL 5.21.00 for Service Pack D
DB3UTILS.DLL 1.03.01.000
• TOSDIC CIE-DS DPCS Chassis
Slot 11
VETHX1 Duplex
Slot 13
VETHX1 Duplex
Slot 16
VLCPX2
Slot 19
VPWSX32
• Bay Networks NetGear DS108 8 port Dual Speed Ethernet hub
• 5x UTP CAT5 ethernet cables
© Copyright 2000 Ci Technologies
Page: 49
Citect for Windows, V5.xx
TONS driver
The Citect I/O Server TCP/IP settings were configured as follows:
IP Address 1: 172.16.64.2 subnet 255.255.192.0
IP Address 2: 172.16.128.2 subnet 255.255.192.0
PCMP
at address 172.16.64.2, configured for Dual support
The DPCS VETHX1 card TCP/IP settings were configured as follows:
Slot 11
Station 0x05, IP address 172.16.64.5 (A), 172.16.128.5 (B)
Slot 13
Station 0x25, IP address 172.16.64.37 (A), 172.16.128.37 (B)
The network configuration diagram is shown below:
Hub
:
172.16.64.2
ONS LAN A
172.16.128.2
ONS LAN B
172.16.64.5 172.16.64.37
172.16.128.5 172.16.128.37
VETHX1 VETHX1
Slot 11 Slot 13
(Primary) (Standby)
DPCS Station
All tests were performed with the release build (Public build) of the driver DLL,
unless debugging required the temporary use of a debug build. After debugging, the
driver was re-built as release before continuing testing.
The test Citect project used had the following configuration:
IO Servers:
Name
“PRIMARY”
Boards:
Name / Server
Type
Address / Port / Interrupt
“ONSB1” / PRIMARY
TONS
0 / Blank / Blank
Name / Server
Type
Address / Port / Interrupt
“ONSB2” / PRIMARY
TONS
0 / Blank / Blank
Ports
Name / Number / Server
Board
Baud / Bits / Stop / Parity
Options
“ONSP1” / 1 / PRIMARY
ONSB1
Blank / Blank / Blank / Blank
Blank
Name / Number / Server
Board
“ONSP2” / 2 / PRIMARY
ONSB2
© Copyright 2000 Ci Technologies
Page: 50
Citect for Windows, V5.xx
TONS driver
Baud / Bits / Stop / Parity
Options
Blank / Blank / Blank / Blank
Blank
IO Devices
Name / Number / Server
Address
Protocol
Port
“DPCS1” / 1 / PRIMARY
$C05.SST[0]
TONS
ONSP1
Name / Number / Server
Address
Protocol
Port
“DPCS2” / 2 / PRIMARY
$C05.SST[2]
TONS
ONSP2
Note that both IO devices are configured to use the same DPCS chassis, however the
use of different addresses allows testing of Citect redundancy features.
4.2.2 Citect Startup Testing
Launch Citect and check for initialisation errors. Repeat several times.
• With the unit connected, both IO devices were observed to come online
immediately, without error.
• With the unit disconnected, both IO devices returned “NO DATA” when
reading the online status tag at startup and both IO devices were placed offline
immediately. When the unit was reconnected, communication resumed at the
next IO device reconnect attempt.
4.2.3 Communication Failure Testing
Remove all ethernet connections, observe offline status, reconnect ethernet, observe
online status. Repeat several times.
• Both IO devices were observed to go offline simultaneously after a 30 second
timeout.
• After going offline, both IO devices were observed to attempt reconnection to
the unit every 30 seconds.
• All reconnect attempts failed until ethernet was reconnected.
• Once ethernet was reconnected, normal communication resumed at the next IO
device reconnect attempt.
Power down the unit, observe offline status, power up the unit, observe online status.
Repeat several times.
• Both IO devices were observed to go offline simultaneously after a 30 second
timeout.
• After going offline, both IO devices were observed to attempt reconnection to
the unit every 30 seconds.
• All reconnect attempts failed until power was restored to the unit, and the
VETHX1 cards had completed initialisation.
• Once the VETHX1 cards finished initialisation, normal communication
resumed at the next IO device reconnect attempt.
© Copyright 2000 Ci Technologies
Page: 51
Citect for Windows, V5.xx
TONS driver
4.2.4 Redundancy Testing
Start with all units online, all ethernet connections in place.
Remove primary bus A ethernet. Observe redundancy changeover to primary bus B
Remove primary bus B ethernet. Observe redundancy changeover to standby bus A
Remove standby bus A ethernet. Observe redundancy changeover to standby bus B
Remove standby bus B ethernet. Observe communication failure.
Replace standby bus A ethernet. Observe communication recovery.
Replace primary bus A and B ethernet. Communication should not switch to primary
card.
Cycle primary card power. Primary card should enter standby mode.
Switch off standby card. Communication should recover to primary card.
• Communication was established normally with primary card stand-by LED
extinguished, and standby card stand-by LED lit. Communication was
observed simultaneously on bus A and B of the primary card. No
communication on the standby card was observed.
• With primary bus A ethernet removed communication with the primary card
continued uninterrupted, with no pause.
• With primary bus B ethernet removed, Citect communication paused for
around 30 seconds before both units went offline. The primary card was then
observed to switch out of RUN mode a short time after, with both ALM-E and
ALM-M LEDs lit.
• On the next connect attempt both units were observed to go online again,
communicating with the standby card simultaneously on bus A and B.
• With standby bus A ethernet removed, communication with the standby card
continued uninterrupted, with no pause.
• With standby bus B ethernet removed, Citect communication paused for
around 30 seconds before both units went offline.
With
standby bus A ethernet replaced, communication was observed to resume
•
on the next connect attempt.
• With primary bus A and B ethernet replaced, communication with the primary
card was not observed to resume.
• After primary card power was cycled, the primary card was observed to enter
standby mode, with no initial communication. Communication to the primary
card (in standby mode) was not observer to recover automatically.
• After standby card power was removed, the primary card was immediately
observed to leave standby mode. Citect communication paused for around 30
seconds before both units went offline, and communication resumed on the
next connect attempt.
• After standby card power was reconnected, the standby card was observed to
enter standby mode again.
• This test was repeated 3 times.
4.2.5 Error Reporting Testing
Error
DRIVER_API_UNAVAILABLE
DRIVER_CANNOT_READ_VARIABLE_DBF
DRIVER_DATA_TYPE_MISMATCH
DRIVER_TAG_NOT_FOUND
© Copyright 2000 Ci Technologies
Passed / Failed
Passed
Passed
Passed
Passed
Page: 52
Citect for Windows, V5.xx
TONS driver
DRIVER_ILLEGAL_ATOM
DRIVER_SECURITY_VIOLATION
DRIVER_ILLEGAL_TAG_ATOM
DRIVER_BAD_ACCESS_VERSION
DRIVER_MODULE_NOT_FOUND
DRIVER_BATCH_FAIL
DRIVER_PARTIAL_BATCH_FAIL
DRIVER_POINT_ERROR
DRIVER_BATCH_ERROR
Passed
Could not generate this error
Could not generate this error
Could not generate this error
Passed
Could not generate this error
Could not generate this error
Passed
Passed
4.2.6 Data Type Read / Write Testing
The following data types were tested:
Type
Passed / Failed
DIGITAL
Passed
BYTE
Passed
INT
Passed
LONG
Passed
REAL
Passed
STRING
Passed
4.2.7 Data Type Matching Testing
The following data type matches were tested:
ONS Type
Citect Type
Expected as
Tested as
Passed / Failed
D_BIT
RDT_DIGITAL
RDT_BYTE
RDT_INTEGER
RDT_LONG
RDT_REAL
RDT_STRING
RDT_DIGITAL
RDT_BYTE
RDT_INTEGER
RDT_LONG
RDT_REAL
RDT_STRING
RDT_DIGITAL
RDT_BYTE
RDT_INTEGER
RDT_LONG
RDT_REAL
RDT_STRING
RDT_DIGITAL
RDT_BYTE
RDT_INTEGER
RDT_LONG
RDT_REAL
RDT_STRING
RDT_DIGITAL
RDT_BYTE
RDT_INTEGER
RDT_LONG
RDT_REAL
RDT_STRING
OK
OK
OK
OK
ERROR
ERROR
ERROR
OK
OK
OK
ERROR
ERROR
ERROR
OK
OK
OK
ERROR
ERROR
ERROR
ERROR
OK
OK
ERROR
ERROR
ERROR
ERROR
OK
OK
ERROR
ERROR
OK
OK
OK
OK
OK
ERROR
ERROR
OK
OK
OK
OK
ERROR
ERROR
OK
OK
OK
OK
ERROR
ERROR
ERROR
OK
OK
OK
ERROR
ERROR
ERROR
OK
OK
OK
ERROR
Passed
Passed
Passed
Passed
Accepted
Passed
Passed
Passed
Passed
Passed
Accepted
Passed
Passed
Passed
Passed
Passed
Accepted
Passed
Passed
Passed
Passed
Passed
Accepted
Passed
Passed
Passed
Passed
Passed
Accepted
Passed
D_BYTE
D_U_BYTE
D_SHORT
D_U_SHORT
© Copyright 2000 Ci Technologies
Page: 53
Citect for Windows, V5.xx
D_LONG
D_U_LONG
D_FLOAT
D_DOUBLE
D_TEXT
D_STRING
D_BIT8
D_BIT16
D_BIT32
D_TIME
RDT_DIGITAL
RDT_BYTE
RDT_INTEGER
RDT_LONG
RDT_REAL
RDT_STRING
RDT_DIGITAL
RDT_BYTE
RDT_INTEGER
RDT_LONG
RDT_REAL
RDT_STRING
RDT_DIGITAL
RDT_BYTE
RDT_INTEGER
RDT_LONG
RDT_REAL
RDT_STRING
RDT_DIGITAL
RDT_BYTE
RDT_INTEGER
RDT_LONG
RDT_REAL
RDT_STRING
RDT_DIGITAL
RDT_BYTE
RDT_INTEGER
RDT_LONG
RDT_REAL
RDT_STRING
RDT_DIGITAL
RDT_BYTE
RDT_INTEGER
RDT_LONG
RDT_REAL
RDT_STRING
RDT_DIGITAL
RDT_BYTE
RDT_INTEGER
RDT_LONG
RDT_REAL
RDT_STRING
RDT_DIGITAL
RDT_BYTE
RDT_INTEGER
RDT_LONG
RDT_REAL
RDT_STRING
RDT_DIGITAL
RDT_BYTE
RDT_INTEGER
RDT_LONG
RDT_REAL
RDT_STRING
RDT_DIGITAL
RDT_BYTE
RDT_INTEGER
RDT_LONG
RDT_REAL
RDT_STRING
© Copyright 2000 Ci Technologies
TONS driver
ERROR
ERROR
ERROR
OK
ERROR
ERROR
ERROR
ERROR
ERROR
OK
ERROR
ERROR
ERROR
ERROR
ERROR
ERROR
OK
ERROR
ERROR
ERROR
ERROR
ERROR
OK
ERROR
ERROR
ERROR
ERROR
ERROR
ERROR
OK
ERROR
ERROR
ERROR
ERROR
ERROR
OK
ERROR
OK
OK
OK
ERROR
ERROR
ERROR
ERROR
OK
OK
ERROR
ERROR
ERROR
ERROR
ERROR
OK
ERROR
ERROR
ERROR
ERROR
ERROR
OK
ERROR
OK
ERROR
ERROR
ERROR
OK
ERROR
ERROR
ERROR
ERROR
ERROR
OK
ERROR
ERROR
ERROR
ERROR
ERROR
ERROR
OK
ERROR
ERROR
ERROR
ERROR
ERROR
OK
ERROR
ERROR
ERROR
ERROR
ERROR
ERROR
OK
ERROR
ERROR
ERROR
ERROR
ERROR
OK
ERROR
OK
OK
OK
OK
ERROR
ERROR
ERROR
OK
OK
OK
ERROR
ERROR
ERROR
ERROR
OK
ERROR
ERROR
ERROR
ERROR
ERROR
OK
ERROR
OK
Passed
Passed
Passed
Passed
Passed
Passed
Passed
Passed
Passed
Passed
Passed
Passed
Passed
Passed
Passed
Passed
Passed
Passed
Passed
Passed
Passed
Passed
Passed
Passed
Passed
Passed
Passed
Passed
Passed
Passed
Passed
Passed
Passed
Passed
Passed
Passed
Passed
Passed
Passed
Passed
Accepted
Passed
Passed
Passed
Passed
Passed
Accepted
Passed
Passed
Passed
Passed
Passed
Passed
Passed
Passed
Passed
Passed
Passed
Passed
Passed
Page: 54
Citect for Windows, V5.xx
TONS driver
4.2.8 Soak Testing
Run the driver for 8 hours, monitoring stability and memory usage.
• Soak test passed successfully. No memory leaks detected.
4.2.9 Multiple Unit Tests
Configure 2 Citect units on different channels and on the same channel and verify
startup / shutdown procedures and driver operation with multiple units.
• Driver passed startup, shutdown and read / write procedures successfully with
2 units on the same channel.
• Driver passed startup, shutdown and read / write procedures successfully with
2 units on separate channels.
4.3 Performance Testing
4.3.1 Introduction
The following are tests that give some indication of the driver’s performance. The
programmer needs to perform these tests since the results feed back into the Constants
structure and the PROTDIR.DBF.
4.3.2 Calculating the Blocking Constant
The Performance test procedure is documented in the driver development kit in
Appendix A, ‘Calculating the Block Constant’. The results of the performance test are
recorded here.
The blocking constant performance tests were not conducted for the TONS driver
since the %R compiler option forces each tag to have a unique UnitType. Blocking is
therefore disabled in the TONS driver.
Block size to read
Average response time
[bits]
[mS]
1
{25% of maximum}
256
{50% of maximum}
512
{75% of maximum}
768
{maximum}
1024
From these results the overhead and rate are determined and the ideal blocking
constant is calculated
Overhead [mS]
=
Word Rate [words / mS]
=
© Copyright 2000 Ci Technologies
Page: 55
Citect for Windows, V5.xx
Blocking constant [words]
TONS driver
=
Note that the calculated blocking constant must now be set by the programmer in the
Constants structure (the Block field) in bytes and in the PROTDIR.DBF (the
BIT_BLOCK field) in bits.
4.3.3 Max Pending Calculation
The number of outstanding requests allowed by the TONS driver should be varied in
the range 2 to 32 (32 being the maximum number of requests supported in a single
batch by the ONS API), and the value corresponding to the maximum data throughput
with no appreciable extra CPU load chosen.
MaxPending
1
2
4
8
16
24
32
Average response time
0.066s
0.106s
0.180s
0.281s
0.300s
0.296s
0.302s
Physical reads per second
14
16
17
17
17
16
16
A MaxPending value of 4 is seen as the best compromise between response time and
reads per second.
5. Testing Release 1.0.01.09
Following testing of TONS driver release 1.0.00.26, a number of modifications were
made to improve driver performance and solve additional ONS API issues. This
section documents the re-testing performed as part of issuing release 1.0.01.09.
5.1 Procedure
The following are points that should be covered by basic testing.
• On startup the IO Device comes online without errors.
• The driver reports the IO Device offline when the IO Device is a) powered down,
b) disconnected.
• The driver will re-establish communication with the IO Device after a) power
cycle, b) disconnection/ reconnection.
• Let the driver run over night and check that no retries or other errors have
occurred.
5.2 Results
The following tests were performed in accordance with the testing procedure
documented in section 4.1.
5.2.1 Test Conditions
The test equipment used was the same as for section 4.2.1, with the exception that the
TONS Driver version was 1.00.01 Build 9.
All tests were performed with the release build (Public build) of the driver DLL
© Copyright 2000 Ci Technologies
Page: 56
Citect for Windows, V5.xx
TONS driver
5.2.2 Citect Startup Testing
Launch Citect and check for initialisation errors. Repeat several times.
• With the unit connected, both IO devices were observed to come online
immediately, without error.
• With the unit disconnected, both IO devices returned “NO DATA” when
reading the online status tag at startup and both IO devices were placed offline
immediately. When the unit was reconnected, communication resumed at the
next IO device reconnect attempt.
5.2.3 Communication Failure Testing
Remove all ethernet connections, observe offline status, reconnect ethernet, observe
online status. Repeat several times.
• Both IO devices were observed to go offline simultaneously after a 30 second
timeout.
• After going offline, both IO devices were observed to attempt reconnection to
the unit every 30 seconds.
• All reconnect attempts failed until ethernet was reconnected.
• Once ethernet was reconnected, normal communication resumed at the next IO
device reconnect attempt.
Power down the unit, observe offline status, power up the unit, observe online status.
Repeat several times.
• Both IO devices were observed to go offline simultaneously after a 30 second
timeout.
• After going offline, both IO devices were observed to attempt reconnection to
the unit every 30 seconds.
• All reconnect attempts failed until power was restored to the unit, and the
VETHX1 cards had completed initialisation.
• Once the VETHX1 cards finished initialisation, normal communication
resumed at the next IO device reconnect attempt.
5.2.4 Soak Testing
Run the driver for 8 hours, monitoring stability and memory usage.
• Soak test passed successfully. No memory leaks detected.
5.3 Performance Testing
5.3.1 Introduction
The following are tests repeat the testing performed in section 4.3 for the modified
driver batching mode.
5.3.2 Max Pending Calculation
The number of outstanding requests allowed by the TONS driver should be varied in
the range 2 to 32 (32 being the maximum number of requests supported in a single
batch by the ONS API), and the value corresponding to the maximum data throughput
with no appreciable extra CPU load chosen.
Note that the TONS driver batch size limit was set to the same value as MaxPending.
MaxPending
Average response time
© Copyright 2000 Ci Technologies
Physical reads per second
Page: 57
Citect for Windows, V5.xx
4
8
16
24
32
48
64
128
192
0.051s
0.056s
0.051s
0.048s
0.044s
0.048s
0.050s
0.055s
0.048s
TONS driver
76
120
190
259
278
280
273
265
270
A MaxPending value of 32 is seen as the best compromise between response time and
reads per second.
© Copyright 2000 Ci Technologies
Page: 58