Citect For Windows, Version 5.xx TONS Driver, User Information and Design

Citect for Windows, Version 5.
xx
TONS driver, User information and design
Citect for Windows, V5.xx TONS driver
Driver version history
Version Modified By Details

1.00 Andrew Peterson Original, including accreditation testing
1.01 Andrew Peterson Added Release 1.0.01.09 testing section
1.02 Andrew Peterson Updated after CiT Review
2.00 Andrew Peterson Driver modified to support ONS Messages
2.01 Andrew Peterson Updated to support S3 PLC. Added documentation
for message support.
2.02 Greg Roberts 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

Contents
1. GENERAL .........................................................................................................6
1.1 ABBREVIATIONS.............................................................................................6
1.2 OVERVIEW .....................................................................................................6
1.3 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.2 Tag Bases .........................................................................................3330
3.6 PROCESS TAG TYPES ................................................................................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

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

5.3 PERFORMANCE TESTING ...........................................................................5754

5.3.1 Introduction ......................................................................................5754
5.3.2 Max Pending Calculation..................................................................5754

1. General
1.1 Abbreviations
API Application Programming Interface
DCB Driver Control Block. The internal data structure used by a Citect
I/O server when communicating with drivers.
DDK Driver Development Kit
DLL Dynamic Link Library
DPCS Distributed Process Control Station
LAN Local Area Network
MFC Microsoft Foundation Class libraries (Win32 C++ object libraries)
NIC Network Interface Card
OIS Operator Interface Station
ONS Toshiba’s Open Network Service
PCMP Toshiba’s Process Control Message Protocol
TONS The Citect driver (DLL and compiler files) for Toshiba’s ONS
WAN 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

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.

2. User information
2.1 Application notes for Device VETHX1
Property Detail
Manufacturer Toshiba Corporation
Device name Communication Control Card VETHX1 for TOSDIC-CIE DS
Comms method 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.

DPCS Station number 14

Slot 11 VETHX1 Bus A 172.16.64.14
Slot 11 VETHX1 Bus B 172.16.128.14
Slot 13 VETHX1 Bus A 172.16.64.46
Slot 13 VETHX1 Bus B 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 Hub
ethernet LAN
DPCS stations
(1 VETHX1 card per station)
2.1.2.3 Single Controller, Multiple DPCS Stations, Ethernet Redundancy


Standard Ethernet
Cards supporting
TCP/IP
:
10bT or 100bT Hub 1 Hub 2
ONS LAN 1
10bT or 100bT
ONS LAN 2
DPCS stations
(2 VETHX1 cards per station)
2.1.2.4 Multiple Controllers, Multiple DPCS Stations, Full Redundancy

:
Hub 3 10bT or 100bT
ONS LAN 1
OIS OIS 1 10bT or 100bT

LAN ONS LAN 2
:
Hub 1 Hub 2
10bT or 100bT
ONS LAN 1
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:

Hub A Hub B
: 172.16.64.1
172.16.128.1
ONS LAN A
ONS LAN B
172.16.64.10 172.16.64.42
172.16.128.10 172.16.128.42
VETHX1 VETHX1
Slot 11 Slot 13
(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.

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.

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

- 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

• 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.
• 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 ‘.’.

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 user-
configured 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 Detail
Driver name TONS
Maximum array size2 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’

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:

2.3.3 Driver Methodology

The ONS API operates in the same manner as the back-end portion of a front-
end/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 32-
bit 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.

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.

Board Name This field is user defined, and is not used by the driver.
Board Type TONS TONS
Address 0 0
I/O Port Blank Not used, any value
Interrupt Blank Not used, any value
Special Opt Blank Not used, any value
Comment This field is user defined and is not used by the driver.
Ports form
Port Name This field is user defined and is not used by the driver.
Port number User defined Any value
Board name Refers to the board previously defined in ‘boards’form.
Baud rate Blank Not used, any value
Data bits Blank Not used, any value
Stop bits Blank Not used, any value
Parity Blank Not used, any value
Special Opt Blank Not used, any value
NB: This driver has a maximum port support count of 32.
I/O Devices form

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

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 Equivalent Citect Data Type

D_NOTYPE (NONE)
UNDEFINED
D_BIT RDT_DIGITAL
RDT_BYTE
RDT_INTEGER
RDT_LONG
D_BITS RDT_DIGITAL[]
RDT_BYTE[]
RDT_INTEGER[]
RDT_LONG[]
D_BYTE RDT_BYTE
RDT_INTEGER
RDT_LONG
D_BYTES RDT_BYTE[]
RDT_INTEGER[]
RDT_LONG[]
D_U_BYTE RDT_BYTE
RDT_INTEGER
RDT_LONG
D_U_BYTES RDT_BYTE[]
RDT_INTEGER[]
RDT_LONG[]
D_SHORT RDT_INTEGER
RDT_LONG
D_SHORTS RDT_INTEGER[]
RDT_LONG[]
D_U_SHORT RDT_INTEGER
RDT_LONG
D_U_SHORTS RDT_INTEGER[]
RDT_LONG[]
D_LONG RDT_LONG
D_LONGS RDT_LONG[]
D_U_LONG RDT_LONG
D_U_LONGS RDT_LONG[]
D_FLOAT RDT_REAL
D_FLOATS RDT_REAL[]
D_DOUBLE RDT_REAL
D_DOUBLES RDT_REAL[]
D_TEXT RDT_STRING

D_TEXTS RDT_STRING[]
D_STRING RDT_STRING
D_STRINGS RDT_STRING[]
D_BIT8 RDT_BYTE
RDT_INTEGER
RDT_LONG
D_BIT8S RDT_BYTE[]
D_BIT16 RDT_INTEGER
RDT_LONG
D_BIT16S RDT_INTEGER[]
D_BIT32 RDT_LONG
D_BIT32S RDT_LONG[]
D_TIME RDT_LONG
RDT_STRING6
D_TIMES RDT_LONG[]
RDT_STRING[]6
Special Polynomial Line Support Tags
Device Data Citect Address Citect R/W Description/Special

Description Format Data Usage/Limitations
Types
Supported
Name of basethe POLYTAG STRING RW Must specify a complete,
polyline tag used valid ONS tag/atom.
for the block read
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 POLYVARx REAL RW A POLYOP read
from 0 to 25 (26 operation is needed
items) before this data can be
read, and a POLYOP
write operation is needed
to set data
POLYOP Read / Write Values Summary
Operation Value Description

Write -1 Read polyline data (from POLYTAG into POLVARx vars)
Write 0 Reset local polyline data (POLYVARx) to 0.0
Write 1 Write polyline data (from POLYVARx vars to POLYTAG)
Write <other> Error. POLYOP read value will be set to 1.
Read 0 No error / Success
Read 1 An invalid value was written to POLYOP
Read 2 A polyline read operation failed
Read 3 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”

Read 4 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 ¦

POLYTAG ¦0x0F000001 ¦ 7¦1024¦ ¦ ¦Basename of polytag ¦

POLYOP ¦0x0F000002 ¦ 1 ¦ 16¦ ¦ ¦Operation ¦
POLYVAR%U(0,0,25)%*64 ¦0x0F000003 ¦ 2¦ 32¦ ¦ ¦Special write only ¦
%N+%R%*16%!%!%! ¦0x00000000 ¦ 0¦ 1¦ ¦ ¦RDT_DIGITAL ¦
^^%N+%!%!%! ¦0x09000000 ¦ 4¦ 32¦ ¦ ¦RDT_LONG, alarms ¦
^^%N+%!%!%! ¦0x09000001 ¦ 1¦ 16¦ ¦ ¦RDT_INTEGER,alarms ¦
%N+%R%!%!%! ¦0x0A000000 ¦ 7¦1024¦ ¦ ¦RDT_STRING ¦
%N+%R%!%!%! ¦0x0B000000 ¦ 8¦ 8¦ ¦ ¦RDT_BYTE ¦
%N+%R%!%!%! ¦0x0C000000 ¦ 1¦ 16¦ ¦ ¦RDT_INTEGER ¦
%N+%R%!%!%! ¦0x0D000000 ¦ 4¦ 32¦ ¦ ¦RDT_LONG ¦
%N+%R%!%!%! ¦0x0E000000 ¦ 2¦ 32¦ ¦ ¦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 Allowable values
Block (bytes) 2 2 (don’t change)
Delay (mS) 0 0 (not used)
MaxPending 32 1 to 32
Polltime (mS) 0 0 (not used)
Timeout (mS) 1000 1000 (not used)
Retry 1 1 (not used)
WatchTime (Sec) 30 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

There are currently no driver-specific parameters.
Other Parameters
[LAN]Timeout 40000 40000
[TONS]Checkallt 0 0 or 1
ags
[TONS]Trace 0 0, 1 or 2
[TONS] 10 10 to 999 ms
Batchsleeptime

[TONS] 200 10 to 9999 ms

Pollmsgsleeptime
[TONS] 32 1 to 256
Onsbatchcount
[TONS]Offlinech 10000 100 to 100000 ms
eck
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 Description

1 API_THREADS The number of threads launched to support Citect units

2 API_READ_COUNT The number of read requests to the ONS API
3 API_WRITE_COUNT The number of write requests to the ONS API
4 API_READ_FAIL The number of read requests returned as errors by the
ONS API
5 API_WRITE_FAIL The number of write requests returned as errors by the
ONS API
6 API_READ_MISMATCH The number of read requests with bad data type
matches
7 API_WRITE_MISMATCH The number of write requests with bad data type
matches
8 MSG_THREADS The number of threads launched to support message
processing
9 MSG_RECEIVE_COUNT The number of messages successfully returned by the
ONS syste,.
10 MSG_RECEIVE_TIMEOUT The number of messages returned by the ONS system
as having timed out.
11 MSG_RECEIVE_ERROR The number of messages returned by the ONS system
as having an error.
12 MSG_CACHE_SIZE The number of IO points currently being cached.
13 MSG_IMMEDIATE_READS The number of immediate reads issued by the driver
due to no valid data in the cache at that point.
14 MSG_TTL_EXPIRED The number of messages discarded after not being read
within the normal time-to-live.
15 MSG_CACHE_READ_COUNT The number of read requests serviced from the
message cache.
16 MSG_CACHE_RESET_COUNT 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.

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 is the day of the week as a string
Mmm is the month of the year as a string
Dd is the numerical day of the month
hh:mm:ss is the current time in hours:minutes:seconds
Yyyy is the year in numeric format
hh:nn:ss.uuu 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 t:D a:000090

c:000010 w:01 e:01 [000008] ‘’ Length 22
<’PV1501.SCN’ = 0>
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.

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 is the day of the week as a string
Mmm is the month of the year as a string
dd is the numerical day of the month
hh:mm:ss is the current time in hours:minutes:seconds
yyyy is the year in numeric format
hh:nn:ss.uuu 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.

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.

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

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> // The actual ONS.H header file include
#ifdef TONS_STDC_UNDEF
#undef __STDC__
#endif
// END ONS INCLUDES
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 Description
Scanner.lib DDK 5.0 standard library
Ctregion.lib DDK 5.0 standard library
DB3UTILS.lib DDK 5.0 standard library
RegChk32.lib DDK 5.0 registration library
MFC42.LIB MFC 4.2 library
MFCS42.LIB Static helper library
MSVCRT.LIB Multithread DLL link for MSVCRT.DLL
OLDNAMES.LIB C Library Backward Compatibility
Libdba.lib ONS API standard library
Libuti.lib ONS API standard library
Libint.lib ONS API standard library
Librep.lib ONS API standard library
Libmem.lib ONS API standard library
Libons.lib 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.

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 Relates to

$Cxx DPCS Status

$Cxxm11, $Cxxm13 Ethernet Interface Type
$Cxxm18 VSVPX1 Card Type
$Cxxm11 to $Cxxm6a 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
$Cxxlcp VLCPXn Backup Status
$Cxxecl Client Communication Status
$Cxxegr Controller Communication Status
$Cxxmer 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.

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

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 Relates to

%Cxxrawnn General raw data
%Cxxdpcnn DPCS data
%Cxxplymmn Polynomial Line
%Cxxsadnn Sensor Adjust
%Cxxstmnn Sequence Timer
%Cxxsctnn Sequence Counter
%Cxxsifnn Sequence Internal Flag
%Cxxstbmmnn Sequence Table
%Cxxstbmmnnoopp Sequence Table
%Cxxanynn 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 user-
configured 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.

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
3.6.2 Process Tag Types

There are 12 distinct types of process tags, as per the table below:
Type number Type name Type Direction Description

210 INDd Analog Input Interface Data
211 PAd Analog Input
212 PINd Analog Input
220 PIDd Analog Output PID Loop
221 SPId Analog Output Sample PID Loop
222 AOd Analog Output
240 SQd Sequence
230 LP1d Digital
231 LP2d Digital

232 DI7d Digital

233 PB3d Digital
234 PB5d 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.

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 Msg TONS Ext ONS Data Citect Common
Byte Type Data Type Alias
Count
ALIT 52 4 ALIT D_LONG LONG ALIT
STIT 56 4 STIT D_LONG LONG STIT
FLIT 60 4 FLIT D_LONG LONG FLIT
Bit change data 68+<bit#>*10 2 ALIT[<bit#>] D_BIT DIGITAL
3.7.4.2 msgPRO_CNF Message Type

TONS class.type: PRO.CNF
Count
3.7.4.3 msgPRO_LO Message Type

TONS class.type: PRO.LO
Count
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>’.
Count
Before 1 <atom> D_BYTE INT

1 <atom>[<bit#>] D_BIT DIGITAL

2 <atom> D_SHORT INT
4 <atom> D_LONG INT
8 <atom> D_FLOAT REAL
TONS class.type: PRO.PRMPOST
Count
After 1 <atom> D_BYTE INT
4 <atom> D_LONG INT
3.7.4.5 msgPRO_DI_DO Message Type

TONS class.type: PRO.DIO
Count
DI before 52 2 DIPRE D_SHORT INT
DI after 54 2 DIPOST D_SHORT INT
DO before 56 2 DOPRE D_SHORT INT
DO after 58 2 DOPOST D_SHORT INT
3.7.4.6 msgPRO_COND_CHANGE Message Type

TONS class.type: PRO.CC
Count
ALIT 52 4 ALIT D_LONG LONG
STIT 56 4 STIT D_LONG LONG
FLIT 60 4 FLIT D_LONG LONG
3.7.4.7 msgPRO_FO_REQ Message Type

TONS class.type: PRO.FO
<FO#> is an integer between 0 and 7
Count
FO[<FO#>] 52+<FO#> 1 FO[<FO#>] D_BYTE INT
3.7.5 msgSYS_ALARM_CHANGE
System Tag Alarm Change
3.7.5.1 msgSYS_CHANGE Message Type

TONS class.type: SYS.CHG

Count
ALIT 52 4 ALIT D_LONG LONG
STIT 56 4 STIT D_LONG LONG
FLIT 60 4 FLIT D_LONG LONG
Bit change data 68+<bit#>*24 2 ALIT[<bit#>] D_BIT DIGITAL
3.7.5.2 msgSYS_CNF Message Type

TONS class.type: SYS.CNF
Not implemented.
Count
3.7.5.3 msgSYS_TAG_PARAM Message Type

TONS class.type: SYS.PRMPRE
Count
Before 1 <atom> D_BYTE INT
4 <atom> D_LONG INT
TONS class.type: SYS.PRMPOST
Count
After 1 <atom> D_BYTE INT
4 <atom> D_LONG INT
3.7.5.4 msgSYS_COND_CHANGE Message Type

TONS class.type: SYS.CC
Not implemented.
Count

3.7.5.5 msgSYS_DO_REQ Message Type

TONS class.type: SYS.DOR
Not implemented.
Count
3.7.5.6 msgSYS_DI_CHANGE Message Type

TONS class.type: SYS.DIC
Not implemented.
Count
3.7.5.7 msgSYS_DI_DO Message Type

TONS class.type: SYS.DIO
Not implemented.
Count
3.7.5.8 msgSYS_DUP_ALARM Message Type

TONS class.type: SYS.DUP
Not implemented.
Count
3.7.5.9 msgSYS_STATUS_CHANGE Message Type

TONS class.type: SYS.SS
Not implemented.
Count
3.7.6 msgPRM_ALARM_CHANGE
Parameter Tag Alarm Change
3.7.6.1 msgPRM_TAG_PARAM Message Type

TONS class.type: PRM.PRMPRE

Not implemented.
Count
TONS class.type: PRM.PRMPOST
Not implemented.
Count
3.7.7 msgEVT_SYSTEM_EVENT
3.7.7.1 msgEVT_SE_NODE_DOWN Message Type

TONS class.type: EVT_ND
Not implemented.
Count
3.7.7.2 msgEVT_SE_NODE_UP Message Type

TONS class.type: EVT_NU
Not implemented.
Count
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.

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.

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.

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 Mapped to Meaning of Error Code
Error (Generic Error label)
0x100 DRIVER_API_UNAVAILABLE GENERIC_SOFTWARE_ERROR The Toshiba ONS API is not installed or is
unavailable. Check the ONS driver
configuration.
0x101 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.
0x102 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.
0x200 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.
0x201 DRIVER_ILLEGAL_ATOM GENERIC_ADDRESS_RANGE_ERROR The ONS atom specified in the Citect tag
address field does not exist for the
specified tag.
0x202 DRIVER_SECURITY_VIOLATION GENERIC_ACCESS_VIOLATION The ONS tag specified in the Citect tag
address field has already been deleted.
0x203 DRIVER_ILLEGAL_TAG_ATOM GENERIC_INVALID_DATA_FORMAT The ONS atom specified in the Citect tag
address field is badly formatted.
0x204 DRIVER_BAD_ACCESS_VERSION GENERIC_ACCESS_VOILATION Dualised switching occurred during
processing of the ONS request.
0x205 DRIVER_MODULE_NOT_FOUND GENERIC_ADDRESS_RANGE_ERROR The specified tag has been deleted
0x206 DRIVER_BATCH_FAIL GENERIC_GENERAL_ERROR Abnormal batch termination
0x207 DRIVER_BATCH_PARTIAL_FAIL GENERIC_GENERAL_ERROR Abnormal batch termination with tag
0x300 DRIVER_POINT_ERROR GENERIC_GENERAL_ERROR Base value for other (undocumented)
point errors
0x400 DRIVER_BATCH_ERROR GENERIC_GENERAL_ERROR Base value for other (undocumented)
batch errors
3.10 Driver Error Help

[Contents of the PROTERR.DBF file. To be defined after the table above is
completed, after testing.]

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.

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.

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 Citect Data Type Description / Special Usage /
(Antecedent Type) Limitations / Valid Ranges
D_NOTYPE
UNDEFINED
D_BIT char RDT_DIGITAL
RDT_BYTE
RDT_INTEGER
RDT_LONG
D_BITS char* RDT_DIGITAL[]
RDT_BYTE[]
RDT_INTEGER[]
RDT_LONG[]
D_BYTE char RDT_BYTE
RDT_INTEGER
RDT_LONG
D_BYTES char* RDT_BYTE[]
RDT_INTEGER[]
RDT_LONG[]
D_U_BYTE unsigned char RDT_BYTE
RDT_INTEGER
RDT_LONG
D_U_BYTES unsigned char* RDT_BYTE[]
RDT_INTEGER[]
RDT_LONG[]
D_SHORT short RDT_INTEGER
RDT_LONG
D_SHORTS short* RDT_INTEGER[]
RDT_LONG[]
D_U_SHORT unsigned short RDT_INTEGER
RDT_LONG
D_U_SHORTS unsigned short* RDT_INTEGER[]
RDT_LONG[]
D_LONG int RDT_LONG
D_LONGS int* RDT_LONG[]
D_U_LONG unsigned int RDT_LONG Caution: Loss of sign
D_U_LONGS unsigned int* RDT_LONG[] Caution: Loss of sign
D_FLOAT float RDT_REAL
D_FLOATS float* RDT_REAL[]
D_DOUBLE double RDT_REAL
D_DOUBLES double* RDT_REAL[]
D_TEXT char* RDT_STRING
D_TEXTS char** RDT_STRING[]
D_STRING char* RDT_STRING
D_STRINGS char** RDT_STRING[]
D_BIT8 unsigned char RDT_BYTE
RDT_INTEGER
RDT_LONG
D_BIT8S unsigned char* RDT_BYTE[]
D_BIT16 unsigned short RDT_INTEGER
RDT_LONG
D_BIT16S unsigned short* RDT_INTEGER[]
D_BIT32 unsigned long RDT_LONG

D_BIT32S unsigned long* RDT_LONG[]

D_TIME unsigned long RDT_LONG As seconds elapsed since 1/1/70
RDT_STRING8 As a formatted string
D_TIMES unsigned long* RDT_LONG[] As seconds elapsed since 1/1/70
RDT_STRING[]6 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 0x0001
OPT_INTEGER 0x0002
OPT_STRING 0x0004
OPT_LONG 0x0008
OPT_REAL 0x0040
OPT_BYTE 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 UNIT_TYPE RAW_TYPE BIT_WIDTH LOW HIGH COMMENT

%N%R%!%!%! 0x07000000 7 1024 RDT_STRING[16]
%N%R%!%!%! 0x08000000 8 8 RDT_BYTE
%N%R%!%!%! 0x10000000 10 16 RDT_UINTEGER
%N%R%!%!%! 0x01000000 1 16 RDT_INTEGER
%N%R%!%!%! 0x04000000 4 32 RDT_LONG
%N%R%!%!%! 0x02000000 2 32 RDT_REAL
3.11.8 Distribution Files

The following table lists the distribution files for the TONS driver:
Filename Description
TONS.DLL The Toshiba ONS Driver
DB3UTILS.DLL DBaseIII Access Routines
TONS.DBF TONS Driver Compiler Specification
PROTDIR.DBF Modified PROTDIR.DBF Protocol Listing
CTREGION.DLL 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”

Toshiba International Corp. Pty. Ltd.

2 Morton St
Parramatta NSW 2150
Ph (02) 9768-6612
Fax (02) 9890-7542
Mobile 0419 414 066
Email emmett@tic.toshiba.com.au
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 preston@tic.toshiba.com.au
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 Structure Specification
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)
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

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 Person Date
Completion Completed
Date9
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 10/2/00 AP 6/2/00
defined in the driver spec.
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, 21/6/00
AM, MP, AP
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.

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

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 “ONSB1” / PRIMARY
Type TONS
Address / Port / Interrupt 0 / Blank / Blank
Name / Server “ONSB2” / PRIMARY

Type TONS
Address / Port / Interrupt 0 / Blank / Blank
Ports
Name / Number / Server “ONSP1” / 1 / PRIMARY
Board ONSB1
Baud / Bits / Stop / Parity Blank / Blank / Blank / Blank
Options Blank
Name / Number / Server “ONSP2” / 2 / PRIMARY

Board ONSB2

Baud / Bits / Stop / Parity Blank / Blank / Blank / Blank

Options Blank
IO Devices
Name / Number / Server “DPCS1” / 1 / PRIMARY
Address $C05.SST[0]
Protocol TONS
Port ONSP1
Name / Number / Server “DPCS2” / 2 / PRIMARY

Address $C05.SST[2]
Protocol TONS
Port 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.
timeout.
• 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.

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 Passed / Failed
DRIVER_API_UNAVAILABLE Passed
DRIVER_CANNOT_READ_VARIABLE_DBF Passed
DRIVER_DATA_TYPE_MISMATCH Passed
DRIVER_TAG_NOT_FOUND Passed

DRIVER_ILLEGAL_ATOM Passed
DRIVER_SECURITY_VIOLATION Could not generate this error
DRIVER_ILLEGAL_TAG_ATOM Could not generate this error
DRIVER_BAD_ACCESS_VERSION Could not generate this error
DRIVER_MODULE_NOT_FOUND Passed
DRIVER_BATCH_FAIL Could not generate this error
DRIVER_PARTIAL_BATCH_FAIL Could not generate this error
DRIVER_POINT_ERROR Passed
DRIVER_BATCH_ERROR 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 OK OK Passed
RDT_BYTE OK OK Passed
RDT_INTEGER OK OK Passed
RDT_LONG OK OK Passed
RDT_REAL ERROR OK Accepted
RDT_STRING ERROR ERROR Passed
D_BYTE RDT_DIGITAL ERROR ERROR Passed
D_U_BYTE RDT_DIGITAL ERROR ERROR Passed
D_SHORT RDT_DIGITAL ERROR ERROR Passed
RDT_BYTE ERROR ERROR Passed
D_U_SHORT RDT_DIGITAL ERROR ERROR Passed

D_LONG RDT_DIGITAL ERROR ERROR Passed

RDT_INTEGER ERROR ERROR Passed
RDT_REAL ERROR ERROR Passed
D_U_LONG RDT_DIGITAL ERROR ERROR Passed
D_FLOAT RDT_DIGITAL ERROR ERROR Passed
RDT_LONG ERROR ERROR Passed
RDT_REAL OK OK Passed
D_DOUBLE RDT_DIGITAL ERROR ERROR Passed
RDT_REAL OK OK Passed
D_TEXT RDT_DIGITAL ERROR ERROR Passed
RDT_STRING OK OK Passed
D_STRING RDT_DIGITAL ERROR ERROR Passed
D_BIT8 RDT_DIGITAL ERROR ERROR Passed
D_TIME RDT_DIGITAL ERROR ERROR Passed

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] =

Blocking constant [words] =
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 Average response time Physical reads per second

1 0.066s 14
2 0.106s 16
4 0.180s 17
8 0.281s 17
16 0.300s 17
24 0.296s 16
32 0.302s 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

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.
timeout.
• 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.
timeout.
• 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 Physical reads per second

4 0.051s 76
8 0.056s 120
16 0.051s 190
24 0.048s 259
32 0.044s 278
48 0.048s 280
64 0.050s 273
128 0.055s 265
192 0.048s 270
A MaxPending value of 32 is seen as the best compromise between response time and
reads per second.

Citect For Windows, Version 5.xx TONS Driver, User Information and Design

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Citect For Windows, Version 5.xx TONS Driver, User Information and Design

Uploaded by

Copyright:

Available Formats

Citect for Windows, Version 5.

Driver version history

Version Modified By Details

© Copyright 2000 Ci Technologies Page: 2

© Copyright 2000 Ci Technologies Page: 3

© Copyright 2000 Ci Technologies Page: 4

5.3 PERFORMANCE TESTING ...........................................................................5754

© Copyright 2000 Ci Technologies Page: 5

The VETHX1 is the ONS-compatible communication control card of the Toshiba

1.3 Driver Description

© Copyright 2000 Ci Technologies Page: 6

© Copyright 2000 Ci Technologies Page: 7

2.1.2 Communication Configuration – VETHX1

© Copyright 2000 Ci Technologies Page: 8

DPCS Station number 14

2.1.2.1 Primary VETHX1 Card Mode

2.1.2.2 Single Controller, Multiple DPCS Stations, No Redundancy

2.1.2.3 Single Controller, Multiple DPCS Stations, Ethernet Redundancy

© Copyright 2000 Ci Technologies Page: 9

2.1.2.4 Multiple Controllers, Multiple DPCS Stations, Full Redundancy

OIS OIS 1 10bT or 100bT

OIS 2 10bT or 100bT

2.1.2.5 Redundancy Example

© Copyright 2000 Ci Technologies Page: 10

With Hub A link to 172.16.64.10 broken, a request for “$C0A.SST” switches to

With Hub B link to 172.16.64.42 broken, a request for “$C0A.SST” defaults to

With all links broken, communication to the DPCS station is lost.

2.1.3 Hints, Tips, and Frequently asked Questions

2.1.3.1 Duplexing VETHX1

© Copyright 2000 Ci Technologies Page: 11

2.1.3.2 DbaAccess Console Application

© Copyright 2000 Ci Technologies Page: 12

2.2 Application Notes for Toshiba ONS Service

2.2.1 ONS Installation Guide

2.2.1.1 System Configuration

2.2.1.2 PCMP Service Installation

2.2.1.3 ONS Driver Installation

© Copyright 2000 Ci Technologies Page: 13

- Toshiba ONS Version Read

2.2.2 ONS Verification Guide

2.2.2.1 PCS-DS Engineering Tool Installation

2.2.2.2 DPCS Package Installation

2.2.2.3 Communication Test

2.2.3 ONS Architecture

© Copyright 2000 Ci Technologies Page: 14

2.3 Driver Reference

© Copyright 2000 Ci Technologies Page: 15

2.3.2 Installation Requirements

The correct version information for CTREGION.DLL is shown below:

The correct version information for DB3UTILS.DLL is shown below:

© Copyright 2000 Ci Technologies Page: 16

2.3.3 Driver Methodology

2.3.4 ONS API Access

© Copyright 2000 Ci Technologies Page: 17

• The particular responsibility of loading, caching and querying

• The responsibility of ensuring full data type compatibility, communicating

2.3.5 Reference: Required Components

2.3.6 Reference: Communications forms

© Copyright 2000 Ci Technologies Page: 18

NB: This driver has a maximum port support count of 32.

I/O Devices form

2.3.7 Citect Tag Address Format

© Copyright 2000 Ci Technologies Page: 19

3.2.1.2 dbaPntFillEx(dbaPoint dbapoint, char tag_atom)