SYS600 - Communication Programming Interface

MicroSCADA Pro SYS600 9.
4
Communication Programming Interface (CPI)
Trace back information:
Workspace Main version a26
Checked in 2014-05-16
1MRS758104 MicroSCADA Pro SYS600 9.4
Issued: 16.5.2014 Communication Programming Interface (CPI)
Version: A/16.5.2014
User’s Guide
Contents
1 Copyrights ............................................................................................. 5
2 Introduction ........................................................................................... 7
2.1 This manual .................................................................................. 7
2.2 Use of symbols ............................................................................. 8
2.3 Related documents ....................................................................... 9
2.4 Document conventions ................................................................. 9
2.5 Document revisions ...................................................................... 10
3 CPI overview .......................................................................................... 11

3.1 NET unit emulation with CPI ......................................................... 11
3.2 Operating principle ........................................................................ 11
3.3 Memory management ................................................................... 13
3.4 Application Communication Protocol (ACP) ................................. 13
3.5 Transmission error handling ......................................................... 17
3.6 Base system configuration ............................................................ 18
4 Creating protocol converters with CPI ............................................... 21

4.1 Slave devices connected to SYS600 via CPI ............................... 21
4.2 Master device connected to SYS600 via CPI ............................... 23
5 CPI library .............................................................................................. 27

5.1 Basic ACP Communications ......................................................... 28
5.2 Communication control services .................................................. 35
5.3 Message filtering services ............................................................ 36
5.4 RTU and SPA process data sending functions ............................. 36
5.4.1 RTU – application level data transmission services ....... 37
5.4.2 SPA - application level data transmission services ......... 43
5.5 Generic ACP packet building ........................................................ 53
5.5.1 Message header information .......................................... 54
5.5.2 Data filling functions ........................................................ 55
5.5.3 Reply status filling functions ........................................... 56
5.6 ACP packet unpacking ................................................................. 57
5.6.1 Message header information .......................................... 57
5.6.2 Data scanning functions ................................................. 60
5.6.3 RTU commands .............................................................. 62
5.6.3.1 General handling ........................................... 62
5.6.3.2 RTU object command handling ..................... 63
5.6.3.3 RTU analog setpoint handling ....................... 63
5.7 Communication supervision .......................................................... 63
5.8 Buffer management ...................................................................... 64
3
SYS600 9.4 MicroSCADA Pro 1MRS758104

User’s Guide
5.9 Initializations ................................................................................. 65

5.10 Bitset functions ............................................................................. 67
6 Support for System Configuration Tool .............................................. 69

6.1 Functionality .................................................................................. 69
6.2 Permanent protocol configuration file ........................................... 70
6.3 Attribute definitions file .................................................................. 71
6.4 Attribute mappings file .................................................................. 75
7 Terminology ........................................................................................... 77
8 Abbreviations ........................................................................................ 79
Index ....................................................................................................... 81
4
User’s Guide
1 Copyrights
The information in this document is subject to change without notice and should not be
construed as a commitment by ABB Oy. ABB Oy assumes no responsibility for any
errors that may appear in this document.
In no event shall ABB Oy be liable for direct, indirect, special, incidental or consequential
damages of any nature or kind arising from the use of this document, nor shall ABB Oy
be liable for incidental or consequential damages arising from the use of any software
or hardware described in this document.
This document and parts thereof must not be reproduced or copied without written
permission from ABB Oy, and the contents thereof must not be imparted to a third party
nor used for any unauthorized purpose.
The software or hardware described in this document is furnished under a license and
may be used, copied, or disclosed only in accordance with the terms of such license.
Copyright © 2014 ABB Oy. All rights reserved.
Trademarks
ABB is a registered trademark of ABB Group. All other brand or product names
mentioned in this document may be trademarks or registered trademarks of their respective
holders.
Guarantee
Please inquire about the terms of guarantee from your nearest ABB representative.
Third Party Copyright Notices
List of third Party Copyrights notices are documented in "3rd party licenses.txt" and
included in SYS600 installation package.
5
User’s Guide
2 Introduction
2.1 This manual

This manual provides thorough information on the Communication Programming Interface
(CPI) and needed information related to it. CPI is available for connecting foreign systems
to SYS600.
CPI interface
Communication Programming Interface CPI is a protocol environment software that is
used for externally implemented protocol converters.
CPI is a collection of functions that enables the data transfer between the SYS600 base
system and the CPI application program. The CPI library contains functions for sending
and receiving messages to or from the SYS600 base system, as well as functions for
packing and unpacking data of messages. The CPI application program may be run on
different computers as can be seen in Figure 2.1 or also on the same computer with
SYS600.
The CPI application program (gateway program), which uses the CPI interface, emulates
the NET containing stations of the RTU, SPA or SPI (RP 570 slave) device type. The
SPI device type can also be emulated as a RTU device type. In this case, the SPI station
should be configured as a RTU station by the SYS600 base system. CPI supports both
the slave and the master communication.
Normally, only those messages sent from the base system to the station devices (RTU,
SPA), which have been configured in the CPI application node, are visible for the CPI
functions. To be able to emulate a conventional NET unit operation, there is also a need
to access messages directed to the CPI application node itself (NET object). To access
these messages, filtering must be disabled using the message filtering functions (see
Chapter 5 CPI library).
7

User’s Guide
Figure 2.1: SYS600 connected to a foreign system that has a CPI application program as a part
of it. The data transmission between the CPI application program and the SYS600 base system
is implemented through the TCP/IP interface.
TCP/IP interface
The communication between applications using CPI and SYS600 is based on the TCP/IP
protocol. Transmission Control Protocol/Internet Protocol is used for data transmission
in LAN network to provide communication with several protocols across the connected
networks of computers (see Figure 2.1). On the TCP/IP interfaces, the ACP messages
are sent via stream type BSD sockets.
The CPI interface is designed to support connections to several applications running one
or more SYS600 base systems. All applications on one certain SYS600 base system can
be reached by using the same TCP/IP socket.
2.2 Use of symbols

This publication includes warning, caution and information symbols where appropriate
to point out safety-related or other important information. It also includes tips to point
out useful hints to the reader. The corresponding symbols should be interpreted as follows:
Warning icon indicates the presence of a hazard which could

! result in personal injury.
Caution icon indicates important information or a warning

related to the concept discussed in the text. It might indicate
the presence of a hazard, which could result in corruption of
software or damage to equipment/property.
Information icon alerts the reader to relevant factors and

conditions.
8
User’s Guide
Tip icon indicates advice on, for example, how to design a

project or how to use a certain function.
Although warning hazards are related to personal injury, and caution hazards are
associated with equipment or property damage, it should be understood that operation
of damaged equipment could, under certain operational conditions, result in degraded
process performance leading to personal injury or death. Therefore, comply fully with
all warnings and caution notices.
2.3 Related documents

The following SYS600 manuals should be available for reference during the use of this
manual:
Name of the manual MRS number
SYS600 9.4 System Objects 1MRS758115
SYS600 9.4 Programming Language SCIL 1MRS758114
SYS600 9.4 System Configuration 1MRS758100
SYS600 9.4 Application Objects 1MRS758113
SYS600 9.4 Status Codes 1MRS758116
2.4 Document conventions

The following conventions are used for the presentation of material:
• The words in names of screen elements (for example, the title in the title bar of a
dialog, the label for a field of a dialog box) are initially capitalized.
• Capital letters are used for file names.
• Capital letters are used for the name of a keyboard key if it is labeled on the keyboard.
For example, press the CTRL key. Although the Enter and Shift keys are not labeled
they are written in capital letters, e.g. press ENTER.
• Lowercase letters are used for the name of a keyboard key that is not labeled on the
keyboard. For example, the space bar, comma key and so on.
• Press CTRL+C indicates that the user must hold down the CTRL key while pressing
the C key (in this case, to copy a selected object).
• Press ALT E C indicates that the user presses and releases each key in sequence (in
this case, to copy a selected object).
• The names of push and toggle buttons are boldfaced. For example, click OK.
• The names of menus and menu items are boldfaced. For example, the File menu.
- The following convention is used for menu operations: Menu Name > Menu
Item > Cascaded Menu Item. For example: select File > Open > New Project.
- The Start menu name always refers to the Start menu on the Windows Task
Bar.
• System prompts/messages and user responses/input are shown in the Courier font.
For example, if the user enters a value that is out of range, the following message
is displayed: Entered value is not valid.
9

User’s Guide
The user may be told to enter the string MIF349 in a field. The string is shown as
follows in the procedure: MIF349
• Variables are shown using lowercase letters: sequence name
2.5 Document revisions

Version Revision number Date History
A 9.4 16.5.2014 New document
10
User’s Guide
3 CPI overview
3.1 NET unit emulation with CPI

CPI communication resembles the communication between the base system and the NET
unit. The CPI application program acts as a communication front-end. This is called the
NET unit emulation. Although CPI is an external and independent application, the base
system does not see any difference between the messages coming from the NET unit or
from the CPI application because of the similar interfaces in both cases.
Figure 3.1: CPI communication emulates the communication between the SYS600 base system
and the NET unit
3.2 Operating principle

The CPI application program usually runs in an infinite loop where it checks with a
cpiSelect function if there are any incoming messages from SYS600. The following
examples show the basic functionality of the CPI interface. The detailed description of
every function presented below can be found in Chapter 5 CPI library.
/* Example of receiving the commands from the base system*/
Gateway()
{
cpiMsgID recv_id,reply_id=0;
cpiBitSet in_set,out_set,exp_set;
int msg_type,reply_pending;
attr char[2];
GV_Initialize_Connection()
/* Infinite loop*/
for(;;)
{
in_set = out_set = exp_set = 0x7;
cpiSelect( &in_set, &out_set, &exp_set,15);
11

User’s Guide
if (cpiISSET(1, in_set)) {
cpiGetMessage(1, &recv_id, &msg_type);
switch( msg_type ) {
case cpiWRMSG:
/* processing of the write message */

cpiGetMsgAttr(recv_id, &attr);
if ( GV_ Is_Config_Attr( &attr )) {
cpiGetReplyBuffer(recv_id,&reply_id);
if (reply_id != 0) {
GV_Process_Write_To_Attribute (recv_id,reply_id,,,);
if (cpiISSET(1, out_set)) {
cpiSendMessage(1,reply_id,5);
reply_pending = 0;
}
else {
reply_pending = 1;
}
}
}
break;
case cpiRDMSG:
/* processing for the read message */

case cpiRPMSG:
/* processing for the reply message */

}
}
if (reply_pending) && cpiISSET(1, out_set)) {
cpiSendMessage(1,reply_id,5);
reply_pending = 0;
}
}
}
/* Example 2, how to send data to the base system */

Gateway()
{
cpiMsgID ind_id, fail_id;
cpiBitSet in_set,out_set,exp_set;
int reply_ready,retries,status;
GV_Initialize_Connection()
reply_ready = 1;
/*Infinite loop*/
for(;;)
{
in_set = out_set = exp_set = 0x1;
cpiSelect( &in_set, &out_set, &exp_set);
/* Sending of an indication value */

if (GV_Indication_To_Send()) && (cpiISSET(1,out_set)) {
if (reply_ready) {
GV_Process_Indication_Data(,,&Block,&Bit,&Val);
cpiSendRtuIndication(ind_id,1,1,Block,Bit,Val,5);
cpiCLR(1,&out_set);
retries = reply_ready = 0;
}
12
User’s Guide
/* Checking the reply message */

if (cpiISSET(1, in_set)) {
cpiGetMessage(1, &recv_id, &msg_type);
switch( msg_type ) {
case cpiRPMSG:
cpiGetReplyStatus(recv_id, &repl_id, &status);
if ((status != OK_STATUS) || (repl_id != ind_id)) {
display_error_msg(“Error reply for indication “, Block, Bit, Val);
}
reply_ready = 1;
}
}
/* Testing the possible exceptions*/

if (cpiISSET(1, exp_set)) {
switch( cpiException(1) {
case TIMEOUT:
cpiGetFailedMessage(1, &fail_id);
if (++retries > 3) {
cpiGiveUp(fail_id);
display_error_msg(“Sending of indication fails“, Block, Bit, Val);
}
else {
cpiRetransmit(fail_id);
}
break;
case TCPIP_ERROR:
/* no connection to the base system*/
}
}
3.3 Memory management

An application automatically reserves the memory needed when the cpiInitRemoteNode
routine is called. CPI reserves memory pools also for message buffers:
• Received messages
• Transmitted messages
• Transmissions failed
These pools are CPI internal and the CPI application program cannot see them directly.
It must have its own memory management for communicating with the protocol it
emulates.
3.4 Application Communication Protocol (ACP)

Communication between the SYS600 base system and front-ends like the NET unit is
based on ACP (Application Communication Protocol). It is an internal protocol of
SYS600 that is generally used in communication between the SYS600 nodes. The CPI
application program can also be seen as one of the nodes.
13

User’s Guide
The NET unit can communicate simultaneously with several applications on the base
system. The CPI library using the ACP communication supports the following types of
message dialogues presented in Figure 3.2:
Figure 3.2: Message dialogues supported in the ACP communication
a) Write commands: The base system writes the value of an attribute to the CPI application
program.
b) Read commands: The base system requests the value of an attribute from the CPI
application program.
c) Write commands: The CPI application program writes data to the base system process
database.
d) Notifications: The system message is sent from the CPI application program to the
base system.
ACP messages
Each communication system contains a set of system objects, which specify the line
properties, connected devices etc. These objects can be created, modified and deleted
by SCIL (Supervisory Control Implementation Language), and setting the attributes of
the objects can change the properties. The detailed description of attributes can be found
in Chapter 6 Support for System Configuration Tool and the creation of protocol
converters in Chapter 4 Creating protocol converters with CPI.
The target of the ACP message sent by the SYS600 base system is an attribute of a
communication system object (NET, STA), which has been configured in the NET unit.
The attributes of the communication system object can be divided into two main
categories:
• Configuration attributes
14
User’s Guide
• Communication attributes
Configuration attributes refer to the internal data of the NET unit.The NET unit can reply
to these messages immediately. Communication attributes refer to the external data of
the device. In this case, the ACP message must first be converted to the protocol of the
external device before sending it forward. The replies to the communication attributes
are usually not sent back to the base system before the actual reply from the external
device is received.
Data transmission from the base system to the CPI application program is done by setting
the attributes of the communication system object or the process object. This may happen
by using SCIL and its commands.
ACP implements the layers presented in Table 3.1
Table 3.1: ACP-OSI layer mapping
OSI ACP Feature Remark ACP layers
Application Varying Not explicity specified ACP
application layer
Proc. database and SCIL interface Device profiles
Presentation ACP Data Array formats Data coding rules
Session Attribute read/write Connectionless session model com-
parable with remote proc. calls
Transport ACP Transport ACP end-to-end acknowledge flow
control by delayed acknoledge
Network Device level network info Device level addressing ACP
network layer
ANSI X3.28 Node level addressing
Link TCP/IP ANSI Common Integrated According to system ACP
X3.28 RAM LINK components and topology link layer
Physical LAN HW RS-232-C Computer Computer According to link ACP
HW HW physical layer
The ACP network layer consists of two sublayers:

• ANSI X 3.28 Network layer handles low level (link layer) message routing
(node-to-node).
• ACP Network layer information is used for routing on the device level (application
layer).
The following shows a list of fields of the ACP protocol messages. The CPI functions
that can be used to get referred information are presented as well.
The first list shown in Table 3.2 presents the fields, which are used for the low level
message routing. The second list in Table 3.3 consists of fields used for routing on the
device level.
Table 3.2: Fields used for the low level message routing
Field Description CPI function
DST Destination node address cpiGetDestination
15

User’s Guide

SRC Source node address cpiGetSource
CMD Command/reply code cpiGetMessageType
(not read directly)
STS Status cpiGetReplyStatus (not read directly)
TNS Transaction number
Table 3.3: Fields used for message routing on the device level
LDS Logical destination cpiGetRtuNo (not read directly), cpiGet-
DeviceType, cpiGetDeviceNumber
LSR Logical source Connection number
CNT Transaction count
FNC Function cpiGetMessageType
(not read directly)
MBX Mailbox
ATR Attribute cpiGetAttribute
IND1 First index cpiGetIndex
IND2 Last index cpiGetIndex
DATA Device data cpiGetNextData, cpiGetNextDataType,
cpiGetNextAddrData
The following examples describe the relationship between SCIL and fields of the ACP
message:
Writing data to the CPI application:
#SET STA1:SDT(1..2)=(1,2)
SET Message type (command + FNC write)

STA1 RTU number (device number and type packed to LDS)
SDT Attribute
(1... First index
...2) Last index
(1,2) Data
Reading data from the application:

@A = STA1:SAM(10)
@A Message type (command + read)

STA1 RTU number (device number and type packed to LDS)
SAM Attribute
16
User’s Guide
(10) First index
Reserved attributes
Because the CPI application program emulates STA objects in the NET unit, the use of
attributes is not completely free. Some attribute names are reserved for the RTU process
data communication. They cannot be used as the attributes of an application unless they
have been used exactly in the same way as in the RTU or SPA devices.
The following attributes are used by the system and therefore they are not allowed to be
used as the attributes of the application program. Except for the attributes below, attributes
can be formed by using any abbreviation that consist of two letters.
Table 3.4: The attributes not allowed to be used as the attributes of the application
program
Attribute Description
DA Process data
SM System status message
The messages to the DA attribute are generated automatically by the base system when
the output process objects are set. If this method is used with the CPI application program,
it must emulate the DA attribute handling exactly in the same way as the RTU device
does.
The attributes IU, SA, AL, AS, MI and MS are used with the RTU type station. It is
recommended that these attributes should be used in the same way as documented in
SYS600 System Objects manual.
3.5 Transmission error handling

When using the CPI programming interface, there are possibilities to handle different
kinds of communication errors between the CPI application program and the base system.
The following is a list of transmission error types on the CPI application program level.
Examples of how the application reacts to each situation are presented as well:
• The TCP/IP connection is not open when the CPI application program tries to send
a message to the base system (or for some other reason the message is not actually
sent):
An error status is returned by one of the ACP Basic communication functions, for
example cpiSendMessage or cpiSendRtuMessage.
• SYS600 base system does not reply to the ACP data message: The failed application
connection is identified by the exception flags of the cpiSelect function. The function
cpiGetTransmissionBuffer cannot get a new buffer if failed transmission exists. It
is therefore possible to retransmit or delete the message that has failed.
• SYS600 base system replies with an error status to the data message: The application
program can read the status of the reply message by using the cpiGetReplyStatus
function. In this case, there is no automatic retransmission mechanism included to
the CPI retransmission mechanism. If the base system replies with the error status
17

User’s Guide
message, it usually will not help to transmit the same message again for it is very
possible that it replies with the error status again.
3.6 Base system configuration

Each base system has a set of objects that specify the base system and its environment,
hardware and software, as well as the physical and logical connections of the base system
and its applications.
Base system objects are defined with SCIL commands in the SYS_BASCON.COM file,
which is executed every time the base system is started. With a few limitations, the user
can also define and modify the base system objects any time when SYS600 is running.
During the operation, the base system objects are in the primary memory of the base
system computer.
The CPI application program emulates the RTU or SPA type of stations, which means
that the interface towards the base system is similar to that of the RTU or SPA stations.
The following describes the configuration of the base system for the CPI application
program which emulates the RTU type of station. The CPI application program requires
a node of its own. Communication between this node and the base system takes place
via a LAN link.
Configuration steps
To configure SYS_BASCON.COM:
1. Define the base system.
2. Define a LAN link.
3. Define an application.
4. Define nodes.
5. Define the RTU stations. The number of RTU stations can be the same as the number
of the connected process units. This way, the information related to a certain process
unit can be routed to the corresponding station in the NET unit. This way, the
information can be differentiated between different process units. In the COM 500i
configuration, it is possible to use a maximum of 8 NCC stations
The definitions are made in the example below. For more information on the system
objects, see SYS600 System Objects. Steps 1..3 are necessary , but they are configured
using the standard SYS_BASCON.COM template. Steps 4..5 are necessary for the CPI
application.
Example
The following is an example of the SYS_BASCON.COM file for communication with
the Modbus slave protocol. An application CPI_TEST together with two stations is
defined in the SYS600 base system.
;***********************************************************
;
; SYS_BASCON.COM
18
User’s Guide
; BASE SYSTEM CONFIGURATION TEMPLATE

;
;***********************************************************
#CREATE SYS:B = LIST(-

SA = 209,- ;STATION ADDRESS OF BASE SYSTEM
ND = 9,- ;NODE NUMBER OF BASE SYSTEM
DN = 3,- ;DEFAULT NET NODE NUMBER
DS = "RTU",- ;STA TYPES: E.G. STA,RTU,SPA,REX
FS = "NEVER") ;FILE SYNCH CRITERIA
;***********************************************************
;
; COMMUNICATION LINKS
#CREATE LIN:V = LIST(- ;REQUIRES TCP/IP

LT = "LAN") ;FOR SYS-SYS AND LAN FRONTEND
#CREATE LIN1:B = %LIN
;***********************************************************
;
; COMMUNICATION NODES
#CREATE NOD:V = LIST(-

LI = 1,-
SA = 203)
#CREATE NOD3:B = %NOD
;***********************************************************
;
; PRINTERS
;***********************************************************
;
; MONITORS
#LOOP_WITH I = 1..5
#CREATE MON'I':B = LIST(-
TT = "LOCAL",- ;TRANSLATION TYPE
DT = "X") ;X MONITOR
@MON_MAP(%I) = -1
#LOOP_END
#LOOP_WITH I = 6..10
#CREATE MON'I':B = LIST(-
DT = "VS") ;VISUAL SCIL MONITOR
@MON_MAP(%I) = -1
#LOOP_END
;***********************************************************
;
; APPLICATIONS
#CREATE APL:V = LIST(-
NA = "CPI_TEST",- ;NAME OF APPLICATION DIRECTORY
AS = "HOT",- ;APPLICATION STATE: COLD,WARM,HOT
HB = 2000,- ;HISTORY BUFFER SIZE)
RC = VECTOR("FILE_FUNCTIONS_CREATE_DIRECTORIES"),-
AP = (1,2),-
MO = %MON_MAP,- ;MONITOR MAPPING
19

User’s Guide
PR = (1,2,3)) ;PRINTER MAPPING

#CREATE APL1:B = %APL
;***********************************************************
; STATIONS
#CREATE STA1:B = LIST(-

TT = "EXTERNAL",-
ST = "RTU",-
ND = 3,-
TN = 1)
#CREATE STA2:B = LIST(-

TT = "EXTERNAL",-
ST = "RTU",-
ND = 3,-
TN = 2)
;***********************************************************
20
User’s Guide
4 Creating protocol converters with CPI
When a protocol converter is implemented using the CPI library, the project normally
consists of the following parts:
• The application programming required in SYS600.
• The program that utilizes the CPI library for data transfer with the SYS600 base
system.
• The program that converts the messages between the foreign protocol and the CPI
application program.
• The program that handles the foreign protocol functions.
• An interface between the CPI part and the foreign protocol part of the program.
Furthermore, the protocol converters done with CPI can usually be divided into two
categories. In the first case, the SYS600 base system is seen as a master and the slave
devices connected via CPI collect data into the SYS600 process database. In the second
case, the SYS600 base system is seen as a slave device and data is sent from the SYS600
process database to the master via CPI. The use of CPI and the work needed in different
parts of the project differs significantly in these two cases. The following sections explain
the differences and give information about the possible solutions of implementing protocol
converters with CPI.
4.1 Slave devices connected to SYS600 via CPI

When slave devices are connected to the SYS600 base system via the CPI, the data flow
is typically from the slave devices into SYS600 as shown in Figure 4.1. Only commands
(e.g. breaker operation) are transferred from the SYS600 base system to the slave devices.
From the SYS600 base system’s point of view, the slave devices are seen either as RTU
or SPA type stations.
21

User’s Guide
Figure 4.1: The CPI application program acts as a master collecting data from the slave device
to the SYS600 process database. The slave device is seen as a RTU station by the SYS600 base
system.
SYS600 base system configuration

The CPI application is configured into the SYS600 base system as a node. This node is
placed on a TCP/IP LAN link. The devices connected to the CPI are configured as RTU
or SPA stations. See Section 3.6 Base system configuration for more information about
base system configuration.
Application programming in SYS600

The need for special application programming in this case is usually very small. The
library can be used to create a process database and picture functions.
Data transfer with the SYS600 base system using the CPI library
The process data received from the slave devices can be sent to the SYS600 process
database using the following CPI functions (detailed descriptions of each function can
be found in Chapter 5 CPI library). Notation “XXX” means that there are several functions
with variable timestamps.
Indications: cpiSendRtuIndicationXXX
Analog values: cpiSendRtuAnalogValueXXX
Pulse counters: cpiSendRtuPulseCounterXXX
Digital values: cpiSendRtuDigitalValue
22
User’s Guide
BitStream values: cpiSendRtuBitStream
The commands from the SYS600 base system can be handled using the following cpi
function:
cpiGetNextAddrData
With this function, it is possible to read the command object type, address and the value.
The object type of the command can be one of the following:
• Object command (binary output).
• Regulation command.
• Digital setpoint.
• Analog setpoint.
• General persistent output.
Converting messages between CPI and the foreign protocol

It is difficult to give any specific instructions for converting messages between CPI and
the foreign protocol. However, the following questions need to be answered:
• How does the addressing of the data differ from the SYS600 base system addressing
method? Is a cross-reference table needed or could it be possible to map the addresses
directly into the SYS600 base system address space?
• How closely do the data types of the foreign protocol match the available types in
the SYS600 base system? What kind of a conversion or scaling is needed?
• Is there a need for intermediate database in the CPI to reduce the data transfer
between the CPI application program and the SYS600 process database?
Implementation of the foreign protocol

The foreign protocol is normally implemented as a separate thread (process), which
simplifies the program structure and makes it easier to handle time critical tasks both in
the CPI part and the foreign protocol part of the program.
Interface between the CPI part and the foreign protocol part of the
program
There are several ways of handling the communication between the CPI part and the
foreign protocol part of the program. The example program delivered with the CPI
installation package named CPI_EXAMPLE uses common global variables for
transferring data between the program parts (threads).
4.2 Master device connected to SYS600 via CPI

When a master device is connected to the SYS600 base system via the CPI, the data flow
is normally from the base system to the master as shown in Figure 4.2. Only commands
(e.g. breaker operation) are transferred from the master into the SYS600 base system. It
is suggested that the CPI application program emulates the RP 570 slave device (SPI)
23

User’s Guide
as closely as possible in order to be able to use the existing applications in the SYS600
base system. These applications are used for data transfer between the SYS600 base
system and the CPI application program (COM 500i).
Figure 4.2: SYS600 connected with the CPI application (e.g. Modbus Slave). The CPI application
acts as a slave providing data from the SYS600 database for the master.
SYS600 base system configuration

The CPI application is configured into the SYS600 base system as a node. This node is
placed on a TCP/IP LAN link. The master device connected to the CPI is configured as
a RTU or SPA station although its behaviour resembles more that of the SPI station. See
Section 3.6 Base system configuration for more information about the base system
configuration.
Application programming in SYS600

The application program in SYS600 must take care of forwarding the data from the
process database to the CPI application program. This is usually done by using event
channels in the process objects that are connected to command procedures. The commands
from the master are received into the input process objects activating a command
procedure that will then operate the actual output process object. When the interface to
the CPI is done according the SPI (RP 570 Slave device) profile, it is possible to use the
existing command procedures and tools (COM 500i). See SYS600 System Objects for
details of the SPI station attribute interface.
24
User’s Guide
Data transfer with SYS600 using the CPI library

The data received from SYS600 can be unpacked with the following CPI functions
(detailed descriptions of each function can be found in Chapter 5 CPI library):
cpiGetRtuNo
cpiGetAttribute
cpiGetIndex
cpiGetNextDataType
cpiGetNextData
cpiGetNextS32Data
The commands received from the master can be sent to the SYS600 base system by using
the following CPI function:
cpiSendRtuDigitalValue
Converting messages between the CPI and the foreign protocol

It is difficult to give any specific instructions for converting messages between the CPI
application program and the foreign protocol. Normally the following questions need to
be answered:
• How does the addressing of the data differ from the SYS600 base system addressing
method? Do we need a cross-reference table or can we map the addresses directly
into the SYS600 base system address space?
• How closely do the data types of the foreign protocol match the available types in
the SYS600 base system? What kind of a conversion or scaling is needed?
• Is there a need for intermediate database in the CPI to reduce the data transfer
between the CPI application and the SYS600 process database?
Implementation of the foreign protocol

The foreign protocol is usually implemented as a separate thread (process), which
simplifies the program structure and makes it easier to handle time critical tasks both in
the CPI part and the foreign protocol part of the program.
Interface between the CPI part and the foreign protocol part of the
program
There are several ways of handling the communication between the CPI part and the
foreign protocol part of the program. The example program delivered with the CPI
installation package named CPI_EXAMPLE uses common global variables for
transferring data between the program parts (threads).
25
User’s Guide
5 CPI library
General
CPI library is a collection of functions for sending and receiving messages between
SYS600 and the CPI application, and also for message handling, packing and unpacking.
The functions contained in the CPI library are specified in this chapter. A list of the
program files is presented in Table 5.1 below.
Table 5.1: Program files for CPI
File Name Description
cpint.lib Microsoft Developer Studio Win32 Static Library file.
cpi.h Header file for the CPI functions.
cpicl.h CPI internal definition, type and function header file.
bufms.h CPI buffer handling definitions.
Part of the definition file cpi.h, which contains the definition for different data types:
typedef int cpiMsgID;
typedef unsigned char cpiObjectType;

/* Object type numbers are same as in the ACP */
#define cpiU8 0
#define cpiS8 1
#define cpiU16 2
#define cpiS16 3
#define cpiU32 4
#define cpiS32 5
#define cpiF32 6
#define cpiADDR 7
#define cpiBV 8
#define cpiB 9
typedef struct {
cpiObjectType ObjectType;
unsigned int ObjectAddress;
int ObjectValue;
}addressItem;
typedef struct {
cpiDataType item_type;
union { /* this definition is cpu specific */
27

User’s Guide
unsigned char U8;

unsigned char S8;
unsigned short int U16;
short int S16;
unsigned long int U32;
unsigned int S32;
float F32;
unsigned short A;
addressItem ADDR;
} value;
}cupidity;
/* Message types */
#define chaperons 1
#define cpiMsgID 2
#define cpiMsgID 3
#define cabinets 4
typedef struct {
unsigned char (year,month,day,hour,minute,second,ms)
} cpiTime;
5.1 Basic ACP Communications

The communication between the SYS600 base system and the NET unit is based on the
ACP, internal communication protocol of SYS600.
Table 5.2: Basic ACP Communications
Function Description
cpiSelect Checks the status of the TCP/IP socket.
cpiException Determines the cause of exception.
cpiSendMessage Sends an ACP formatted message to SYS600.
cpiSendRtuMessage Sends an ACP formatted message to SYS600 from RTU.
cpiSendSystemMessage Sends a system message from any device.
cpiSendStandardSys- Sends a system message which activates RUNNING/SUSPENDED
temMessage events for APL_EVENT event channel.
cpiSendStandardSys- Sends a system message which activates RUNNING/SUSPENDED
temMessageWithBinary events for APL_EVENT event channel and updates process objects
used by the System Self Supervision.
cpiSendNodeSystemMes- Sends a system message for the CPI node itself, analog status
sage point updated.
cpiSendNodeSystemMes- Sends a system message for the CPI node itself, analog and binary
sageWithBinary status points are updated. Binary status point is used by the System
Self Supervision.
cpiSendStandardUserActiv- Sends a user activity event system message from the application
ityMessage using CPI to any device.
28
User’s Guide
cpiGetMessage Reads an ACP formatted message from the received message
queue.
cpiClearExceptionStatus Clearing the status when an exception has occurred.
cpiSetApplicationCold Set the "data not accepted flag" of the application.
cpiGetApplicationCold Returns the "data not accepted flag" of the application.
cpiSelect
This function checks the TCP/IP socket in case there are any messages coming from the
base system application, and if there are any connections ready for writing. It also returns
information if any of the connections have failed or any message has not got a reply in
time. Some of the communication between the base system and application is actually
done inside this function, so it must be called in the main loop of the CPI application.
The cpiSelect function returns when one of the specified input connections has received
a message, or after the specified time has elapsed.
When this function is called, its arguments specify which connections the user is interested
in. Then the function modifies the arguments to indicate the status of each connection.
Table 5.3: The bit position indicates the status of the connection
RD WR EX Description
bit0 bit0 bit0 connection 1 flags
RD Bit is set when CPI has received a message from this connection.
WR Bit is set when CPI does not wait any reply from this connection.
EX Bit is set when CPI has lost this connection or data message does not get reply
from this connection. The actual cause of exception can be determined by using
the cpiException function.
int cpiSelect(cpiBitSet *RD, cpiBitSet *WR, cpiBitSet *EX, long MS);
RD Received message flags (max 16 connections)

WR Ready for writing flags
EX Failed connections flags
MS Max. waiting time in milliseconds
Return values:
0 : OK
cpiException
This function determines the cause of exception (cpiSelect EX flags).
int cpiException(int CONNECTION);
Return values:
29

User’s Guide
1 : TCP/IP error
- Connection to this node has been lost
2 : No reply error
- Message sent by CPI has not received a reply from
SYS600
6 : Application error
- Message sent by CPI has received a reply with error
status from SYS600
cpiSendMessage
This function sends an ACP formatted message to SYS600. Before using this function,
the message buffer must be reserved by using the functions cpiGetTransmissionBuffer
or GetReplyBuffer, and formatted by using some of the cpiPutXXXData functions
presented in Section 5.5.2 Data filling functions. (Notation XXX means that any function
of this type is available.)
int cpiSendMessage(int DESTIN, cpiMsgID ID, int TIMEOUT);
DESTIN Destination connection number

ID Message buffer identification
TIMEOUT Waiting time for the base system reply in milliseconds,
if 0 -> no time-out supervision
Return values:
0 : OK
-2 : Invalid MsgID ; the buffer ID is not free, or it is
unknown
cpiSendRtuMessage
This function sends an ACP formatted message to SYS600 from the RTU. Before using
this function, the message buffer must be reserved by using the function
cpiGetTransmissionBuffer and formatted by using some of the cpiPutXXXData functions
int cpiSendRtuMessage(int DESTIN, int SOURCE, cpiMsgID ID, int TIMEOUT);

SOURCE Source RTU number
TIMEOUT Waiting time for the base system reply
in milliseconds,
if 0 -> no time-out supervision
Return values:
0 : OK
-2 : Invalid MsgID
cpiSendSystemMessage
The following function can be used to send a system message from any device. This
function is present for backward compatibility and the usage of it is currently discouraged.
Function cpiSendStandardSystemMessage is preferred instead.
30
User’s Guide
int cpiSendSystemMessage(int con, int source, int address, int dataValid, short
status)
source Source logical device, the following macro LOGICAL_AD-
DRESS(deviceType,deviceNumber)
address address of the ANSI analog input process object to be
updated
dataValid cpiDATA_VALID
;The updated data values from the device are valid
cpiDATA_NOT_VALID
status status value for the ANSI analog input process object
Example:
;Sending NET1 line status 12602 to address 6103:
cpiSendSystemMessage( con,
LOGICAL_ADDRESS(NET_DEVICE,1),
6103,
0,
12602)
cpiSendStandardSystemMessage
This function can be used to send a system message from any device. State values
cpiDEVICE_STATUS_CHANGES_TO_SUSPENDED and
cpiDEVICE_STATUS_CHANGES_TO_RUNNING will activate the predefined event
channel APL_EVENT. For more information, see SYS600 Application Objects. When
cpiSendStandardSystemMessage function is called, an ANSI analog input status point
with settings UN=0, OA=address in the receiving application is updated also. The usage
of this function is preferred instead of cpiSendSystemMessage.
int cpiSendStandardSystemMessage(int con, int source, int address, int newState,
short status)
where
source source Source logical device, the following macro should
be used to calculate the value LOGICAL_ADDRESS(device-
Type, deviceNumber)
updated
newState cpiDEVICE_STATUS_NOT_CHANGED
;Device status is not changed
cpiDEVICE_STATUS_CHANGES_TO_SUSPENDED
;Device status changes to suspended
cpiDEVICE_STATUS_CHANGES_TO_RUNNING
;Device status changes to running
Example:
; Send a suspension status 13251 from SPA device 2.
cpiSendStandardSystemMessage( con,
LOGICAL_ADDRESS(SPA_DEVICE, 2)
1002,
cpiDEVICE_STATUS_CHANGES_TO_SUSPENDED,
13251)
cpiSendStandardSystemMessageWithBinary
This function can be used to send a system message from any device. State values
cpiDEVICE_STATUS_CHANGES_TO_SUSPENDED and
cpiDEVICE_STATUS_CHANGES_TO_RUNNING will activate the predefined event
31

User’s Guide
channel APL_EVENT, see System Application Objects manual for more information.
When cpiSendStandardSystemMessageWithBinary function is called, an ANSI analog
input status point with settings UN=0, OA=address and an ANSI binary input status
point with settings UN=0, OA=address+16777216 (1000000hex) in the receiving
application are updated. Values for the binary object are 1=OK, 0=not OK. The usage
of this function is preferred instead of cpiSendSystemMessage.
int cpiSendStandardSystemMessageWithBinary(int con, int source, int address, int
newState, short status)
where
con Connection number to destination application
source Source logical device, the following macro should be
used to calculate the value LOGICAL_ADDRESS(deviceType,
deviceNumber)
updated. The address of binary input status object is
address+16777216
newState cpiDEVICE_STATUS_NOT_CHANGED
;Device status is not changed (binary input status object
not updated)
cpiDEVICE_STATUS_CHANGES_TO_SUSPENDED
;Device status changes to suspended (binary input status
object updated to 0)
cpiDEVICE_STATUS_CHANGES_TO_RUNNING
;Device status changes to running (binary input status
object updated to 1)
Example:
; Send a 'RUNNING' status from SPA device 2, analog input status object will be
updated with value 0 (no error) and the binary input will be updated with value
1 (connection OK)
cpiSendStandardSystemMessageWithBinary( con,
LOGICAL_ADDRESS(SPA_DEVICE, 2
1002,
cpiDEVICE_STATUS_CHANGES_TO_RUNNING,
0);
cpiSendNodeSystemMessage
This function can be used to send a system message from the CPI node itself. Calling
this function will update the ANSI analog input process object with the setting UN=0,
OA=address. The value of the process object can be given with the parameter STATUS
but for correct co-operation with System Self Supervision, it is recommended to use the
value 10001=NETP_SYSTEM_INITIALIZED. SSS uses this process object in its displays
to indicate the status of the node.
int cpiSendNodeSystemMessage(int con, int address, short status)
where
updated, value used by SSS is 6000+node number
Example:
; Send NETP_SYSTEM_INITIALIZED status message indicating that the CPI node has
started and established connection to the basesystem.
cpiSendNodeSystemMessage( con,
32
User’s Guide
6002,
10001);
cpiSendNodeSystemMessageWithBinary
This function can be used to send a system message from the CPI node itself. Calling
this function will update the ANSI analog input process object with the setting UN=0,
OA=address, and the ANSI binary input process object with setting UN=0, OA=address
+ 1000000hex. The value of the analog input process object can be given with the
parameter STATUS but for correct co-operation with System Self Supervision, it is
recommended to use the value 10001=NETP_SYSTEM_INITIALIZED. The value of
the binary input object will always be 1.
SSS uses these process objects in its displays to indicate the status of the node.
int cpiSendNodeSystemMessageWithBinary(int con, int address, short status)
where
updated, value used by SSS is 6000+node number
Example:
; Send NETP_SYSTEM_INITIALIZED status message indicating that the CPI node has
started and established connection to the basesystem.
cpiSendNodeSystemMessageWithBinary( con,
6002,
10001);
cpiSendStandardUserActivityMessage
This function can be used to send a user activity event system message from the station
object to any device. When cpiSendStandardUserActivityMessage function is called, a
corresponding ACP message is sent to the basesystem node. The content of the message
is based on the information in the structure pointer by the pUAL_Event.
Parameter pathstr should refer to attribute MN
int cpiSendStandardUserActivityMessage (int con, UAL_EventType *pUALEvent, char
*pathstr, int timeout, cpiMsgID *id);
pUAL_EVENT Pointer UAL_EventType Structure containing the user
activity event information
pathstr pointer to NULL-terminated string of max. 16 characters
to identify the sender STA object
TIMEOUT Timeout in ms
cpiGetMessage
This function reads an ACP formatted message from the received message queue.
This function must not be called before the unpacking of the

previous message is completely read, because the data of the
previous message will be overwritten by this function.
33

User’s Guide
int cpiGetMessage( int SOURCE, cpiMsgID *ID, *MSGTYPE);

SOURCE Source connection number
MSGTYPE Type of the received message,
1=write, 2=read, 3=reply,
4= notification
Return values:
0 : OK
-4 : No messages from this source
cpiClearExceptionStatus
This function clears a certain status code when an exception has occurred. If, for example,
the function cpiException has returned 6=Application Error, the status can be cleared in
order to retry the data transmission to the base system as well as enable the accessing of
CPI Node from other MicroSCADA application. This function is needed, for example,
in the Hot Standby implementation, if the main application receiving the data is not ready
to accept data and causes an exception, access from WD application is still needed.
int cpiClearExceptionStatus(int CONNECTION, short c_status);
Example: if cpiException has returned 6 = application error, the
status should be cleared with a call
cpiClearExceptionStatus(mConn, SYST_APPLICATION_DOES_NOT_EXIST);
Return values:
0 : OK
cpiSetApplicationCold
This function sets the value of the "data not accepted" flag of the given application. This
function is not necessarily used but it can be used if there is a need clear the mentioned
flag. See also cpiGetApplicationCold.
void cpiSetApplicationCold( int CONNECTION, int STATE);
CONNECTION Source connection number
STATE 0=application accepts data
1=application does not accept data
Return values: none
cpiGetApplicationCold
This function returns the value of the "data not accepted" flag of the given application.
This function is needed in Hot Standby implementations in order to know if the next
transmission to the application should be done or not. In case an error
SYST_APPLICATION_DOES_NOT_EXIST=7049 has been returned to the previous
data transmission, the "data not accepted" flag of the receiving application is set to 1 to
indicate that the application is not ready to accept data. The retransmission can be done
after a delay to see if the situation has changed. In MicroSCADA version 9.3 and newer,
the application which is in COLD state may also accept data since it uses its own
buffering.
34
User’s Guide
int cpiGetApplicationCold( int CONNECTION);

CONNECTION Source connection number
Return values:
0 : application accepts data
1 : application does not accept data
5.2 Communication control services

These functions control the failed message transmission.
Table 5.4: Communication control services
cpiGetFailedMessage Returns the ID of the failed message.
cpiRetransmitMessage Retransmits the message, which is in the
failed message queue.
cpiGiveUp Deletes a message from the failed mes-
sage queue.
cpiGetFailedMessage
This function returns the id of the failed message. The failed message has not received
a reply from the application.
int cpiGetFailedMessage(int DESTIN, cpiMsgID *ID);
ID Id for failed message
Return values:
0 : OK
-4 : No failed messages in this connection
cpiRetransmitMessage
This function retransmits the message, which is in the failed message queue.
int cpiRetransmit(cpiMsgId ID);
Return values:
0 : OK, retransmission started
-2 : Invalid MsgID
cpiGiveUp
This function deletes a message from the failed message queue.
int cpiGiveUp(cpiMsgId ID);
Return values:
0 : OK
35

User’s Guide
-2 : Invalid MsgID
5.3 Message filtering services

Normally, only messages from the base system to station devices (RTU, SPA) configured
in the CPI application node are visible for the CPI functions. To be able to emulate a
conventional NET unit operation, there is a need to also access messages directed to the
CPI application node itself (NET object). This filtering can be controlled and monitored
with the following functions.
When the filtering is switched off, all messages except diagnostic messages (the NET
object attribute names NS and DS are reserved for the internal use of CPI) directed to
the CPI node are passed through the interface and can be further processed with the CPI
functions.
Table 5.5: Message filtering
cpiNetMessageFiltering Monitors the filtering of messages sent by the base system.
cpiSetNetMessageFiltering Controls the filtering of messages sent by the base system.
cpiNetMessageFiltering
The current state of the filtering can be read by this function.
int cpiNetMessageFiltering();
Return values:
0 = off
1 = on
cpiSetNetMessageFiltering
Controls filtering of messages sent by the base system.
void cpiNetMessageFiltering(int value);
value:
0 = off
1 = on (default)
5.4 RTU and SPA process data sending functions

The following functions are also considered to be automatic functions for building and
sending certain ACP messages to the SYS600 process database. Each Send... function
reserves a buffer for message, fills it and sends it to the base system.
Each one of the following functions can also be made manually. Instructions for this can
be found in Section 5.5 Generic ACP packet building and in Section 5.6 ACP packet
unpacking.
36
User’s Guide
5.4.1 RTU – application level data transmission services
The RTU Object Model is based on an object type and object block number concept (see
SYS600 Application Objects). For input process data the object block number range is
1…255. For commands (from the SYS600 application to the CPI application) the range
is 1…2047.
Table 5.6: RTU - application level data transmission services
cpiSendRtuStatusMessage Sends an ACP formatted notification message to SYS600.
cpiSendRtuIndication Sends indication values to the base system process database.
cpiSendRtuIndicationBlock Sends an indication value block to the base system process data-
base.
cpiSendRtuIndication- Sends the indication values with timestamp to the base system
WithTS process database.
cpiSendRtuAnalogValue Sends an analog value to the base system process database.
cpiSendRtuAnalogValue- Sends an analog value with timestamp to the base system process
WithTS database.
cpiSendRtuPulseCounter Sends a pulse counter value to the base system process database.
cpiSendRtuPulseCounter- Sends a pulse counter value with timestamp to the base system
WithTS process database.
cpiSendRtuBitStream Sends a bit string to the process object database of the base sys-
tem.
cpiSendRtuStatusMessage
This function sends an ACP formatted notification message to SYS600. A reply to this
message is not expected.
int cpiSendRtuStatusMessage(int DESTIN, int SOURCE, int STYPE, int DATAVALID,
short STATUS );
STYPE Status type
0 -> Device status message
1 -> Terminal status message
2 -> Terminal event message
3 -> Terminal message
DATAVALID 0 -> data is not longer valid in this RTU.
1-> data is valid in this RTU
STATUS Status code
Return values:
0 : OK
-13 : No buffer -> CPI cannot get a buffer for the message
After starting the application program (the connections to the

base systems and the remote RTU should be established), it is
37

User’s Guide
important to send the system status message to the base system.

The status parameter should be set as OK_STATUS (or
RTUP_DEVICE_STARTED) and the DATAVALID parameter
as TRUE. The base system marks the object status related to
the process data of the source RTU to OK (OS=0) or
OBSOLETE_STATUS (OS=2) based on the DATAVALID
parameter.
The following status codes are valid when the front-end emulates the RTU device (see
SYS600 Status Codes):
RTU level status codes:
0 OK_STATUS
12602 RTUP_DEVICE_SUSPENDED
12603 RTUP_TIMEOUT_WHILE_WAITING_RESPONSE
12604 RTUP_DEVICE_STOPPED
12605 RTUP_DEVICE_STARTED
12658 RTUC_INVALID_INDEX_RANGE
12662 RTUC_ATTRIBUTE_IS_WRITE_ONLY
12665 RTUC_NOT_EXECUTED_RESPONSE
12676 RTUC_UNEXPECTED_VALUE
Descriptions:
0 OK_STATUS
The purpose of this status message is to indicate that the CPI application program
considers the RTU connection to be working properly. This should always be sent right
after the start-up situation, when a connection has been established. It should also be
sent after a communication break, when the connection has been re-established.
12602 RTUP_DEVICE_SUSPENDED
When the CPI application program activates an RTU device image for the process
communication, this is the first system message to be sent. It indicates that the CPI
application program does not currently have the connection to this RTU but it is trying
to establish it since this is the RTU connection start-up situation.
It is also sent when the CPI application program detects that the connection to a certain
RTU is lost. The DATAVALID parameter is set to false to indicate that the process
database image of this RTU is no longer valid (see above).
12603 RTUP_TIMEOUT_WHILE_WAITING_RESPONSE
This status message indicates that the RTU did not react to the message initiated from
a SYS600 application. Note that this means no response at all. The negative acknow-
ledgements are handled by the "Not executed response" status code.
38
User’s Guide
12604 RTUP_DEVICE_STOPPED
The RTU device emulated in the CPI application program can be stopped by setting
its IU attribute to zero. This means that the connection to the RTU is properly discon-
nected. When this is done, the RTU image should send this status message to the SYS600
application. The DATAVALID flag should be set to FALSE since the updating of the
SYS600 process database now stops from this RTU image.
12605 RTUP_DEVICE_STARTED
When the IU attribute of a device is set to one (1), the RTU image should respond by
this system message. If this is the first time the RTU image is started after start-up, the
DATAVALID should be set to FALSE. If the RTU image receives an IU attribute while
the device connection is OK, the DATAVALID is set to TRUE.
12658 RTUC_INVALID_INDEX_RANGE
If the SYS600 application attempts to update an attribute with an invalid index (e.g.
index equal to 5 when the highest allowed index is 4), the RTU image responds with
this status message.
12662 RTUC_ATTRIBUTE_IS_WRITE_ONLY
The RTU image responds with this status message for attempts to read values from at-
tributes that can only be written. A typical example might be some of the command
type attributes.
12665 RTUC_NOT_EXECUTED_RESPONSE
This status message is sent to the SYS600 application when the RTU responds to the
command with a negative acknowledgement from the application.
12676 RTUC_UNEXPECTED_VALUE
This status message indicates the attempts to write an invalid value to a RTU image
attribute, e.g. a text value to an integer type attribute.
Node level status codes:

14016 NETW_UNKNOWN_DESTINATION_DEVICE
14018 NETW_UNKNOWN_DEVICE_ATTRIBUTE
14044 NETW_INVALID_STATION_ADDRESS
cpiSendRtuIndication
This function sends an indication value to the base system process database.
int cpiSendRtuIndication(int DESTIN, int SOURCE, int BLOCK, int BIT, int VAL,
int STATUS, int TIMEOUT, cpiMsgID *ID);
BLOCK Object address of the process object
BIT Bit number destination word (0..15)
VAL Value of bit 0,1 for single indications, 10,11,12,13 for
double indications
39

User’s Guide
BVAL 16 bit value

TS Timestamp
TIMEOUT Timeout in ms;
STATUS Status code for data (0= ok)
Return values:
0 : OK
-7 : buffer full, the filling of the ACP message has been
failed
-13 : cannot get buffer for transmission message
-20 : connection waiting
Sending failed because of the reply for the previously
sent message
-22 : Invalid value
cpiSendRtuIndicationBlock
This function sends an indication value block to the base system process database.
int cpiSendRtuIndicationBlock(int DESTIN, int SOURCE, int BLOCK, int BVAL, int
STATUS, int TIMEOUT, cpiMsgID *ID);
double indications
BVAL 16 bit value
TS Timestamp
Return values:
0 : OK
failed
The sending failed because the reply for the previously
sent message has not been received
-22 : Invalid value
cpiSendRtuIndicationWithTS
This function sends an indication value with timestamp to the base system process
database.
int cpiSendRtuIndicationWithTS(int DESTIN, int SOURCE, int BLOCK, int BIT, int
VAL, cpiTime TS, int STATUS, int TIMEOUT, cpiMsgID *ID);
40
User’s Guide

double indications
BVAL 16 bit value
TS Timestamp
Return values:
0 : OK
failed
The sending failed because the reply for the previously
sent message
-22 : Invalid value
cpiSendRtuAnalogValue
This function sends an analog value to the base system process database.
int cpiSendRtuAnalogValue(int DESTIN, int SOURCE, int BLOCK, int VAL,int STATUS,
int FLAGS, int TIMEOUT, cpiMsgID *ID);
BLOCK Object address of process object
VAL Value of an analog value, the value range is [-
2000...+2000].
Incoming values must be scaled to this range.
TS Timestamp
FLAGS Status flags of analog value process objects
bit0 -> Lo Alarm flag
bit1 -> Lo Warning flag
bit2 -> Hi Warning flag
bit3 -> Hi Alarm flag
Return values:
0 : OK
failed
The sending failed because of the reply for the previ-
ously sent message
-22 : Invalid value
cpiSendRtuAnalogValueWithTS
This function sends an analog value with timestamp to the base system process database.
int cpiSendRtuAnalogValueWithTS(int DESTIN, int SOURCE, int BLOCK, int VAL,
cpiTime TS, int STATUS, int FLAGS, int TIMEOUT, cpiMsgID *ID);
41

User’s Guide

VAL Value of an analog value, the value range is [-
2000...+2000].
Incoming values must be scaled to this range.
TS Timestamp
Return values:
0 : OK
failed
The sending failed because of the reply for the previ-
ously sent message
-22 : Invalid value
cpiSendRtuPulseCounter
This function sends a pulse counter value to the base system process database.
int cpiSendRtuPulseCounter(int DESTIN, int SOURCE, int BLOCK, long VAL,int
STATUS,int FLAGS, int TIMEOUT, cpiMsgID *ID);
VAL Value of the pulse counter
TS Timestamp
TIMEOUT Timeout in milliseconds
FLAGS Status flags of the pulse counter process objects
bit4 -> End of the period flag
Return values:
0 : OK
-7 : Buffer full, the filling of the ACP message has been
failed
-13 : Cannot get buffer for transmission message
-20 : Connection waiting
The sending failed because the reply to the previously
-22 : Invalid value
cpiSendRtuPulseCounterWithTS
This function sends a pulse counter value with timestamp to the base system process
database.
42
User’s Guide
int cpiSendRtuPulseCounterWithTS(int DESTIN, int SOURCE, int BLOCK, long VAL,

cpiTime TS, int STATUS, int FLAGS, int TIMEOUT, cpiMsgID *ID);
TS Timestamp
Return values:
0 : OK
-7 : Buffer full, the filling of the ACP message has been
failed
-The sending failed because the reply to the previously
-22 : Invalid value
cpiSendRtuBitStream
This function sends a bit string to the process object database of the base system.
int cpiSendRtuBitStream(int DESTIN, int SOURCE, int ADDR, int LEN, char STREAM[],
int TIMEOUT, cpiMsgID *ID);
ADDR Address of the process object
LEN Length of bitstream in bits !!
STREAM Array of bits stored on the char array
(Bitstream begins fromv bit0 of first char)
Return values:
0 : OK
-7 : Buffer full, the length of the bit stream is too long.
5.4.2 SPA - application level data transmission services
The following functions reserve a buffer for a message, fill and send it from the SPA
type device to the base system.
Table 5.7: SPA - application level data transmission services
cpiSendSpaAnalogValueWithTSandFlags Sends an analog value with alarm flags and
timestamp to the base system process data-
base.
43

User’s Guide
cpiSendSpaAnalogValueWithTS Sends an analog value with timestamp to the
base system process database.
cpiSendSpaAnalogValue Sends an analog value to the base system pro-
cess database.
cpiSendSpaDigitalValueWithTSandFlags Sends a digital value with alarm flags and
timestamp to the base system process data-
base.
cpiSendSpaDigitalValueWithTS Sends a digital value with timestamp to the base
system process database.
cpiSendSpaDigitalValue Sends a digital value to the base system pro-
cess database.
cpiSendSpaIndicationWithTS Sends an indication value with timestamp to the
base system process database.
cpiSendSpaIndicationBlockWithTS Sends an indication value block with timestamp
to the base system process database.
cpiSendSpaIndication Sends an indication value to the base system
process database.
cpiSendSpaIndicationBlock Sends an indication value block to the base
cpiSendSpaPulseCounterWithTS Sends a pulse counter value with timestamp to
the base system process database.
cpiSendSpaStatusMessage Sends an ACP formatted notification message
to SYS600.
cpiSendSpaMessage Sends an ACP formatted message to SYS600
from SPA.
cpiSendSpaBitStream3 Updates a bitstream process object in the base
cpiSendSpaBitStream3WithTS Updates a bitstream process object with
timestamp in the base system process data-
base.
cpiSendBufferedSpaIndicationWithTS Sends an indication value with timestamp to the
base system process database. Indication is
marked as buffered.
cpiSendSpaBufferedIndicationBlockWithTS Sends an indication value block with timestamp
to the base system process database. Indication
block is marked as buffered.
cpiSendSpaAnalogValueWithTSandFlags
The parameter 'FLAGS' is used to provide alarm information of the measured value.
int cpiSendSpaAnalogValueWithTSandFlags(int DESTIN, int SOURCE, int BLOCK, float
VAL, cpiTime TS, int STATUS, int FLAGS, int TIMEOUT, cpiMsgID *ID);
SOURCE Source SPA number
44
User’s Guide
VAL Value of an analog value

TS Timestamp
Return values:
0 : OK
-7 : Buffer full, the filling of the ACP message failed
-22 : Invalid value
cpiSendSpaAnalogValueWithTS
int cpiSendSpaAnalogValueWithTS(int DESTIN, int SOURCE, int BLOCK, float VAL,
cpiTime TS, int STATUS, int TIMEOUT, cpiMsgID *ID);
TS Timestamp
Return values:
0 : OK
-20 : Connection waiting, previously sent message has not
been received
-22 : Invalid value
cpiSendSpaAnalogValue
This function sends an analog value without timestamp to the base system process
database.
int cpiSendSpaAnalogValue(int DESTIN, int SOURCE, int BLOCK, float VAL, int
STATUS Status code for data (0 = ok)
45

User’s Guide
Return values:
0 : OK
-22 : Invalid value
cpiSendSpaDigitalValueWithTSandFlags
This function sends a digital value with timestamp to the base system process database.
The parameter FLAGS is used to provide alarm information of the measured value.
int cpiSendSpaDigitalValueWithTSandFlags(int DESTIN, int SOURCE, int BLOCK, short
VAL, cpiTime TS, int STATUS, int FLAGS, int TIMEOUT, cpiMsgID *ID);
VAL Digital value
TS Timestamp
Return values:
0 : OK
-22 : Invalid value
cpiSendSpaDigitalValueWithTS
This function sends a digital value with timestamp to the base system process database.
int cpiSendSpaDigitalValueWithTS(int DESTIN, int SOURCE, int BLOCK, short VAL,
VAL Digital value
TS Timestamp
Return values:
0 : OK
46
User’s Guide

-22 : Invalid value
cpiSendSpaDigitalValue
This function sends a digital value without timestamp to the base system process database.
int cpiSendSpaDigitalValue(int DESTIN, int SOURCE, int BLOCK, short VAL, int
VAL Digital value
TS Timestamp
Return values:
0 : OK
-7 : buffer full, the filling of the ACP message failed
-22 : Invalid value
cpiSendSpaIndicationWithTS
database.
int cpiSendSpaIndicationWithTS(int DESTIN, int SOURCE, int BLOCK, int BIT, int
VAL, cpiTime TS, int STATUS, int TIMEOUT, cpiMsgID *ID);
double indications
BVAL 16 bit value
TS Timestamp Timestamp
Return values:
0 : OK
47

User’s Guide

-22 : Invalid value
cpiSendSpaIndicationBlockWithTS
This function sends an indication value block with timestamp to the base system process
database.
int cpiSendSpaIndicationBlockWithTS(int DESTIN, int SOURCE, int BLOCK, int BVAL,
VAL Value of bit 0,1 for single indications,
BVAL 16 bit value
TS Timestamp
Return values:
0 : OK
-22 : Invalid value
cpiSendSpaIndication
This function sends an indication value to the base system process database.
int cpiSendSpaIndication(int DESTIN, int SOURCE, int BLOCK, int BIT, int VAL,
int STATUS, int TIMEOUT, cpiMsgID *ID);
BVAL 16 bit value
Return values:
0 : OK
-22 : Invalid value
48
User’s Guide
cpiSendSpaIndicationBlock
This function sends an indication value block to the base system process database.
int cpiSendSpaIndicationBlock(int DESTIN, int SOURCE, int BLOCK, int BVAL, int
10,11,12,13 for double indications
BVAL 16 bit value
Return values:
0 : OK
-22 : Invalid value
cpiSendSpaPulseCounterWithTS
This function sends a pulse counter value with timestamp to the base system process
database.
int cpiSendSpaPulseCounterWithTS(int DESTIN, int SOURCE, int BLOCK, long VAL,
TS Timestamp
Return values:
0 : OK
-22 : Invalid value
cpiSendSpaStatusMessage
This function sends an ACP formatted notification message to SYS600.
49

User’s Guide
int cpiSendSpaStatusMessage(int DESTIN, int SOURCE, int STYPE, int DATAVALID,

short STATUS );
SOURCE Destination connection number
STYPE Status type
0 -> Device status message
1 -> Terminal status message
2 -> Terminal event message
3 -> Terminal message
DATAVALID 0 -> Data is not longer valid in this spa unit.
1-> Data is valid in this spa
STATUS Status code
Return values:
0 : OK
-13 : No buffer -> cpi cannot get buffer for message
The following status codes are valid when the front-end emulates the SPA device (see
SYS600 Status Codes):
SPA status codes:
0 OK_STATUS
13201 SPAC_SC_DATA_OVERFLOW
13202 SPAC_TOO_LONG_REPLY_RECEIVED
13203 SPAC_SPA_ADDRESS_NOT_CONFIGURED
13204 SPAC_DEVICE_MUST_BE_ALLOCATED
13205 SPAC_UNKNOWN_DIAGNOSTIC_COUNTER
13206 SPAC_INVALID_INDEX_RANGE
13207 SPAC_INVALID_RT_ATTRIBUTE_VALUE
13208 SPAC_UNKNOWN_SPA_ATTRIBUTE
13209 SPAC_ILLEGAL_APPLICATION_FOR_OPERATION
13210 SPAC_ATTRIBUTE_IS_WRITE_ONLY
13211 SPAC_ILLEGAL_BROADCAST_ACTION
13212 SPAC_UNEXPECTED_RESPONSE
13213 SPAC_INVALID_ATTRIBUTE_VALUE
13214 SPAC_CHAR_TYPE_EXPECTED
13215 SPAC_INTERNAL_ERROR
13216 SPAC_INVALID_POINT_DEFINITION
13217 SPAC_DATABASE_UPDATE_COMPLETED
13218 SPAC_TOO_MANY_ARGUMENTS
13219 SPAC_ARGUMENT_EXPECTED
13220 SPAC_UNABLE_TO_ALLOCATE_MEMORY
50
User’s Guide
13221 SPAC_POINT_DEFINITION_NOT_FOUND
13222 SPAC_NO_ACKNOWLEDGE_RESPONSE
13223 SPAC_UNEXPECTED_VALUE_TYPE
13224 SPAC_ILLEGAL_OBJECT_TYPE
13225 SPAC_ONLY_WRITE_IS_POSSIBLE
13226 SPAC_NO_ACKNOWLEDGE_REPLY
13227 SPAC_EVENT_DATA_DISCREPANCY_DETECTED
13251 SPAP_DEVICE_SUSPENDED
13252 SPAP_DEVICE_STOPPED
13253 SPAP_DEVICE_STARTED
13254 SPAP_OUT_OF_BUFFERS
13255 SPAP_TIMEOUT_WHILE_WAITING_RESPONSE
13256 SPAP_UNEXPECTED_BC_REPLY
13257 SPAP_BROADCAST_FAILURE
13258 SPAP_DATABASE_UPDATE_COMPLETED
17201 SPCP_TIMEOUT_WHILE_WAITING_CTS
17202 SPCP_CTS_LINE_FAILURE_WHILE_TRANSM
17203 SPCP_REDUNDANCY_ERRORS_IN_RESPONSE
17205 SPCP_TIMEOUT_WHILE_WAITING_RESPONSE
17211 SPPC_INVALID_ATTRIBUTE_VALUE
Node level:
14016 NETW_UNKNOWN_DESTINATION_DEVICE
14018 NETW_UNKNOWN_DEVICE_ATTRIBUTE
cpiSendSpaMessage
This function sends an ACP formatted message to SYS600 from SPA. Before using this
function, the message buffer must be reserved by using the function
cpiGetTransmissionBuffer and formatted by using some of the cpiPutXXXData functions
int cpiSendSpaMessage(int DESTIN, int SOURCE, cpiMsgID ID, int TIMEOUT);
TIMEOUT Waiting time for the base system reply in milliseconds,
0-> no time-out supervision
51

User’s Guide
Return values:
0 : OK
-2 : Invalid MsgID
cpiSendSpaBitStream3
This function updates a bitstream process object in the base system process database.
int cpiSendSpaBitStream3(int DESTIN, int SOURCE, int ADDR, int LEN, char STREAM[]
, int STATUS, int TIMEOUT, cpiMsgID *ID);
LEN Length of bitstream in bits
STREAM Array of bits stored on the char array (Bitstream begins
from bit 0 of first char)
STATUS Status code for data (0 = OK)
FLAGS Status flags of the pulse counter
Return values:
0 : OK
-7 : Buffer full, the length of the bit stream is too long
cpiSendSpaBitStream3WithTS
This function updates a bitstream process object in the base system process database.
Timestamp of the process object is updated with a given time.
int cpiSendSpaBitStream3(int DESTIN, int SOURCE, int ADDR, int LEN, char STREAM[]
, int STATUS, cpiTime TS, int TIMEOUT, cpiMsgID *ID);
LEN Length of bitstream in bits
STREAM Array of bits stored on the char array (Bitstream begins
from bit 0 of first char)
STATUS Status code for data (0 = OK)
TS Timestamp
FLAGS Status flags of the pulse counter
Return values:
0 : OK
-7 : Buffer full, the length of the bit stream is too long
cpiSendBufferedSpaIndicationWithTS
database. The indication is marked with BE_SUBITEM, which can be used to indicate
that the data has been buffered in the application.
52
User’s Guide
int cpiSendSpaBufferedIndicationWithTS(int DESTIN, int SOURCE, int BLOCK, int

BIT,int VAL, cpiTime TS, int STATUS, int TIMEOUT, cpiMsgID *ID);
VAL VAL Value of bit 0,1 for single indications,10,11,12,13
for double indications
BVAL 16 bit value
TS Timestamp
Return values:
0 : OK
-22 : Invalid value
cpiSendSpaBufferedIndicationBlockWithTS
This function sends an indication value block with timestamp to the base system process
database. The indication is marked with BE_SUBITEM, which can be used to indicate
that the data has been buffered in the application.
int cpiSendSpaBufferedIndicationBlockWithTS(int DESTIN, int SOURCE, int BLOCK,
int BVAL, cpiTime TS, int STATUS, int TIMEOUT, cpiMsgID *ID);
BVAL 16 bit value
TS Timestamp
Return values:
0 : OK
-22 : Invalid value
5.5 Generic ACP packet building

All of the functions for sending RTU or SPA process data presented in the previous
section can be done manually by using the following functions. It is possible to build up
53

User’s Guide
messages with them also for special purposes, usually when the functions needed do not
exist. This can occur, for example, when several analog values need to be sent in a single
message.
Before any of the following packet building functions can be called, the buffer where
the message is going to be built up must be reserved by using the
cpiGetTransmissionBuffer function.
5.5.1 Message header information
In order to be able to emulate a conventional NET unit operation, the following functions
can be freely used for setting the logical destination and source.
Table 5.8: Message header source
cpiPutSource Sets the logical source of the message.
cpiPutDestination Sets the logical destination of the message.
cpiPutSource
With this function the logical source of the message can be set.
int cpiPutSource(cpiMsgID id, int SOURCE)
SOURCE SOURCE Source logical device, the following macro should
Type, deviceNumber)
Example:
;Setting the logical source for NET1:
cpiPutSource(id, LOGICAL_ADDRESS(NET_DEVICE,1));
Return values:
0 : OK
-5 : Unknown Message ID
cpiPutDestination
With this function the logical destination of the message can be set.
int cpiPutDestination(cpiMsgID id, int DESTINATION)
DESTINATION Destination logical device, the following macro should
Type,deviceNumber)
Example:
;Setting the logical destination for APL1:
cpiPutSource(id, LOGICAL_ADDRESS(APL_DEVICE,1));
Return values:
0 : OK
-5 : Unknown Message ID
54
User’s Guide
5.5.2 Data filling functions
The ACP message can be filled with the process data by using the following functions.
Table 5.9: Data filling functions
cpiPutData Puts data to the ACP message.
cpiPutRtuData Puts the process data with status to the ACP
message.
cpiPutRtuDataWithoutStatus Puts the process data without status to the ACP
message.
cpiPutRtuDataWithTS Puts the process data with timestamp to the
ACP message.
The object type determines also the type of the value. If the
object type is 0=NO_OBJECT_TYPE, the type of the value
is free.
cpiPutData
Puts data to the ACP message (See Table 5.1 and file cpi.h).
int cpiPutData(cpiMsgID id, cpiData *data)
cpiPutRtuData
This function adds the process data with status to the ACP message.
int cpiPutRtuData (cpiMsgID ID, cpiObjectType OT, int BLOCK, cpiData VAL, int
STATUS);
ID Identification number for message
OT Object type of RTU process object
BLOCK Object address of RTU process object
(1 ... 255)
VAL Value for process object
TS Time stamp
STATUS Status code
0 -> OK
Return values:
0 : OK
-2 : Invalid MsgID
-7 : Message buffer is full, adding the data has not suc-
ceeded
cpiPutRtuDataWithoutStatus
This function adds the process data without status to the ACP message.
int cpiPutRtuDataWithoutStatus(cpiMsgID ID, cpiObjectType OT, int BLOCK, cpiData
VAL);
55

User’s Guide

(1 ... 255)
TS Time stamp
STATUS Status code
0 -> OK
Return values:
0 : OK
-2 : Invalid MsgID
ceeded
cpiPutRtuDataWithTS
This function adds the process data with timestamp to the ACP message.
int cpiPutRtuDataWithTS (cpiMsgID ID, cpiObjectType OT, int BLOCK, cpiData VAL,
cpiTime TS, int STATUS);
(1 ... 255)
TS Time stamp
STATUS Status code
0 -> OK
Return values:
0 : OK
-2 : Invalid MsgID
ceeded
5.5.3 Reply status filling functions
Table 5.10: Reply status filling functions

cpiPutReplyStatus Adds the status of the reply to the reply mes-
sage.
cpiPutReplyStatus
The following function adds the status of the reply to the reply message. If the reply
status is OK, there is no need to use this function.
int cpiPutReplyStatus (cpiMsgID ID, int STATUS);
STATUS Status code
56
User’s Guide
Return values:
0 : OK
-2 : invalid MsgID
5.6 ACP packet unpacking

The message received from the SYS600 base system can be unpacked by using the
following functions.
5.6.1 Message header information
The following functions are used to read the header information of the received message.
See also Section 3.4 Application Communication Protocol (ACP).
Table 5.11: Message header information
cpiGetDestination Reads the station address of the destination node from
the message (CPI application node).
cpiGetSource Reads the station address of the source node from the
message (SYS600 node).
cpiGetRtuNo Reads the station number from the message.
cpiGetAttribute Reads the attribute from the message.
cpiGetIndex Reads the index from the message.
cpiGetReplyStatus Reads the reply status of the message.
cpiGetReplyDefinition Reads the reply definition of the message.
cpiGetMessageType Reads the type of the incoming message.
cpiGetMessageLength Reads the length of the received message.
cpiGetDeviceType Retrieves the logical device type message.
cpiGetDeviceNumber Retrieves the logical device number message.
cpiGetDestination
This function reads the station address of the destination node from the message (CPI
application node).
int cpiGetDestination( cpiMsgID ID, int *DESTIN);
ID Identification number for the message
DESTIN The CPI application node station address
Return values:
0 : OK
-5 : Invalid message buffer
57

User’s Guide
cpiGetSource
This function reads the station address of the source node from the message (SYS600
node).
int cpiGetSource( cpiMsgID ID, int *SOURCE);
SOURCE Station address of the source
Return values:
0 : OK
cpiGetRtuNo
This function checks which RTU station the message is meant to.
int cpiGetRtuNo(cpiMsgID ID, int *RTU);
RTU number
RTU RTU number
Return values:
0 : OK
cpiGetAttribute
This function reads the attribute of the message.
int cpiGetAttribute( cpiMsgID ID, char *ATTRIBUTE);
ATTRIBUTE Attribute of the message
Return values:
0 : OK
cpiGetIndex
This function reads the index of the message.
int cpiGetIndex( cpiMsgID ID, int *FIRST, int *LAST);
FIRST First index of the message
LAST Last index of the message
Return values:
0 : OK
58
User’s Guide
cpiGetReplyStatus
This function reads the reply status of the message.
int cpiGetReplyStatus( cpiMsgID ID, cpiMsgID *REPLYID, int *STATUS);
REPLYID Id of the reply message, which is a response for the
sent message
STATUS Status of the reply
Return values:
0 : OK
cpiGetReplyDefinition
This function reads the reply definition of the message.
int cpiGetReplyDefinition(cpiMsgID ID, cpiMsgHeader *HEADER);
HEADER Header information of the message
Return values:
0 : OK
cpiGetMessageType
This function reads the type of the message.
int cpiGetMessageType (cpiMsgID ID, int *MSGTYPE); 1=write, 2=read, 3=reply, 4=
notification
MSGTYPE Type of the incoming message
Return values:
0 : OK
cpiGetMessageLength
This function reads the length of the message.
int cpiGetMessageLength (cpiMsgID ID, int *LENGTH);
ID identification number for the message
LENGTH Length of the received message (the whole ACP message)
Return values:
0 : OK
cpiGetDeviceType
A new function will be implemented to retrieve the logical device type message.
59

User’s Guide
int cpiGetDeviceType(cpiMsgID *msg, int *deviceType)
Return values (constants defined in cpi.h):

APL_DEVICE = 1
NET_DEVICE = 2
RTU_DEVICE = 4
IEC_DEVICE = 29
cpiGetDeviceNumber
A new function will be implemented to retrieve the logical number message.
int cpiGetDeviceNumber(cpiMsgID *msg, int *deviceNumber)
Return values:
0 : OK
-1 : If fails
5.6.2 Data scanning functions
The data part of the message can be read with the following functions.
Table 5.12: Data scanning functions
cpiGetNextData Reads the next data item from the received
message.
cpiGetNextDataType Reads the type of the next item in the message.
cpiGetNextS32Data Reads the next item from the message.
cpiGetTimeData Retrieves the time information from the message
written in RTU_ATIME format.
cpiGetNextData
The following function reads the next data item from the received message. The function
is used to read items one by one from the message to the cpiData structure. The function
returns the value of the same type as the values in the message. Because the type of data
may vary between messages, the type information of cpiData must be used when the
data of the message is used by the CPI application program.
int cpiGetNextData (cpiMsgID ID, cpiData *VAL);
VAL Value (structure!)
Return values:
0 : OK
-1 : Connection error, the reading of the next item from
the message has failed.
More detailed information can be read from the global
variable cpi_errno. The explanations for cpi_errno values
can be read from the Status Codes manual.
-2 :Invalid MsgID
60
User’s Guide
-10 : No data items left in the buffer
cpiGetNextDataType
This function reads the type of the next item in the message. The function does not
remove the item from the message.
int cpiGetNextDataType (cpiMsgID ID, cpiDataType *VAL);
VAL Value
Return values:
0 : OK
the message has failed for some reason.
variable cpi_errno. The explanation for cpi_errno values
-2 : Invalid MsgID
cpiGetNextS32Data
The following function reads the next item from the message. The item is converted to
the long type. The items of the binary type cannot be read by using this function.
int cpiGetNextS32Data (cpiMsgID ID, long *VAL);
VAL VAL Value
Return values:
0 : OK
the message has failed for some reason.
variable cpi_errno. The explanation for cpi_errno values
-2 : Invalid MsgID
cpiGetTimeData
This function can be used to retrieve time information from the message written in
RTU_ATIME format.
int cpiGetTimeData(cpiMsg *msg, cpiTime *time);
Return values:
0 if ok
-1 if fails
61

User’s Guide
5.6.3 RTU commands
5.6.3.1 General handling
This function can be used to read command data from the message.
Table 5.13: Data scanning functions
cpiGetNextAddrData Reads the next Address Type item from the
message
cpiGetNextAddrData
The following function reads the next Address Type item from the message. This can
be used for unpacking the process commands from SYS600, which are sent via the
process database. All of the commands that are sent via the SYS600 process database
use the DA attribute and the Address Type data item. The data is divided into three parts:
object type, object address and object value.
int cpiGetNextAddrData (cpiMsgID ID, cpiData *VAL);
VAL Value (structure!)
Return values:
0 : OK : OK
-1 : : Connection error, the reading of the next item from
the message has failed.
variable cpi_errno. The explanations for cpi_errno values
-2 : Invalid MsgID
Example of use:
cpiGetAttribute(id, AT);
if (!strcmp(AT,"DA"))
/* compare AT to see if it is DA = command via process database*/
{
i = 0;
printf("DA message received \n");
while(cpiGetNextAddrData (id, &data) == 0) {
printf(" OT = %d", data.value.ADDR.ObjectType );
printf(" OA = %d", data.value.ADDR.ObjectAddress);
printf(" OV = %d\n", data.value.ADDR.ObjectValue);
switch(data.value.ADDR.ObjectType) {
case cpiOBJECT_COMMAND:
printf("Object Command received\n");
switch(data.value.ADDR.ObjectValue) {
case 0: printf("IMMEDIATE COMMAND OFF \n"); break;
case 1: printf("IMMEDIATE COMMAND ON \n"); break;
case 16: printf("INHIBIT COMMAND \n"); break;
case 17: printf("CHECK BACK COMMAND \n"); break;
case 32: printf("EXECUTE COMMAND OFF \n"); break;
62
User’s Guide
case 33: printf("EXECUTE COMMAND ON \n"); break;

}
break;
case cpiANALOG_SETPOINT:
printf("Analog Setpoint received\n");
break;
}
}
}
5.6.3.2 RTU object command handling
The (byte) value received when a command is activated is byte coded as shown in
Table 5.14 (see also the example of use in Section 5.6.3.1 General handling):
Table 5.14: The received values and descriptions
Object Command Status High Nibble Value Low Nibble Value
IMMEDIATE COMMAND 0
ON 1
OFF 0
CHECK BACK COMMAND 1
INHIBIT 0
CHECK 1
BACK
EXECUTE COMMAND 2
ON 1
OFF 0
Table 5.15: Regulation commands

Object Command Status
IMMEDIATE COMMAND 0 1/0
COMMAND STOP 3 Ignored
5.6.3.3 RTU analog setpoint handling
The value of the analog setpoint is stored into the ObjectValue field of the cpiData
structure.
5.7 Communication supervision

Table 5.16: Communication supervision
cpiConnectionStatus Checks the status of an application connection.
63

User’s Guide
cpiConnectionStatus
This function checks the status of an application connection. It also returns the status
code of the last reply message, if it is rejected by the base system.
int cpiConnectionStatus (int DESTIN);
DESTIN Connection number of the destination
Return values:
0 : OK
1 : Waiting connection
others : Refer to the Status Codes manual
5.8 Buffer management

The following functions reserve buffers for different message types.
Table 5.17: Buffer management
cpiGetTransmissionBuffer Reserves a buffer for transmission.
cpiGetReplyBuffer Reserves a buffer for a reply message transmis-
sion.
cpiGetDefinedReplyBuffer Reserves a buffer for a reply message.
cpiGetNotificationBuffer Reserves a buffer for a notification message.
cpiGetTransmissionBuffer
This function reserves a buffer for transmission. The function returns with an error status
if the transmission queue is full or if the failed transmission queue contains messages.
The length of the transmission queue is 1 in this version, so the previously sent message
must get a reply from the base system before a new buffer can be reserved.
int cpiGetTransmissionBuffer(int CON, cpiMsgID *ID);
CON Connection number of the destination
ID Id for a message buffer
Return values:
0 : OK
-13 : No buffers left
-20 : Connection is still waiting for a reply for the previ-
ously sent message
cpiGetReplyBuffer
This function reserves a buffer for a reply message transmission. It is used when it is
possible to send the reply message back to the base system immediately.
int cpiGetReplyBuffer(cpiMsgID RQ, cpiMsgID *ID);
RQ Id of the message which is a response for the sent mes-
sage
64
User’s Guide
ID Id for a reply message
Return values:
0 : OK
-15 : Invalid source ID
cpiGetDefinedReplyBuffer
This function reserves a buffer for a reply message. It is used when the reply message
cannot immediately be sent back to the base system.
int cpiGetDefinedReplyBuffer(cpiMsgHeader *HEADER, cpiMsgID *ID);
HEADER Header data of the message to which this message is a
reply
ID Id for a reply message
Return values:
0 : OK
-13 : no buffers left
cpiGetNotificationBuffer
This function reserves a buffer for a notification message. It is used to send system status
messages to the base system.
int cpiGetNotificationBuffer(int CON, cpiMsgID *ID);
CON Destination connection
ID Id for reply message
Return values:
0 : OK
5.9 Initializations
Table 5.18: Initializations
cpiInitThisNode Initialises data of this node.
cpiInitRemoteNode Gives information of the SYS600 node to CPI.
cpiCreateConnection Creates a connection and starts the communic-
ation between CPI and SYS600.
cpiCloseConnection Removes the connection between CPI and
SYS600.
These functions initialize the TCP/IP connections between the SYS600 applications and
the CPI application program. Figure 5.1 explains what kind of initialization is needed
when connecting CPI to SYS600.
65

User’s Guide
Figure 5.1: Initialisation needed when connecting CPI to SYS600.
Example of initialization needed for CPI:

basesystem.sin_family = AF_INET;
basesystem.sin_port = SPIDERSERVER;
strcpy(&basesystem.sin_addr,”192.00.00.100”);
cpiInitThisNode(202, 2);
cpiInitRemoteNode(basesystem, 209, 9);
cpiCreateConnection(9, 1, &con1);
cpiCreateConnection(9, 5, &con2);
CPI sends an analog value from RTU2 to application 1 by using the following function:
cpiSendAnalogValue(con1, 2, block, val, status, &ID);
cpiInitThisNode
This function initializes the data of this node.
int cpiInitThisNode(cpiNodeAddress SA, cpiNodeNumber NA);
SA Node address of this socket (1...254).
NA Node number of this socket (1...250)
Return values:
0 : OK
-26 : Invalid data
cpiInitRemoteNode
This function gives information of the SYS600 node to CPI.
int cpiInitRemoteNode(cpiTCPIPAddress TA, cpiNodeAddress NA, cpiNodeNumber NN);
TA SYS600 TCP/IP address
66
User’s Guide
NA Node address of SYS600 socket (1...254)

NN Node number of SYS600 (1...250)
Return values:
0 : OK
-1 : Connection error
-8 : Invalid address
-14 : Invalid node
-17 : Invalid tcp address
cpiCreateConnection
This function creates a connection and starts the communication between CPI and
SYS600.
int cpiCreateConnection( cpiNodeNumber NN, int AN, int *CN,);
NN Node number of SYS600
AN Application number in SYS600, where this connection is
created.
CN Connection number. This return value is used as a destin-
ation number when sending messages to SYS600.
Return values:
0 : OK
-1 : Connection error
-14 : Invalid node number
cpiCloseConnection
This function removes the connection between CPI and SYS600.
int cpiCloseConnection(int CN);
CN Connection number
Return values:
0 : OK
-1 : Connection error, invalid connection number
5.10 Bitset functions

The following functions are used to handle the bitset data type. The bitset data type is
used in the cpiSelect function.
Table 5.19: Bitset functions
cpiSET Sets one bit in a bit set.
cpiCLR Clears one bit from a bit set.
cpiISSET Checks the value of one bit and returns it.
67

User’s Guide
cpiSET
This function sets one bit in the bit set.
int cpiSET(int BIT, cpiBitSet *BITSET)
BIT A number of bit which is set to 1, (0 = first bit)
BITSET Bitmask to use with cpiSelect
Return values:
0 : If the tested bit does not belong to the bitset
1 : If the tested bit belongs to the bitset
cpiCLR
This function clears one bit from the bit set.
int cpiCLR(int BIT, cpiBitSet *BITSET)
BIT A number of bit which is cleared to 0, (0 = first bit)
BITSET Bitmask to use with cpiSelect
Return values:
cpiISSET
This function checks the value of one bit and then returns it.
int cpiISSET(int BIT, cpiBitSet *BITSET)
BIT A number of bit whose state is tested
BITSET Tested bit mask
Return values:
68
User’s Guide
6 Support for System Configuration Tool
This chapter provides instructions on how to provide support for the CPI communication
protocol configuration in the System Configuration Tool.
When using the System Configuration Tool for configuring

the CPI application program, the SYS600 base system revision
needs to be 8.4.3 or newer.
Definitions:
• Configuration attribute: a value that is stored into the permanent protocol
configuration file by the System Configuration Tool. This value is later utilised
when the CPI application protocol is started in SYS600.
• Attribute definitions: the information about all the CPI configuration attributes. It
includes names, data types, data structures, description texts, help texts and
description texts for different attribute values of all CPI configuration attributes to
be used by the System Configuration Tool.
Dependencies on other systems

The base system and communication system are configured during system start-up by
using the functionality included in the System Configuration Tool. The CPI application
program utilizes its own permanent protocol configuration file during start-up. For more
information about base system configuration, see Chapter 3 CPI overview.
6.1 Functionality
The included CPI protocols are recognised from the SYS600 computer in System
Configuration Tool based on following requirement:
Under \sc\prog folder, each sub-folder is assumed to be named according to the CPI
application program, if
• it includes the permanent protocol configuration file named Config.ini.
• it includes the attribute definitions file named Attr_Def.scl.
• it includes the attribute mappings file named Attr_Map.ini.
The station type to be attached into the CPI protocol communication line is either RTU
or SPA.
The CPI application program, i.e. the executable file, may either exist in the same
computer where the System Configuration Tool is running or on an external computer.
However, the permanent protocol configuration file, attribute definitions and mappings
files need to exist in a sub-folder under the \sc\prog folder on the same computer where
the System Configuration Tool is being used. If the CPI application program is running
on an external computer, one of its drives can be mapped through LAN to the computer
69

User’s Guide
in which SYS600 is running. Through this kind of drive mapping, the files for configuring
CPI application program are located only in the SYS600 computer. The protocol to be
used for the CPI application program is concluded from the sub-folder name under the
\sc\prog folder.
Figure 6.1 shows the MODBUS SLAVE communication protocol included in system
configuration. The folder \sc\prog\modbus_slave exists in SYS600 computer, where the
System Configuration Tool is located. The name of the protocol is displayed as MODBUS
SLAVE in the object tree (the included underscore character is removed and the sub-folder
name is uppercased).
Figure 6.1: The CPI protocol in the Object Tree of the System Configuration Tool
The permanent protocol configuration file must be named Config.ini. This file contains
the configuration parameters to be used by the CPI application program. The format of
this file follows the Windows Initialisation File Format specification. Those parameters,
which are shown and configured in the System Configuration Tool as a property of the
CPI communication line, should be included under the section name Configuration.
The attribute definitions file must be named Attr_Def.scl. This file contains e.g. limit
values and descriptions for the configuration parameters to be used by the System
Configuration Tool. The format of the file follows the SCIL syntax.
6.2 Permanent protocol configuration file

The format of this file follows the Windows Initialisation File Format specification. All
the configuration attributes, that are needed to be shown in the System Configuration
Tool, need to exist as key names and values under the section name Configuration. Other
section names may be used to store CPI application program related information, which
does not needed to be shown in the System Configuration Tool.
[Configuration]
key_name_1=key value 1
…
key_name_n=key name i
[Section_name_2]
…
key_name_n=key name n
…
70
User’s Guide
[Section_name_m]
…
key_name_n=key name n
The key name is the same as the attribute name in the Attribute definitions file
Attr_Def.scl.
Example of Config.ini
[Configuration]
own_node_number=4
own_station_number=204
base_system_node_number=9
base_system_station_number=209
tcp_ip_address=194.142.148.36
application_number=1
communication_port_name=COM1
baud_rate=9600
parity=0
stop_bit_count=0
data_bit_count=8
flow_control=0
6.3 Attribute definitions file

The format of each attribute definition follows the SCIL syntax. The following common
definitions are valid for all data types:
<Attribute name> = LIST(-
data_type=<attribute data type>,-
modifiable=<attribute editable>,-
descriptive_text=<name text for attribute>,-
default_value=<default value for attribute>,-
help_text=<help text for attribute>)
The name of the attribute is unique for all the CPI configuration attributes. All spaces
must be replaced with the underscore character. For example, the attribute TCP/IP
Address is presented as TCP_IP_ADDRESS as valid CPI attribute name for the System
Configuration Tool.
Possible data types for the attributes are:
• Integer
• Real
• Text
• Time
• Boolean
If an attribute is modifiable, the value is TRUE. Otherwise the attribute value is FALSE.
If the attribute is defined to be modifiable, its value can be edited in the edit area of the
System Configuration Tool. If the attribute is non-modifiable, the editing of the attribute
is disabled in the edit area of the System Configuration Tool. Figure 6.2 shows the
71

User’s Guide
Attribute Tree of the System Configuration Tool, where all the CPI attributes are included
in the View named All Attributes and under a group name CPI Configuration Attributes.
Figure 6.2: The Attribute Tree and Edit area of the System Configuration Tool
The Attribute Tree uses descriptive text. When a CPI attribute has been selected in the
object tree, the Status bar (in Figure 6.3) displays the help text at the bottom of the System
Configuration Tool.
Figure 6.3: The Status bar
A default value is utilised for an attribute, when the CPI application protocol is added
into the System Configuration Tool. It is possible for to change the attribute value
according to its attribute definitions by using the edit area.
Definitions for different attribute data types

Table 6.1: Integer
INTEGER
Attribute definition Description data type Example
Data_type TEXT ”INTEGER"
Min_value INTEGER 1
Max_value INTEGER 7
Modifiable BOOLEAN TRUE
Special_values VECTOR of INTEGERs (1, 3, 7)*
Value_descriptions VECTOR of TEXTs (”Not in Use”, ”Synhcronised”, ”Asyn-
chronised”)*
Descriptive_text TEXT "Example Integer Attribute"
72
User’s Guide
Default_value INTEGER 3
Help_text TEXT "This is an example of an integer attrib-
ute."
Table 6.2: Real

REAL
Data_type TEXT ”REAL”
Min_value REAL 1.0
Max_value REAL 1.5
Descriptive_text TEXT “Example Real Attribute”
Default_value REAL 1.1
Help_text TEXT “This is an example of a real attribute.”
Table 6.3: Text

TEXT
Data_type TEXT ”TEXT”
Min_length INTEGER 4
Max_length INTEGER 5
Descriptive_text TEXT “Example Text Attribute”
Default_value TEXT ”COM1”
Help_text TEXT “This is an example of a text attribute.”
Table 6.4: Time

TIME
Data_type TEXT ”TIME”
Min_value TIME Pack_time(1978,1,1,0,0,0)**
Max_value TIME Pack_time(2045,12,31,23,59,59)**
Descriptive_text TEXT “Example Time Attribute”
Default_value TIME Pack_time(1999,12,20,12,0,0)**
Help_text TEXT “This is an example of a time attrib-
ute.”
Table 6.5: Boolean

BOOLEAN
73

User’s Guide
Data_type TEXT ”BOOLEAN”

Descriptive_text TEXT “Example Boolean Attribute”
Default_value BOOLEAN TRUE
Help_text TEXT “This is an example of a boolean attrib-
ute.”
* The VECTOR data type can be recognised from the parentheses around the enumerated
INTEGER or TEXT values. If only one item is included in the VECTOR, there is a need
to specifically use the VECTOR statement around the attribute value, VECTOR(1)
** The PACK_STR is a SCIL function, which can be used to convert the year/month/day
and hour/minute/seconds representation to the TIME data type format of SCIL. E.g.
PACK_STR(YEAR, MONTH, DAY,HOUR,MINUTE,SECOND).
Example of Attr_Def.scl
#create GL_ATTRIBUTES:V = LIST(-
OWN_NODE_NUMBER = LIST(-
data_type=”INTEGER”,-
min_value=1,-
max_value=99,-
modifiable=TRUE,-
descriptive_text=”Own Node Number”,-
default_value=4,-
help_text=”Specifies the own node number to be
used in CPI application program.”),-
OWN_STATION_NUMBER = LIST(-
min_value=1,-
max_value=255,-
modifiable=TRUE,-
descriptive_text=”Own Station Number”,-
default_value=204,-
help_text=”Specifies the own station number to
be used in CPI application program.”),-
BASE_SYSTEM_NODE_NUMBER = LIST(-
min_value=1,-
max_value=99,-
modifiable=TRUE,-
descriptive_text=”Base System Node Number”,-
default_value=9,-
help_text=”Specifies the base system node number
to be used in CPI application program.”),-
BASE_SYSTEM_STATION_NUMBER = LIST(-
min_value=1,-
max_value=255,-
modifiable=TRUE,-
descriptive_text=”Base System Station Number”,-
74
User’s Guide
default_value=209,-
help_text=”Specifies the base system station
number to be used in CPI application program.”),-
TCP_IP_ADDRESS = LIST(-
data_type=”TEXT”,-
min_length=7,-
max_length=15,-
modifiable=TRUE,-
descriptive_text=”TCP/IP Address”,-
default_value=”192.142.148.36”,-
help_text=”Specifies the TCP/IP address to be
used in CPI application program.”),-
APPLICATION_NUMBER = LIST(-
min_value=1,-
max_value=99,-
modifiable=TRUE,-
descriptive_text=”Application Number”,-
default_value=1,-
help_text=”Specifies the application number,
where CPI application program is running.”),-
COMMUNICATION_PORT_NAME = LIST(-
data_type=”TEXT”,-
min_length=4,-
max_length=5,-
modifiable=TRUE,-
descriptive_text=”Communication Port Name”,-
default_value=”COM1”,-
help_text=”Specifies the communication port
name, which CPI application program is
utilising.”))
#return %GL_ATTRIBUTES
The format of this file needs to follow the SCIL syntax. There
is always a risk that due to a typing error the Attr_Def.scl file
is not applicable to the SCIL syntax. In the SCIL Editor, it is
possible to define the Syntax Check mechanism into use
automatically during the saving operation by selecting Options
– Check Syntax at Save. Therefore, the editing this file should
be done by using the SCIL Editor.
6.4 Attribute mappings file

The section name refers to the SYS600 object where the attribute name belongs.
[NODE] Base System Node Object (NOD:B)
[NODE_LINK] Communication Line Object (NET:S)
75

User’s Guide
[STATION] Communication Station (STA:S)

Object
The key name in this file is the same as the attribute name in the attribute definitions
file, as well as the key name in the permanent protocol configuration file. The key value
in this file represents the two-char attribute name to be used for defining the property to
the SYS600 object.
For example, if a key name own_station_number with a key value SA exists inside the
NODE section, it means that the configuration attribute is referenced to the NOD’n’:BSA
attribute in SYS600, where ’n’ equals the node number object.
Example Attr_Map.ini
[NODE]
own_station_number=SA
[NODE_LINK]
communication_port_name=SD
baud_rate=BR
stop_bit_count=SB
[STATION]
in_use=IU
76
User’s Guide
7 Terminology
Term Description
Application Communic- An internal protocol of SYS600 that is generally used in communication
ation Protocol (ACP) between the SYS600 nodes.
ACP Message Communication between the SYS600 nodes is implemented by using
ACP. It supports three types of message dialogs: write commands, read
commands and notifications.
Attribute Individual data items that form a part of an object are called attributes.
Each object has a set of attributes that store information and describe
the qualities of the object. Attributes contain, for example measured
values, texts, program lines, time stamps etc. depending on the object
type.
Base System The Base System offers services to the applications. It provides database
structures, database handling mechanisms and file handling functionality.
The Base System also offers an application programming interface for
attaching functions as separate programs.
BSD Socket Socket interface defined in the Unix version developed by Berkeley
Software.
Communication Pro- Protocol environment software that is used for externally implemented
gramming Interface protocol converters. The CPI Library is a collection of functions for
(CPI) and CPI Library sending and receiving message to or from the SYS600 base system, as
well as functions for packing and unpacking data of messages.
CPI Application Pro- In some cases called a Gateway program.
gram An application program made by using the CPI interface exchanges data
between SYS600 and a foreign system. It emulates the NET containing
stations of the RTU, SPA or SPI device type.
Communication Sys- Handles the data transmission in the SYS600 system as well as between
tem the devices. The communication can be divided into upper level commu-
nication and process communication.
Local Area Network Used for upper level communication between the base system and
workplaces. It has a large capacity for data transmission.
Message Buffer A place in the memory to store the ACP messages to or from the SYS600
base system. The CPI Buffer Management functions reserve buffers for
different message types.
NET SYS600 communication unit.
NET Emulation A CPI application program that resembles the behaviour of the NET unit.
Node Communication object in SYS600, for example, the SYS600 base system
or a CPI application program.
Node Number A unique identifier of a node.
Open System Connec- A model for network architecture standardised by ISO.
tion (OSI)
Protocol A protocol is a set of rules and conventions for transmitting information
in the network. They govern the content, format, timing, sequencing and
error control of messages.
RTU Remote Terminal Unit
77

User’s Guide
SCIL A high level language especially designed for composing customized,

process specific supervisory control software. Data transmission from
the base system to the CPI application program is done by setting the
attributes of the communication system objects or process objects.
SPA Device A SPACOM module connected to SYS600 is seen as a SPA device.
System Configuration Manages the configuration of the base system and the NET communic-
Tool ation unit.
TCP/IP Transmission Control Protocol/Internet Protocol, used for data transmis-
sion in the LAN network to provide communication with several protocols
across the connected networks of computers.
Thread An independent part of the program that is active until it stops itself or it
is stopped by the main program. Threads can be used to isolate tasks.
Usually, a foreign protocol is implemented as a thread.
78
User’s Guide
8 Abbreviations
Abbreviation Description
ACP Application Communication Protocol
Communication Pro- Communication Programming Interface, a protocol environment software
gramming Interface that is used for externally implemented protocol converters. The CPI
(CPI) and CPI Library Library is a collection of functions for sending and receiving message to
or from the SYS600 base system, as well as functions for packing and
unpacking data of messages.
ISO International Standards Organization
LAN Local Area Network
OSI Open System Interconnection
RTU Remote Terminal Unit
SCIL Supervisory Control Implementation Language
TCP/IP Transmission Control Protocol/Internet Protocol
79
User’s Guide
Index
A
ACP .................................................... 13, 28, 77, 79
ACP-OSI ................................................... 15, 77, 79
ACP protocol messages ........................... 14–15, 77
Analog setpoint ..................................................... 23
Application Communication Protocol .................... 13
Application Programming ............................... 22, 24
Attr_Def.scl ........................................................... 70
Attr_Map.ini .......................................................... 69
Attribute definitions ............................................... 69
Attributes ........................................................ 17, 77
Attribute Tree ........................................................ 72
B
Base system ......................................................... 77
Base System Configuration ...................... 18, 22, 24
Base System Node Object ................................... 75
Bit position ............................................................ 29
Boolean ................................................................ 72
BSD socket ....................................................... 8, 77
C
Cause of exception ............................................... 29
Communication
attributes ........................................................... 15
system .............................................................. 77
Communication Line Object ................................. 75
Communication Station Object ............................. 75
Config.ini ............................................................... 70
Configuration attributes .................................. 14, 69
Connections
CPI application program as a master ............... 22
CPI application program as a slave .................. 24
Connection status ................................................. 29
Converting messages ..................................... 23, 25
CPI ........................................................................ 79
CPI_EXAMPLE .............................................. 23, 25
CPI application program ....................................... 77
81

User’s Guide
CPI Library ...................................................... 27, 79 cpiSendRtuIndication ................................. 22, 39

cpiClearExceptionStatus .................................. 34 cpiSendRtuIndicationBlock ............................... 40
cpiCloseConnection ......................................... 67 cpiSendRtuIndicationWithTS ............................ 40
cpiCLR .............................................................. 68 cpiSendRtuMessage .................................. 17, 30
cpiConnectionStatus ........................................ 64 cpiSendRtuPulseCounter ........................... 22, 42
cpiCreateConnection ........................................ 67 cpiSendRtuPulseCounterWithTS ..................... 42
cpiException ..................................................... 29 cpiSendRtuStatusMessage .............................. 37
cpiGetApplicationCold ...................................... 34 cpiSendSpaAnalogValue .................................. 45
cpiGetAttribute ............................................ 25, 58 cpiSendSpaAnalogValueWithTS ...................... 45
cpiGetDefinedReplyBuffer ................................ 65 cpiSendSpaAnalogValueWithTSandFlags ....... 44
cpiGetDestination ............................................. 57 cpiSendSpaBitStream3 .................................... 52
cpiGetDeviceType ............................................ 59 cpiSendSpaBitStream3WithTS .................. 52–53
cpiGetFailedMessage ....................................... 35 cpiSendSpaDigitalValue ................................... 47
cpiGetIndex ................................................ 25, 58 cpiSendSpaDigitalValueWithTS ....................... 46
cpiGetMessage ................................................ 33 cpiSendSpaDigitalValueWithTSandFlags ........ 46
cpiGetMessageLength ..................................... 59 cpiSendSpaIndication ....................................... 48
cpiGetMessageType ......................................... 59 cpiSendSpaIndicationBlock .............................. 49
cpiGetNextAddrData .................................. 25, 62 cpiSendSpaIndicationBlockWithTS .................. 48
cpiGetNextData .......................................... 25, 60 cpiSendSpaIndicationWithTS ........................... 47
cpiGetNextDataType .................................. 25, 61 cpiSendSpaMessage ....................................... 51
cpiGetNextS32Data .................................... 25, 61 cpiSendSpaPulseCounterWithTS .................... 49
cpiGetNotificationBuffer .................................... 65 cpiSendSpaStatusMessage ............................. 49
cpiGetReplyBuffer ...................................... 30, 64 cpiSendStandardSystemMessage ................... 31
cpiGetReplyDefinition ....................................... 59 cpiSendStandardUserActivityMessage ............ 33
cpiGetReplyStatus ...................................... 17, 59 cpiSET .............................................................. 68
cpiGetRtuNo ............................................... 25, 58 cpiSetApplicationCold ...................................... 34
cpiGetSource .................................................... 58 cpiSetNetMessageFiltering .............................. 36
cpiGetTimeData ................................................ 61
cpiGetTransmissionBuffer ........ 17, 30, 51, 54, 64 D
cpiGiveUp ......................................................... 35
cpiInitRemoteNode ..................................... 13, 66 Data transfer ................................................... 22, 25
cpiInitThisNode ................................................. 66 Data Types ..................................................... 71–72
cpiISSET .......................................................... 68 Deleting messages ............................................... 35
cpiNetMessageFiltering .................................... 36 Device level routing .............................................. 15
cpiPutData ........................................................ 55 Digital setpoint ...................................................... 23
cpiPutDestination ............................................. 54
cpiPutReplyStatus ............................................ 56 E
cpiPutRtuData .................................................. 55
cpiPutRtuDataWithoutStatus ............................ 55 Edit Area ............................................................... 72
cpiPutRtuDataWithTS ...................................... 56 Emulation ........................................................ 11, 77
cpiPutSource .................................................... 54 Example Attr_Map.ini ........................................... 76
cpiPutXXXData ........................................... 30, 51 Example of Attr_Def.scl ........................................ 74
cpiRetransmitMessage ..................................... 35 Example of Config.ini ........................................... 71
cpiSelect ..................................................... 11, 29 EX connection ...................................................... 29
cpiSendBufferedSpaIndicationWithTS ............. 52
cpiSendMessage ........................................ 17, 30 F
cpiSendNodeSystemMessage ......................... 32
cpiSendNodeSystemMessageWithBinary ........ 33 Failed message .................................................... 35
cpiSendRtuAnalogValue ............................. 22, 41 Failed Message .................................................... 35
cpiSendRtuAnalogValueWithTS ....................... 41 Fields .................................................................... 15
cpiSendRtuBitStream ................................. 23, 43 Functionality ......................................................... 69
cpiSendRtuDigitalValue .............................. 22, 25 Functions .............................................................. 27
82
User’s Guide
G P
Gateway program ............................................. 7, 77 Packet
General persistent output ..................................... 23 building ............................................................. 53
GetDeviceNumber ................................................ 60 unpacking ......................................................... 57
Program files ........................................................ 27
I Protocol .......................................................... 21, 77
Protocol Converter ............................................... 21
Implementation of the foreign protocol ................. 23 Protocol Implementation ....................................... 25
Infinite loop ........................................................... 11
Integer .................................................................. 72 R
K RD connection ...................................................... 29
Read commands .................................................. 14
Key name ....................................................... 71, 76 Real ...................................................................... 72
Regulation command ........................................... 23
L Reserved attributes .............................................. 17
Revision ................................................................ 69
LAN ................................................................... 8, 77 Routing ................................................................. 15
Location of files ..................................................... 70 RP 570 slave device ............................................. 23
Low level message routing ................................... 15 RTU Object Model ................................................ 37
RTU station ......................................... 18, 69, 77, 79
M
S
Memory management .......................................... 13
Message SCIL .......................................................... 14, 78–79
buffers ........................................................ 13, 77 SPA device ..................................................... 69, 78
conversion .................................................. 23, 25 Status Bar ............................................................. 72
dialogues .......................................................... 14 Status codes
failure types ...................................................... 17 RTU .................................................................. 38
Modbus Slave ....................................................... 70 SPA ................................................................... 50
SYS_BASCON.COM ............................................ 18
N System Configuration Tool ............................. 69, 78
System Start-Up ................................................... 69
Naming of files ...................................................... 70
NET ................................................................. 11, 77 T
NET emulation ................................................ 11, 77
Node ................................................... 13, 22, 57, 77 TCP/IP .................................................. 8, 29, 78–79
Node number ........................................................ 77 Text ....................................................................... 72
Notifications .......................................................... 14 Thread ............................................................ 23, 78
Time ...................................................................... 72
O Transmission error handling ................................. 17
Type definitions .................................................... 27
Object command .................................................. 23
Object type of command ...................................... 23 W
OSI ....................................................................... 15
WR connection ..................................................... 29
Write commands ................................................... 14
83
Contact us
1MRS758104 A/16.5.2014 © Copyright 2014 ABB. All rights reserved.

ABB Oy
Substation Automation Products
P.O. Box 699
FI-65101 Vaasa
FINLAND
Tel. +358 10 22 11
Fax. +358 10 224 1094
www.abb.com/substationautomation

SYS600 - Communication Programming Interface

Uploaded by

SYS600 - Communication Programming Interface

Uploaded by

MicroSCADA Pro SYS600 9.

3 CPI overview .......................................................................................... 11

4 Creating protocol converters with CPI ............................................... 21

5 CPI library .............................................................................................. 27

Communication Programming Interface (CPI)

5.9 Initializations ................................................................................. 65

6 Support for System Configuration Tool .............................................. 69

2.1 This manual

Communication Programming Interface (CPI)

2.2 Use of symbols

Warning icon indicates the presence of a hazard which could

Caution icon indicates important information or a warning

Information icon alerts the reader to relevant factors and

Tip icon indicates advice on, for example, how to design a

2.3 Related documents

2.4 Document conventions

Communication Programming Interface (CPI)

2.5 Document revisions

3.1 NET unit emulation with CPI

3.2 Operating principle

Communication Programming Interface (CPI)

/* processing of the write message */

/* processing for the read message */

/* processing for the reply message */

/* Example 2, how to send data to the base system */

cpiSelect( &in_set, &out_set, &exp_set);

/* Sending of an indication value */

/* Checking the reply message */

/* Testing the possible exceptions*/

3.3 Memory management

3.4 Application Communication Protocol (ACP)

Communication Programming Interface (CPI)

Figure 3.2: Message dialogues supported in the ACP communication

The ACP network layer consists of two sublayers:

Communication Programming Interface (CPI)

Field Description CPI function

SET Message type (command + FNC write)

Reading data from the application:

@A Message type (command + read)

(10) First index

3.5 Transmission error handling

Communication Programming Interface (CPI)

3.6 Base system configuration

; BASE SYSTEM CONFIGURATION TEMPLATE

#CREATE SYS:B = LIST(-

#CREATE LIN:V = LIST(- ;REQUIRES TCP/IP

#CREATE NOD:V = LIST(-

Communication Programming Interface (CPI)

PR = (1,2,3)) ;PRINTER MAPPING

#CREATE STA1:B = LIST(-

#CREATE STA2:B = LIST(-

4 Creating protocol converters with CPI

4.1 Slave devices connected to SYS600 via CPI

Communication Programming Interface (CPI)

SYS600 base system configuration

Application programming in SYS600

BitStream values: cpiSendRtuBitStream

Converting messages between CPI and the foreign protocol

Implementation of the foreign protocol

4.2 Master device connected to SYS600 via CPI

Communication Programming Interface (CPI)

SYS600 base system configuration

Application programming in SYS600

Data transfer with SYS600 using the CPI library

Converting messages between the CPI and the foreign protocol

Implementation of the foreign protocol

typedef unsigned char cpiObjectType;

Communication Programming Interface (CPI)

unsigned char U8;

5.1 Basic ACP Communications

int cpiSelect(cpiBitSet *RD, cpiBitSet *WR, cpiBitSet *EX, long MS);

RD Received message flags (max 16 connections)

Communication Programming Interface (CPI)

DESTIN Destination connection number

DESTIN Destination connection number

Communication Programming Interface (CPI)

int cpiSelect(cpiBitSet RD, cpiBitSet WR, cpiBitSet *EX, long MS);

int cpiGetMessage( int SOURCE, cpiMsgID ID, MSGTYPE);

int cpiGetDeviceType(cpiMsgID msg, int deviceType)