Calling DLL Functions from WinCC V7: C++ Integration Tutorial

Overview

Siemens WinCC V7 (and the V7.x service packs) supports calling external dynamic-link libraries (DLLs) directly from C / VBS actions attached to buttons, pictures, or scheduled tasks. This pattern is the standard way to integrate a custom Visual C++ module that talks to third-party hardware (RFID readers, barcode scanners, weigh scales, custom serial devices) without rebuilding the WinCC runtime in C. The integration path is short, but it is strict: the DLL must export C-linkage symbols with __declspec(dllexport), the file must be visible to the WinCC runtime (BIN folder or PATH), and the action script must wrap every native call in #pragma code("dllgraph.dll") / #pragma code() so the WinCC C interpreter loads the binary stub correctly.

This tutorial consolidates the standard Siemens procedure with a working C++ project, the recommended Build / Deploy steps, and a troubleshooting matrix for the most common failure modes (function not found, error return, silent no-op, GetComputerNameEx returning blanks).

Prerequisites

1. WinCC V7.x installed and licensed, with the "C-Script" option active in the project properties (right-click the project in WinCC Explorer → Properties → Options tab).
2. Microsoft Visual C++ build environment. Visual Studio 2010 through 2019 are confirmed compatible with WinCC V7 C-scripts. Target the same architecture (x86 or x64) as the WinCC runtime - mixed-bit DLLs are the most common cause of silent load failures.
3. Administrator rights on the engineering station to write into \\\\<project>\\bin\\ and to update the PATH environment variable.
4. Read access to the WinCC Information System (installed locally or via Siemens Industry Online Support) for the chapter "ANSI-C function descriptions → Standard functions → code".

Architecture: How WinCC Loads a DLL

WinCC C actions are compiled at runtime by the dllgraph.dll interpreter. When a script reaches a foreign function call, WinCC must resolve the symbol at execution time using the standard Windows loader rules:

1. The #pragma code("YourDll.dll") directive tells the interpreter to bind subsequent function calls to YourDll.dll.
2. Windows searches the following locations, in order, for the DLL: the directory of the running process (explorer.exe for WinCC runtime), the current working directory, the Windows system directory, the Windows directory, and finally each folder listed in the PATH environment variable.
3. If the loader finds the file, it maps it into the WinCC process and binds exported symbols. If the file is missing, the action returns the string error at runtime - the same symptom a student would see when calling a function that does not exist.

A DLL is, by definition, a shared module that can be loaded into any process that has the right import table. For background on the Windows loader behavior see the Microsoft Learn article Dynamic link library (DLL) and the general reference at Dynamic-link library (Wikipedia).

Step 1 - Build a C++ DLL with C-Linkage Exports

Create a new Win32 Dynamic-Link Library project in Visual Studio. The single most important rule is that the functions WinCC will call must be exported with C linkage and the __declspec(dllexport) storage class. Without the C linkage, the C++ compiler mangles the symbol name (?init_port3@@YAXXZ) and the WinCC interpreter - which looks up the undecorated name - cannot find it.

Header file: RfidPort.h

#ifdef RFIDPORT_EXPORTS
#define RFIDPORT_API extern "C" __declspec(dllexport)
#else
#define RFIDPORT_API extern "C" __declspec(dllimport)
#endif

RFIDPORT_API int  init_port3(void);
RFIDPORT_API int  read_uid(char* buf, int buflen);
RFIDPORT_API void close_port3(void);

Source file: RfidPort.cpp

#include "RfidPort.h"
#include <windows.h>

RFIDPORT_API int init_port3(void)
{
    HANDLE h = CreateFileA("\\\\.\\COM3",
        GENERIC_READ | GENERIC_WRITE,
        0, NULL, OPEN_EXISTING, 0, NULL);
    if (h == INVALID_HANDLE_VALUE) return -1;
    return 0;
}

RFIDPORT_API int read_uid(char* buf, int buflen)
{
    // ... real read implementation ...
    return 0;
}

RFIDPORT_API void close_port3(void)
{
    // ... cleanup ...
}

Project settings to verify

Build the project. The output RfidPort.dll is the file you will deploy to WinCC.

Step 2 - Deploy the DLL to a Location WinCC Can Find

WinCC runtime runs under the account that started the WinCC Runtime. Windows DLL search order will only look in the directories listed above. The two recommended deployment locations are:

1. Project BIN folder: C:\Siemens\WinCC\WinCCProjects\<YourProject>\bin\. Drop RfidPort.dll here. This is the path WinCC uses for its own dllgraph.dll, so the loader will always find co-located files.
2. System PATH: Add the folder containing RfidPort.dll to the PATH environment variable. Restart the WinCC Runtime after the change. Use this for shared libraries that several projects use.

If the runtime is on a different machine from the engineering station, copy the DLL to the same project folder on the runtime PC and confirm the bitness. A 32-bit RfidPort.dll on a 64-bit runtime (or vice-versa) will not load and will return a runtime error string in the action output log.

Step 3 - Call the DLL from a WinCC C Action

Open Graphics Designer, drop a button on a screen, and configure a C action on the mouse-click event:

1. Right-click the button → Properties → Events → "Mouse" → "Press left".
2. Assign a C action (not a VBS action - VBS uses CreateObject("ComObject") for COM servers, not raw DLLs).
3. Paste the code below:

#include "apdefap.h"

void OnClick(char* lpszPictureName, char* lpszObjectName, char* lpszPropertyName, UINT nFlags, int nX, int nY)
{
    DWORD dwSize = MAX_COMPUTERNAME_LENGTH + 1;
    char  szName[MAX_COMPUTERNAME_LENGTH + 1];

    #pragma code("kernel32.dll")
    BOOL WINAPI GetComputerNameExA(DWORD, LPSTR, LPDWORD);
    #pragma code()

    if (GetComputerNameExA(3, szName, &dwSize))
        printf("Computer name: %s\r\n", szName);
    else
        printf("GetComputerNameEx failed: %lu\r\n", GetLastError());
}

For the custom RFID DLL, the script is:

#pragma code("RfidPort.dll")
int  init_port3(void);
int  read_uid(char* buf, int buflen);
void close_port3(void);
#pragma code()

void OnClick(char* lpszPictureName, char* lpszObjectName, char* lpszPropertyName, UINT nFlags, int nX, int nY)
{
    int rc = init_port3();
    if (rc != 0) {
        printf("init_port3 failed, rc=%d\r\n", rc);
        return;
    }
    char uid[64] = {0};
    read_uid(uid, sizeof(uid));
    printf("UID = %s\r\n", uid);
    close_port3();
}

Notice the four-line block at the top: the prototypes are declared between #pragma code("RfidPort.dll") and #pragma code(). This pair of pragmas is mandatory; the WinCC compiler inserts the __declspec(dllimport) declaration only for symbols listed inside the block. Outside the block, calls to those names will fail to link.

Step 4 - Build the WinCC Project and Activate Runtime

1. In WinCC Explorer, right-click the project → "Rebuild". This compiles the C actions and refreshes the bin\ directory of the runtime image.
2. Open Graphics Designer, right-click the picture → "Assign picture to ..." (if not already assigned).
3. Open WinCC Runtime (Start → Programs → Siemens Automation → WinCC → WinCC Runtime). Click the button. The output of printf is written to the WinCC diagnostic log (<project>\Diagnostics\WinCC_Sys_*.log) and to the APDIAG output window of the GDI runtime.

Verification

Troubleshooting Matrix

Common Pitfalls

Mixing C and C++ linkage. If the prototype inside the #pragma code() block is declared as extern "C++" int init_port3(); the symbol will be C++-mangled and unresolvable. Keep the prototypes plain C.

Calling convention. Win32 APIs use WINAPI (= __stdcall). User C functions are typically __cdecl (the Visual C++ default). Mismatched conventions corrupt the stack and crash the runtime the first time the function returns. Use WINAPI on the prototype inside the pragma block when wrapping a Win32 API:

#pragma code("kernel32.dll")
BOOL WINAPI GetComputerNameExA(DWORD, LPSTR, LPDWORD);
#pragma code()

Static vs. dynamic CRT. The default Visual Studio CRT is the DLL variant (/MD). The WinCC runtime already ships with the matching MSVCRxxx.dll. If you switch to /MT (static), the binary grows but you remove one possible STATUS_DLL_NOT_FOUND cause on air-gapped runtime PCs.

Runtime version drift. A DLL built on Visual Studio 2019 against the v142 toolset will require vcruntime140.dll and msvcp140.dll on the target. Match the Visual Studio toolset to the redistributable installed on every WinCC Runtime PC, or use /MT as a workaround.

Data execution across action boundaries. The runtime may unload the script module between actions, so any state your DLL keeps in process-local globals survives but the DLL file itself can be reloaded. Do not store connection handles in the WinCC tag system; store them inside the DLL and key them by an integer handle returned to the C action.

Reference: WinCC C Pragma and Standard Functions

WinCC defines code as a documented standard function in the ANSI-C for creating functions and actions reference. The exact syntax is:

#pragma code("dllname.dll")
<function prototypes>
#pragma code()

The official Siemens FAQ at Entry ID 8301801 - How do you call a Windows DLL function in a WinCC C script? covers the kernel32 sample used in this tutorial, the GetComputerNameEx implementation, and the recommended WINAPI calling convention. The general WinCC scripting documentation is searchable from Siemens Industry Online Support under "WinCC V7.x > Function descriptions > ANSI-C function descriptions > Standard functions > code".

Field-Commissioning Checklist

1. Confirm the WinCC project is rebuilt after dropping the DLL into bin\.
2. Confirm dumpbin /exports shows the undecorated C symbols.
3. Confirm x86 / x64 parity between the DLL and the WinCC runtime.
4. Add a temporary OutputDebugStringA in the DLL entry point to verify it is loaded on first use.
5. Tail the WinCC diagnostic log (WinCC_Sys_*.log) for the printf() outputs of the C action.
6. Remove the temporary debug output before sign-off.

Notes for Multi-Project / Multi-Runtime Deployments

When the same DLL is shared between several WinCC projects on the same runtime PC, prefer the PATH approach with a versioned subfolder (e.g. C:\Siemens\SharedLibs\RfidPort\1.4\) and document the version inside the project README. Avoid copying the DLL into each project's bin\ folder; that path makes upgrades and roll-backs painful. When upgrading the DLL, stop the WinCC Runtime, swap the file, then start the runtime - the Windows loader keeps the old copy mapped until the process exits.