CtrlExtension, basics

In order to add custom C++ functions to the CONTROL, it is necessary to write a CtrlExtension that implements a derivation of the BaseExternHdl class.

Note: Please consider the requirements for API development when creating custom

Permissible classes and libraries

All non - WinCC OA libraries and all following library classes may be used to implement custom CONTROL functions:

  • bcm.dll or .so (Linux)

  • libBasics.dll or .so (Linux)

  • libConfigs.dll or .so (Linux)

  • libDatapoint.dll or .so (Linux)

  • libMessages.dll or .so (Linux)

  • libManager.dll or .so (Linux)

  • libCtrl.dll or .so (Linux)

  • libV24.lib or .a (Linux)

These libraries are part of the WinCC OA API interface.

Prohibited classes and libraries

The following libraries

  • libComDrv.lib or .a (Linux)

are also included in the API interface. However, they may not be used.

Loading a CtrlExtension

Via the keyword #uses you can specify which CTRL extensions are needed in a script or in a panel. Therfore, the extensions must not be entered into the config file anymore. This facilitates the use of the extensions and the extensions are loaded first when they are needed. Which extensions a manager should load can also be defined via entries in the config.level file. We, however, recommend to use the keyword #uses. How to use the keyword #uses or how you can define which extensions should be loaded via the entries in the config.level file are described in the following.

Note:

  • The driver plug-ins used under Linux with CtrlADO were renamed due to QT4:

    QMYSQL3 -> QMYSQL (for MySQL 4 and higher)

    QOCI8 -> QOCI (for Oracle 9i, 10g and higher)

  • The libraries will first be searched for in the local installation.

Loading a CtrlExtension via Keyword #uses

Via the keyword #uses you can define which extension a panel or a script needs. The file extension can be omitted since it is set automatically depending on the operating system.

#uses "CtrlADO"

The extensions specified in a script or in a panel are not valid only in the script but manager wide and remain in the memory until the manager is stopped. The extensions are loaded into the memory by the CTRL kernel. The keyword can be used in each script before the functions and in panel global functions. An arbitrary number of #uses definitions can be used in panels and scripts. Note that the opening of panels may take a little bit longer when one or more big libraries are loaded for the first time.

Note:

Remember that "uses" is a keyword and cannot be used as a variable.

Loading a CtrlExtension via the Entries in the config.level file

In order for a manager to load an extension it must be

  1. copied to the bin directory of the WinCC OA project,

  2. an entry must be made in the config.level file.

A CTRL extension is searched as follows:

  1. The defined name is searched.

  2. The different extensions: ".dll", ".so", ".shlib" are searched.

  3. The "lib" Prefix is searched (tried). This means:

    "lib" + entry + ".dll"

    "lib" + entry + ".so"

Note:

We recommend to use a CONTROL extension without file name extension in the #uses statement since the script remains platfrom neutral and can be executed without changes on all platforms. If you specify the extension, for example, "CtrlADO.dll", this extension would not be found under Linux since it is called CtrlADO.so. It is better to use #uses "CtrlADO".

Example

Under Windows the following config entry can be used to load a DLL:

CtrlDLL = "CtrlADO"

First, the program looks for this DLL in the <proj_path>/bin directory. If it is not found there, the program looks in the <wincc_oa_path>/bin directory.

This entry can only be made in the [ui] or [ctrl] section. If a DLL is used by UI and CTRL, it must be entered in both sections. Any number of DLLs may be loaded.

CtrlExtension example

An example for a CtrlExtension can be found inside the /api/TemplateCtrlExt/ folder of the WinCC OA installation. Please consider the README file!