API, basics

The WinCC OA API (Application Programming Interface) offers a number of functions adding special Managers to this process control system. A manager is a program that communicates with the system via a protocol defined by WinCC OA.

Note

Documentation of the API functions can be found in your installation directory <wincc_oa_path>/api/docu (if you select the API installation from the installation options!).

Classes, include files

In order to facilitate work with the large number of C++ classes available in WinCC OA, all include files are named exactly the same as the class name with the extension ".hxx". A class called "ManagerIdentifier", for example, can be found in the file "ManagerIdentifier.hxx". I.e., for each class you use, you must include the appropriate include file using the #include directive.

Many classes can also be used without an explicit #include, for example because Manager.hxx already includes many other files.

Note

When using Solaris, user defined functions inside the .hxx file, that are called with userDefFunc(), must be declared inside a "extern "C"{<functions>}" block. e.g.:

extern "C"

{

TABUTIL_EXPORT int tabUtilTranslateDirection(const DynVar &in, DynVar &out);

TABUTIL_EXPORT int tabUtilBar (const DynVar &in, DynVar &out);

TABUTIL_EXPORT int tabUtilConcate (const DynVar &in, DynVar &out);

}

Event and Data manager

The central manager in WinCC OA is the Event Manager that is the center of communications of the control system. As soon as a manager is loaded, it usually just exchanges messages with the Event Manager.

The second key manager is the Data Manager that takes care of all data management tasks. When the program is launched, every manager connects to the Data Manager to obtain initialization data. After successful initialization, the program connects to the Event Manager (except for the Event Manager itself, of course). The connections to the Data and Event Manager are maintained until the Manager is terminated.

The program can only connect to the Data and Event Manager if there is no other connection by a manager with the same manager identifier. Especially with API managers, make sure that all managers have the same manager type and only differ in terms of their manager number.

Caution

ALWAYS recompile custom managers built with a particular WinCC OA version when using a more recent version (also applies to branch versions!).
WCCIL API supports release builds only, so it is not possible to compile own managers in debug mode.

note

64-bit operation systems are supported starting from WinCC OA version 3.11, please refer to software-requirements. Any customer-developed 32-bit Manager, CONTROL Extentions and Error-Handling must be changed to 64-bit.

Messages

The managers communicate with each other using messages. WinCC OA defines a fixed set of messages used for communication.

The majority of API functions are used to generate and send messages. The managers receive messages using the doReceive() function that is applied to all ingoing messages.

Chapter	Description
API, basics	General overview and links to the chapters.
API installation	Installation under NT and Linux.
Create API manager/driver	Step by step introduction to create a manager.
Demo Manager	This example manager shows how to connect to the Data and Event Managers. It also connects to a data point and copies a new value to another data point every time.
SampleDriver	This driver example is based on ComDrv. Two drivers communicate with each other via "namedPipes".
TCP driver	This is an example of drivers communicating via TCP or UDP.
API messages	As long as you use the documented API functions, it is not necessary to have detailed knowledge of messages: messages are generated and sent by API functions.
API manager classes	This chapter describes the essential classes for the API manager development.
ComDrv driver	The general driver is a collection of classes, covering the functional range that every driver in WinCC OA should possess. It also defines an interface to the hardware-specific part.
Configuration panels for new drivers	Two prepared example scripts have been provided to make it easier for you to integrate new drivers in WinCC OA. All you need to do is add the name and type at specified points in the scripts, and define your commands.
EWO (External Widget Object)	An EWO (External Widget Object) is a graphical object (a Widget) created by some external party (customer) and can be embedded into any WinCC OA Panel. It is similar to what is known as ActiveX on Windows, but it is not limited to the Microsoft Operating systems.

V 3.11 SP1