Resolving WinCC TagPrefix SetTagBit Errors in C Scripts

Problem Overview

When programming WinCC Runtime HMI screens in C (WinCC V7.x or WinCC Professional), a common pattern is to read the active picture window's TagPrefix and use it as a namespace prefix to address a process tag. The following code skeleton is representative of the failure pattern engineers encounter:

char *a;          // parent picture window name
char *b;          // scratch buffer
char *c;          // parent picture name
char *d;          // resolved tag name

a = GetParentPictureWindow(lpszPictureName);
c = GetParentPicture(lpszPictureName);
b = strcat(c, ".pdl");
d = GetTagPrefix(b, a);
SetTagBit(d, 1);

The script compiles, the variable d is populated (verified with printf), and the program reaches the final line, where execution fails. Two distinct defects hide inside the snippet: an unsafe strcat on a WinCC-owned string pointer, and a malformed tag name passed to SetTagBit. Each defect produces a different observable symptom — undefined behavior vs. a "Tag not found" runtime error — and both must be corrected to obtain a stable script.

Root Cause Analysis

Defect 1 — Undefined behavior from in-place strcat on a WinCC-allocated buffer

The GetParentPicture() function returns a pointer to an internal string buffer that is owned and managed by the WinCC runtime. WinCC's C API contract is that callers treat this pointer as read-only. Appending ".pdl" to that buffer with strcat(c, ".pdl") violates the contract in two ways:

1. The runtime buffer has a fixed allocation size; writing past the end overwrites adjacent heap metadata or other WinCC structures.
2. Even when the write fits, you have corrupted state that the runtime will re-use on the next graphics dispatch cycle, leading to a delayed crash, a hang, or a silent mis-read on the next call to any of the picture APIs.

This is the typical cause of "works the first time, crashes the second" behavior observed during commissioning. The fix is to copy the string into a caller-owned buffer before any concatenation, and to size that buffer to the worst case WinCC's documentation specifies (typically 256 bytes for tag names, 512 bytes for picture paths).

Defect 2 — Malformed tag identifier passed to SetTagBit

SetTagBit() expects a fully qualified tag name in the WinCC tag namespace, for example Plant1_Area3_Motor_HMI.Start. It does not accept picture names, .pdl file names, or arbitrary concatenations thereof. The GetTagPrefix() call returns the configured prefix string that the picture window was instantiated with; the offset portion of the tag is supplied by the picture's link configuration, not by the C script. The original code treats d (the prefix) as if it were a complete tag, which is why WinCC reports the tag as non-existent.

Environment and Prerequisites

• Siemens WinCC V7.x or WinCC Professional (TIA Portal) runtime with C scripting enabled on the HMI device.
• A picture window configured with a dynamic TagPrefix property in the Properties pane. See the Siemens TIA Portal VBS object model reference for the TagPrefix property for the equivalent VBS semantics — the same property name and value semantics apply in C.
• A consistent tag-naming convention in the AS/HMI connection: every tag the picture uses must share the same suffix after the prefix boundary (e.g., {Prefix}_Start, {Prefix}_Stop, {Prefix}_Ack).
• Global functions header apdefap.h included in the script project so the WinCC C API prototypes are visible.

Method 1 — TagPrefix With Consistent Tag Offset

This is the supported pattern when the picture window's internal links all use the same offset suffix. The picture is designed once with relative tag references, and the prefix is swapped at runtime to redirect every link to a new underlying tag.

Design constraint

Every tag configured on the picture's I/O fields, buttons, and I/O symbols must follow the form {TagPrefix}<Suffix> where <Suffix> is identical across all controls. Example suffixes: _Start, _Stop, _Status. If the suffixes are not identical, you cannot redirect the picture's tags with a single prefix change.

Working C implementation

#include "apdefap.h"

void OnClick_YesButton(char* lpszPictureName, char* lpszObjectName)
{
    /* Caller-owned scratch buffer. WinCC tag names are limited
       to MAX_TAGNAME (255) characters in V7.x. */
    char szTag[256];
    char szPrefix[128];
    char* pszParentWindow = NULL;
    char* pszParentPicture = NULL;
    DWORD dwState = 0;

    pszParentWindow = GetParentPictureWindow(lpszPictureName);
    pszParentPicture = GetParentPicture(lpszPictureName);

    if (pszParentWindow == NULL || pszParentPicture == NULL)
    {
        /* Picture is not hosted inside a picture window.
           No TagPrefix to resolve; abort. */
        return;
    }

    /* Read the configured prefix into a local buffer.
       GetTagPrefix copies the prefix into the caller's buffer;
       it does NOT return a pointer into WinCC-owned memory. */
    GetTagPrefix(pszParentPicture, pszParentWindow, szPrefix, sizeof(szPrefix));

    /* Construct the full tag name: {Prefix}_Start.
       snprintf is bounds-checked and avoids the strcat hazard. */
    _snprintf(szTag, sizeof(szTag), "%s_Start", szPrefix);

    /* Defensive check: confirm the tag exists before writing. */
    if (GetTagBitWait(szTag, &dwState, 1) != 0)
    {
        /* Tag not present in the AS connection or in the HMI tag table.
           Log and exit. */
        printf("TagPrefix set failed: tag '%s' not found\n", szTag);
        return;
    }

    SetTagBit(szTag, 1);
}

Method 2 — Direct Link With PDLRTSetLink

When the underlying tag structure varies between invocations — different tag types, different suffixes, or even different AS connection points — the TagPrefix pattern cannot work because the picture's static link configuration fixes the suffix. The alternative is to override the link dynamically using the WinCC graphics runtime link API.

The relevant function is PDLRTSetLink(), which is exported by the WinCC graphics runtime. It accepts a fully qualified link source string and re-points the I/O field at the new tag at runtime.

#include "apdefap.h"

void OnClick_YesButton(char* lpszPictureName, char* lpszObjectName)
{
    char szLink[512];
    char szPrefix[128];
    char* pszParentWindow = NULL;
    char* pszParentPicture = NULL;

    pszParentWindow = GetParentPictureWindow(lpszPictureName);
    pszParentPicture = GetParentPicture(lpszPictureName);

    if (pszParentWindow == NULL || pszParentPicture == NULL)
        return;

    GetTagPrefix(pszParentPicture, pszParentWindow, szPrefix, sizeof(szPrefix));

    /* Different tags this time — no fixed suffix required. */
    _snprintf(szLink, sizeof(szLink), "PLC1::S7_Distributed::Motor_%s.CmdStart", szPrefix);

    /* Re-point the named I/O field on the hosted picture.
       The link parameter is the field's object name on the child picture. */
    PDLRTSetLink(lpszPictureName, lpszObjectName, szLink);

    /* The new link is a bit tag; drive it high. */
    SetTagBit(szLink, 1);
}

Method 2 is the more flexible pattern and is the recommended approach for adaptive HMI applications where the same picture window is reused for many different process units with structurally different tag sets. The trade-off is that the link change is one-shot: each field must be redirected explicitly.

Memory-Safe C Coding in WinCC

The original strcat bug is the most common memory error in WinCC C scripts because engineers coming from managed-runtime environments assume WinCC returns strings they own. They do not. The following table summarizes the ownership semantics of each API the script uses.

Rule of thumb: if a WinCC C API returns a char*, treat the pointer as a loaner. Copy it into a local buffer with strncpy or snprintf before you do anything beyond a printf. Functions that take a buffer + length pair (the Get* family) are the safe alternative and should be preferred.

Function Reference

Verification Procedure

1. Open the WinCC Graphics Designer, select the picture window, and confirm the TagPrefix property is bound to a tag (e.g., a WinCC string tag named CurrentUnit) or a script that returns a prefix such as Unit_3.
2. Add a Global Script action bound to the "Yes" button. Use the Method 1 code from this article.
3. In the WinCC Tag Simulator, ensure at least one tag matching {Prefix}_Start exists for the prefix the picture window is currently displaying. Example: if CurrentUnit = Unit_3, confirm that Unit_3_Start is defined in the tag management.
4. Start Runtime. Click "Yes." Use the Tag Diagnostics view (WinCC Explorer > Tools > Tag Diagnostics) to confirm the value of {Prefix}_Start has been set to 1.
5. Click "No." Confirm the same tag is reset to 0 by a complementary SetTagBit(szTag, 0) call in the "No" button handler.
6. Open the Global Script diagnostic output (or the aplog.txt file in the WinCC project directory) and confirm no Tag not found or memory-access error messages are logged across 100+ click cycles.

Troubleshooting Matrix

Best Practices

• Reserve a fixed-size char buffer for every string the script constructs. Reasonable default sizes: 128 bytes for a single prefix, 256 bytes for a tag name, 512 bytes for a fully qualified PLC link path.
• Never call strcpy or strcat on a pointer returned by a WinCC Get* function. Always copy first.
• Validate tag existence with GetTagBitWait (or the type-appropriate read function) before any write. A single Tag not found event in a 24-hour production run indicates a configuration drift that will not fix itself.
• Standardize the picture's link suffix in the Graphics Designer before authoring any C scripts against the picture window. The script's responsibility is to supply the prefix; the picture's responsibility is to supply the suffix.
• If the tag namespace is highly dynamic (different tag types per invocation), design the picture with placeholder links and use PDLRTSetLink from a startup action to point each placeholder at the correct tag at runtime.
• Log every TagPrefix resolution to the diagnostic output during commissioning. Remove the verbose logging before production sign-off, but leave a single-line trace so post-incident analysis is possible.

FAQ