Channel-API Specification - · PDF fileSIEMENS AG Automatisierungstechnik A&D PT1 D2 WinCC Channel Developers Kit Channel-API Specification Date 29.02.2000 Version 5.0 File < WinCC\ChnDk\Manuals\ChnAPI5.doc

$Page 1: Channel-API Specification - · PDF fileSIEMENS AG Automatisierungstechnik A&D PT1 D2 WinCC Channel Developers Kit Channel-API Specification Date 29.02.2000 Version 5.0 File < WinCC\ChnDk\Manuals\ChnAPI5.doc$
SIEMENS AGAutomatisierungstechnik

A&D PT1 D2

WinCCChannel Developers Kit

Channel-API Specification

Date29.02.2000

Version5.0

File< WinCC\ChnDk\Manuals\ChnAPI5.doc

Page1 of 111

Copyright SIEMENS AG 1994-2000All Rights Reserved.



A&D PT1 D2



Date29.02.2000

Version5.0


Page2 of 111


Table of Contents1 API OF THE CHANNEL SCHEDULING.....................................................................................................7

1.1 INTEGRATION OF A CHANNEL INTO THE WINCC SYSTEM STRUCTURE.............................................................71.2 GENERAL...................................................................................................................................................8

1.2.1 Conventions......................................................................................................................................81.2.1.1 Name conventions....................................................................................................................................... 8

1.2.1.1.1 Allocation of names of a channel-DLL .................................................................................................. 81.2.1.1.2 Allocation of names for language DLLs ................................................................................................ 8

1.2.2 Error recovery in the API functions...................................................................................................91.2.3 Channel-DLL with several units......................................................................................................101.2.4 Storage of a channel unit................................................................................................................101.2.5 Virtual connections .........................................................................................................................11

1.2.5.1 General manipulation of a virtual connection............................................................................................. 111.2.5.2 Channel-specific expansion of a virtual connection................................................................................... 111.2.5.3 Data structure of a virtual connection ........................................................................................................ 12

1.2.5.3.1 Status of a virtual connection.............................................................................................................. 131.2.5.3.2 Properties of a virtual connection ....................................................................................................... 13

1.2.5.3.2.1 Write and/or rcead access released ............................................................................................ 141.2.5.3.2.2 Define behaviour with regard to time synchronization ................................................................. 14

1.2.6 WinCC-variable...............................................................................................................................141.2.6.1 General manipulation of a WinCC-variable ............................................................................................... 141.2.6.2 Channel-specific expansion of a WinCC-variable...................................................................................... 141.2.6.3 Data type of a WinCC-variable .................................................................................................................. 151.2.6.4 Data structure of a WinCC-variable........................................................................................................... 16

1.2.6.4.1 Channel unit-relevant status bits of a variable .................................................................................... 171.2.7 Runtime mode and Configuration mode.........................................................................................18

1.3 API FUNCTIONS OF A CHANNEL .................................................................................................................181.3.1 Initialization of a channel ................................................................................................................19

1.3.1.1 Initialization of a channel during loading.................................................................................................... 191.3.1.2 Interrogation of the entry points of the channel-DLL.................................................................................. 191.3.1.3 Interrogation of the number of supported units.......................................................................................... 211.3.1.4 Interrogation of the properties of a channel unit ........................................................................................ 21

1.3.1.4.1 Property bit CHNCAP_OWNCYCLE................................................................................................... 251.3.1.4.2 Property bit CHNCAP_CLIENTONLY................................................................................................. 261.3.1.4.3 Property bit CHNCAP_WRITE2BYTE ................................................................................................ 261.3.1.4.4 Property bit CHNCAP_WRITE2BIT .................................................................................................... 261.3.1.4.5 Property bit CHNCAP_SIGNALALIVE................................................................................................ 261.3.1.4.6 Property bit CHNCAP_SIGNALSTART .............................................................................................. 271.3.1.4.7 Property bit CHNCAP_REENTRANT ................................................................................................. 271.3.1.4.8 Property bit CHNCAP_REMOTEVARIABLE ...................................................................................... 271.3.1.4.9 Property bit CHNCAP_ONLINECONN ............................................................................................... 271.3.1.4.10 Property bit CHNCAP_ONLINEVARIABLE ...................................................................................... 271.3.1.4.11 Property bit CHNCAP_REGISTERVARIABLE.................................................................................. 271.3.1.4.12 Property bit CHNCAP_OWNPROPERTIES ..................................................................................... 281.3.1.4.13 Property bit CHNCAP_USEMFC ...................................................................................................... 281.3.1.4.14 Property bit CHNCAP_INTELBYTEORDER..................................................................................... 281.3.1.4.15 Property bit CHNCAP_TMSYNCMASTER ....................................................................................... 281.3.1.4.16 Property bit CHNCAP_TMSYNCSLAVE........................................................................................... 28

1.3.1.5 Registration of the virtual connections of a channel unit ............................................................... ............ 281.3.1.5.1 Registration of a virtual connection in the initialization of a channel unit .......................................... .. 291.3.1.5.2 Registration of a virtual connection during the runtime............................................................... ........ 301.3.1.5.3 Status of a virtual connection after registration................................................................................... 30


A&D PT1 D2



Date29.02.2000

Version5.0


Page3 of 111


1.3.1.6 Registration of the WinCC-variables allocated to a channel unit ............................................................... 301.3.1.7 Start of a channel by the WinCC data manager ........................................................................................ 31

1.3.1.7.1 Steps of the channel unit for start in Configuration mode ................................................................... 341.3.1.7.2 Steps of a channel unit for start in Runtime mode .............................................................................. 35

1.3.1.7.2.1 Reading of information from the storage of the channel unit ....................................................... 351.3.1.7.2.2 Opening and initializing the channel device................................................................................. 351.3.1.7.2.3 Creating and initializing the specific connections......................................................................... 351.3.1.7.2.4 Initiating a time synchronisation................................................................................................... 361.3.1.7.2.5 Notifying the data manager of the status of the initialized virtual connection............................... 361.3.1.7.2.6 Changing the time of the WinCC machine through a channel unit .............................................. 371.3.1.7.2.7 Releasing system messages through a channel unit................................................................... 38

1.3.1.8 Obligatory sequences in the initialization of a channel .............................................................................. 381.3.2 Shutdown of a channel ...................................................................................................................38

1.3.2.1 Shutdown of the channel units through the WinCC data manager ............................................................ 391.3.2.2 Unloading of the channel-DLL through the operating system.................................................................... 39

1.3.3 Planning support through the channel unit .....................................................................................391.3.3.1 Dialog expansion in the planning of virtual connections ............................................................................ 40

1.3.3.1.1 Planning of virtual connections with MFC dialogs............................................................................... 411.3.3.1.2 Planning of virtual connections with standard Windows means.......................................................... 441.3.3.1.3 Tasks in the planning of the channel-specific part of a virtual connection .......................................... 45

1.3.3.2 Dialog expansion in the configuration of WinCC-variables........................................................................ 461.3.3.2.1 Variables configuration for SIMATIC S5/S7 controls .......................................................................... 461.3.3.2.2 Configuration of WinCC-variables with MFC dialogs .......................................................................... 461.3.3.2.3 Planning of WinCC-variables with standard Windows means ............................................................ 491.3.3.2.4 Tasks in the planning of the channel-specific part of a variable.......................................................... 491.3.3.2.5 Return of bit width of a specific variable address................................................................................ 501.3.3.2.6 Return a new variable address with given variable address plus offset.............................................. 51

1.3.3.3 Planning of the configuration of a channel or channel unit ........................................................................ 511.3.4 Variable interface............................................................................................................................53

1.3.4.1 Management of cyclical requests .............................................................................................................. 531.3.4.1.1 Channel unit with own cycle management.......................................................................................... 531.3.4.1.2 Cycle management by the WinCC data manager............................................................................... 54

1.3.4.2 Access result of a variable......................................................................................................................... 541.3.4.3 Allocation of a transaction ID through the WinCC data manager .............................................................. 551.3.4.4 Recoding of process values in the byte order of the coupled unit and back.............................................. 561.3.4.5 Read process values................................................................................................................................. 57

1.3.4.5.1 Reading of variables for cycle management through the channel ...................................................... 581.3.4.5.2 Reading of variables for cycle management by the WinCC data manager......................................... 591.3.4.5.3 Possible optimizations in the reading of variables .............................................................................. 59

1.3.4.5.3.1 Optimization through collection of overlapping address areas..................................................... 591.3.4.5.3.2 Optimization through declaration of several address areas in one request ................................. 60

1.3.4.5.4 Reading the process values from the coupled unit ............................................................................. 601.3.4.5.5 Return of read process values to the WinCC data manager............................................................... 60

1.3.4.6 Abort read process values......................................................................................................................... 621.3.4.7 Write process values ................................................................................................................................. 63

1.3.4.7.1 Description of the data to be written ................................................................................................... 641.3.4.7.2 Adaptation of the byte order of the data to be written ......................................................................... 651.3.4.7.3 Possible optimizations in the writing of variables................................................................................ 65

1.3.4.7.3.1 Several address areas in one request........................................................................................... 651.3.4.7.4 Writing the process values into the coupled unit................................................................................. 651.3.4.7.5 Return of the write status to the WinCC data manager....................................................................... 66

1.3.4.8 Access to WinCC-variables through the coupled unit of a channel unit .................................................... 671.3.4.8.1 Which WinCC-variables a coupled unit of a channel unit can access ................................................ 671.3.4.8.2 Server access to process variables of own virtual connection............................................................ 671.3.4.8.3 Server access to WinCC system variables ......................................................................................... 681.3.4.8.4 Read server access to a WinCC-variable ........................................................................................... 68

1.3.4.8.4.1 Reading of WinCC-variables of the virtual connection................................................................. 681.3.4.8.4.2 Reading of WinCC system variables ........................................................................................... 70

1.3.4.8.5 Write server access to a WinCC-variable ........................................................................................... 711.3.4.8.5.1 Writing of WinCC-variables of the virtual connection ................................................................... 711.3.4.8.5.2 Writing of WinCC system variables.............................................................................................. 73

1.3.5 Time synchronization......................................................................................................................741.3.5.1 Channel unit as a time master................................................................................................................... 74


A&D PT1 D2



Date29.02.2000

Version5.0


Page4 of 111


1.3.5.2 Channel unit as time slave ........................................................................................................................ 751.3.6 Change of channel-specific data formats .......................................................................................75

1.3.6.1 Changing the description of a virtual connection ....................................................................................... 751.3.6.1.1 Converting from internal representation into a string .......................................................................... 751.3.6.1.2 Conversion from a string into the internal representation ................................................................... 76

1.3.6.2 Changing the variable address.................................................................................................................. 771.3.6.2.1 Conversion from internal representation into a string ......................................................................... 771.3.6.2.2 Conversion from a string into the internal representation ................................................................... 77

1.3.7 Interface for language change........................................................................................................781.3.8 Diagnosis interface .........................................................................................................................79

2 ADDITONAL API FUNCTIONS IN WINCC 4.X........................................................................................80

2.1 CHANNEL-SPECIFIC DATA CONVERSION ....................................................................................................802.1.1 ChnGetConversionlist.....................................................................................................................80

2.1.1.1 Parameters:............................................................................................................................................... 802.1.1.2 Structure Components:.............................................................................................................................. 81

2.1.2 ChnConvertAsToOs........................................................................................................................812.1.2.1 Parameters:............................................................................................................................................... 812.1.2.2 Notes: ........................................................................................................................................................ 81

2.1.3 ChnConvertOsToAs........................................................................................................................822.1.3.1 Parameters:............................................................................................................................................... 822.1.3.2 Notes: ........................................................................................................................................................ 822.1.3.3 Configuring Tag-Properties and Address .................................................................................................. 82

2.2 ADDITIONAL D/M CALLBACKS....................................................................................................................832.2.1 pfnGetVariableInfo..........................................................................................................................832.2.2 pfnGetProjectFileName ..................................................................................................................84

3 ADDITIONAL FUNCTIONALITY IN WINCC V 5.X...................................................................................85

3.1 NEW IN WINCC V5.X ...............................................................................................................................853.2 TIME-STAMPS AND QUALITY-CODES .........................................................................................................85

3.2.1 VARIABLEACCESSRESULTEX ....................................................................................................853.2.2 READFINISHCBEX ........................................................................................................................863.2.3 CHN_WRITEDESCRIPTOREX......................................................................................................873.2.4 ChnStartWriteEx .............................................................................................................................87

3.3 CHANNEL DIAGNOSIS INTERFACE..............................................................................................................893.3.1 Trace Flags.....................................................................................................................................893.3.2 Status of Connections ....................................................................................................................903.3.3 The C++ Class CChnDiagnose ......................................................................................................90

3.3.3.1 Constructor:............................................................................................................................................... 903.3.3.2 Methods..................................................................................................................................................... 91

3.3.3.2.1 CChnDiagnose::CreateConnection .................................................................................................... 913.3.3.2.2 CChnDiagnose::DeleteConnection..................................................................................................... 913.3.3.2.3 CChnDiagnose::SetConnectionState ................................................................................................. 913.3.3.2.4 CChnDiagnose::WriteFormat.............................................................................................................. 923.3.3.2.5 CChnDiagnose::WriteHResult ............................................................................................................ 923.3.3.2.6 CChnDiagnose::WriteApiReturn ......................................................................................................... 923.3.3.2.7 CChnDiagnose::WriteMemory ............................................................................................................ 933.3.3.2.8 CChnDiagnose::CreateCounter.......................................................................................................... 933.3.3.2.9 CChnDiagnose::SetCounter ............................................................................................................... 933.3.3.2.10 CChnDiagnose::IncrementCounter................................................................................................... 943.3.3.2.11 CChnDiagnose::CreateUserFlag ...................................................................................................... 943.3.3.2.12 CChnDiagnose::CompareFlags........................................................................................................ 95

3.3.3.3 Usage........................................................................................................................................................ 963.3.3.3.1 Initialization of the DLL: ...................................................................................................................... 963.3.3.3.2 Deinitialization of the DLL: .................................................................................................................. 963.3.3.3.3 Performing Log-/Tracefile Outputs...................................................................................................... 96

4 BIBLIOGRAPHY .......................................................................................................................................97

5 A N N E X ..................................................................................................................................................98


A&D PT1 D2



Date29.02.2000

Version5.0


Page5 of 111


5.1 QUALITY-CODES IN WINCC 5 ...................................................................................................................985.1.1 Quality Code according to Profibus PA ..........................................................................................98

5.1.1.1 Coding of status ........................................................................................................................................ 985.1.1.2 Use of the status byte for profile compliant devices .................................................................... .............. 995.1.1.3 Status Attribution Definition ..................................................................................................................... 100

5.1.2 Quality Code according to OPC ...................................................................................................1025.1.2.1 The Quality BitField ................................................................................................................................. 1035.1.2.2 The Substatus BitField ............................................................................................................................ 103

5.1.2.2.1 Substatus for BAD Quality: ............................................................................................................... 1045.1.2.2.2 Substatus for UNCERTAIN Quality:.................................................................................................. 1055.1.2.2.3 Substatus for GOOD Quality: ........................................................................................................... 106

5.1.2.3 The Limit BitField..................................................................................................................................... 1075.1.3 Priority of Quality Codes...............................................................................................................1085.1.4 Mapping WinCC-Status to Quality Codes ....................................................................................109

5.2 TERMS / ABBREVIATIONS ........................................................................................................................109


A&D PT1 D2



Date29.02.2000

Version5.0


Page6 of 111


1 API OF THE CHANNEL SCHEDULINGThis document describes the interface between the WinCC data manager and a communications channel-DLL.

1.1 Integration of a channel into the WinCC system structure

A channel provides the link between a WinCC system and a coupled unit via a communications medium. Thechannel maps the specific properties of the coupled unit to the standardized interface between the WinCC datamanager and the channel.

Data Manager

WinCC Explorer

Channel-DLL Channel-DLL Channel-DLL

Explorer-DLL

B & B Configuration

AP Configuration

AP Runtime

B & B Runtime

SystemManager

Client-DLL

Text-LibraryConfiguration

PasswordConfiguration

VariablesConfiguration

Text-LibraryRuntimeSystem

TagManagement

PasswordRuntimeSystem

···The services of a channel are only claimed through the WinCC data manager. The Channel-API describes theinterface between a channel and the WinCC data manager and consists of the formal description of the APIfunctions and the description of the dynamic sequences between the WinCC data manager and the channel.

A WinCC channel is realized as WINDOWS DLL and is dynamically integrated into the system. Each WinCCchannel represents access to a certain type of coupled unit with a defined protocol (e.g. access to a SIMATICS5 with the protocol TF is achieved using the channel S5TF).

Several WinCC channels can be active at any one time.


A&D PT1 D2



Date29.02.2000

Version5.0


Page7 of 111


1.2 General

1.2.1 Conventions

The following conventions are used in this description:

Script SignificanceBold names of functions described in this APIItalic names of function parametersStructures structures used within the Channel-API

The names of all API functions of a channel begin with the mnemonic Chn, thus for example ChnInit,ChnUnLoad.

1.2.1.1 Name conventions

Within the WinCC system there exist conventions for filenames that also affect the development of a channel.

1.2.1.1.1 Allocation of names of a channel-DLL

Each channel-DLL uses the filename-extension .CHN, thus S5TF.CHN or S5TRSP.CHN.

1.2.1.1.2 Allocation of names for language DLLs

The names of language DLLs for a channel-DLL are to be allocated according to the following scheme:

- The first 5 characters are freely selectable.- The next 3 characteristics are the short form of the respective language- The ending of the language DLL is .LNG

The short form of the respective language is to be selected according to the following table:

Language ID Language Sublanguage Short form0x0406 Danish Danish DAN0x0413 Dutch Dutch (standard) NLD0x0813 Dutch Belgian (Flemish) NLB0x0409 English American ENU0x0809 English British ENG0x0c09 English Australian ENA0x1009 English Canadian ENC0x1409 English New Zealand ENZ0x1809 English Irish ENI0x040b Finnish Finnish FIN0x040c French French (standard) FRA0x080c French Belgian FRB0x0c0c French Canadian FRC0x100c French Swiss FRS


A&D PT1 D2



Date29.02.2000

Version5.0


Page8 of 111


Language ID Language Sublanguage Short form0x0407 German German (standard) DEU0x0807 German Swiss DES0x0c07 German Austrian DEA0x040f Icelandic Icelandic ISL0x0410 Italian Italian (standard) ITA0x0810 Italian Swiss ITS0x0414 Norwegian Norwegian (standard) NOR0x0814 Norwegian Norwegian (Nynorsk) NON0x0416 Portuguese Portuguese (Brazilian) PTB0x0816 Portuguese Portuguese (standard) PTG0x041d Swedish Swedish SVE0x040a Spanish Spanish (standard)) ESP0x080a Spanish Mexican ESM0x0c0a Spanish Spanish (modern) ESN

Language ID Language Sublanguage Short form0x041f Turkish TRK0x0415 Polish PLK0x0405 Czech CSY0x041b Slovakian SKY0x040e Hungarian HUN

Language ID Language Sublanguage Short form0x0419 Russian RUS

Language ID Language Sublanguage Short form0x0408 Greek ELL

Language-ID Language Sublanguage Short-form0x08040x04040x04120x0411

ChineseChinese traditionalKoreanJapanese

SimplifiedTraditional

CHSCHTKORJPN

1.2.2 Error recovery in the API functions

Error recovery is the same in all functions of the Channel-API. All API functions supply as result a value of thetype BOOL which states whether the API function was executed free of error (result TRUE) or has errors(result FALSE).For additional information on the cause of error, the caller of an API function can transfer a pointer to astructure of type CMN_ERROR. In this structure the API function stores further information concerning thelocation and cause of error.

The structure CMN_ERROR is defined as follows in the file ohioapi.h:

typedef struct{

DWORD dwError1,dwError2,dwError3,dwError4,dwError5;


A&D PT1 D2



Date29.02.2000

Version5.0


Page9 of 111


TCHAR szErrorText[512];} CMN_ERROR,

*PCMN_ERROR,**PPCMN_ERROR;

The declaration of a pointer to the structure CMN_ERROR is optional, i.e. the caller of an API function can alsoenter NULL. In this case the caller does not desire any additional information concerning the cause of the error.

The structure components dwError1 to dwError5 contain specific error codes of an API function. Therespective meaning must be described for the respective API function. In szErrorText the cause of error is stored as plain text.

1.2.3 Channel-DLL with several units

A channel-DLL can support several units of the same type.

For example, the channel-DLL S5-TF can be operated both with a SINEC-H1 unit (CP1413) and a SINEC-L2unit (CP5412), in some circumstances at the same time.

The channel-DLL is loaded once by the WinCC data manager, irrespective of the number of supported units.Then follows the interrogation of the maximum number of units the channel supports. For each unit, thechannel-DLL must supply a unique name that’s used by the WinCC data manager to identify the channel unit.

All API functions of the channel-DLL are invoked with a unit ID. The value of the unit ID ranges from 0 to(number of supported units - 1).It is the task of the channel-DLL to define a relation between the unit ID and the internal channel unitstructures.

1.2.4 Storage of a channel unit

The WinCC data manager maintains a Compound File for each WinCC project, which contains an ownstorage (channel storage) for each channel unit of a project.

A channel unit can, by means of the API function ChnEditProperties, define a specific configuration for thechannel unit or the whole channel. The channel unit must store the configured values in the storage allocatedto it.

At startup, the channel unit receives a pointer to the interface of the channel storage for the active project andcan read the previously configured values from this storage.

If the channel storage contains no values at startup, the channel unit must work with defined initializationvalues.


A&D PT1 D2



Date29.02.2000

Version5.0


Page10 of 111


1.2.5 Virtual connections

1.2.5.1 General manipulation of a virtual connection

Virtual connections are virtual communications channels for the WinCC data manager that are given a uniquename and that are allocated to a channel unit within a WinCC project.The channel unit allocates a channel-specific connection to the virtual connection; the channel-specificconnection is realized using a communications medium of the channel unit.

The WinCC data manager requests process values during the runtime from the coupled unit via the virtualconnection (reading and writing). The channel unit performs the communications steps required for therequest for the process values via the channel-specific connection and thereby supplies the WinCC datamanager with process values.

1.2.5.2 Channel-specific expansion of a virtual connection

A channel-specific communications channel is allocated to each virtual connection via the channel unit. Thechannel unit is responsible for the nature and description of the communications channel.For example, the channel-specific connection of the S5-TF channel is a TF application relationship, the one of aS5-AS511 channel would be a serial connection.

The structure of the channel-specific connection description is known only to the relevant channel unit. For thisreason, each virtual connection has a memory area whose structure and contents are only known to therelevant channel unit and which contains the channel-specific connection description.

Structure and contentare known only to thechannel unit.

General part of avirtual connection

The content of the specific part of the virtual connection is entered when it is configured. To this end it isnecessary that each channel offers the possibility of itself performing, at the request of the WinCC dialogsystem, the configuration of the channel-specific part of the virtual connection in the form of channel-specificdialogs.The WinCC dialog system receives the channel-specific data and stores its string representation with thegeneral part of the virtual connection in the database. The size of the string-representation of the channel-specific data is limited to 256 characters maximum.

Note:More information on the channel-specific expansion of the WinCC dialog system can be found in chapter1.3.3.1, Dialog expansion in the planning of virtual connections, page 40.

When a virtual connection is loaded, the channel-specific data are accepted by the WinCC data manager,without interpretation, into the runtime structure of the virtual connection.The channel unit thereby receives during the runtime the description of the virtual connection in the same formwhich was predefined during the planning.


A&D PT1 D2



Date29.02.2000

Version5.0


Page11 of 111


1.2.5.3 Data structure of a virtual connection

A virtual connection is defined as follows in WinCC:

#include <ChnAPI.h>

typedef struct{

TCHAR szName[LCS_MAXNAMELENGTH + 2];DWORD dwChannelId;WORD wMachineId;WORD wState;WORD wCaps;DWORD dwChannelReserved;DWORD dwTimeSyncCycle;PVOID pvExt;

} LOGCONNECTIONSTRUCT,*PLOGCONNECTIONSTRUCT,**PPLOGCONNECTIONSTRUCT;

The structure elements have the following meaning:

Structure element MeaningSzName Name of the virtual connection, ends with ‘\0’

DwChannelId ID of the relevant channel. Is entered by the WinCC data managerduring the runtime in order to identify the channel to which the virtualvariable is allocated. May not be changed by the channel.

WmachineId ID of the machine on which the conversion of the virtual connection in achannel-specific connection is effected.Is established and entered by the WinCC data manager during theruntime.

Wstate Status bits of the virtual connectionLCS_NOTESTABLISHED 0x0001 set Virtual connection not operational

erased Channel has established specific connection, thevirtual connection is operational

LCS_HANDSHAKEERROR 0x0002 set Error in communications handshakeerased No error in communications handshake

LCS_HARDWAREERROR 0x0004 set Error in the communications hardware used by thechannel

erased Communications hardware of the channel okay

LCS_NORESOURCE 0x0008 set No resources for creating the channel-specificconnection exist

erased Resources for creating the specific connection exist

Wcaps Properties of the virtual connection

LCC_CANREADVAR 0x0010 set Variables can be read via this virtual connectionerased No variables can be read via this virtual connection


A&D PT1 D2



Date29.02.2000

Version5.0


Page12 of 111


Structure element MeaningLCC_CANWRITEVAR 0x0020 set Variables can be written via this virtual connection

erased No variables can be written via this virtualconnection

LCC_TMSYNCMASTER 0x0040 set The current time is transmitted to the coupled unitby the channel unit using this connection. This bit isset by the WinCC data manager

erased No transmission of the time to the coupled unit

LCC_TMSYNCSLAVE 0x0080 set The channel unit receives the time from thecoupled unit via this connection. This bit is set bythe WinCC data manager.

erased No time is expected from the switching partner viathis connection.

DwChannelReserved Can be freely used by the channel, e.g. in order to enter a reference onthe channel-internal connection scheduling

DwTimeSyncCycle Cycle of the time synchronization in milliseconds.

PvExt Pointer to channel-specific data area

For manipulation of the property flags LCC_TIMEMASTER and LCC_TIMESLAVE, see chapter1.3.5,Timesynchronization.

1.2.5.3.1 Status of a virtual connection

The field wState of the structure LOGCONNECTIONSTRUCT contains the current status of a virtualconnection..

The status of a virtual connection may not be changed directly in the management structure by achannel unit, but only using a callback function whose address the channel unit receives at startup.(See also chapter 1.3.1.7.2.4, page 36, Initiating a time synchronisation)

1.2.5.3.2 Properties of a virtual connection

The field wCaps of the structure LOGCONNECTIONSTRUCT contains the properties of a virtual connection.

The properties of a virtual connection are predefined once during configuration by the channel unit and may nolonger be changed during the runtime.

The following properties are predefined at the current point in time:

• Block/release reading of variables via this connection• Block/release writing of variables via this connection• Predefine behaviour of the virtual connections regarding time synchronization.

1.2.5.3.2.1 Write and/or rcead access released

The property LCC_CANREADVAR defines that the WinCC data manager can read variable values from thecoupled unit via the virtual connection. The property LCC_CANWRITEVAR defines that the WinCC datamanager can write variable values into the coupled unit via the virtual connection.


A&D PT1 D2



Date29.02.2000

Version5.0


Page13 of 111


If neither of the property bits is set, the WinCC data manager can execute neither a write job nor a read job viathe virtual connection.

1.2.5.3.2.2 Define behaviour with regard to time synchronization

The properties LCC_TMSYNCMASTER and LCC_TMSYNCSLAVE are allocated by the WinCC data managerto the virtual connection during the configuration of the time synchronization. These properties tell a channelunit how a virtual connection behaves with regard to time synchronization.For more information, see chapter 1.3.5, Time synchronization.

1.2.6 WinCC-variable

1.2.6.1 General manipulation of a WinCC-variable

WinCC-variables are the central element for accessing process values. Within a WinCC project they are givena unique name and a data type, among other things.A WinCC-variable is allocated to a virtual connection which defines which channel supplies the process valuesof the variables and via which connection.

ChannelWinCC-variable

Virtual connection

Virtual connection

WinCC-variables are stored in a projectwide database. At startup of a WinCC machine, all variables of a projectare loaded and the corresponding runtime structures are created.

1.2.6.2 Channel-specific expansion of a WinCC-variable

Each WinCC-variable has a channel-specific address description of the source/drain of the process value. Thenature of the address description depends on the type of coupled unit of the channel unit.

The channel-specific address description is known only to the relevant channel unit. For this reason, eachWinCC-variable has a memory area whose structure and content are known only to the relevant channel unitand which contains the channel-specific address description.


A&D PT1 D2



Date29.02.2000

Version5.0


Page14 of 111


Structure and contentare known only to thechannel unit

General part of aWinCC-variable

The content of the specific part is declared when the WinCC-variable is planned. To this end it is necessary thateach channel offers the possibility of itself executing, at the request of the WinCC dialog system, theconfiguration of the channel-specific part of the WinCC-variable in the form of channel-specific dialogs.The WinCC dialog system receives the channel-specific data and stores its string-representation with thegeneral part of the WinCC-variable in the database. The size of the string-representation of the channel-specificdata is limited to 256 characters maximum.

When a WinCC-variable is loaded, the channel-specific data is accepted by the WinCC data manager, withoutinterpretation, into the runtime structure of the variable.The channel unit thereby receives, during the runtime, the description of the variable in the same form that waspredefined during the configuration phase.

1.2.6.3 Data type of a WinCC-variable

Each WinCC-variable has a data type. This may be a simple data type (see the following table) or a structureddata type.

TYPE Remark StageBOOL 8-Bit, (1 = TRUE, 0 = FALSE) 1SCHAR 8-Bit, signed 1BYTE 8-Bit, unsigned 1SWORD 16-Bit, signed 1WORD 16-Bit, unsigned 1SDWORD 32-Bit, signed 1DWORD 32-Bit, unsigned 1float 32-Bit, IEEE 754 1double 64-Bit, IEEE 754 1TEXT8 ASCII - text without closing ‘0’, field for data length 1TEXT16 UNICODE - text without closing ‘0’, field for data length 1Raw data BYTE-Array, field for data length 1

Arrays 2Structures 2Bit fields 2

The channel unit is responsible for the conversion of the byte order between the WinCC-internal format and theformat in which the data are present in the coupled unit.

1.2.6.4 Data structure of a WinCC-variable

A WinCC-variable represents a process value for the WinCC data manager. A WinCC-variable is allocated to avirtual connection and thus also a channel unit. The variables are updated by request of the WinCC datamanager through the unit.


A&D PT1 D2



Date29.02.2000

Version5.0


Page15 of 111


typedef struct{

LPTSTR lptstrName;DWORD dwFlags;DWORD dwOsDataSizeDWORD dwAsDataSize;DWORD dwLogConnId;PVOID pvTypeDescr;PVOID pvExt;

} VARIABLESTRUCT,*PVARIABLESTRUCT,**PPVARIABLESTRUCT;

Structure element MeaninglptstrName Pointer to names of variables in the system

dwFlags Flags of the variables

dwOsDataSize Size in bits of the data area of the variables in the WinCC system

dwAsDataSize Base size in bits of the address of the variables in the coupled unit

dwLogConnId ID of the virtual connection allocated to the variables. Is entered by theWinCC data manager.Note: dwLogConnId contains a pointer to theLOGCONNECTIONSTRUCT – the virtual connection the variablebelongs to – casted to a DWORD. You can cast this DWORDback to a PLOGCONNECTIONSTRUCT-pointer to get access tothe virtual connection.

PvTypeDescr Pointer to description of the WinCC data type of the variables. InWinCC stage 1 is filled by value NULL

PvExt Pointer to memory area which contains the channel-specific variabledescription.

Note:The structure of a WinCC-variable can be expanded still further.

In the component dwOsDataSize, the WinCC data manager stores the size of the WinCC-variables in bits. Incontrast, the component dwAsDataSize contains the size of the memory area that is allocated to the WinCC-variables in the coupled unit of the channel unit. This value is also declared in bits.

Both components can assume varying values.

Example:A WinCC-variable has the WinCC data type DWORD, i.e. 32 bit unsigned. This variable is allocated a dataword in the coupled unit.The components dwOsDataSize and dwAsDataSize then have the following values:

dwOsDataSize = 32dwAsDataSize = 16


A&D PT1 D2



Date29.02.2000

Version5.0


Page16 of 111


1.2.6.4.1 Channel unit-relevant status bits of a variable

The field dwFlags in the general part of a variable contains status bits which are set or not set by the channelunit during planning..

The following status bits are provided for use by a channel unit:

DEFINE Bitmask Meaning Set byVARC_DMCANREAD 0x80000000 set WinCC data manager can request values for this

variable by means of the functionChnStartRead.

Channelunit

erased WinCC data manager cannot request any valuesfor this variable by means of the functionChnStartRead.

VARC_DMCANWRITE 0x40000000 set WinCC data manager can write values in thisvariable by means of the functionChnStartWrite.

Channelunit

erased WinCC data manager cannot write values in thisvariable by means of the functionChnStartWrite.

VARC_SERVERACCESS 0x20000000 set Values of this variable can be changed on theinitiative of the coupled unit of the channel unit

Channelunit

erased Values of this variable cannot be changed on theinitiative of the coupled unit of the channel unit

VARC_RAW 0x10000000 set The WinCC data type of the variable is raw data. Datamanager/channel l

erased The WinCC data type of the variable is a scalardata type.

VARC_FIELD 0x08000000 set The WinCC data type of the variable is either astructure, an array or a bit field.

Datamanager

erased The WinCC data type of the variable is either ascalar data type or raw data.

Datamanager/channel

VARC_DMHOLDVALUE 0x04000000 set The Data-Manager will hold the process-valueeven if there is no client requesting this variable.

Channel-Unit

erased The Data-Manager will only hold the processpariable if there is a client requesting thevarable.

VARC_CONFIG_INCOMPLETE

0x00200000 set The variable ist not configured correctly. TheData-Manager will not request it from thechannel.

Channelunit

erased The variable is correctly configured and can berequested by the Data-Manager

The named status bits are set/reset by the channel unit in the general part of the variable description duringplanning.

1.2.7 Runtime mode and Configuration mode

In order to be able to access part of the services of a channel unit without the communications hardwarerequired by the unit being installed, the channel unit can instead be operated in Configuration mode rather thanin Runtime mode


A&D PT1 D2



Date29.02.2000

Version5.0


Page17 of 111


Only in Runtime mode does the channel unit perform the communications mechanisms for initialization. InConfiguration mode, a channel unit is only required for the support of the WinCC dialog system in the planningof WinCC-variables and virtual connections.

1.3 API functions of a channel

The Channel-API is composed of the following part areas:

• Initialization of the channel - Initialization by the operating system during the loading of the channel-DLL (LibMain) - Interrogation of the entry points of the channel-DLL - Interrogation of the number of supported units - Language selection - Interrogation of the properties of a channel unit - Registration of all virtual connections of the channel unit - Registration of all WinCC-variables allocated to the channel unit - Start of the channel unit

• Shutdown of the channel - Shutdown by the WinCC data manager - Unloading by the operating system

• Expansions of the planning - Dialog expansion in the planning of WinCC-variables - Dialog expansion in the planning of virtual connections - Planning of the configuration of a channel unit

• Variables interface - Start updating of one or more variables - Start transfering of one or more values of variables into a coupled unit - Stop updating of one or more variables - Change of byte order of process data

• Time synchronization• Change of channel-specific data formats

- Conversion of the channel-specific description of a variable address from the internalrepresentation into a string.

- Conversion of the channel-specific description of a variable address from a string into the internalrepresentation.

- Conversion of the channel-specific description of a virtual connection from the internalrepresentation into a string.

- Conversion of the channel-specific description of a virtual connection from a string into the internalrepresentation.

• Online services- Language change- Diagnosis

1.3.1 Initialization of a channel

The initialization of a WinCC channel can be divided into several steps:

1. Initialization upon loading of the DLL (chapter 1.3.1.1, page 19)2. Interrogation of the entry points of the channel-DLL (chapter 1.3.1.2, page 19)3. Declaration of the current language (chapter Interface for language change 1.3.7, page 78)4. Interrogation of the number of supported units


A&D PT1 D2



Date29.02.2000

Version5.0


Page18 of 111


5. Interrogation of the properties of the channel by the WinCC data manager (chapter 1.3.1.4, page 216. Registration of the virtual connections of this channel by the WinCC data manager (chapter 1.3.1.5, page

28)7. Registration by the WinCC data manager of all WinCC-variables allocated to the virtual connections of the

channel (chapter 1.3.1.6, page 30)8. Startup of the channel unit channel by the WinCC data manager (chapter 1.3.1.7, page 31)

1.3.1.1 Initialization of a channel during loading

The WinCC data manager loads a channel-DLL by means of the system call LoadLibrary. The channel-DLL isthen loaded by the operating system and initialized by the standard mechanisms of the system.

In general, initialization during loading should be kept as short as possible in order to avoid any delay of thestartup behaviour of WinCC.

1.3.1.2 Interrogation of the entry points of the channel-DLL

After the channel-DLL has been loaded, the WinCC data manager determines the entry points of the channel-DLL by means of the function ChnGetEntryPoints.

ChnGetEntryPoints

#include <ChnAPI.h>

BOOL ChnGetEntryPoints(PCHN_ENTRYPOINTS pEntries,PCMN_ERROR pes)

PARAMETERS

pEntries Ptr to structure in which the API function stores the addresses of the remaining APIfunctions

pes Ptr to standard WinCC error structure

RETURN

TRUE No errorsFALSE Error in API function, description of cause of error via the pointer pes

The mechanism by which the entry points of the API functions of the channel are supplied by the channel-DLLshortens the initialization stage of the WinCC data manager since the function GetProcAddress only needs tobe invoked once.

The structure CHN_ENTRYPOINTS is defined in ChnAPI.h.

typedef struct{

DWORD dwSize;PCHN_GETUNITCOUNT pfnGetUnitCount;PCHN_GETCAPS pfnGetCaps;PCHN_REGISTERCONN pfnRegisterConnection;PCHN_REGISTERVARIABLE pfnRegisterVariable;PCHN_START pfnStart;PCHN_UNLOAD pfnUnLoad;PCHN_GETCONNPPCOUNT pfnGetConnectionPPCount;


A&D PT1 D2



Date29.02.2000

Version5.0


Page19 of 111


PCHN_GETCONNPP pfnGetConnectionPP;PCHN_EDITCONN pfnEditConnection;PCHN_GETVARIABLEPPCOUNT pfnGetVariablePPCount;PCHN_GETVARIABLEPP pfnGetVariablePP;PCHN_EDITVARIABLE pfnEditVariable;PCHN_GETADDRESSUNITSIZE pfnGetAddressUnitSize;PCHN_EDITPROPERTIES pfnEditProperties;PCHN_STARTREAD pfnStartRead;PCHN_STARTWRITE pfnStartWrite;PCHN_STOPREAD pfnStopRead;PCHN_CHANGEBYTEORDER pfnChangeByteOrder;PCHN_CNVTCONNSTRING pfnConvertConnectionToString;PCHN_CNVTCONNBINARY pfnConvertConnectionToBinary;PCHN_CNVTVARIABLSTRING pfnConvertVariableToString;PCHN_CNVTVARIABLEBINARY pfnConvertVariableToBinary;PCHN_CHANGELANG pfnChangeLanguage;PCHN_BUILDVARIABLEADDRESS pfnBuildVariableAddress;PCHN_STOPREADEX pfnStopReadEx;

} CHN_ENTRYPOINTS,*PCHN_ENTRYPOINTS,**PPCHN_ENTRYPOINTS;

Structure element MeaningdwSize Size of structure in bytespfnGetUnitCount Entry point of API function ChnGetUnitCounpfnGetCaps Entry point of API function ChnGetCapspfnRegisterConnection Entry point of API function ChnRegisterConnectionpfnRegisterVariable Entry point of API function ChnRegisterVariablepfnStart Entry point of API function ChnStartpfnUnLoad Entry point of API function ChnUnLoadpfnGetConnectionPPCount Entry point of API function ChnGetConnectionPropPageCountpfnGetConnectionPP Entry point of API function ChnGetConnectionPropPagepfnEditConnection Entry point of API function ChnEditConnectionpfnGetVariablePPCount Entry point of API function ChnGetVariablePropPageCountpfnGetVariablePP Entry point of API function ChnGetVariablePropPagepfnEditVariable Entry point of API function ChnEditVariablepfnGetAddressUnitSize Entry point of API function ChnGetAddressUnitSizepfnEditProperties Entry point of API function ChnEditPropertiespfnStartRead Entry point of API function ChnStartReadpfnStartWrite Entry point of API function ChnStartWritepfnStopRead Entry point of API function ChnStopReadpfnChangeByteOrder Entry point of API function ChnChangeByteOrderpfnConvertConnectionToString Entry point of API function ChnConvertConnectionToStringpfnConvertConnectionToBinary Entry point of API function ChnConvertConnectionToBinarypfnConvertVariableToString Entry point of API function ChnConvertVariableToStringpfnConvertVariableToBinary Entry point of API function ChnConvertVariableToBinarypfnChangeLanguage Entry point of API function ChnChangeLanguagepfnBuildVariableAddress Entry point of API function ChnBuildVariableAddresspfnStopReadEx Entry point of API function ChnStopReadEx

Note:The structure CHN_ENTRYPOINTS can be further expanded during the development of WinCC.Components already existing will be retained.


A&D PT1 D2



Date29.02.2000

Version5.0


Page20 of 111


The data manager sets dwSize in this structure to the size of the buffer in bytes before callingChnGetEntryPoints. The channel has to check dwSize to assure the buffer is large enough to hold a pointerfor each entry-point. All function pointers are set to NULL.

The channel-DLL enters the addresses of the API functions in the function ChnGetEntryPoints. If an APIfunction is not supported (e.g. alternative API functions depending on whether the channel-DLL planning issupported with MFC means or not), the corresponding entry in the structure is left empty or filled by NULL.

1.3.1.3 Interrogation of the number of supported units

The WinCC data manager inquires the number of supported units of the channel-DLL by means of the functionChnGetUnitCount.

ChnGetUnitCount

#include <ChnAPI.h>

DWORD ChnGetUnitCount(void)

PARAMETERS

None

RETURN

Number of units of the channel-DLL (at least 1))

The channel-DLL supplies the number of units supported by it. The further course of initialization is effected foreach unit under declaration of the unit ID.Here:

Unit-ID 0 - Unit 1Unit-ID 1 - Unit 2

1.3.1.4 Interrogation of the properties of a channel unit

The properties of a channel unit are inquired by the function ChnGetCaps .

ChnGetCaps#include <ChnAPI.h>

BOOL ChnGetCaps(DWORD dwUnitId,PCHN_CAPS pCaps,PCMN_ERROR pes);

PARAMETERS

dwUnitId ID of the channel unit whose properties were interrogated

pCaps Pointer to structure in which the channel unit stores the required properties


A&D PT1 D2



Date29.02.2000

Version5.0


Page21 of 111


pes Pointer to standard WinCC error structure

RETURN


The properties of a channel unit are determined by means of the function ChnGetCaps. The information isstored in a structure of type CHN_CAPS..

CHN_CAPS

typedef struct{

LONG lCaps;TCHAR szUnitName[65];INT iBitmapDll16x16;INT iBitmapDll32x32;INT iBitmapDll48x48;INT iBitmapUnit16x16;INT iBitmapUnit32x32;INT iBitmapUnit48x48;INT iIconDll;INT iIconUnit;

} CHN_CAPS,*PCHN_CAPS,**PPCHN_CAPS;

The structure elements have the following meaning:

Structure element MeaningLCaps Properties of the channel unit according to the following table

szUnitName Name of the channel unit, ends with "\0). The name of the channel unitidentifies the unit in the WinCC system (e.g. in the selection of achannel unit in a dialog)

iBitmapDll16x16 Resource ID of a bit map of size 16x16, allocated to the channel-DLL



iBitmapUnit16x16 Resource ID of a bit map of size 16x16, allocated to the channel unit.

iBitmapUnit32x32 Resource ID of a bit map of size 32x32, allocated to the channel unit

iBitmapUnit48x48 Resource ID of a bit map of size 48x48, allocated to the channel unit

iIconDll Resource ID of an icon of size 32x32, allocated to the channel-DLL

iIconUnit Resource ID of an icon of size 32x32, allocated to the channel unit


A&D PT1 D2



Date29.02.2000

Version5.0


Page22 of 111


The resource IDs of the bit maps and icons are required for the visual representation of the channel-DLL and itsunits within the WinCC system.The bit maps and icons are loaded by the data manager with the instance handle of the channel-DLL and musttherefore be linked as resources to the channel-DLL.

For the resource IDs of the bit maps and icon of the channel-DLL, on each call the function ChnGetCaps isgiven the same values, the values for the bit maps and the icon of the channel unit may differ from call to call ofthe function.

The channel units defines which WinCC features it supports and which it does not support via the property bitsin the component Icaps of the structure CHN_CAPS. Each property is allocated a bit according to the followingtable

DEFINE Bit mask MeaningCHNCAP_OWNCYCLE 0x00000001 set Channel unit has its own management of cyclical

requests.erased Management of cyclical requests through WinCC data

manager

CHNCAP_CLIENTONLY 0x00000002 set Channel unit does not support communication with itscoupled unit on its initiative

erased Channel unit can process requests of its coupled unit.

CHNCAP_WRITE2BYTE 0x00000004 set Channel unit can write values directly onto byteaddresses in its coupled unit.

erased Channel unit cannot write onto byte addresses in itscoupled unit

CHNCAP_WRITE2BIT 0x00000008 set Channel unit can write directly onto bit addresses in itscoupled unit.

erased Channel unit cannot write onto bit addresses in itscoupled unit.

CHNCAP_SIGNALALIVE 0x00000010 set Channel unit carries out own life monitoringerased Channel has no own life monitoring

CHNCAP_SIGNALSTART 0x00000020 set Channel unit automatically signals coupled unit onrestart

erased No signalling of coupled unit by channel on restart

CHNCAP_REENTRANT 0x00000040 set Channel unit is reentranterased Channel unit is not reentrant.

CHNCAP_REMOTEVARIABLE 0x00000080 set Channel unit allows access to variables which areplanned in coupled unit.

erased No access to variables which are planned in coupledunit

CHNCAP_DIAGNOSE 0x00000100 set Channel unit offers diagnosis optionserased Channel unit offers no diagnosis options

CHNCAP_ONLINECONN 0x00000200 set Channel unit can allocate virtual connections tospecific connections during runtime

erased Channel can only create virtual connections duringinitialization stage

CHNCAP_ONLINEVARIABLE 0x00000400 set Channel unit can register WinCC-variable during


A&D PT1 D2



Date29.02.2000

Version5.0


Page23 of 111


DEFINE Bit mask Meaningruntime

erased Channel unit cannot register WinCC-variable duringruntime

CHNCAP_REGISTERVARIABLE 0x00000800 set Registration of WinCC-variables allocated to channelunit

erased No registration of WinCC-variables

CHNCAP_OWNPROPERTIES 0x00001000 set Channel unit supports planning of internalconfiguration values through own dialog.

erased No own planning of internal configuration values

CHNCAP_USEMFC 0x00002000 set Channel implements its specific dialogs with Visual-C++ and MFC

erased Channel implements its specific dialogs with standardWindows SDK means

CHNCAP_INTELBYTEORDER 0x00004000 set Process values of coupled unit of channel unit are inINTEL byte order

erased Process values of coupled unit of channel unit are notin INTEL byte order.

CHNCAP_TMSYNCMASTER 0x00008000 set Channel unit is time mastererased Channel unit is not time master.

CHNCAP_TMSYNCSLAVE 0x00010000 set Channel unit is time slaveerased Channel unit is not time slave

If a channel unit supports one or more of the listed properties, it sets the corresponding bits in the componentICaps of the structure CHN_CAPS.

1.3.1.4.1 Property bit CHNCAP_OWNCYCLE

Through the property bit CHN_OWNCYCLE, the channel unit defines whether or not it contains its ownmanagement of cyclical requests.

If it has its own cycle management, the channel unit receives the variables to be updated by means of thefunction ChnStartRead. The channel unit inserts the variables into its cycle management. As soon as one ormore variables are ready for updating, the channel unit carries out the steps needed to request the data. Thedata which have been read are passed to the WinCC data manager by means of a callback function and theupdated variable(s) are inserted back into the cycle management.

One or more WinCC-variables can be logged off using the function ChnReadStop for one channel unit.

The following illustration shows the schematic operation of variable updating for own cycle management by thechannel unit:


A&D PT1 D2



Date29.02.2000

Version5.0


Page24 of 111


WinCC data manager Channel Coupled unit------------------------------------------> ------------------>ChnStartRead(...) Request

processvalue(s)

<------------------------------------------ <------------------(*pfnReadFinish)(...)

------------------>Requestprocessvalue(s)

<------------------------------------------ <------------------(*pfnReadFinish)(...)

------------------------------------------>ChnStopRead(...)

In the case of cycle management by the WinCC data manager, the latter logs on a WinCC-variable with achannel unit by means of the function ChnStartRead as soon as the cycle of the variable requires updating.The channel unit performs the communications steps necessary for requesting the process values. Theprocess values which have been read are transferred to the WinCC data manager by means of a callbackfunction. As soon as the WinCC data manager receives the process values of the variable, he catalogs thevariable(s) in his cycle management again.If a renewed request of the variable after the expiry of the cycle time is necessary, the process begins again.

By using the function ChnStopRead, the WinCC data manager can cancel the requests for variables whichwere transferred to a channel unit by means of the function ChnStartRead. In this case the channel unit mustdecide how the cancel process is to be performed.

The following picture shows the schematic operation of variables updating for cycle management by the WinCCdata manager:

WinCC data manager Channel Coupled unit

ChnStartRead(...)Requestprocessvalue(s)

(*pfnReadFinish)(...)

ChnStartRead(...)Requestprocessvalue(s)

(*pfnReadFinish)(...)

1.3.1.4.2 Property bit CHNCAP_CLIENTONLY

A channel unit uses the property bit CHNCAP_CLIENTONLY to define whether or not the coupled unit canactively access a WinCC-variable


A&D PT1 D2



Date29.02.2000

Version5.0


Page25 of 111


If this bit is set, the coupled units of the channel unit can access WinCC-variables at their own initiative. Thetype of access (read, write) depends on the respective WinCC-variable. (For a precise description, see chapter1.3.4.8, Access to WinCC-variables through the coupled unit of a channel unit, page 67)

1.3.1.4.3 Property bit CHNCAP_WRITE2BYTE

A channel unit uses the property bit CHNCAP_WRITE2BYTE to define whether or not it can write to byteaddresses of its coupled unit

Writing to byte addresses means that the lowbyte of a word can be written without the highbyte being changed,and vice versa.

1.3.1.4.4 Property bit CHNCAP_WRITE2BIT

A channel unit uses the property bit CHNCAP_WRITE2BIT to define whether or not it can write bits.

Writing bits means that a bit can be written in the memory area of the coupled unit without other bits beingchanged thereby.

1.3.1.4.5 Property bit CHNCAP_SIGNALALIVE

A channel unit uses the property bit CHNCAP_SIGNALALIVE to define whether or not it performs its own lifemonitoring.

If there is own life monitoring, the channel unit ensures that both the communications channel and the coupledunit itself are ready for communication.

1.3.1.4.6 Property bit CHNCAP_SIGNALSTART

A channel unit uses the property bit CHNCAP_SIGNALSTART to define whether or not it automatically informsits coupled unit of a restart.

If there is an automatic restart display, a channel unit informs its coupled unit of its new start. The Channel-APIdoes not state how the communication of the restart to the coupled unit takes place.

1.3.1.4.7 Property bit CHNCAP_REENTRANT

A channel unit uses the property bit CHNCAP_REENTRANT to define whether or not its API functions arereentrant.

A reentrant channel unit ensures that its API functions can be invoked by several threads of the WinCC datamanager simultaneously. Any necessary synchronization of the threads by operating system resources(semaphors, events etc.) takes place through the channel unit.

If the channel unit is not reentrant, the WinCC data manager synchronizes his threads.

1.3.1.4.8 Property bit CHNCAP_REMOTEVARIABLE

A channel unit uses the property bit CHNCAP_REMOTEVARIABLE to define whether or not can it accessvariables which are planned in the coupled unit.


A&D PT1 D2



Date29.02.2000

Version5.0


Page26 of 111


Variables which are planned in the coupled unit are identified by names. The channel unit is able to make thesenames available to the WinCC data manager if required.

1.3.1.4.9 Property bit CHNCAP_ONLINECONN

A channel unit uses the property bit CHNCAP_ONLINECONN to define whether or not it can register furthervirtual connections if it was started in Runtime mode

If a channel unit is started in Runtime mode and has set the property bit CHNCAPS_ONLINECONN, newlyplanned virtual connections are immediately registered with the channel unit by the WinCC data manager usingthe function ChnRegisterConnection. The channel unit creates the corresponding specific connection, so thatthe virtual connection is immediately operational.

1.3.1.4.10 Property bit CHNCAP_ONLINEVARIABLE

A channel unit uses the property bit CHNCAP_ONLINEVARIABLE to define whether or not can register furtherWinCC-variables during the runtime

1.3.1.4.11 Property bit CHNCAP_REGISTERVARIABLE

A channel unit uses the property bit CHNCAP_REGISTERVARIABLE to define whether or not it desires theregistration in the initialization stage of the WinCC-variables which are allocated to the virtual connections of theunit.If the channel unit does not desire the registration of the WinCC-variables allocated to it, the WinCC datamanager does not invoke the function ChnRegisterFunction in the initialization stage.

1.3.1.4.12 Property bit CHNCAP_OWNPROPERTIES

A channel unit uses the property bit CHNCAP_OWNPROPERTIES to define whether or not it contains its ownplanning of internal configuration values.

1.3.1.4.13 Property bit CHNCAP_USEMFC

A channel unit uses the property bit CHNCAP_USEMFC to define whether the channel-specific dialogs areimplemented by means of Visual-C++ and MFC or standard Windows means.

This property significantly influences the planning operation of the channel-specific descriptions with WinCC-variables and virtual connections.

1.3.1.4.14 Property bit CHNCAP_INTELBYTEORDER

A channel unit uses the property bit CHNCAP_INTELBYTEORDER to define whether or not process data inthe coupled unit are in INTEL byte order.

1.3.1.4.15 Property bit CHNCAP_TMSYNCMASTER

A channel unit uses the property bit CHNCAP_TMSYNCMASTER to define whether or not it is a time master.As time master, a channel unit cyclically receives the current time from the data manager by means of acallback function (component pfnTimedCallback in CHN_STARTSTRUCT)..


A&D PT1 D2



Date29.02.2000

Version5.0


Page27 of 111


1.3.1.4.16 Property bit CHNCAP_TMSYNCSLAVE

A channel unit uses the property bit CHNCAP_TMSYNCSLAVE to define whether or not it is a time slave.As time slave, the channel unit receives the time via a mechanism known only to the channel unit. If thechannel unit receives the time, it can transfer this to the data manager by means of a callback function.

The channel unit receives the address of the callback function of the data manager at startup in the componentpfnTimeChange of the start structure CHN_STARTSTRUCT.

1.3.1.5 Registration of the virtual connections of a channel unit

Virtual connections are registered with a channel by means of the function ChnRegisterConnection. Thevirtual connections are only registered if the channel unit is loaded in Runtime mode.

ChnRegisterConnection#include <ChnAPI.h>

BOOL ChnRegisterConnection(DWORD dwUnitId,PLOGCONNECTIONSTRUCT pConnection,PCMN_ERROR pes);

PARAMETERS

dwUnitId ID of the channel with which the virtual connection is registered

pConnection Pointer to a virtual connection.


RETURN


The WinCC data manager registers a virtual connection with a channel unit by means of the functionChnRegisterConnection.The establishment of the relevant specific connection is only effected upon the call of the function ChnStart.

If several virtual connections are allocated to one channel unit, the function is invoked once for each virtualconnection.The description of the channel-specific connection is in the specific part of the virtual connection.


A&D PT1 D2



Date29.02.2000

Version5.0


Page28 of 111


pConnection Virtualconnection

Specific part

General part

pvExt

The channel unit has the option of storing a reference in the management block of the specific connection inthe structure element dwChannelReserved of the virtual variable. If the channel unit receives a pointer to avirtual connection during updating, it can immediately access the internal management block via its reference.

If the channel unit is able to create further virtual connections in online operation, the functionChnRegisterConnection can be invoked each time in the further course.The property of creating further virtual connections in online operation is indicated by the channel unit throughthe flag CHNCAP_ONLINECONN in the functionChnGetCaps.

1.3.1.5.1 Registration of a virtual connection in the initialization of a channel unit

On each startup of a WinCC machine, the WinCC data manager loads the virtual connections from thedatabase and registers them with the allocated channel unit by means of the functionChnRegisterConnection.

This enters the virtual connection to be registered in a suitable management, so that the relevant specificconnection can be created for each registered virtual connection when the function ChnStart is invoked.

This step is repeated until all virtual connections of the channel unit have been registered.

1.3.1.5.2 Registration of a virtual connection during the runtime

A channel unit uses the property CHNCAP_ONLINECONN to define whether it is able to register further virtualconnections and create the corresponding channel-specific connections during the runtime (see chapter1.3.1.4, Interrogation of the properties of a channel unit, page 21).

A virtual connection newly created during the runtime is first stored in the database which contains the virtualconnections.In the next step, the WinCC data manager checks whether the allocated channel unit possesses the property toregister virtual connections during the runtime. If not, the new virtual connection only becomes active after thenext startup of the WinCC machine.

If the online registration is supported by the channel unit, the WinCC data manager loads the new virtualconnection from the database and registers it with the allocated channel unit by means of the functionChnRegisterConnection.This immediately creates the relevant channel-specific connection.

1.3.1.5.3 Status of a virtual connection after registration

The status field dwState in the management structure of the virtual connection is not changed duringregistration.Only on the startup of the channel unit in the function ChnStart, when the relevant specific connection for avirtual connection is created, does the channel unit set the status.


A&D PT1 D2



Date29.02.2000

Version5.0


Page29 of 111


1.3.1.6 Registration of the WinCC-variables allocated to a channel unit

WinCC-variables are registered with a channel unit by means of the function ChnRegisterVariable.Registration only takes place if the channel unit is loaded in Runtime mode and has the propertyCHNCAP_REGISTERVARIABLE.

ChnRegisterVariable#include <ChnAPI.h>

BOOL ChnRegisterVariable(DWORD dwUnitId,PLOGCONNECTIONSTRUCT pConnection,PPVARIABLESTRUCT ppVariable,DWORD dwVariableCount,PCMN_ERROR pes);

PARAMETERS

dwUnitId ID of the unit with which the variables are registered

ppVariable Pointer to array which contains the pointers to the variables to be registered

pConnection Pointer to management structure of the virtual connection to which thevariable is allocated.

dwVariableCount Number of variables which are registered


RETURN

TRUE No errorsFALSE Error in API function, description of the cause of error via the pointer pes

The WinCC data manager registers one or more variables with a channel unit by means of the functionChnRegisterVariable.The parameter ppVariable indicates an array which contains the pointers to the variables to be registered. Thenumber of variables to be registered is given in dwVariableCount.

ppVariable

Pointer-array

Variable 1

Variable 2


A&D PT1 D2



Date29.02.2000

Version5.0


Page30 of 111


Important:The memory of the arrays to which ppVariable points is only valid during the call ofChnRegisterVariable. The channel unit must secure the addresses of the variables in its own memoryarea.

Registration of the WinCC-variables is connection-specific. All variables given in a call of ChnRegisterVariableare allocated to the virtual connection pConnection. If several virtual connections belong to one channel unit,the function ChnRegisterVariable is invoked several times if necessary.

If the channel unit is able to register further WinCC-variables in online operation, the functionChnRegisterVariable is invoked each time in the further course. The variables registered in online operationare then added to the already existing variables. The erasing of variables is not provided for.The property of registering further WinCC-variables in online operation is indicated by the channel unit throughthe flag CHNCAP_ONLINEVARIABLE in the function ChnGetCaps.

The registration of the WinCC-variables with a channel unit is not absolutely vital for operation. The channelunit can stop the registration of the WinCC-variables by the WinCC data manager through the channel propertyCHNCAP_REGISTERVARIABLE (see chapter 1.3.1.4, Interrogation of the properties of a channel unit, page21)

1.3.1.7 Start of a channel by the WinCC data manager

A channel unit is started by the WinCC data manager through the function ChnStart. By invoking this function,the WinCC data manager ends the initialization stage of the unit.The unit performs the remaining initialization steps and is operational upon the ending of the function.

ChnStart#include <ChnAPI.h>

BOOL ChnStart(DWORD dwUnitId,BOOL bModeRuntime,PCHN_STARTSTRUCT pcis,PCMN_ERROR pes);

PARAMETERS

dwUnitId ID of the channel unit which was started

bModeRuntime TRUE if the channel unit was started in Runtime mode, FALSE if inConfiguration mode

pcis Pointer to start structure.


RETURNTRUE No errorsFALSE Error in API function, description of cause of error via the pointer pes


A&D PT1 D2



Date29.02.2000

Version5.0


Page31 of 111


The structure CHN_STARTSTRUCT is contained in ChnAPI.h:

typedef struct{

DWORD dwSize; DWORD dwMaxDataAmount,

dwMaxTextAddress, dwBinaryAddressSize, dwMaxTextConnection, dwBinaryConnectionSize;CHN_TIMEDCALLBACK pfnTimedCallback,DWORD dwTimedCycle;LPSTORAGE pActiveProjectStorage;LCSTATUSCHANGECB pfnLogConnStatusChange;READFINISHCB pfnReadFinish;WRITEFINISHCB pfnWriteFinish;TIMECHANGECB pfnTimeChange;SYSMSGCB pfnSysMessage;GETVALUECB pfnGetValue;SETVALUECB pfnSetValue;GETVALUENAMECB pfnGetValueName;SETVALUENAMECB pfnSetValueName;

} CHN_STARTSTRUCT,*PCHN_STARTSTRUCT,**PPCHN_STARTSTRUCT;

The initialization of a channel unit is terminated using the function ChnStart. The flag bModeRuntime indicateswhether the unit is being operated in Runtime mode or Configuration mode.

The WinCC data manager stores information in the start structure which is of interest for the channel. Thesefields are marked with E in the following structure.For its part, the channel stores information in the WinCC data manager in the start structure. These fields aremarked with A in the following structure.

CHN_STARTSTRUCT

Component Description E/A

DwSize Size of the structure in bytes A

DwMaxDataAmount Maximum length of a data packet which is routed from this channelto the WinCC data manager

DwMaxTextAddress Maximum length of the textual representation of the channel-specific address description

A

DwBinaryAddressSize Length of the binary representation of the channel-specific addressdescription

A

DwMaxTextConnection Maximum length of the textual representation of the channel-specific connection description

A

DwBinaryConnectionSize Length of the binary representation of the channel-specific A


A&D PT1 D2



Date29.02.2000

Version5.0


Page32 of 111


Component Description E/Aconnection description

PfnTimedCallback The data manager calls this function to initiate a timesynchronisation on the channel. If the channel can not act as atime-master, it should enter a NULL value here.

A

dwTimedCycle not used. A

pActiveProjectStorage Pointer to active project storage of the channel unit.

Note: you are not allowed to write to the active projectstorage within the ChnStart-function. Writing to the projectstorage is only allowed in ChnEditProperties !

E

pfnLogConnStatusChange Ptr to callback function of the WinCC data manager, via which thechannel unit informs the WinCC data manager of a change instatus of a virtual connection.

E

pfnReadFinish Ptr to callback function of the WinCC data manager, which isinvoked by the channel unit as soon as values of one or morevariables have been read

E

pfnWriteFinish Ptr to callback function of the WinCC data manager, which is calledby the channel unit as soon as values of one or more variableshave been transferred into the coupled unit

E

pfnTimeChange Here the WinCC data manager enters the address of a callbackfunction which the channel unit must invoke if it wants to set thetime of the WinCC system. The data manager can also enterNULL. In this case the channel unit cannot change the time.

E

pfnSysMessage Ptr to callback function of the WinCC data manager which can beused to transmit the channel unit system messages to the WinCCdata manager.

E

pfnGetValue Here the WinCC data manager enters the address of a callbackfunction which the channel unit can invoke in order to ascertain thevalue of one or more variables if the coupled unit so requests.

E

pfnSetValue Here the WinCC data manager enters the address of a callbackfunction which the channel unit can invoke in order to set the valueof one or more variables if the coupled unit has supplied thesewithout being requested.

E

pfnGetValueName Here the WinCC data manager enters the address of a callbackfunction which the channel unit can invoke in order to ascertain thevalue of one or more variables identifiable by name, if the coupledunit so requires.

E

pfnSetValueName Here the WinCC data manager enters the address of a callbackfunction which the channel unit can invoke in order to set the valueof one or more variables identifiable by name, if the coupled unithas supplied these without request.

E


A&D PT1 D2



Date29.02.2000

Version5.0


Page33 of 111


Depending on whether the channel unit was started in Configuration mode or Runtime mode, it must performthe steps described in the following two chapters.

1.3.1.7.1 Steps of the channel unit for start in Configuration mode

If a channel unit is opened in Configuration mode, the following API functions can be invoked by the WinCCdata manager:

ChnGetUnitCountChnGetCapsChnStartChnUnLoadChnGetConnectionPropPageCount for planning with MFC meansChnGetConnectionPropPage „ChnEditConnection for planning with standard Windows meansChnGetVariablePropPageCount for planning with MFC meansChnGetVariablePropPage „ChnEditVariable for planning with standard Windows meansChnGetAddressUnitSizeChnEditPropertiesChnConvertConnectionToStringChnConvertConnectionToBinaryChnConvertVariableToStringChnConvertVariableToBinaryChnChangeLanguage

On startup in Configuration mode, the channel unit must ensure that all operating means it requires for theprocessing of the named functions are available.

1.3.1.7.2 Steps of a channel unit for start in Runtime mode

If a channel unit is opened in Runtime mode, despite of the functions mentioned in chapter 1.3.1.7.1, the theWinCC data manager must be allowed to call the following API functions:

ChnRegisterConnectionChnRegisterVariableChnStartReadChnStartWriteChnStopReadChnChangeByteOrder

In addition to the steps which the channel has to perform for startup in Configuration mode, the following stepsmust be performed for a startup in Runtime mode:

1.3.1.7.2.1 Reading of information from the storage of the channel unit

The component pActiveProjectStorage of the startstructure CHN_STARTSTRUCT contains a pointer to theinterface of the storage of the channel unit.

This storage is either empty or contains the values planned in the planning of the channel-specific configurationin the function ChnEditProperties.

If the storage is empty, the started channel unit must work with defined initialization values. Otherwise it usesthe stored configuration values.


A&D PT1 D2



Date29.02.2000

Version5.0


Page34 of 111


1.3.1.7.2.2 Opening and initializing the channel device

The channel unit checks whether the device through which it wants to perform the communication with thecoupled unit is available and performs the necessary steps in order to use the device (opening, initializing, etc.).

1.3.1.7.2.3 Creating and initializing the specific connections

The channel-specific connections pertaining to the virtual connections registered by means of the functionChnRegisterConnection must be created and prepared for the communication.After the creation of the channel-specific connection, the channel unit informs the WinCC data manager of thestatus of the connection. To do this it uses for each virtual connection the callback functionpfnLogConnStatusChange declared in the start structure at the startup of the channel unit.

The status of a virtual connection can assume a combination of the following status bits :

DEFINE Status bits of the virtual connectionLCS_NOTESTABLISHED 0x0001 set The specific connection is initialized, but not

operational. No communication can take place.erased The specific connection is initialized and

operational, i.e. communication can take place.

LCS_HANDSHAKEERROR 0x0002 set A protocol error has occurred duringcommunication with the coupled unit (e.g. noacknowledgement of a request).

Erased No protocol error occurring

LCS_HARDWAREERROR 0x0004 set Error in the communications hardware used by thechannel

erased Communications hardware of the channel okay

LCS_NORESOURCE 0x0008 set The necessary resources for creating the specificconnection are not available

erased All resources required for the creation of thespecific connection are available

1.3.1.7.2.4 Initiating a time synchronisation

A channel unit may enter the address of a function that should be called by the data-manager to initiate atime synchronization in the component pfnTimedCallback of the structure CHN_STARTSTRUCT. This is onlynecessary, if the channel has the CHNCAPS_TMSYNCMASTER capabilities flag set.

CHN_TIMEDCALLBACK

typedef void (*CHN_TIMEDCALLBACK)(DWORD dwUnitId,

SYSTEMTIME *Ipst);

PARAMETERS

dwUnitId ID of the unit whose timed callback function is being called


A&D PT1 D2



Date29.02.2000

Version5.0


Page35 of 111


lpst Pointer to the WINDOWS structure SYSTEMTIME, which contains the currenttime

1.3.1.7.2.5 Notifying the data manager of the status of the initialized virtual connection

A change in the status of a virtual connection is communicated to the data manager via a callback function. Thechannel unit receives the address of the callback function in the function ChnStart in the start structure.

LCSTATUSCHANGECB

typedef void (*LCSTATUSCHANGECB)(PLOGCONNECTIONSTRUCT pConnection,

WORD wState,WORD wMode);

PARAMETERS

pConnection Pointer to WinCC structure of the virtual connection whose status has changed

wState Status flag which has changed

wMode Indication whether the flag is set (LCS_SET) or reset (LCS_RESET.

Examples:(In the following examples, pConnection is a pointer to the WinCC structure of a virtual connection andpfnLogConnChange the address of the callback function of the WinCC data manager.)

• Resetting of all status bits after the successful initialization of a virtual connection (*pfnLogConnChange)( pConnection, LCS_NOTESTABLISHED | LCS_HANDSHAKERROR | LCS_HARDWARERROR, LCS_RESET); • Setting of the status bit upon clearing of a connection

(*pfnLogConnChange)(pConnection,LCS_NOTESTABLISHED,LCS_SET);

1.3.1.7.2.6 Changing the time of the WinCC machine through a channel unit

A channel unit can change the time of the WinCC machine by means of a callback function of the datamanager. The channel unit receives the address of the callback function in the function ChnStart in the startstructure

TIMECHANGECB

typedef void (*TIMECHANGECB)(DWORD dwUnitId,SYSTEMTIME lpst);


A&D PT1 D2



Date29.02.2000

Version5.0


Page36 of 111


PARAMETERS

dwUnitId ID of the channel unit which changes the time

lpst Pointer to structure SYSTEMTIME, which receives the new time to be set

The structure SYSTEMTIME is a standard Windows structure.:

typedef struct _SYSTEMTIME{

WORD wYear;WORD wMonth;WORD wDayOfWeek;WORD wDay;WORD wHour;WORD wMinute;WORD wSecond;WORD wMilliseconds;

} SYSTEMTIME;

1.3.1.7.2.7 Releasing system messages through a channel unit

A channel unit can route system messages to the WinCC data manager. Depending on the type of systemmessage, this is processed in different ways in the data manager (see next table).

SYSMSGCB

typedef void (*SYSMSGCB)(DWORD dwMessageType,LPTSTR lptstrMessage);

PARAMETERS

dwMessageType Type of system message which is routed to the data manager

The type of system message can assume the following values:

SMG_SYSMSG System message, can be displayed and archivedthrough the signal system

lptstrMessage Pointer to message text which is routed to the data manager.

1.3.1.8 Obligatory sequences in the initialization of a channel

The WinCC data manager performs the following steps in the initialization of a channel unit:

1. The channel-DLL is loaded by means of the operating system function LoadLibrary. The DLL entry functionis invoked in the channel-DLL.

2. The WinCC data manager determines the entry points of the channel functions by means of the APIfunction ChnGetEntryPoints.


A&D PT1 D2



Date29.02.2000

Version5.0


Page37 of 111


3. The WinCC data manager determines the number of units which are supported by the channel.4. The WinCC data manager determines the properties of the channel by means of the channel function

ChnGetCaps.5. If the channel unit is loaded in Configuration mode, go to step 7. If no virtual connections are planned for the

channel unit, go to step 6, otherwise register the virtual connections of the channel by means of the channelfunction ChnRegisterConnections.

6. If the channel unit is loaded in Configuration mode or no virtual connections are planned for the channelunit, go to step 7, otherwise register the variables of the channel by means of the channel functionChnRegisterVariable.

7. Start of the channel by means of the channel function ChnStart.

1.3.2 Shutdown of a channel

The closing process of a channel-DLL can be divided into the following steps:

1. Shutdown of the channel unit(s) through the data manager2. Shutdown of the channel through the operating system

1.3.2.1 Shutdown of the channel units through the WinCC data manager

The release of a channel unit upon termination of the WinCC system is effected through the functionChnUnLoad.

ChnUnLoad

#include <ChnAPI.h>

BOOL ChnUnLoad(DWORD dwUnitId,PCMN_ERROR pes)

PARAMETERS

dwUnitId ID of the channel unit


RETURN


On shutdown, the channel unit must perform the following tasks through the data manager:

• Immediate termination of all current communications jobs• Release of the channel-specific connections kept by it• Release of the system resources allocated by it (dialog resources, memory etc.)

The memory of the virtual connections of the channel unit and the WinCC-variables is subject to themanagement of the WinCC data manager and must not be released through the channel.


A&D PT1 D2



Date29.02.2000

Version5.0


Page38 of 111


1.3.2.2 Unloading of the channel-DLL through the operating system

After the release of all units of a channel, the unloading of the channel-DLL is effected through the standardmechanisms of the operating system.

Die The channel-DLL must ensure that all relevant units were released after unloading.

1.3.3 Planning support through the channel unit

The design of WinCC allows for the coupling to a WinCC machine of additional coupled units via own channel-DLLs in addition to the systems already provided for.

The channel-DLL hides from the WinCC system the manner in which addresses of the process memory of itscoupled unit are indicated and how the connection is described via which it communicates with its coupled unit.This has a direct effect on the planning of WinCC-variables and virtual connections.

Each WinCC-variable consists of a general part and a channel-specific part. The general part is described bythe WinCC system, while the structure of the specific part is known only to the channel unit.

Specific part of avariable

General part of avariable

The same process applies for virtual connections.

Specific part ofvirtual connection

General part ofvirtual

Since only the channel unit knows the structure of the specific part, it is necessary for the channel-DLL toexpand the configuration of WinCC-variables and virtual connections in the form of channel-specific dialogs.

The operation in the configuration of WinCC-variables and virtual connections depends on whether the channelunit has implemented the manipulation of its dialogs with standard Windows mechanisms or by means ofVisual-C++ and MFC.

The type of implementation realized in a channel unit is communicated by the unit through the propertyCHNCAP_USEMFC.


A&D PT1 D2



Date29.02.2000

Version5.0


Page39 of 111


1.3.3.1 Dialog expansion in the planning of virtual connections

In the planning of a virtual connection, the WinCC dialog system only knows the general values of theconnection. These include the name of the virtual connection and the relevant channel.The structure of the general part of a virtual connection is defined through WinCC.

In the planning of a virtual connection, it is the task of the channel-DLL to provide the connection with achannel-specific connection description which defines the channel connection via which the coupled unit isreached.

The operation in the planning of the specific part of a virtual connection is determined through the type ofimplementation of the dialogs in the channel-DLL.In the implementation of a channel, there is a choice of two alternatives:

1. The channel-DLL is implemented by means of Visual-C++ and uses MFC means to realize its specificdialogs.

The specific dialogs are displayed as Property Pages in Property Sheets. 2. The channel-DLL is generated with a Windows-capable compiler and uses standard Windows mechanisms

to realize its specific dialogs.The specific dialogs are displayed as separate dialogs of the channel.

The first alternative presupposes Visual-C++ with MFC as development environment, while the secondalternative allows the implementation of the channel-specific dialogs with all Windows-capable compilers.

The way in which a channel-DLL is implemented is communicated by it through the propertyCHNCAP_USEMFC.

1.3.3.1.1 Planning of virtual connections with MFC dialogs

In the configuration of virtual connections with MFC dialogs, the specific dialog of the channel is part of aProperty Sheet.The following picture shows by way of example the general Property Page, the specific Property Page of thechannel is hidden.


A&D PT1 D2



Date29.02.2000

Version5.0


Page40 of 111


After the selection of the specific Property Page of a channel, the general Property Page disappears and thespecific page appears.The following picture shows by way of example the specific property page of the channel S5TF.

Note:The property pages listed here are examples which demonstrate the handling of the planning of a virtualconnection. The content of the pages is neither obligatory nor may a function of the channel S5TF bederived from the content.


A&D PT1 D2



Date29.02.2000

Version5.0


Page41 of 111


The operation of the planning of a virtual connection in the use of Visual-C++ and MFC is as follows:

WinCC data manager Channelunit

------------------------------------------------------------------->ChnGetConnectionPropPageCount

<-------------------------------------------------------------------Number of pages (1 <= number <= 10)

------------------------------------------------------------------->ChnGetConnectionPropPage

<-------------------------------------------------------------------CPropertyPage-Object

------------------------------------------------------------------->ChnGetConnectionPropPage


The WinCC data manager uses the function ChnGetConnectionPropPageCount to establish how manyproperty pages the channel unit requires for the planning of the specific part of a virtual connection. The unitsupplies a number between 1 and 10.In the next step the WinCC data manager obtains the property pages of the channel unit by means of thefunction ChnGetConnectionPropPage. The channel unit supplies an MFC object of class CPropertyPageback, which the WinCC data manager inserts into his property sheet.This step is repeated until all property pages of the channel unit have been collected.


A&D PT1 D2



Date29.02.2000

Version5.0


Page42 of 111


ChnGetConnectionPropPageCount#include <ChnAPI.h>

BOOL ChnGetConnectionPropPageCount(DWORD dwUnitId,PLOGCONNECTIONSTRUCT pConnection,PPLOGCONNECTIONSTRUCT ppConnection,DWORD dwConnectionCount,BOOL bEditNew,PINT piPageCount,PCMN_ERROR pes)

PARAMETERS

DwUnitId ID of channel unit

PConnection Pointer to WinCC structure of the virtual connection which will be plannednext.

PpConnection Pointer to array with pointers to already planned virtual connections

DwConnectionCount Number of already planned virtual connections

BEditNew Flag which shows whether the next connection should be a new virtualconnection (TRUE) or an already existing one (FALSE)

PiPageCount Ptr to INT in which the channel unit stores the number of property pagesrequired for the planning of the declared virtual connection.

Pes Pointer to standard WinCC error structure

RETURN

TRUE No errors

FALSE Error in API function

The WinCC data manager uses the function ChnGetConnectionPropPageCount to determine the number ofproperty pages which the channel unit requires for the planning of the given connection.The pointer pConnection points to the management structure of the virtual connection which will be plannednext.The flag bEditNew shows whether a new virtual connection is planned or an already existing one.

ChnGetConnectionPropPage

#include <ChnAPI.h>

BOOL ChnGetConnectionPropPage(DWORD dwUnitId,PLOGCONNECTIONSTRUCT pConnection,


A&D PT1 D2



Date29.02.2000

Version5.0


Page43 of 111


PPLOGCONNECTIONSTRUCT ppConnection,DWORD dwConnectionCount,BOOL bEditNew,INT iPageIndex,VOID **ppPage,PCMN_ERROR pes)

PARAMETERS


PConnection Pointer to WinCC structure of the virtual connection which will be plannednext.



BEditNew Flag which shows whether the next connection should be a new virtualconnection (TRUE) or an already existing one (FALSE)

IPageIndex Index of the page which is collected.

PpPage Ptr to pointer in which the channel unit stores the address of an MFCobject of class CPropertyPage.


RETURN

TRUE No errors


The WinCC data manager uses the function ChnGetConnectionPropPage to collect a property page fromeach channel unit. The index of the property page is given in iPageIndex (start index = 0).The channel unit creates an MFC object of class CPropertyPage and supplies the data manager with a pointerto this object. The WinCC data manager inserts the object into its property sheet. This process is repeated untilall pages of the channel unit have been collected.

The WinCC data manager inserts the property pages of the channel unit into an object of type CPropertySheet.In the processing of the property dialog, the member functions of the relevant object in the channel unit areactivated when a property page of the channel unit is activated. (See also the MFC documentation of classCPropertyPage).

The parameter ppConnection points to an array with pointers to already existing virtual connections. Theirnumber is given in dwConnectionCount.The array can be used by the channel unit in order to perform consistency checks in the planning of virtualconnections.

1.3.3.1.2 Planning of virtual connections with standard Windows means

If the specific dialogs of a channel-DLL are realized with standard Windows means, the planning of the specificpart of a virtual connection is effected by means of the function ChnEditConnection.


A&D PT1 D2



Date29.02.2000

Version5.0


Page44 of 111


ChnEditConnection#include <ChnAPI.h>

BOOL ChnEditConnection(DWORD dwUnitId,PLOGCONNECTIONSTRUCT pConnection,PPLOGCONNECTIONSTRUCT ppConnection,DWORD dwConnectionCount,BOOL bEditNew,PCMN_ERROR pes);

PARAMETERS


PConnection Pointer to parameter set of the virtual connection which is to be planned



BEditNew Flag which shows whether a new virtual connection should be planned(TRUE) or an already existing one (FALSE)


RETURN

TRUE Specific part of the virtual connection was correctly planned, the planned data are inthe specific data area.

FALSE Termination of planning, specific data area was not changed

In the function ChnEditConnection, the channel unit performs all the steps necessary for the planning of thespecific data of the virtual connection.With the acceptance of the values by the user, the unit stores the planned values in the specific data area ofthe virtual connection and supplies TRUE as function result. If the user terminates the planning, the functionsupplies FALSE.

In each case the function may not be terminated until the planning has been concluded or aborted.

The parameter ppConnection points to an array with pointers to already existing virtual connections. Theirnumber is given in dwConnectionCount.The array can be used by the channel unit to perform consistency checks in the planning of virtual connections.

1.3.3.1.3 Tasks in the planning of the channel-specific part of a virtual connection

In the planning of the specific part of a virtual connection, the channel unit is responsible for the correctprocessing of the following points:


A&D PT1 D2



Date29.02.2000

Version5.0


Page45 of 111


1. The channel unit identifies defective entries during planning and indicates the cause of error through thecorresponding text.

2. With the acceptance of the planning data, the channel unit changes the input data into the channel-specific

format and copies this channel-specific description into the channel-specific memory area of the virtualconnection (pConnection->pvExt).

3. After the acceptance of the planning data, the channel unit sets in the field wCaps in the general part of the

virtual connection a combination of the bits LCC_CANREAD and LCC_CANWRITE, which tell the WinCCdata manager which services the virtual connection supports.

4. After the termination of the planning of a virtual connection, all system resources which were reserved

during planning must be released.

1.3.3.2 Dialog expansion in the configuration of WinCC-variables

In the configuration of a WinCC-variable, the WinCC dialog system only knows the general values of thevariable. These include for example the name of the variable and the relevant virtual connection.The structure of the general part of a virtual connection is defined through WinCC.

In the planning of a WinCC-variable, it is the task of the channel-DLL to provide the variable with a channel-specific address description which defines at which address in the coupled unit the process data are located.

The operation in the configuration of the specific part of a WinCC-variable is determined through the type ofimplementation of the dialogs in the channel-DLL.In the implementation of a channel, there is a choice of two alternatives:

1. The channel-DLL is implemented by means of Visual-C++ and uses MFC means to realize its specificdialogs.

The specific dialogs are displayed as Property Pages in Property Sheets. 2. The channel-DLL is generated with a Windows-capable compiler and uses standard Windows mechanisms

to realize its specific dialogs.The specific dialogs are displayed as separate dialogs of the channel.

The first alternative presupposes Visual-C++ with MFC as the development environment, the secondalternative allows the implementation of the channel-specific dialogs with all Windows-capable compilers.

The way in which a channel-DLL is implemented is communicated by it through the propertyCHNCAP_USEMFC.

1.3.3.2.1 Variables configuration for SIMATIC S5/S7 controls

If the coupled unit of a channel unit is a control of type SIMATIC S5 or SIMATIC S7, functions of the generalSIMATIC DLL can be accessed in the development of the channel unit..

This DLL contains both the structure of the specific address description and the total specific planning of aSIMATIC variables address (see also /1/)

1.3.3.2.2 Configuration of WinCC-variables with MFC dialogs

In the configuration of WinCC-variables with MFC dialogs, the specific dialog of the channel is part of a propertysheet.


A&D PT1 D2



Date29.02.2000

Version5.0


Page46 of 111


The configuration of a virtual connection in the use of Visual-C++ and MFC is as follows:

WinCC data manager Channelunit

------------------------------------------------------------------->ChnGetVariablePropPageCount

<-------------------------------------------------------------------Number of pages (1 <= number <= 10)

------------------------------------------------------------------->ChnGetVariablePropPage


------------------------------------------------------------------->ChnGetVariablePropPage


The WinCC data manager uses the function ChnGetVariablePropPageCount to establish how many propertypages the channel unit requires for the planning of the specific part of a WinCC-variable. The unit supplies anumber between 1 and 10.In the next step the WinCC data manager obtains the property pages of the channel unit by means of thefunction ChnGetVariablePropPage. The channel unit supplies an MFC object of class CPropertyPage, whichthe WinCC data manager inserts into his property sheet.This step is repeated until all property pages of the channel unit have been collected.

ChnGetVariablePropPageCount#include <ChnAPI.h>

BOOL ChnGetVariablePropPageCount(DWORD dwUnitId,PVARIABLESTRUCT pVariable,BOOL bEditNew,PINT piPageCount,PCMN_ERROR pes)

PARAMETERS

dwUnitId ID of channel unit

pVariable Pointer to WinCC structure of the WinCC-variable which is will be planned next.

bEditNew Flag which shows whether the next variable should be a new WinCC-variable(TRUE) or an already existing one (FALSE)

piPageCount Ptr to INT in which the channel unit stores the number of property pages requiredfor the planning of the given WinCC-variable.


RETURN


A&D PT1 D2



Date29.02.2000

Version5.0


Page47 of 111


TRUE No errors


The WinCC data manager uses the function ChnGetVariablePropPageCount to determine the number ofproperty pages which the channel unit requires for the planning of the declared WinCC-variable.The pointer pVariable points to the management structure of the WinCC-variable connection which will beplanned next, the pointer pVariable->pvExt to the memory area in which the channel unit stores the channel-specific address description.The flag bEditNew shows whether a new WinCC-variable is planned or an already existing one.

ChnGetVariablePropPage

#include <ChnAPI.h>

BOOL ChnGetVariablePropPage(DWORD dwUnitId,PVARIABLESTRUCT pVariable,BOOL bEditNew,INT iPageIndex,VOID **ppPage,PCMN_ERROR pes)

PARAMETERS


pVariable Pointer to WinCC structure of the WinCC-variable which is will be planned next.

bEditNew Flag which shows whether the next variable should be a new virtual connection(TRUE) or an already existing one (FALSE)

iPageIndex Index of the page which is collected

ppPage Ptr to pointer in which the channel unit stores the address of an MFC object ofclass CPropertyPage.


RETURN

TRUE No errors


The WinCC data manager uses the function ChnGetVariablePropPage to collect a property page from eachchannel unit.The channel unit creates an MFC object of class CPropertyPage and supplies the data manager with a pointerto this object. The WinCC data manager inserts the object into its property sheet. This process is repeated unitlall pages of the channel unit have been collected.


A&D PT1 D2



Date29.02.2000

Version5.0


Page48 of 111


The WinCC data manager inserts the property pages of the channel unit into an object of type CPropertySheet.In the processing of the property dialog, the member functions of the relevant object in the channel unit areactivated when a property page of the channel unit is activated. (See also the MFC documentation of classCPropertyPage).

1.3.3.2.3 Planning of WinCC-variables with standard Windows means

If the specific dialogs of a channel-DLL are realized with standard Windows means, the planning of the specificpart of a virtual connection is effected by means of the function ChnEditVariable.

ChnEditVariable#include <ChnAPI.h>

BOOL ChnEditVariable(DWORD dwUnitId,PVARIABLESTRUCT pVariable,BOOL bEditNew,PCMN_ERROR pes)

PARAMETERS


pVariable Pointer to parameter set of the WinCC-variable which is to be planned

bEditNew Flag which shows whether a new WinCC-variable should be planned (TRUE) oran already existing one (FALSE)


RETURN

TRUE Specific part of the variable was correctly planned, the planned data are in the specificdata area.

FALSE Termination of planning, specific data area was not changed

In the function ChnEditVariable, the channel unit performs all the steps necessary for the planning of thespecific data of the WinCC-variable.With the acceptance of the values by the user, the unit stores the planned values in the specific data area ofthe WinCC-variable (pVariable->pvExt) and supplies TRUE as function result. If the user terminates theplanning, the function supplies FALSE.

In each case the function may not be terminated until the planning has been concluded or aborted.

1.3.3.2.4 Tasks in the planning of the channel-specific part of a variable

In the planning of the specific part of a variable, the channel unit is responsible for the correct processing of thefollowing points:


A&D PT1 D2



Date29.02.2000

Version5.0


Page49 of 111


1. The channel unit identifies defective entries during planning and indicates the cause of error through thecorresponding text.

2. With the acceptance of the planning data, the channel unit changes the input data into the channel-specific

format and copies this channel-specific variable description into the channel-specific memory area of thevariable (pVariable->pvExt).

3. The channel unit determines from the input variable address the length of the memory area which is

described by this variables address and stores this length in the general part of the WinCC-variable. 4. The channel unit sets in the general part of the variable a combination of the bits VARC_DMCANREAD,

VARC_DMCANWRITE, and VARC_SERVERACCESS (see chapter 1.2.6.4.1, Channel unit-relevant statusbits of a variable, page 17)

5. After termination of the planning of a variable, all resources which were reserved during the planning must

be released.

1.3.3.2.5 Return of bit width of a specific variable address

For each planned variable, the WinCC data manager can inquire the minimum bit width of the data type of thevariable from the relevant channel unit by means of the function ChnGetAddressUnitSize.

ChnGetAddressUnitSize#include <ChnAPI.h>

BOOL ChnGetAddressUnitSize(DWORD dwUnitId,PVARIABLESTRUCT pVariable,PDWORD pdwBitSize,PCMN_ERROR pes)

PARAMETERS

DwUnitId ID of the channel unit

PVariable Pointer to parameter set of the WinCC-variable for whose address the minimumdata width of the data type is being inquired.

PdwBitSize Pointer to DWORD in which the channel unit stores the minimum bit width of thedata type.


RETURN

TRUE No errors

FALSE Error, precise cause of error in standard error structure

For the given variable, the channel unit establishes the minimum bit width of the data type and supplies this inbits.


A&D PT1 D2



Date29.02.2000

Version5.0


Page50 of 111


Example:The coupled unit of the channel unit is a SIMATIC S5, the specific variable address is DB45, DW23. Theminimum bit width of the data type for DW is one word, i.e. 16 bits. The function supplies the value 16 viathe pointer pdwBitSize.

1.3.3.2.6 Return a new variable address with given variable address plus offset

The function ChnBuildVariableAddress allows the WinCC data manager to access a data element within adata structure of a planned variable directly by returning its channel specific address.

ChnBuildVariableAddress

#include <ChnAPI.h>

BOOL ChnBuildVariableAddress( DWORD dwUnitId, PVARIABLESTRUCT pVariableIn, PVARIABLESTRUCT pVariableOut, DWORD dwOffsetInBit, PCMN_ERROR pes)

PARAMETERS


pVariableIn Pointer to parameter set of the WinCC-variable that is a data structure containingthe desired data element.

pVariableOut Pointer to parameter set of the WinCC-variable that is the desired data element.

dwOffsetInBit DWORD containing the offset of the desired data element within the datastructure in bits.


RETURN

TRUE No errors

FALSE Error, precise cause of error in standard error structure

Example:The coupled unit of the channel unit is a SIMATIC S5, the specific variable address is DB100, DW10. Thevariable consists of 16 data words. The WinCC data manager wants a direct access to the fourth dataword, so it would deliver the UnitId, a pointer to the VARIABLESTRUCT and the offset within this variable( would be 48 bits in this example) and the ChnBuildVariableAddress funtion would return the specificvariable address DB100 DW13.

1.3.3.3 Planning of the configuration of a channel or channel unit

Each channel unit has the possibility of planning internal configuration values through its own dialog. Adistinction is made between global configuration values and configuration values specific to a channel unit.


A&D PT1 D2



Date29.02.2000

Version5.0


Page51 of 111


channel-DLL defines through the property bit CHNCAP_OWNPROPERTIES whether it supports its ownplanning for internal configuration values.

The planning of the configuration values is effected through the function ChnEditProperties.

ChnEditProperties#include <ChnAPI.h>

BOOL ChnEditProperties(DWORD dwUnitId,PWORD pwRestartMode,LPSTORAGE pStorage,PCMN_ERROR pes)

PARAMETERS

dwUnitId CHNUNIT_ALL Planning of the global configuration values, whichapply independently of a channel unit

otherwise ID of the channel unit whose configuration values areplanned n

pwRestartMode Pointer to WORD variable in which the channel unit stores when thechanges of the configuration values become valid.The channel unit can store the following values:

LCEP_NONE No change takes placeLCEP_NORESTART No restart of the system for activation of the

changed values of the channel unitnecessary

LCEP_RESTART Restart of the system for activation of thechanged values of the channel unitnecessary

pStorage Pointer to storage in which the channel unit can store its configurationvalues.Note: ChnEditProperties is the only function that ist allowed towrite (an read) to the storage!


RETURN

TRUE No errors in the planning of the channel-internal properties.

FALSE Termination of planning

The total extent of the planning of the channel-internal configuration is a matter for the channel unit.

On the call of the function ChnEditProperties in the parameter pStorage, the channel unit receives a pointer toa storage within a compound file.This storage must be used by the channel unit in order to store the data accruing in the planning of thechannel-internal configuration.

The structure of the storage can be freely selected by the channel unit.


A&D PT1 D2



Date29.02.2000

Version5.0


Page52 of 111


At startup, the channel unit then receives access to this storage again.

1.3.4 Variable interface

The variable interface of the channel receives the functions which are necessary for access to the processvalues in the coupled unit.

• Read process values A channel unit reads process values from the process memory of a coupled unit and transfers these to the

WinCC data manager. • Write process values

A channel unit accepts data from the WinCC data manager and writes them in the process memory of acoupled unit.

In addition, the following points must be noted in the variable interface: • Who manages cyclical requests?• How does the channel unit change read process values into the WinCC format and how does it supply the

read process values?• How does the channel unit receive the process values to be written and how is the conversion of the values

to be written into the format of the coupled unit effected?• How does the channel unit inform the WinCC data manager of the status of the process data access?

1.3.4.1 Management of cyclical requests

The behaviour of the variable interface is significantly influenced by whether the channel unit performs its owncycle management or relinquishes the cycle management to the WinCC data manager

1.3.4.1.1 Channel unit with own cycle management

If variables are updated by a channel unit with own cycle management, the WinCC data manager logs thevariable(s) on once by means of the function ChnStartRead. The organisation of the cycle time is leftcompletely to the channel unit.

New process values of a variable are communicated to the WinCC data manager by means of a callbackfunction.If the updating of one or more variables is no longer necessary, the WinCC data manager logs the variables offby means of the function ChnStopRead.

The following picture shows the schematic operation of variables updating where there is own cyclemanagement through the channel.


A&D PT1 D2



Date29.02.2000

Version5.0


Page53 of 111


WinCC data manager Channel Coupled unit

ChnStartRead(...)

(*pfnReadFinish)(...) Request processvalue(s)

(*pfnReadFinish)(...) Request processvalue(s)

ChnStopRead(...)

1.3.4.1.2 Cycle management by the WinCC data manager

In the case of cycle management by the WinCC data manager, the latter logs a WinCC-variable on with achannel unit by means of the function ChnStartRead as soon as the cycle of the variable requires updating.The channel unit carries out the communications steps necessary for requesting the process values. Theprocess values which have been read are passed to the WinCC data manager by means of a callback function.As soon as the WinCC data manager receives the process values of the variable, it catalogs the variable(s) inhis cycle management again.If a renewed request of the variable after the expiry of the cycle time is necessary, the request process beginsagain.

By using the function ChnStopRead, the WinCC data manager can abort the requests for variables whichwere passed to a channel unit by means of the function ChnStartRead. In this case the channel unit mustdecide how the cancel process is to be performed.The following picture shows the schematic operation of variables updating for cycle management by the WinCCdata manager.

WinCC data manager Channel Coupled unit--------------------------------------> ------------------->ChnStartRead(...) Request process

value(s)<------------------------------------- <-------------------(*pfnReadFinish)(...)

--------------------------------------> ------------------->ChnStartRead(...) Request process

value(s)<------------------------------------- <-------------------(*pfnReadFinish)(...)

1.3.4.2 Access result of a variable

According to the access to process data in the coupled unit (read or write), the channel unit informs the WinCCdata manager of the status of the access. For the service read process values with the read values, if theservice was processed without errors, for the service write process values only the access status iscommunicated.


A&D PT1 D2



Date29.02.2000

Version5.0


Page54 of 111


For each variable of a request, the channel unit stores the status of the access to process data in the coupledunit in a structure of type VARIABLEACCESSRESULT.

VARIABLEACCESSRESULT

typedef struct{

PVOID pvData;WORD wStatus;DWORD dwTransactId;

} VARIABLEACCESSRESULT,*PVARIABLEACCESSRESULT,**PPVARIABLEACCESSRESULT;

Structure component MeaningpvData Pointer to data area in which the channel unit stores read process data. The

data area is initialized in the reading of process values by the channel unit forthe duration of the acknowledgement.If data were written, the channel unit enters the values NULL..

wStatus Here the channel unit enters the status of the access.

dwTransactId Transaction ID which was allocated on the request of the variable (seechapter 1.3.4.3, page 55).

Status bits of a variable

The channel unit stores information concerning the success of the access in wStatus. The following bit valuescan be used:

0 No error in access

DM_VARSTATE_HANDSHAKE_ERROR In access to process data, an error occurred in the operation of theprotocol

DM_VARSTATE_ADDRESS_ERROR The requested address area is too short / not available, blocked etc.

DM_VARSTATE_CONNECTION_ERROR Access to the process data is not possible, because there is aninterruption of the connection via which the access was to beeffected.

1.3.4.3 Allocation of a transaction ID through the WinCC data manager

For both the service read process values and the service write process values, the data manager can declareone or more variables.For each read and write job, the WinCC data manager allocates a transaction ID by means of which it identifiesthe declared variables in the further operation.

The channel unit must note the given transaction ID during the whole length of processing the relevant variableand declare it again on the acknowledgement of completed processing.


A&D PT1 D2



Date29.02.2000

Version5.0


Page55 of 111


1.3.4.4 Recoding of process values in the byte order of the coupled unit and back

The channel unit defines whether process data in its coupled unit are in INTEL byte order or not using theproperty bit CHNCAP_INTELBYTEORDER.

If the process data in the coupled unit are not in INTEL byte order, the following recodings must be effected:

- Before the process values are written, these must be recoded into the byte order of the coupled unit.

- After the process values are read, these must be converted into the byte order of the WinCC system(INTEL byte order).

The recoding of the process values is effected by means of the function ChnChangeByteOrder..

ChnChangeByteOrder#include <ChnAPI.h>

BOOL ChnChangeByteOrder(DWORD dwUnitId,PVOID pvData,DWORD dwStartOffset,DWORD dwNextOffset,DWORD dwElementSize,DWORD dwCount,PCMN_ERROR pes);

PARAMETERS


pvData Pointer to data area which contains the data which are being recoded.

dwStartOffset Offset of the first datum which is being recoded.

dwNextOffset Offset starting from the current datum at which the next datum which isbeing recoded is located.

dwElementSize Length in bytes of the data to be recoded

dwCount Number of elements which are being recoded


RETURN


The parameters of the function ChnChangeByteOrder are to be interpreted as follows:


A&D PT1 D2



Date29.02.2000

Version5.0


Page56 of 111


pvData

dwNextOffset

dwStartOffset

}dwElementSize

The data buffer to which pvData points can contain in some circumstances several areas in which the byteorder must be changed. The number of areas to be recoded is given in dwCount. The parameter dwStartoffsetcontains the offset from the start of the data buffer at which the first area to be recoded is located. Theparameter dwNextOffset contains the offset from the current area at which the next area to be recoded islocated.

The parameter dwElementSize defines the length in bytes of an area to be recoded. The conversion of the byteorder is effected according to this length.

Example:

The actual values of the element length dwElementSize is 2, i.e. an area to be recoded consists of 2 bytes orone word. In this case the function ChnChangeByteOrder must ensure that the declared area is recodedaccording to the byte order of one word.

1.3.4.5 Read process values

Process values are read from the process memory of a coupled unit by means of the function ChnStartRead.The WinCC data manager logs on one or more WinCC-variables with a channel unit for updating.

ChnStartRead#include <ChnAPI.h>

BOOL ChnStartRead(DWORD dwUnitId,PLOGCONNECTIONSTRUCT pConnection,PPVARIABLESTRUCT ppVariable,DWORD dwVariableCount,DWORD dwCycle,DWORD dwTransactId,PCMN_ERROR pes);

PARAMETERS


pConnection Pointer to parameter set of the virtual connection via which the variable(s)are updated

ppVariable Pointer to array which contains pointer to variable to be updated


A&D PT1 D2



Date29.02.2000

Version5.0


Page57 of 111


dwVariableCount Number of entries of array

dwCycle Cycle in ms, in which the variables are requested. Only relevant forchannel units which form their cycle themselves.

dwTransactId Transaction ID of this job


RETURN


The transaction ID of this job is given in dwTransactId. The number of logged on variables is given indwVariableCount. The pointer ppVariable points to an array which contains pointers to the descriptions of thevariables to be updated. The values of all variables are read via the virtual connection pConnection.

ppVariable Variable 1Index 0

Index 1Variable 2

Variable (N+1)Index N

Important:

The memory of the arrays to which ppVariable points is only valid during the call of ChnStartRead.The channel unit must secure the addresses of the variables in its own memory area.

Note:Do not call READFINISHCB in your implementation of ChnStartRead. This may cause deadlocks inthe DataManager.

The processing steps which the channel unit has to perform after the logging on of one or more variables forupdating depend on whether the channel unit has its own cycle management or the WinCC data managerperforms the cycle management.

1.3.4.5.1 Reading of variables for cycle management through the channel

If the management of the cyclical requests is effected by the channel unit itself, the WinCC data manager logson the variables to be updated with the channel unit by means of the function ChnStartRead. For each call ofthe function, one or more variables and the cycle time in which the variables must be requested are transferred.If the WinCC data manager wishes to log on several variables with different updating cycles for updating at thesame time, he calls the function ChnStartRead several times consecutively and for each call declares allvariables with the same updating cycle.

For each call, the channel unit must perform the following steps:

• Integrate the declared variables in the cycle management of the channel unit


A&D PT1 D2



Date29.02.2000

Version5.0


Page58 of 111


• Perform the necessary communications steps as soon as the cycle of one or more variables requests anupdating

As soon as one or more variables are requested, the channel unit must perform the following steps: • Optimization steps in order to reduce the number of communications steps required for access to the

process memory of the coupled unit (optional).• Read the process values from the coupled unit (obligatory).• Return the read process values to the WinCC data manager (obligatory)• Renewed enqueuing of the read variables into the cycle management of the channel unit.

In the event of the break of a connection (connection termination), all variables logged on by the WinCC datamanager for this connection remain active in the channel unit. The channel unit must ensure that thesevariables are requested again after connection is re-established.

1.3.4.5.2 Reading of variables for cycle management by the WinCC data manager

If the management of the cyclical requests is effected by the channel unit itself, the WinCC data manager logson the variables to be updated with the channel unit by means of the function ChnStartRead. For each call ofthe function, all variables to updated at one time are transferred. The parameter dwCycle has no meaning incycle management by the WinCC data manager.The channel unit performs the following steps with the declared variables:

• Optimization steps in order to reduce the number of communications steps required for access to theprocess memory of the coupled unit (optional)

• Read the process values from the coupled unit (obligatory)• Return the read process values to the WinCC data manager (obligatory)

1.3.4.5.3 Possible optimizations in the reading of variables

In order to reduce the number of communications steps required for access to the process memory of thecoupled unit, the channel unit can perform the following optimization steps:

• Collecting overlapping address areas of several variables which are updated via one virtualconnection.

• Declare several address areas in one request telegram to the coupled unit

1.3.4.5.3.1 Optimization through collection of overlapping address areas

The channel unit can explore all variables waiting for updating, for the same data areas.If two or more variables are found with the same data area, the whole memory area which contains the data ofall variables of this data area can be requested from the coupled unit in one communications step and then thedata actually required can be distributed to the variables.

Example:A WinCC machine is coupled with a SIMATIC S5 control via a corresponding channel. On the call of thefunction ChnStartRead, the following variables are declared:

V1: DB 100, DW 1V2: DB 101, DW 10V3: DB 100, DW 5V4: DB 101, DW 95


A&D PT1 D2



Date29.02.2000

Version5.0


Page59 of 111


The channel unit identifies common address areas for V1 and V3 and for V2 and V4 (the same data block ineach case).

The optimization produces two request steps to the coupled unit:

Requ.1: DB 100, DW 1-5Requ.2: DB 101, DW 5-95

From the read data areas, the channel unit then copies the required values into the relevant variables.

1.3.4.5.3.2 Optimization through declaration of several address areas in one request

This optimization step can only be performed if the communications protocol used allows it..

Instead of several requests with one data area each going to the coupled unit, several data areas are declaredin one request. This again reduces the number of communications steps required.

1.3.4.5.4 Reading the process values from the coupled unit

The channel unit performs the necessary communications steps in order to read the process values from thecoupled unit.

WinCC does not specify technical requirements concerning the communications operation.

1.3.4.5.5 Return of read process values to the WinCC data manager

For each variable requested, the channel unit supplies the status of the access and the read data, if the accesswas effected without error, via an access result.

To this end the channel unit must allocate the memory for an access result for each variable requested andstore the following information within it:

• Status of the access (access with/without error)• For access without errors, the address of the memory area which containes the read data• The transaction ID allocated to the variable in the request

The fully processed variables and the relevant access results are returned to the WinCC data manager in theform of two arrays.One array contains the addresses of the requested variables, the other the relevant access results. Theallocation between variable and access result is effected through the same array index.


Index 1Variable 2



A&D PT1 D2



Date29.02.2000

Version5.0


Page60 of 111


ppAccessResult Index 0

Index 1

Index N

Data Var. 1Access res. Var. 1

Data Var. 2Access res. Var. 2

Access without error

The channel unit enters the value 0 in the field wStatus of the access result. The address of the memoryarea which contains the read process values is given in the field pvData of the access result. Thetransaction ID of the variables is stored in dwTransactId.

Access with error

The channel unit enters the cause of the access error in the field wStatus by means of status bits (seechapter 1.3.4.2, page Fehler! Textmarke nicht definiert.) and the value NULL in the field pvData. Thetransaction ID of the variables is stored in dwTransactId.

The return of the read WinCC-variables is effected by means of a callback function whose address the channelreceives in the function ChnStart.

READFINISHCBtypedef VOID (*READFINISHCB)(

PPVARIABLESTRUCT ppVariable,PPACCESSRESULT ppAccessResult,DWORD dwVariableCount);

The array ppVariable contains pointers to the variables whose processing by the channel unit has beenconcluded. The array ppAccessResult contains pointers to the relevant access results.

The order of the pointers to the variables and access results can differ from the order upon the initiation of thejob in the function ChnStartRead.The allocation between variable and access result is effected via the common array index.

In the invoked callback function, the WinCC data manager converts the byte order of the read data by means ofthe function ChnChangeByteOrder.

After the callback function has been invoked, the channel unit can release all memory areas which wereallocated through the channel unit during the processing of the acknowledged variables.

Note:Do not call READFINISHCB in your implementation of ChnStartRead. This may cause deadlocks inthe DataManager.


A&D PT1 D2



Date29.02.2000

Version5.0


Page61 of 111


1.3.4.6 Abort read process values

The WinCC data manager can abort the request of one or more variables by means of the functionsChnStopRead or StopReadEx. ChnStopRead is supported for old channels only. New implementationsshould use ChnStopReadEx.

ChnStopRead#include <ChnAPI.h>

BOOL ChnStopRead(DWORD dwUnitId,PPVARIABLESTRUCT ppVariable,DWORD dwVariableCount,PCMN_ERROR pes);

PARAMETERS


PpVariable Ptr to array which contains pointers to the variables whose request is to beaborted.

DwVariableCount Number of variables in the array ppVariable


RETURN


The parameter ppVariable points to an array which contains pointers to the variable whose request is to beaborted.The channel unit searches for the declared variable and immediately terminates their processing. There is noacknowledgement to the WinCC data manager.

ChnStopReadEx#include <ChnAPI.h>

BOOL ChnStopReadEx(DWORD dwUnitId,PPVARIABLESTRUCT ppVariable,DWORD dwVariableCount,DWORD dwCycle,PCMN_ERROR pes);

PARAMETERS


PpVariable Ptr to array which contains pointers to the variables whose request is to be


A&D PT1 D2



Date29.02.2000

Version5.0


Page62 of 111


aborted.

DwVariableCount Number of variables in the array ppVariable

dwCycle Cycle in ms, in which the variables are requested. Only relevant forchannel units which form their cycle themselves.


RETURN


The parameter ppVariable points to an array which contains pointers to the variable whose request is to beaborted.The channel unit searches for the declared variable and immediately terminates their processing. There is noacknowledgement to the WinCC data manager.

1.3.4.7 Write process values

Process values are written into the process memory of a coupled unit by means of the function ChnStartWriteThe WinCC data manager logs on with a channel unit one or more WinCC-variables which contain the processmemory addresses in the coupled unit and the value to be written.

ChnStartWrite#include <ChnAPI.h>

BOOL ChnStartWrite(DWORD dwUnitId,PLOGCONNECTIONSTRUCT pConnection,PPVARIABLESTRUCT ppVariable,DWORD dwVariableCountPPCHN_WRITEDESCRIPTOR ppWriteDescriptor,DWORD dwTransactId,PCMN_ERROR pes);

PARAMETERS


pConnection Pointer to parameter set of the virtual connection via which the variable(s)are to be written

ppVariable Pointer to array which contains pointer to description of the variable to bewritten


ppWriteDescriptor Pointer to array which contains pointer to description of the data to bewritten

dwTransactId Transaction ID of this job.


A&D PT1 D2



Date29.02.2000

Version5.0


Page63 of 111



RETURN


The transaction ID of this job is given in dwTransactId. The number of logged on variables is given indwVariableCount. The pointer ppVariable points to an array which contains pointers to the descriptions of thevariables to be updated. The values of all variables are written via the virtual connection pConnection.


Index 1Variable 2


The pointer ppWrite points to an array which contains pointers to the description of the data to be written. Theallocation between variable and description of the data to be written is effected via the same array index.

ppWriteDescriptor Index 0

Index 1

Index N

Data Var. 1Data descr. 1


Important:

The memory of the arrays ppVariable and ppWriteDescriptor is only valid during the call ofChnStartWrite. The channel unit must secure the addresses of the variables and the addresses ofthe data descriptions in its own memory area.

1.3.4.7.1 Description of the data to be written

For each variable to be written, the channel unit reaceives a description of the data to be written in the form of amemory area of the structure CHN_WRITEDESCRIPTOR;

CHN_WRITEDESCRIPTORtypedef struct{

DWORD dwOffsetFromBase;DWORD dwWriteLength;PVOID pvData;

} CHN_WRITEDESCRIPTOR,


A&D PT1 D2



Date29.02.2000

Version5.0


Page64 of 111


*PCHN_WRITEDESCRIPTOR,**PPCHN_WRITEDESCRIPTOR;

Structure component MeaningdwOffsetFromBase Write offset in bits, which must be added to the base address of the variable

dwWriteLength Length in bits of the data to be written

pvData Pointer to data which are being written.

For each variable to be written, the channel unit must calculate the effective write address from which the datacan be written in the coupled unit.The effective write address is derived from the base address of the data to be written and the write offset, whichis contained in dwOffsetFromBase.

Example:

The coupled unit is a SIMATIC S5 control, the base address of the data to be written is DB100, DW2, thewrite offset dwOffsetFromBase contains the value 4, i.e. 4 bytes (or 2 words) must be added to the baseaddress from DW2.The effective write address is DB100, DW4.

If the channel supports write access to a single bit (property bit CHNCAP_WRITE2BIT), each bit to be written iscoded in the write data as a byte (byte value = 0: bit is not set, byte value <> 0: bit is set).

1.3.4.7.2 Adaptation of the byte order of the data to be written

Before the WinCC data manager starts a write job by means of the function ChnStartWrite, the byte order ofthe data to be written is adapted to the byte order of the coupled unit of the channel unit by means of thefunction ChnChangeByteOrder.

1.3.4.7.3 Possible optimizations in the writing of variables

In order to reduce the number of communications steps required for write access to the process memory of thecoupled unit, the channel unit can perform the following optimization steps:

• Declare several address areas in one write telegram to the coupled unit

1.3.4.7.3.1 Several address areas in one request

This optimization step can only be performed if the communications protocol used allows it.

Instead of sending several requests with one data area each to the coupled unit, several data areas aredeclared in one request. This reduces the number of communications steps required.

1.3.4.7.4 Writing the process values into the coupled unit

The channel unit performs the necessary communications steps in order to write the process values into thecoupled unit.

WinCC does not specify technical requirements concerning the communications operation.


A&D PT1 D2



Date29.02.2000

Version5.0


Page65 of 111


1.3.4.7.5 Return of the write status to the WinCC data manager

For each variable written, the channel unit supplies the following information to the WinCC data managerconcerning the access result:

• Status of the access (access with/without error) The transaction ID allocated to the variable in the request.

Access without error The channel unit enters the value 0 in wStatus. The transaction ID of the variables is stored indwTransactId.

Access with error The channel unit enters the cause of the access error in wStatus by means of status bits (see chapter1.3.4.2, page 54). The transaction ID of the variables is stored in dwTransactId.

The return of the read WinCC-variables is effected by means of a callback function whose address the channelreceives in the function ChnStart.

WRITEFINISHCB typedef VOID (*WRITEFINISHCB)( PPVARIABLESTRUCT ppVariable, PPACCESSRESULT ppAccessResult, DWORD dwVariableCount); For each variable written, the channel unit supplies the status of the write access via an access result. To this end the channel unit must allocate the memory for an access result for each variable requested andstore the following information within it: • Status of the access (access with/without error)• The transaction ID allocated to the variable in the request.

The fully processed variables and the relevant access results are returned to the WinCC data manager in theform of two arrays.One array contains the addresses of the requested variables, the other the relevant access results. Theallocation between variable and access result is effected through the same array index.


A&D PT1 D2



Date29.02.2000

Version5.0


Page66 of 111



Index 1Variable 2


ppAccessResult Index 0

Index 1

Index N

Access res. Var. 1

Access res. Var. 2

The order of the pointers to the variables and access results can differ from the order upon the initiation of thejob in the function ChnStartWrite. However, with each variable the access result which was declared at jobinitiation must be returned.

1.3.4.8 Access to WinCC-variables through the coupled unit of a channel unit

A channel unit defines, through the property bit CHNCAPS_CLIENTONLY, whether or not its coupled units canaccess variables of the WinCC system on their own intitiative.

If this bit is not set (channel unit is client and server), the WinCC data manager isolates for this channel unit theinterface via which the server access of the channel to the WinCC-variable takes place.

1.3.4.8.1 Which WinCC-variables a coupled unit of a channel unit can access

The coupled units of a channel unit can access the following WinCC-variables:

- Process variables of the virtual connection via which the coupled unit is coupled to the WinCCsystem. This access can be read and write.

- Internal system variables of the WinCC system.The corresponding buts of the relevant system variable determine whether a coupled unit has readand/or write access to a system variable of the WinCC system. Thus there are system variableswhich a coupled unit of a channel unit cannot access, or to which there is only read access or readand write access.

1.3.4.8.2 Server access to process variables of own virtual connection

If a channel unit was started in Runtime mode, a channel receives by means of the functionChnRegisterVariable all planned WinCC-variables which are allocated to a virtual connection. A coupled unitof the channel unit can, at its own initiative, read and write access the variables for which the flagVARC_SERVERACCESS is set


A&D PT1 D2



Date29.02.2000

Version5.0


Page67 of 111


coupled unit

Processvariables

virt. connect.

Only the coupled unit which is coupled to the channel unit via the relevant virtual connection can access thevariables allocated to a virtual connection.

1.3.4.8.3 Server access to WinCC system variables

WinCC system variables are variables which contain internal system values and are not allocated to any virtualconnection.An example for a system variable would be the name of the current user.

One part of the WinCC system variable is created on startup through the system core, another part through theWinCC client applications such as BUB, MELD, etc...All system variables possess attributes by means of which access to the variable can be restricted. Thusaccess to many system variables can only be read, to some read and write, and to some not at all.

All coupled units of a channel unit can access the WinCC system variables.

coupled unit N

coupled unit 1

WinCC system variable

virt. conn. 1

virt. conn. N

1.3.4.8.4 Read server access to a WinCC-variable

If the channel unit receives a read request from the coupled unit, it requests the current value of the relevantWinCC-variable from the data manager and supplies it to the coupled unit.

1.3.4.8.4.1 Reading of WinCC-variables of the virtual connection

The channel unit requests from the data manager the current value of one or more WinCC-variables byinvoking a callback function whose address the channel receives in the component pfnGetValue ofCHN_STARTSTRUCT. The channel unit establishes the relevant WinCC-variable by comparing the data


A&D PT1 D2



Date29.02.2000

Version5.0


Page68 of 111


requested by the coupled unit with the entries in the channel-specific expansion of the WinCC-variables,registered by the function ChnRegisterVariable, of the virtual connection.

GETVALUECB

typedef BOOL (*GETVALUECB)(PPVARIABLESTRUCT ppVariable,PPVARIABLEACCESSRESULT ppVariableAccessResult,DWORD dwVariableCount);

PARAMETERS

ppVariable Pointer to array which contains pointer to description of the variableto be read

ppVariableAccessResult Pointer to array which contains pointers to access results for theWinCC-variables

dwVariableCount Number of entries of arrays

RETURN

TRUE No errorsFALSE Error in callback function

The number of logged on variables is given in dwVariableCount. The pointer ppVariable points to an arraywhich contains pointers to the description of the variables to be read.

ppVariable Variable 1Pointer 0

Pointer 1Variable 2

Variable (N+1)Pointer N

The pointer ppVariableAccessResult points to an array which contains pointers to the access results of the datato be read. The allocation between variable and access result is effected via the same array index.


A&D PT1 D2



Date29.02.2000

Version5.0


Page69 of 111


ppVariableAccessResul Pointer 0

Pointer 1

Pointer N

Data Var. 1Access result 1


The channel unit provides all required memory areas, including the buffer for the variables values, before thecall and releases these again after its termination.The WinCC data manager adapts the byte order of the read data before termination of the call to the byte orderof the coupled unit by means of the function ChnChangeByteOrder.

If the function supplies the value FALSE, pes contains the description of the error occurring.

1.3.4.8.4.2 Reading of WinCC system variables

The channel unit requests from the data manager the current value of one or more WinCC-variables byinvoking a callback function whose address the channel receives in the component pfnGetValueName ofCHN_STARTSTRUCT.

GETVALUENAMECB

typedef BOOL (*GETVALUENAMECB)(PPVARIABLENAMESTRUCT ppVariableName,PPVARIABLEACCESSRESULT ppVariableAccessResult,DWORD dwVariableCount);

PARAMETERS

ppVariable Pointer to array which contains pointer to description of the variableto be read

ppVariableAccessResult Pointer to array which contains pointers to access results for theWinCC-variables


RETURN


The number of logged on variables is given in dwVariableCount. The pointer ppVariableName points to anarray which contains pointers to the description of the variables to be read.


A&D PT1 D2



Date29.02.2000

Version5.0


Page70 of 111


ppVariableName Variable name 1

Variable name 2

Variable name (N+1)

Pointer 0

Pointer 1

Pointer N

The pointer ppVariableAccessResult points to an array which contains pointers to the access results of the datato be read. The allocation between variable and access result is effected via the same array index.

ppVariableAccessResul Pointer 0

Pointer 1

Pointer N



The channel unit provides all required memory areas, including the buffer for the variables values, before thecall and releases these again after its termination.The WinCC data manager adapts the byte order of the read data before termination of the call to the byte orderof the coupled unit by means of the function ChnChangeByteOrder.


1.3.4.8.5 Write server access to a WinCC-variable

If the channel unit receives a write request from the coupled unit, it compilates a list of the relevant WinCC-variables with their new values and transfers these to the data manager.

1.3.4.8.5.1 Writing of WinCC-variables of the virtual connection

The channel unit informs the data manager of the new value of one or more WinCC-variables by invoking acallback function whose address the channel receives in the component pfnSetValue ofCHN_STARTSTRUCT. The channel unit establishes the relevant WinCC-variables by comparing the addresssupplied by the coupled unit with the WinCC-variables, registered by the function ChnRegisterVariable, of thevirtual connection.

SETVALUECB

typedef BOOL (*SETVALUECB)(PPVARIABLESTRUCT ppVariable,PPCHN_WRITEDESCRIPTOR ppWriteDescriptor,PDWORD pdwStateDWORD dwVariableCount);

PARAMETERS


A&D PT1 D2



Date29.02.2000

Version5.0


Page71 of 111



ppWriteDescriptor Pointer to array which contains pointers to access data to be written(CHN_WRITEDESCRIPTOR, (CHN_WRITEDESCRIPTOR see page.64)

pdwState Pointer to array in which the data manager writes the access results


RETURN


The number of variables to be written is given in dwVariableCount. The pointer ppVariable points to an arraywhich contains pointers to the description of the variables to be written.

ppVariable Variable 1Pointer 0

Pointer 1Variable 2

Variable (N+1)Pointer N

The pointer ppWriteDescriptor points to an array which contains pointers to the descriptions of the data to bewritten. The allocation between variable and description of the data to be written is effected via the same arrayindex.

ppWriteDescriptor Pointer 0

Pointer 1

Pointer N



The channel unit provides all required memory areas, including the buffer for the variables values, before thecall and releases these again after its termination.

Before the new values are written into the internal process image during the execution of the callback function,the WinCC data manager adapts the byte order of the data to be written to the internal byte order by means ofthe function ChnChangeByteOrder.by means of the function ChnChangeByteOrder.If the function supplies the value FALSE, pes contains the description of the error occurring.


A&D PT1 D2



Date29.02.2000

Version5.0


Page72 of 111


1.3.4.8.5.2 Writing of WinCC system variables

The channel unit informs the data manager of the new value of one or more WinCC-variables by invoking acallback function whose address the channel receives in the component pfnSetValueName ofCHN_STARTSTRUCT.

SETVALUENAMECB

typedef BOOL (*SETVALUENAMECB)(PPVARIABLENAMESTRUCT ppVariableName,PPCHN_WRITEDESCRIPTOR ppWriteDescriptor,PDWORD pdwStateDWORD dwVariableCount);

PARAMETERS

ppVariableName Pointer to array which contains pointer to names of the variables to bewritten

ppWriteDescriptor Pointer to array which contains pointers to description of the data to bewritten

pdwState Pointer to array in which the data manager writes the access results


RETURN


The number of variables to be written is given in dwVariableCount. The pointer ppVariableName points to anarray which contains pointers to the names of the variables to be written.

ppVariableName

Variable name 2

Variable name 1

Variable name (N+1)

Pointer 0

Pointer 1

Pointer N

The pointer ppWriteDescriptor points to an array which contains pointers to the description of the data to bewritten. The allocation between variable and description of the data to be written is effected via the same arrayindex.


A&D PT1 D2



Date29.02.2000

Version5.0


Page73 of 111


ppWriteDescriptor Pointer 0

Pointer 1

Pointer N



The channel unit provides all required memory areas, including the buffer for the variables values, before thecall and releases these again after its termination.The channel unit provides all required memory areas, including the buffer for the variables values, before thecall and releases these again after its termination.


1.3.5 Time synchronization

For a channel unit, the manipulation of the time synchronization of a WinCC system is relevant in the followingpoints:

• Is the channel unit a time master? If yes, how does it receive the time, to which coupled units does it sendthe time and in what form?

• Is the channel unit a time slave? If yes, from which coupled units and in what form does it receive the timeand how does it set the time in the WinCC system?

1.3.5.1 Channel unit as a time master

As a time master, the channel unit supplies one or more of its coupled units with the current time of the WinCCsystem. The manner in which the coupled units receive the current time is subject to the channel unit.

Using the property bit CHNCAP_TMSYNCMASTER, a channel unit indicates to the WinCC data manager thatit is able to transfer the current time to its coupled units via its connections. If this property bit is set, the WinCCdata manager takes account of the virtual connections of the channel unit when planning the timesynchronization.

When the channel unit is started, it receives all virtual connections allocated to the channel unit, by means ofthe function ChnRegisterConnection.In the planning of the time synchronization, the virtual connections chosen are those via which the time istransmitted to the coupled units and the cycle in which the transfer is to take place. The WinCC data managersets in the selected virtual connections the property bit LCC_TMSYNCMASTER, which the channel unit cancheck in the function ChnRegisterConnection and defines the cycle for the time synchronization in thecomponent dwTimeSyncCycle of the structure LOGCONNECTIONSTRUCT.

If the property bit LCC_TMSYNCMASTER is set with one or more virtual connections, the channel unit mustensure that the current time is transmitted to the corresponding coupled unit.For the current time, the channel unit must use the Windows system time.


A&D PT1 D2



Date29.02.2000

Version5.0


Page74 of 111


1.3.5.2 Channel unit as time slave

As time slave, the channel unit receives the current time from one of its coupled units.

Using the property bit CHNCAP_TMSYNCSLAVE, a channel unit indicates to the WinCC data manager that itis able to receive the current time from a coupled unit via one of its connections. If this property bit is set, theWinCC data manager takes account of the virtual connections of the channel unit when planning the timesynchronization.

In order to change the time of the WinCC system, the channel unit uses a callback function of the datamanager, which it has received in the component pfnChangeTime of the structure CHN_STARTSTRUCT in thefunction ChnStart.

1.3.6 Change of channel-specific data formats

WinCC-variables and virtual connections consist of a general and a channel-specific part. The channel-specificpart is stored as a string in the relevant database. This string representation has to be language-independent.

When a channel unit is started through the WinCC data manager by means of the function ChnStart, the unitsupplies the lengths for the binary and textual representation of both the variable description and thedescription of the virtual connection (dwMaxTextAddress, dwBinaryAddressSize, dwMaxTextCorrection,dwBinaryConnectionSize in the structure CHN_STARTSTRUCT).

1.3.6.1 Changing the description of a virtual connection

1.3.6.1.1 Converting from internal representation into a string

The conversion of the channel-specific description of a virtual connection into a string is effected by means ofthe function ChnConvertConnectionToString.

ChnConvertConnectionToString

#include <ChnAPI.h>

BOOL ChnConvertConnectionToString(DWORD dwUnitId,PVOID pvTextConnection,PVOID pvBinaryConnection,PCMN_ERROR pes);

PARAMETERS

dwUnitId ID of the channel unit which is performing the conversion.

pvTextConnection Pointer to memory area in which the function stores the textualrepresentation of the connection description.

pvBinaryConnection Pointer to memory area which contains the channel-specificrepresentation of the connection description.


A&D PT1 D2



Date29.02.2000

Version5.0


Page75 of 111



RETURN


The memory areas to which the pointers pvTextConnection and pvBinaryConnection point are provided by theWinCC data manager. The channel unit must ensure that the maximum length of the text of the connection isnot exceeded.

The format of the textual representation is subject to the channel unit.

1.3.6.1.2 Conversion from a string into the internal representation

The conversion of the channel-specific description of a virtual connection from a string into the internal binaryformat is effected by means of the function ChnConvertConnectionToBinary.

ChnConvertConnectionToBinary#include <ChnAPI.h>

BOOL ChnConvertConnectionToBinary(DWORD dwUnitId,PVOID pvBinaryConnection,PVOID pvTextConnection,PCMN_ERROR pes);

PARAMETERS

dwUnitId ID of the channel unit which is performing the conversion

pvBinaryConnection Pointer to memory area in which the function stores the binaryrepresentation of the connection description.

pvTextConnection Pointer to memory area which contains the textual representation of theconnection description.


RETURN


The memory areas to which the pointers pvTextConnection and pvBinaryConnection point are provided by theWinCC data manager.


A&D PT1 D2



Date29.02.2000

Version5.0


Page76 of 111


1.3.6.2 Changing the variable address

1.3.6.2.1 Conversion from internal representation into a string

The conversion of the channel-specific description of a WinCC-variable into a string is effected by means of thefunction ChnConvertVariableToString.

ChnConvertVariableToString

#include <ChnAPI.h>

BOOL ChnConvertVariableToString(DWORD dwUnitId,PVOID pvTextVariable,PVOID pvBinaryVariable,PCMN_ERROR pes);

PARAMETERS


pvTextVariable Pointer to memory area in which the function stores the textualrepresentation of the variable description.

pvBinaryVariable Pointer to memory area which contains the channel-specificrepresentation of the variable description.


RETURN


The memory areas to which the pointers pvTextVariable and pvBinaryVariable point are provided by theWinCC data manager. The channel unit must ensure that the maximum length of the text of the variable is notexceeded.

The format of the textual representation is subject to the channel unit.

The string representation consists of a language-dependent, a new-line character (‘\n’) and a language-independent part. The language-dependent part is used by the control-center to display the address in thecolumn „Parameters“ of the listview. The language-independent part is used to store the address in theproject-database.

1.3.6.2.2 Conversion from a string into the internal representation

The conversion of the channel-specific description of a WinCC-variable from a string into the internal binaryformat is effected by means of the function ChnConvertVariableToBinary.


A&D PT1 D2



Date29.02.2000

Version5.0


Page77 of 111


ChnConvertVariableToBinary#include <ChnAPI.h>

BOOL ChnConvertVariableToBinary(DWORD dwUnitId,PVOID pvBinaryVariable,PVOID pvTextVariable,PCMN_ERROR pes);

PARAMETERS


pvBinaryVariable Pointer to memory area in which the function stores the binaryrepresentation of the connection description

pvTextVariable Pointer to memory area which contains the textual representation of theconnection description.


RETURN

TRUE No errors, textual representation could be converted into binary representation.FALSE Error in API function, description of the cause of error via the pointer pes

The memory areas to which the pointers pvTextVariable and pvBinaryVariable point are provided by theWinCC data manager. The channel unit must ensure that the maximum length of the binary representation ofthe variable is not exceeded.

The address-string to be analyzed by this function is the language-independent part of the string generatedby ChnConvertVariableToString.

1.3.7 Interface for language change

The parts of a channel-DLL which expand the WinCC dialog system (specific planning of a WinCC-variable anda virtual connection) must be able to perform a change of the current language in the channel dialogs duringthe runtime.

The language change is performed by means of the function ChnChangeLanguage and applies for all units ofthe channel-DLL.

ChnChangeLanguage

#include <ChnAPI.h>

BOOL ChnChangeLanguage(PDWORD pdwLanguageId,PCMN_ERROR pes)


A&D PT1 D2



Date29.02.2000

Version5.0


Page78 of 111


PARAMETERS

pdwLanguageId Ptr to DWORD. The LOW word contains the ID of the new language to beused


RETURN

TRUE No error, language changed. FALSE Error in API function, language could not be changed

The language currently to be used for all units of a channel is changed during the runtime by means of thefunction ChnChangeLanguage.The parameter pdwLanguageId points to a DWORD value whose LOW word contains the ID of the newlanguage. The language ID is a standard WINDOWS language ID as generated by the WINDOWS macroMAKELANGID.

If the channel supports the declared language, it performs the necessary steps for changing the language,leaves the declared language unchanged and supplies as result the value TRUE.If the declared language is not supported, the channel stores the ID of the language it is currently using via thepointer pdwLanguageId and supplies the result FALSE.

The language change affects the following parts of the channel:

• Dialogs for planning the specific part of WinCC-variables and virtual connections• Textual representation of the address description of a WinCC-variable• Textual representation of the description of a virtual connection

1.3.8 Diagnosis interface

A diagnostic interface will be defined for future versions of the channel-API. Currently, each channel mayimplement its own communication diagnosis.


A&D PT1 D2



Date29.02.2000

Version5.0


Page79 of 111


2 Additonal API Functions in WinCC 4.X

2.1 Channel-specific Data Conversion

A channel may add specific data-conversion routines to the list of standard-routines offered by the data-manager. To achieve this, it has to implement the following subset of functions defined in the channel-API:� ChnGetConversionlist� ChnConvertOsToAs� ChnConvertAsToOs

2.1.1 ChnGetConversionlist

This function returns the pointer to an array of data conversion methods that are implemented in thechannel-DLL and are appropriate for a specific tag. Each method is described by a structure of typeCHNCNVSTRUCT.

BOOL ChnGetConversionList( DWORD dwUnitId, PVARIABLESTRUCT pVariable, DWORD dwOsDataType, PCHNCNVMETHOD pCnvMethod, PDWORD pdwCnvMethodCount, HINSTANCE *phInstance, PCMN_ERROR pes);

2.1.1.1 Parameters:

dwUnitId Zero-based unit-idpVariable Pointer to the CHNVARIABLESTRUCT-structure for the tagdwOsDataType Specifies the OS-datatype of the tagpCnvMethod Pointer to an array of pointers to CHNCNVMETHOD-structures.

The buffer for this array has to be allocated by the caller (data-manager).pdwCnvMethodCount Pointer to a DWORD-variable that contains the number of

CHNCNVMETHOD-structures the caller requests. On return, the channelstores the number of actually stored conversion-methods in this variable.If called with pCnvMethod = NULL, ChnGetConversionList shall return thenumber of CHNCNVMETHOD-structures the buffer should allow.

phInstance Pointer to a HINSTANCE-variable where the channel stores the handle of itsactive language-resource-file

pes Pointer to a CMN_ERROR-structure

typedef struct{ UINT uResourceId; WORD wMethodId; DWORD dwAsDataSize;} CHNCNVMETHOD,


A&D PT1 D2



Date29.02.2000

Version5.0


Page80 of 111


*PCHNCNVMETHOD, **PPCHNCNVMETHOD;

2.1.1.2 Structure Components:

uResourceId Resource-Id of the string-resource describing the conversion-methodwMethodId Number in the range 0..65535 identifying the conversion methoddwAsDataSize resulting AS-datasize when this conversion method is used

The conversion list should be build by the channel dependent on the combination of the WinCC-internaldata-type (as defined by pVariable->dwOsDataSize and the parameter dwOsDataType) and the AS-data-type (as defined by the address specified for the tag).The channel places the module-handle of its open language-resource file in *phInstance and the resource-IDof the string describing the conversion-method in the corresponding CHNCNVSTRUCT. The Data-Managerloads the string from the resource-DLL to fill the combobox "Format conversion".

2.1.2 ChnConvertAsToOs

This function converts the contents of the input-buffer according to the selected conversion method(dwConversion) and places the result into the output-buffer.

BOOL ChnConvertAsToOs(DWORD dwUnitId,PVARIABLESTRUCT pVariable,DWORD dwOsDataType,PVOID pvOsValue,PVOID pvAsValue,WORD wMethodId,PDWORD pdwStatus,PCMN_ERROR pes);

2.1.2.1 Parameters:

dwUnitId zero-based unit-idpVariable pointer to CHNVARIABLESTRUCTpvOsValue pointer to output-buffer, size of buffer according dwOsDataSizepvAsValue pointer to input-buffer, size of buffer according to dwAsDataSizewMethodId identifier for conversion-methodpdwStatus returns an error status if conversion failedpes pointer to CMN_ERROR structure

2.1.2.2 Notes:

Memory for both buffers is allocated and freed by the WinCC Data Manager.ChnChangeByteOrder will be called after this call if CHNCAP_INTELBYTEORDER flag is not set.


A&D PT1 D2



Date29.02.2000

Version5.0


Page81 of 111


2.1.3 ChnConvertOsToAs

This function converts the contents of the input-buffer according to the selected conversion method(dwConversion) and places the result into the output-buffer.

BOOL ChnConvertOsToAs(DWORD dwUnitId,PVARIABLESTRUCT pVariable,DWORD dwOsDataType,PVOID pvOsValue,PVOID pvAsValue,WORD wMethodId,PDWORD pdwStatus,PCMN_ERROR pes);

2.1.3.1 Parameters:

dwUnitId zero-based unit-idpVariable pointer to CHNVARIABLESTRUCTpvOsValue pointer to input-buffer, size of buffer according dwOsDataSizepvAsValue pointer to output-buffer, size of buffer according to dwAsDataSizewMethodId identifier for conversion-methodpdwStatus returns an error status if conversion failedpes pointer to CMN_ERROR structure

2.1.3.2 Notes:

Memory for both buffers is allocated and freed by the WinCC Data Manager.ChnChangeByteOrder will be called before this call if CHNCAP_INTELBYTEORDER flag is not set.

2.1.3.3 Configuring Tag-Properties and Address

When the user creates a new tag, the following happens:1. D/M allocates memory for VARIABLESTRUCT and channel-specific extension (pvExt)2. D/M displays property sheet "Tag properties"3. User enters a name for the tag4. User selects a data-type for the tag5. User clicks on the "Address"-button to define the channel-specific address6. D/M calls ChnEditVariable7. Channel displays its "Tag Address" property-sheet8. User enters address and clicks OK9. D/M calls ChnGetConversionList and fills the combobox "Format Conversion"

The conversion list returned by the channel should be dependent on the connection-settings, theselected data-type and address of the tag.

10. User selects format conversion and clicks OK

When the user re-opens the property-sheet "Tag Properties" and changes the "Data Type"-selection:1. D/M calls ChnGetConversionList and fills the combobox "Format Conversion"2. If the previously selected format conversion is still an element of the conversion-list, it is marked as

selected and the tag-properties are considered valid by the D/M.If the previously selected format conversion, due to the change of the data-type, is no longer an elementof the conversion-list then no format conversion is selected and the tag-properties are consideredinvalid/incomplete. The user has to select another format conversion and/or change the address.


A&D PT1 D2



Date29.02.2000

Version5.0


Page82 of 111


When the user re-opens the property-sheet "Tag Properties" and changes the tags "Address":1. D/M calls ChnGetConversionList and fills the combobox "Format Conversion"2. If the previously selected format conversion is still an element of the conversion-list, it is marked as

selected and the tag-properties are considered valid by the D/M.If the previously selected format conversion, due to the change of the data-type, is no longer an elementof the conversion-list then no format conversion is selected and the tag-properties are consideredinvalid/incomplete. The user has to select another format conversion and/or change the address.

On the "Address" property-sheet, the channel should allow all addresses that are compatible with thecurrently selected data-type and the possible format conversions.

2.2 Additional D/M callbacks

2.2.1 pfnGetVariableInfo

This functions returns specified Information for the tags in the list.

BOOL pfnGetVariableInfo(DWORD dwInfoId,PPVARIABLESTRUCT ppVariable,DWORD dwVariableCount,PVOID* ppInfoBfr,DWORD dwInfoSize,PDWORD pdwStatus);

dwInfoId Id of the requested information type, e.g. VARINFO_TYPE orVARINFO_CONVERSIONID

ppVariable pointer to an array of pointers to VARIABLESTRUCTSdwVariableCount number of tag to return information forppInfoBuffer pointer to an array of pointers to Buffers that contain the requested

informationdwInfoSize size of each info buffer (depends on the type if information requested

via dwInfoId)pdwStatus returns an error status if conversion failed


A&D PT1 D2



Date29.02.2000

Version5.0


Page83 of 111


2.2.2 pfnGetProjectFileName

This function returns the complete path (drive, directory, filename and extension) for the current project file(.mcp) in a string-buffer.

BOOL pfnGetProjectFileName(LPTSTR pszFileNameBfr,DWORD dwBfrSize);

pszFileNameBfr Buffer for the file name (has to be allocated by the channel)dwBfrSize size of the pszFileNameBfr buffer

For more information about the usage of these new API-functions see the Modbus example providedwith the Channel Development Kit 5.0. You will find there implementation examples for thesefunctions !


A&D PT1 D2



Date29.02.2000

Version5.0


Page84 of 111


3 Additional Functionality in WinCC V 5.X

3.1 New in WinCC V5.X

• There are now two different applications for configuration and runtime mode. (There is no MCP.EXEapplication)

• WinCC channels may now be loaded more than once by different applications and should be awareof that !

• Time-Stamps and Quality-Codes are now supported (see chapter 3.2 / p 85)• A diagnosis interface for WinCC channels is now available (see chapter 3.3 / p 89)• The channel untis are now sorted alphabetically when displayed in the WinCCExplorer• The pfnSysMessage callback function can now be used (see chapter 1.3.1.7.2.7 on page 38 for

more information)

3.2 Time-Stamps and Quality-Codes

Starting with Version 5 the WinCC Channel API provides additional callbacks that support Time-Stamps andQuality-Code information.

3.2.1 VARIABLEACCESSRESULTEX

typedef struct{ PVOID pvData; WORD wStatus; DWORD dwTransactId; PWORD pwQuality; DATE* pdateLastChange;} VARIABLEACCESSRESULTEX, *PVARIABLEACCESSRESULTEX, **PPVARIABLEACCESSRESULTEX;


A&D PT1 D2



Date29.02.2000

Version5.0


Page85 of 111


Remarks:Qualitycodes are only evaluated when wStatus is 0 (Status OK). Otherwise the value of pwQuality is ignoredand only wStatus is evaluated. If the pointer pdateLastChange is NULL, the WinCC data-manager will usethe system time to create a timestamp.

3.2.2 READFINISHCBEX

typedef void (*READFINISHCBEX)(PPVARIABLESTRUCT ppvVariable, PPVARIABLEACCESSRESULTEX ppAccessResult, DWORD dwVariableCount);

The array ppVariable contains pointers to the variables whose processing by the channel unit has beenconcluded. The array ppAccessResulEx contains pointers to the relevant extended access results that alsocontain a time stamp and quality information.

The order of the pointers to the variables and access results can differ from the order upon the initiation of thejob in the function ChnStartRead.The allocation between variable and access result is effected via the common array index.

In the invoked callback function, the WinCC data manager converts the byte order of the read data by means ofthe function ChnChangeByteOrder.

After the callback function has been invoked, the channel unit can release all memory areas which wereallocated through the channel unit during the processing of the acknowledged variables.

Note:Do not call READFINISHCBEX in your implementation of ChnStartRead. This may causedeadlocks in the DataManager.

Structure component MeaningpvData Pointer to data area in which the channel unit stores read process data. The

data area is initialized in the reading of process values by the channel unit forthe duration of the acknowledgement.If data were written, the channel unit enters the values NULL.

wStatus Here the channel unit enters the status of the access.

dwTransactId

pwQuality

pdateLastChange

Transaction ID which was allocated on the request of the variable.

Pointer to a word containing the quality. (see table below for qualities)

Pointer to a DATE type containing the Time-Stamp. (has to be GMT)


A&D PT1 D2



Date29.02.2000

Version5.0


Page86 of 111


3.2.3 CHN_WRITEDESCRIPTOREX

The CHN_WRITEDESCRIPTOREX structure is basically the same as the CHN_WRITEDESCRIPTORstructure but contains two additional elements for quality and time-stamp information. TheCHN_WRITEDESCRIPTOREX structure is used by the SETVALUECBEX and ChnStartWriteEx calls.

typedef struct{ DWORD dwOffsetFromBase; DWORD dwWriteLength; PVOID pvData; PWORD pwQuality; DATE* pdateLastChange;} CHN_WRITEDESCRIPTOREX, *PCHN_WRITEDESCRIPTOREX, **PPCHN_WRITEDESCRIPTOREX;

Structure component MeaningdwOffsetFromBase Write offset in bits, which must be added to the base address of the variable

dwWriteLength Length in bits of the data to be written

pvData Pointer to the data to write.

pwQuality

pdateLastChange

Pointer to a word containing the quality. (see table below for qualities)

Pointer to a DATE type containing the Time-Stamp. (GMT)

Remarks:If the pointer pdateLastChange is NULL, the WinCC data-manager will use the system time to create atimestamp.

3.2.4 ChnStartWriteEx

#include <ChnAPI.h>

BOOL ChnStartWriteEx( DWORD dwUnitId, PLOGCONNECTIONSTRUCT pConnection, PPVARIABLESTRUCT ppVariable, DWORD dwVariableCount, PPCHN_WRITEDESCRIPTOREX ppWriteDescriptor, DWORD dwTransactId, PCMN_ERROR pes);

PARAMETERS


A&D PT1 D2



Date29.02.2000

Version5.0


Page87 of 111



pConnection Pointer to parameter set of the virtual connection via which the variable(s)are to be written



ppWriteDescriptor Pointer to array which contains pointer to description of the data to bewritten (CHN_WRITEDESCRIPTOREX)

dwTransactId Transaction ID of this job.


RETURN


Remarks:The ChnStartWriteEx call has the same functionality as described in the ChnStartWrite section butuses CHN_WRITEDESCRIPTOREX structures for additional quality an time-stamp information.An implementation of the ChnStartWriteEx funtion cannot replace the ChnStartWrite function! Youalways have to implement ChnStartWrite, as the WinCC data-manager also may call ChnStartWrite,if there is no quality-code or timestamp available.

3.2.5 CHN_ENTRYPOINTS

This is the CHN_ENTRYPOINTS-structure used in WinCC V5.

typedef struct _EntryPoints{ DWORD dwSize; PCHN_GETUNITCOUNT pfnGetUnitCount; PCHN_GETCAPS pfnGetCaps; PCHN_REGISTERCONN pfnRegisterConnection; PCHN_REGISTERVARIABLE pfnRegisterVariable; PCHN_START pfnStart; PCHN_UNLOAD pfnUnLoad; PCHN_GETCONNPPCOUNT pfnGetConnectionPPCount; PCHN_GETCONNPP pfnGetConnectionPP; PCHN_EDITCONN pfnEditConnection; PCHN_GETVARIABLEPPCOUNT pfnGetVariablePPCount; PCHN_GETVARIABLEPP pfnGetVariablePP; PCHN_EDITVARIABLE pfnEditVariable; PCHN_GETADDRESSUNITSIZE pfnGetAddressUnitSize; PCHN_EDITPROPERTIES pfnEditProperties; PCHN_STARTREAD pfnStartRead; PCHN_STARTWRITE pfnStartWrite; PCHN_STOPREAD pfnStopRead;


A&D PT1 D2



Date29.02.2000

Version5.0


Page88 of 111


PCHN_CHANGEBYTEORDER pfnChangeByteOrder; PCHN_CNVTCONNSTRING pfnConvertConnectionToString; PCHN_CNVTCONNBINARY pfnConvertConnectionToBinary; PCHN_CNVTVARIABLESTRING pfnConvertVariableToString; PCHN_CNVTVARIABLEBINARY pfnConvertVariableToBinary; PCHN_CHANGELANG pfnChangeLanguage; PCHN_BUILDVARIABLEADDRESS pfnBuildVariableAddress; PCHN_STOPREADEX pfnStopReadEx; PCHN_GETCONVERSIONLIST pfnGetConversionList; PCHN_CONVERTASTOOS pfnConvertAsToOs; PCHN_CONVERTOSTOAS pfnConvertOsToAs; PCHN_STARTWRITEEX pfnStartWriteEx;} CHN_ENTRYPOINTS, *PCHN_ENTRYPOINTS, **PPCHN_ENTRYPOINTS;

3.3 Channel Diagnosis Interface

WinCC 5 provides an additional interface for channel diagnosis. This interface allows the channel1. to show statistical data in the channel diagnosis control (ChnDiagX.ocx) delivered with WinCC2. formatted logfile and tracefile outputs3. tracefile configuration within the channel diagnosis control

You have to include the following header file

#include “ChnDiag.h”

(found in \ohio_prj\channels\include) and link against CCChnDiag.lib (found in \ohio_prj\channels\lib) to usethe functionality in the CCChnDiag.DLL.

3.3.1 Trace Flags

These flags are used by the channel diagnosis DLL to categorize the tracefile and logfile outputs.

Bit Meaning DefineF Fatal Error TRACE_FATALE Error TRACE_ERRORW Warning TRACE_WARNINGI Information TRACE_INFOS Operation succeeded TRACE_SUCCESSL Show this in logfile TRACE_LOGU Check user flags TRACE_USERreserved16 ... 24

Reserved bits TRACE_RESERVED_0...TRACE_RESERVED_8


A&D PT1 D2



Date29.02.2000

Version5.0


Page89 of 111


User-Flags0 ... 15

User defined flags TRACE_USER_0...TRACE_USER_15

Table 3-1

These bits can be combined freely. Outputs in tracefiles and logfiles will only take place, if the combinationmatches the settings the user made. If the L-flag (TRACE_LOG) is set, there will be an output to the logfile –regardless of the other bits.

3.3.2 Status of Connections

Predefined values for connection status:

Define Bit MeaningCONNSTATE_OK 0x0001 The connection is OK and runningCONNSTATE_WARN 0x0002 The connection is OK but there may be problemsCONNSTATE_DOWN 0x0004 The connection is down.

Table 3-2

3.3.3 The C++ Class CChnDiagnose

The CCChnDiag.DLL provides the C++ class CChnDiagnose. The WinCC channel instantiates an object ofthis class to get access to the functionality of the channel diagnosis interface.

3.3.3.1 Constructor:

CChnDiagnose *pDiagnose = new CChnDiagnose(CString& csName, CString& csHelpFile);CChnDiagnose *pDiagnose = new CChnDiagnose(LPTSTR szName, LPTSTR szHelpFile);

PARAMETERS:

csName/szName Name of the channel to be shown in the user interface. (The channel’sfilename without the extension)

csHelpFile/szHelpFile

Name of the channel’s helpfile without any language specific extensionand without filename extension. E.g. helpfile: “MyChannelENU.hlp” willresult in „MyChannel“

Return value:Pointer to the allocated C++ object


A&D PT1 D2



Date29.02.2000

Version5.0


Page90 of 111


3.3.3.2 Methods

3.3.3.2.1 CChnDiagnose::CreateConnection

Functionality:

Creates a handle for a virtual connection.

HANDLE CChnDiagnose::CreateConnection(CString& csName, WORD wState = CONNSTATE_DOWN); HANDLE CChnDiagnose::CreateConnection(LPTSTR pszName, WORD wState = CONNSTATE_DOWN);

csName/pszName The connection’s name that will be shown in the user interface.wState Initial status of this connection

Return value:Handle for this connection. Used for creating counters, setting the status and deleting the connection.

3.3.3.2.2 CChnDiagnose::DeleteConnection

Functionality:Deletes the connection with the given handle from the internal list of the CCChnDiag.DLL

BOOL CChnDiagnose::DeleteConnection(HANDLE hConnection);

hConnection Handle of the connection to be deleted

Return value:TRUE: SuccessFALSE: Error

3.3.3.2.3 CChnDiagnose::SetConnectionState

Functionality:Changes the state of the given connection.

BOOL CChnDiagnose::SetConnectionState(HANDLE hConnection, WORD wState);

hConnection The connection’s handlewState New state to set (see Table 3-2)

Return value:TRUE SuccessFALSE Error; maybe the connection did not exist in the internal list


A&D PT1 D2



Date29.02.2000

Version5.0


Page91 of 111


3.3.3.2.4 CChnDiagnose::WriteFormat

Functionality:

Writes a formatted string to the output files regarding the trace flags.

void CChnDiagnose::WriteFormat(DWORD dwFlags, LPTSTR pszFmt, ...);

dwFlags DWORD containing the trace flags (see Table 3-1)pszFmt Format string for output... va list

Return value:None

3.3.3.2.5 CChnDiagnose::WriteHResult

Functionality:

Writes a formatted string containing an HRESULT to the output files regarding the trace flags. The givenHRESULT will be decoded and the corresponding error message will be added to the string.

void CChnDiagnose::WriteHResult(DWORD dwFlags,HRESULT hResult,LPTSTR pszFmt,...);

dwFlags DWORD containing the trace flags (see Table 3-1)hResult HRESULTpszFmt Format string for output... va list

Return value:None

3.3.3.2.6 CChnDiagnose::WriteApiReturn

Functionality:

Writes the result of a WinCC API call to the output files regarding the trace flags. The WinCC error structureCMN_ERROR will be evaluated and added to the string.

void CChnDiagnose::WriteApiReturn(DWORD dwFlags, BOOL bOk,

PCMN_ERROR pes,LPCTSTR pszFmt,...);

dwFlags DWORD containing the trace flags (see Table 3-1)


A&D PT1 D2



Date29.02.2000

Version5.0


Page92 of 111


bok Return value of the API call (TRUE/FALSE)pes WinCC error structurepszFmt Format string for output... va list

Return value:None

3.3.3.2.7 CChnDiagnose::WriteMemory

Functionality:Dumps a block of memory into the output files regarding the trace flags.

void CChnDiagnose::WriteMemory(DWORD dwFlags, LPVOID pvMem, DWORD dwBytes, DWORD dwOffset, LPCTSTR pszFmt, ...);

dwFlags DWORD containing the trace flags (see Table 3-1)pvMem Void pointer to the memory blockdwBytes Size of the memory blockdwOffset Offset within the memory block (will be 0 in most cases)pszFmt Format string for output... va list

Return value:None

3.3.3.2.8 CChnDiagnose::CreateCounter

Functionality:Creates a counter to count any channel- or connection-specific events or data (e.g. transmitted bytes,connection failures etc.)

HANDLE CChnDiagnose::CreateCounter(CString& csName, HANDLE hConnection);

HANDLE CChnDiagnose::CreateCounter(LPTSTR pszName, HANDLE hConnection);

csName/pszName The counter’s name that will be shown in the user interfacehConnection Handle of the connection this counter belongs to (returned by

CreateConnection). If hConnection is NULL, this counter will not belong to aconnection but to the channel.

Return value:Handle of the counter. Used for later access.

3.3.3.2.9 CChnDiagnose::SetCounter


A&D PT1 D2



Date29.02.2000

Version5.0


Page93 of 111


Functionality:

Sets the given counter to an (inital) value;

void CChnDiagnose::SetCounter(HANDLE hCounter, VARIANT vtStart, UNIT uiHelp=0);

void CChnDiagnose::SetCounter(HANDLE hCounter, DWORD dwStart, UNIT uiHelp=0);

void CChnDiagnose::SetCounter(HANDLE hCounter, CString& csStart, UNIT uiHelp=0);

void CChnDiagnose::SetCounter(HANDLE hCounter, LPTSTR pszStart, UNIT uiHelp=0);

void CChnDiagnose::SetCounter(HANDLE hCounter, float fStart, UNIT uiHelp=0);

hCounter Handle of the counter to be setvtStart Value as a variantdwStart Value as a DWORDcsStart/pszStart Value as a stringfStart Value as a floatuiHelp Help-ID for online help using the helpfile named in the constructor

Return value:None

3.3.3.2.10 CChnDiagnose::IncrementCounter

Functionality:Increments a counter by a given value.

void CChnDiagnose::IncrementCounter(HANDLE hCounter, VARIANT vtStep);

void CChnDiagnose::IncrementCounter(HANDLE hCounter, DWORD dwStep);

void CChnDiagnose::IncrementCounter(HANDLE hCounter, float fStep);

hCounter Handle of the counter to be incrementedvtStep Value to increment by as a VariantdwStep Value to increment by as a DWORDfStep Value to increment by as a float

Return value:None

3.3.3.2.11 CChnDiagnose::CreateUserFlag

Functionality:

Creates a user defined flag and attaches a name that can be displayed in the user interface.

BOOL CChnDiagnose::CreateUserFlag(WORD wFlag, CString& csName);


A&D PT1 D2



Date29.02.2000

Version5.0


Page94 of 111


BOOL CChnDiagnose::CreateUserFlag(WORD wFlag, CString& csName, Cstring& csLongName);

BOOL CChnDiagnose::CreateUserFlag(WORD wFlag, LPTSTR pszName, LPTSTR pszLongName = NULL);

wFlag A WORD containing the user flag (e.g. TRACE_USER_0)csName/pszName Name to identify the flag in the output filescsLongName/pszLongName

Name to display in the user interface. If unused the short name will bedisplayed.

Return value:TRUE SuccessFALSE

3.3.3.2.12 CChnDiagnose::CompareFlags

Functionality:Compares the given flags with the user settings and returns TRUE if the flags are matching. This is used todetermine whether an output action will take place at all to improve performance by avoiding unnecessarycalls.

BOOL CChnDiagnose::CompareFlags(DWORD dwFlags);

dwFlags DWORD containing the trace flags

Return value:TRUE dwFlags matches the user settingsFALSE dwFlags does not match the user settings

Help functionSoll eine Ausgabe von Online-Hilfe über das COM-Interface möglich sein, so muß beim erzeugen einesDiagnose-Objekts im Konstruktor der Name der Hilfe-Datei, die verwendet werden soll, angegeben werdenund die Online-Hilfe muß auf dem System, von dem aus auf das COM-Interface zugegriffen werden sollebenfalls installiert sein. Wird dann beim Setzen eines Counters als zusätzlicher Parameter noch einepassende Help-ID für diesen Counter-Wert angegeben, so kann die Applikation, die das COM-Interfaceverwendet (später das schon erwähnte ActiveX-Control) die passende Online-Hilfe anzeigen, z.B. durchDoppelklick auf den Counter-Wert oder Kontext-Menü.If the Online Help shall be accessed via the COM interface, the name of the help file must be indicated withinthe constructor when a diagnosis object is created and the Online Help must be installed as well on thesystem used to access the COM interface. If, when setting a counter, the appropriate help-ID for this countervalue is indicated as an additional parameter, then the application using (used by?) the COM interface (laterthe already mentioned ActiveX-Control) can display the corresponding online help, e.g. by double-clickingonto the counter value or the context(?) menu.

3.3.3.3 Usage

3.3.3.3.1 Initialization of the DLL:


A&D PT1 D2



Date29.02.2000

Version5.0


Page95 of 111


#include “ChnDiagnose.h”

CChnDiagnose *pDiagnose = new CChnDiagnose(“MyChannel”, “MyChannel”);HANDLE hErrCount = pDiagnose->CreateCounter(“Connection Errors”, NULL);

3.3.3.3.2 Deinitialization of the DLL:

delete pDiagnose;

3.3.3.3.3 Performing Log-/Tracefile Outputs

// write to the logfilepDiagnose->WriteFile(TRACE_LOG, “Error Number %02x in Module %s.”, dwErr, szN1);pDiagnose->SetCounter(hErrCount, “NoConnection”, uiHelpCoConn);

- or -

// check first whether trace output is enabled at all

if(CompareFlags(TRACE_ERROR | TRACE_USER | TRACE_USER_4))pDiagnose->WriteMemory(TRACE_ERROR | TRACE_USER | TRACE_USER_4,

pMemoryBlock,dwReceivedBytes,0,“Error %02x in Telegram:”,dwErr);

For more information about the usage of channel diagnosis functionality see the Modbus exampleprovided with the Channel Development Kit 5.0. You will find there implementation examples forthese functions !


A&D PT1 D2



Date29.02.2000

Version5.0


Page96 of 111


4 BIBLIOGRAPHY

/1/ API description of the generic SIMATIC DLLWinCC project


A&D PT1 D2



Date29.02.2000

Version5.0


Page97 of 111


5 A n n e x

5.1 Quality-Codes in WinCC 5

5.1.1 Quality Code according to Profibus PA

Excerpt from "Profibus PA, Draft Profile for Process Control Devices, General Requirements, V2.93, 26.7.98"

5.1.1.1 Coding of status

Quality Quality Substatus Limits

Gr Gr QS QS QS QS Qu Qu Description27 26 25 24 23 22 21 20

0 0 = bad0 1 = uncertain1 0 = good (Not Cascade)1 1 = good (Cascade)

Meaning at = bad

0 0 0 0 0 0 = non-specific 0 0 0 0 0 1 = configuration error,

(value not accepted) 0 0 0 0 1 0 = not connected 0 0 0 0 1 1 = device failure 0 0 0 1 0 0 = sensor failure 0 0 0 1 0 1 = no communication (last

usable value) 0 0 0 1 1 0 = no communication (no

usable value) 0 0 0 1 1 1 = out of service 0 0 1 0 0 0 = configuration changed,

variable adapted

Meaning at = uncertain

0 1 0 0 0 0 = non-specific0 1 0 0 0 1 = last usable value0 1 0 0 1 0 = substitute-set0 1 0 0 1 1 = initial value0 1 0 1 0 0 = sensor conversion not accurate0 1 0 1 0 1 = engineering unit range violation0 1 0 1 1 0 = sub-normal0 1 0 1 1 1 = configuration error, value adapted

Meaning at = good (Non-Cascade)


A&D PT1 D2



Date29.02.2000

Version5.0


Page98 of 111


1 0 0 0 0 0 = ok1 0 0 0 0 1 = active block alarm1 0 0 0 1 0 = active advisory alarm (priority < 8)1 0 0 0 1 1 = active critical alarm (priority > 8)1 0 0 1 0 0 = unacknowledged block alarm1 0 0 1 0 1 = unacknowledged advisory alarm1 0 0 1 1 0 = unacknowledged critical alarm1 0 1 0 0 0 = initiate fail safe

Meaning at = good (Cascade)

1 1 0 0 0 0 = ok1 1 0 0 0 1 = initialisation acknowlegded1 1 0 0 1 0 = initialisation request1 1 0 0 1 1 = not invited1 1 0 1 0 0 = not selected1 1 0 1 0 1 = do not select1 1 0 1 1 0 = local override1 1 0 1 1 1 = fail safe active1 1 1 0 0 0 = initiate fail safe

Meaning of the bits ‘Limits’

0 0 = ok 0 1 = low limited *) 1 0 = high limited *) 1 1 = constant

Table 3. Coding of the Status Byte

*) Crossing the HI (LO) and HI_HI (LO_LO) limits the corresponding bits in the FB parameter ALARM_SUMmust be switched to 1 in addition, i.e. the bits "low limited" and "high limited" are not only switched dependingon the physical limits of the device.

5.1.1.2 Use of the status byte for profile compliant devices

0 0 0 1 0 0 0 1

Bad - sensor failure, low limited - lower physical range of the sensor reached

0 0 0 1 0 0 1 0

Bad - sensor failure, high limited - upper physical range of the sensor reached

1 0 0 0 1 0 0 1

good (Non-Cascade), active advisory alarm, low limited - LO_LIM of OUT is crossed

1 0 0 0 1 0 1 0

good (Non-Cascade), active advisory alarm, high limited - HI_LIM of OUT is crossed


A&D PT1 D2



Date29.02.2000

Version5.0


Page99 of 111


1 0 0 0 1 1 0 1

good (Non-Cascade), active critical alarm, low limited - LO_LO_LIM of OUT is crossed

1 0 0 0 1 1 1 0

good (Non-Cascade), active critical alarm, high limited - HI_HI_LIM of OUT is crossed

1 0 0 0 0 1 * *

good (Non-Cascade), active block alarm - Parameter with S attribute changed

5.1.1.3 Status Attribution Definition

The status which an output parameter may have is shown in the following table. The definition of the statusattribute is the same for all parameters (input, output, and contained). There are four states of quality of thedata, an enumerated set of sixteen substatus values for each quality, and four states of the limits placed onthe data. Limit information is generated for all status attributes of all parameters having status. In this table,status is shown in lowest (Good - O.K.) to highest priority (Bad - Out of Service). When multiple conditionsexist which may impact status, the condition having the highest priority will determine the parameter status.

List of Valid Values

The quality, substatus, and limit components of status are defined as follows:Quality - The quality used will be determined by the highest priority condition.

0 = Bad - The value is not useful.

1 = Uncertain - The quality of the value is less than normal, but the value may still be useful.

2 = Good (Non-cascade) - The quality of the value is good. Possible alarm conditions may beindicated by the substatus.

3 = Good (Cascade) - The value may be used in control.

Substatus - Substatus values in the status attribute are defined as follows, for each Quality from lowest tohighest within each quality category:

BAD Substatus:

0 = non-specific - There is no specific reason why the value is bad. Used for propagation.

1 = Configuration Error - Set if the value is not useful because there is some other problem with theblock, depending on what a specific manufacturer can detect.

2 = Not Connected - Set if this input is required to be connected and is not connected .

3 = Device Failure - Set if the source of the value is affected by a device failure.

4 = Sensor Failure - Set if the device can determine this condition. The Limits define which directionhas been exceeded.

5 = No Communication, with last usable value - Set if this value had been set by communication,which has now failed.


A&D PT1 D2



Date29.02.2000

Version5.0


Page100 of 111


6 = No Communication, with no usable value - Set if there has never been any communication withthis value since it was last Out of Service.

7 = Out of Service - The value is not reliable because the block is not being evaluated, and may beunder construction by a configurer. Set if the block mode is O/S.

Uncertain Substatus:

0 = Non-specific - There is no specific reason why the value is uncertain. Used for propagation.

1 = Last Usable Value - Whatever was writing this value has stopped doing so. (This happens whenan input is disconnected by an configurer.)

2 = Substitute value - ?.

3 = Initial Value - Set when the value of an input parameter is written while the block is Out ofService.

4 = Sensor Conversion not Accurate - Set if the value is at one of the sensor limits. The Limits definewhich direction has been exceeded. Also set if the device can determine that the sensor hasreduced accuracy (e.g. degraded analyser), in which case no limits are set.

5 = Engineering Unit Range Violation - Set if the value lies outside of the range of values defined forthis parameter. The Limits define which direction has been exceeded.

6 = Sub-normal - Set if a value derived from multiple values has less than the required number ofGood sources.

Good (Non-cascade) Substatus:

0 = O.K. - No error or special condition is associated with this value.

1 = Active Block Alarm - Set if the value is good and the block has an active Block Alarm.

2 = Active Advisory Alarm - Set if the value is good and the block has an active Alarm with a priorityless than 8.

3 = Active Critical Alarm - Set if the value is good and the block has an active Alarm with a prioritygreater than or equal to 8.

4 = Unacknowledged Block Alarm - Set if the value is good and the block has an unacknowledgedBlock Alarm.

5 = Unacknowledged Advisory Alarm - Set if the value is good and the block has anunacknowledged Alarm with a priority less than 8.

6 = Unacknowledged Critical Alarm - Set if the value is good and the block has an unacknowledgedAlarm with a priority greater than or equal to 8.

Good (Cascade) Substatus:

0 = O.K. - No error or special condition is associated with this value.

1 = Initialisation Acknowledge(IA) - The value is an initialised value from a source (cascade input,remote-cascade in, and remote-output in parameters).

2 = Initialisation Request(IR) - The value is an initialisation value for a source (back calculation inputparameter), because the lower loop is broken or the mode is wrong.

3 = Not Invited (NI) - The value is from a block which does not have a target mode that would usethis input. This covers all cases other than Fail Safe Active, Local Override, and Not Selected. Thetarget mode can be the next permitted mode of higher priority in the case of shedding a supervisorycomputer.


A&D PT1 D2



Date29.02.2000

Version5.0


Page101 of 111


4 = Not Selected(NS) - The value is from a signal selector which has not selected the correspondinginput. This tells the upper block to limit in one direction, not to initialise.

5 = Do Not Select(DNS) - The value is from a block which should not be selected, due to conditionsin or above the block.

6 = Local Override(LO) - The value is from a block that has been locked out by a local key switch oris a Complex AO/DO with interlock logic active. The failure of normal control must be propagated toa PID block for alarm and display purposes. This also implies Not Invited.

7 = Fail Safe Active(FSA) - The value is from a block that has FAIL-SAFE active. The failure ofnormal control must be propagated to a PID block for alarm and display purposes. This also impliesNot Invited.

8 = Initiate Fail Safe(IFS) - The value is from a block that wants its downstream output block (e.g.AO) to go to Fail Safe. This is determined by a block option to initiate Fail Safe if the status of theprimary input and/or cascade input goes Bad. See the status options table in Part 2 and 3.

Limit: The following limit conditions will be always available in the status attribute.

0 = O.K. - The value is free to move.

1 = Low limited - The value is from a block that cannot generate or use a lower value because it islimited in that direction, either internally or by the transducer.

2 = High limited - The value is from a block that cannot generate or use a higher value because it islimited in that direction, either internally or by the transducer.

3 = Constant (high and low limited) - The value cannot move, no matter what the process does.

The four cases are mutually exclusive. A constant cannot also be limited in just one direction.

5.1.2 Quality Code according to OPC

Excerpt from "OPC Data Access Custom Interface Specification 2.0 (RC4/17/98)".

These flags represent the quality state for a item’s data value. This is intended to be similar to but slightlysimpler than the Fieldbus Data Quality Specification (section 4.4.1 in the H1 Final Specifications). Thisdesign makes it fairly easy for both servers and client applications to determine how much functionality theywant to implement.

The low 8 bits of the Quality flags are currently defined in the form of three bit fields; Quality, Substatus andLimit status. The 8 Quality bits are arranged as follows:

QQSSSSLLThe high 8 bits of the Quality Word are available for vendor specific use. If these bits are used, the standardOPC Quality bits must still be set as accurately as possible to indicate what assumptions the client can makeabout the returned data. In addition it is the responsibility of any client interpreting vendor specific qualityinformation to insure that the server providing it uses the same ‘rules’ as the client. The details of such anegotiation are not specified in this standard although a QueryInterface call to the server for a vendorspecific interface such as IMyQualityDefinitions is a possible approach.Details of the OPC standard quality bits follow:


A&D PT1 D2



Date29.02.2000

Version5.0


Page102 of 111


5.1.2.1 The Quality BitField

QQ BIT VALUE DEFINE DESCRIPTION0 00SSSSLL Bad Value is not useful for reasons indicated

by the Substatus.1 01SSSSLL Uncertain The quality of the value is uncertain for

reasons indicated by the Substatus.2 10SSSSLL N/A Not used by OPC3 11SSSSLL Good The Quality of the value is Good.

Comment:

A server which supports no quality information must return 3 (Good). It is also acceptable for a server tosimply return Bad or Good (0x00 or 0xC0) and to always return 0 for Substatus and limit.It is recommended that clients minimally check the Quality Bit field of all results (even if they do not check thesubstatus or limit fields).Even when a ‘BAD’ value is indicated, the contents of the value field must still be a well defined VARIANTeven though it does not contain an accurate value. This is to simplify error handling in client applications. Forexample, clients are always expected to call VariantClear() on the results of a Sychronous Read. Similarlythe IAdviseSink needs to be able to interpret and ‘unpack’ the Value and Data included in the Stream even ifthat data is BAD.If the server has no known value to return then some reasonable default should be returned such as a NULstring or a 0 numeric value.

5.1.2.2 The Substatus BitField

The layout of this field depends on the value of the Quality Field.


A&D PT1 D2



Date29.02.2000

Version5.0


Page103 of 111


5.1.2.2.1 Substatus for BAD Quality:

SSSS BIT VALUE DEFINE DESCRIPTION0 000000LL Non-specific The value is bad but no specific reason is

known.1 000001LL Configuration Error There is some server specific problem with

the configuration. For example the item inquestion has been deleted from theconfiguration.

2 000010LL Not Connected The input is required to be logicallyconnected to something but is not. Thisquality may reflect that no value isavailable at this time, for reasons like thevalue may have not been provided by thedata source.

3 000011LL Device Failure A device failure has been detected.4 000100LL Sensor Failure A sensor failure had been detected (the

’Limits’ field can provide additionaldiagnostic information in some situations).

5 000101LL Last Known Value Communications have failed. However, thelast known value is available. Note that the‘age’ of the value may be determined fromthe TIMESTAMP in the OPCITEMSTATE.

6 000110LL Comm Failure Communications have failed. There is nolast known value available.

7 000111LL Out of Service The block is off scan or otherwise locked.This quality is also used when the activestate of the item or the group containingthe item is InActive.

8-15 N/A Not used by OPC

Comment

Servers which do not support Substatus should return 0. Note that an ‘old’ value may be returned with theQuality set to BAD (0) and the Substatus set to 5. This is for consistency with the Fieldbus Specification.This is the only case in which a client may assume that a ‘BAD’ value is still usable by the application.


A&D PT1 D2



Date29.02.2000

Version5.0


Page104 of 111


5.1.2.2.2 Substatus for UNCERTAIN Quality:

SSSS BIT VALUE DEFINE DESCRIPTION0 010000LL Non-specific There is no specific reason why the value

is uncertain.1 010001LL Last Usable Value Whatever was writing this value has

stopped doing so. The returned valueshould be regarded as ‘stale’. Note thatthis differs from a BAD value withSubstatus 5 (Last Known Value). Thatstatus is associated specifically with adetectable communications error on a‘fetched’ value. This error is associatedwith the failure of some external source to‘put’ something into the value within anacceptable period of time. Note that the‘age’ of the value can be determined fromthe TIMESTAMP in OPCITEMSTATE.

2-3 N/A Not used by OPC4 010100LL Sensor Not Accurate Either the value has ‘pegged’ at one of the

sensor limits (in which case the limit fieldshould be set to 1 or 2) or the sensor isotherwise known to be out of calibrationvia some form of internal diagnostics (inwhich case the limit field should be 0).

5 010101LL Engineering UnitsExceeded

The returned value is outside the limitsdefined for this parameter. Note that in thiscase (per the Fieldbus Specification) the‘Limits’ field indicates which limit has beenexceeded but does NOT necessarily implythat the value cannot move farther out ofrange.

6 010110LL Sub-Normal The value is derived from multiple sourcesand has less than the required number ofGood sources.


Comment

Servers which do not support Substatus should return 0.


A&D PT1 D2



Date29.02.2000

Version5.0


Page105 of 111


5.1.2.2.3 Substatus for GOOD Quality:

SSSS BIT VALUE DEFINE DESCRIPTION0 110000LL Non-specific The value is good. There are no special

conditions1-5 N/A Not used by OPC6 110110LL Local Override The value has been Overridden. Typically

this means the input has beendisconnected and a manually enteredvalue has been ‘forced’.


Comment

Servers which do not support Substatus should return 0.


A&D PT1 D2



Date29.02.2000

Version5.0


Page106 of 111


5.1.2.3 The Limit BitField

The Limit Field is valid regardless of the Quality and Substatus. In some cases such as Sensor Failure it canprovide useful diagnostic information.

LL BIT VALUE DEFINE DESCRIPTION0 QQSSSS00 Not Limited The value is free to move up or down1 QQSSSS01 Low Limited The value has ‘pegged’ at some lower limit2 QQSSSS10 High Limited The value has ‘pegged’ at some high limit.3 QQSSSS11 Constant The value is a constant and cannot move.

Comment

Servers which do not support Limit should return 0.

Symbolic Equates are defined for values and masks for these BitFields in the “QUALITY” section of the OPCheader files.


A&D PT1 D2



Date29.02.2000

Version5.0


Page107 of 111


5.1.3 Priority of Quality Codes

Quality Substatus

Good (NC) O.K.

Good (NC) Active Block Alarm

Good (NC) Active Advisory Alarm

Good (NC) Active Critical Alarm

Good (NC) Unack Block Alarm

Good (NC) Unack Advisory Alarm

Good (NC) Unack Critical Alarm

Uncertain non-specific

Uncertain Last Usable Value (LUV)

Uncertain Substitute / Manual Entry

Uncertain Initial Value

Uncertain Sensor Conversion not Accurate

Uncertain Engineering Unit Range Violation

Uncertain Sub-normal

Uncertain Configuration Error

Uncertain Simulated value

Good (C) O.K.

Good (C) Initialisation Acknowledge

Good (C) Initialisation Request

Good (C) Not Invited

Good (C) Not Selected

Good (C) Do Not Select

Good (C) Locked Out

Good (C) Fail Safe Active

Good (C) Initiate Fail Safe

Bad non-specific

Bad Configuration changed, variable adapted

Bad Configuration Error, value not accepted

Bad Not Connected

Bad Sensor Failure

Bad Device Failure

Bad No Comm, with LUV

Bad No Comm, no LUV

Bad Out of Service

Lowest Priority

Highest Priority


A&D PT1 D2



Date29.02.2000

Version5.0


Page108 of 111


5.1.4 Mapping WinCC-Status to Quality Codes

WinCC-DM Variablestate Quality Code according to Profibus PA/OPCDM_VARSTATE_SERVERDOWN (0x4000) Bad, out of service, 0x1CDM_VARSTATE_HARDWARE_ERROR(0x0004)

Bad, device failure, 0x0C

DM_VARSTATE_NOT_ESTABLISHED(0x0001)

Bad, not connected, 0x08

DM_VARSTATE_TIMEOUT (0x2000) Uncertain, last usable value, 0x44DM_VARSTATE_HANDSHAKE_ERROR(0x0002)

Bad, no communication (no usable value), 0x18

DM_VARSTATE_ADDRESS_ERROR(0x0400)

Bad, configuration changed, variable adapted, 0x20

DM_VARSTATE_INVALID_KEY (0x0800) Bad, configuration error, value not accepted, 0x04DM_VARSTATE_ACCESS_FAULT (0x1000) Bad, configuration error, value not accepted, 0x04DM_VARSTATE_MAX_RANGE (0x0020) Uncertain, engineering unit range violation, high limit

set, 0x56DM_VARSTATE_MIN_RANGE (0x0040) Uncertain, engineering unit range violation, low limit

set, 0x55DM_VARSTATE_CONVERSION_ERROR(0x0080)

Uncertain, engineering unit range violation, no limits,0x54

DM_VARSTATE_STARTUP_VALUE (0x0100) Uncertain, initial value, 0x4CDM_VARSTATE_DEFAULT_VALUE (0x0200) Uncertain, substitute-set, 0x48

5.2 Terms / abbreviations

Term ExplanationVirtual connection Virtual communications channel with unique name and uniform behaviour

towards the WinCC system

Channel-specificconnection

Real communications channel of a defined communications medium

Channel-specificconnection description

Connection parameter of the channel-specific connection

Channel-specific variabledescription

Channel-specific description of a variable address


A&D PT1 D2



Date29.02.2000

Version5.0


Page109 of 111


—A—Additonal API Functions in WinCC 4.X 82API structures

CHN_CAPS 22CHN_ENTRYPOINTS 20CHN_STARTSTRUCT 32CHN_WRITEDESCRIPTOR 66CMN_ERROR 9LOGCONNECTIONSTRUCT 12VARIABLEACCESSRESULT 56VARIABLESTRUCT 16

—B—Byte order

of the coupled unit 57recoding 57

—C—Callback function

for acknowledgement of the status of a write job 33for delivery of read process values 33, 63for delivery of the write status 68GETVALUECB 71GETVALUENAMECB 72SETVALUECB 73SETVALUENAMECB 75

CChnDiagnose 91Channel unit with own cycle managment 54Channel without own cycle management 55Channel-DLL with several units 10Channel-specific expansion of a virtual connection 11Channel-specific expansion of a WinCC-variable 15Channel-specific variable-address 15CHN_CAPS 22CHN_ENTRYPOINTS 20CHN_STARTSTRUCT 32CHN_TIMEDCALLBACK 36CHN_WRITEDESCRIPTOR 66CHN_WRITEDESCRIPTOREX 88ChnChangeByteOrder 57ChnChangeLanguage 80CHNCNVMETHOD 83ChnConvertAsToOs 83ChnConvertConnectionToBinary 78ChnConvertConnectionToString 77ChnConvertOsToAs 84ChnConvertVariableToBinary 80ChnConvertVariableToString 79ChnEditConnection 46ChnEditProperties 53ChnEditVariable 50ChnGetAddressUnitSize 51ChnGetCaps 22ChnGetConnectionPropPageCount 44ChnGetConversionlist 82ChnGetEntryPoints 19ChnGetUnitCount 21ChnGetVariablePropPageCount 48, 49ChnRegisterConnection 29

ChnRegisterVariable 30ChnStart 32ChnStartRead 59ChnStartWrite 65ChnStartWriteEx 89ChnUnLoad. 39CMN_ERROR 9, 10CompareFlags 96Configuring Tag-Properties and Address 84Conventions 8CreateConnection 92CreateCounter 94CreateUserFlag 96Cyclical requests 54

—D—Data formats

Change of channel specific 77Data type of a WinCC-variable 15DeleteConnection 92

—E—Error recovery 9Error recovery in the API functions 9

—G—GETVALUECB 71GETVALUENAMECB 72

—I—IncrementCounter 95Initialization of a channel 19Initialization of a channel during loading 19Initialization of a channel unit

Parameter for the WinCC data manager 33Initialization of a channel-unit

Obligatory sequences 38

—L—Language change online 80LCC_CANREADVAR 13LCC_CANWRITEVAR 13LCC_TMSYNCMASTER 13LCC_TMSYNCSLAVE 13LCS_HANDSHAKEERROR 12LCS_HARDWAREERROR 12LCS_NORESOURCE 13LCS_NOTESTABLISHED 12LCSTATUSCHANGECB 36LOGCONNECTIONSTRUCT 12

—M—Mapping WinCC-Status to Quality Codes 110


A&D PT1 D2



Date29.02.2000

Version5.0


Page110 of 111


—O—OPC 103Optimization

in the reading of process values 61in the reading of WinCC-variables 61in the writing of WinCC-variables 67

—P—pfnGetProjectFileName 86pfnGetVariableInfo 85Planning

Configuration of a channel 53of virtual connections 40of WinCC-variable 47

Priority of Quality Codes 109Process values

Abort of a write job 63Description of the data to be written 66Optimizations in the reading 61Return of read values 62Return of the write status 67To write 65

Profibus PA 99Properties

of a channel unit 22of a virtual connection 13

Properties of a channel unitAccess to remote-variable 27Editing of the channel properties 23No registration of WinCC-variables 23Online-registration of WinCC-variables 23Process values in INTEL byte order 23Reentrant 27Time master 23Time slave 23

Properties of a channel unitAccess to remote-variable 23Client-functionality 23, 26Diagnosis options 23Dialogs by means of MFC 28No registration of WinCC-variables 28Online-registration of virtual connections 27Online-registration of virtual connections 23Online-registration of WinCC-variables 27Own cycle management 23, 25, 54Own life monitoring 23, 26Own restart display 23, 27Process values in INTEL byte order 28Reentrant 23Supporting the Project-Browsers 28Time master 28Time slave 28Writing onto bit addresses 23, 26Writing onto byte addresses 23Writing to byte addresses 26

—Q—Quality-Codes 99

—R—Read process values 59READFINISHCB 63READFINISHCBEX 88Registration of a virtual connection 28

during the runtime 30Registration of a virtual connection when starting

WinCC 30Registration of a WinCC-variable 30Result

Function result of the API functions 9

—S—SetConnectionState 93SetCounter 95SETVALUECB 73SETVALUECBEX 89SETVALUENAMECB 75Shutdown of a channel 39

through the operating system 39through the WinCC data manager 39

Statusof a virtual connection 13, 36of a WinCC-variable 56

Status of a virtual connection 36Storage of a channel unit 10

—T—The Limit BitField 108The Quality BitField 104The Substatus BitField 104Time synchronisation

Initiating 36Time synchronization 76

Changing the time of a WinCC machine 37Channel unit as a time master 76Channel unit as time slave 77

TIMECHANGECB 37To be defined

Diagnosis-API 81Transaction ID 57

—V—VARC_FIELD 17VARC_RAW 17VARC_SERVERACCESS 17Variable interface 54VARIABLEACCESSRESULT 56VARIABLEACCESSRESULTEX 87VARIABLESTRUCT 16Virtual connection 11

Data structure 12Registration with a channel unit 28

—W—WinCC system structure 7WinCC-variable 14

Access result 56


A&D PT1 D2



Date29.02.2000

Version5.0


Page111 of 111


Data type 15internal data structure 16optimized requests 61, 67Status bits 56

WriteApiReturn 94WRITEDESCRIPTOREX 88WRITEFINISHCB 68WriteFormat 93WriteHResult 93WriteMemory 94

Documents

Channel-API Specification - · PDF fileSIEMENS AG Automatisierungstechnik A&D PT1 D2 WinCC Channel Developers Kit Channel-API Specification Date 29.02.2000 Version 5.0 File < WinCC\ChnDk\Manuals\ChnAPI5.doc