WinCC C-Action OnPropertyChanged Boolean Logic Explained

Overview

Siemens WinCC exposes a per-property C-Action that fires every time a configured object property changes value. The script in this reference is a canonical OnPropertyChanged handler that reads three user-defined configuration properties from a custom WinCC object, evaluates a boolean expression, and writes the result to the two visibility properties @On_Vis and @Off_Vis. The exact line that confuses engineers is the nested equality comparison:

Result = ((Neg == NegRes) == Signal);

The expression is valid ISO C, has no precedence trickery, and reduces to a single boolean that can be rendered in a truth table. This article decodes that line, explains why GetPropBOOL is used in this specific handler instead of GetTagBit, and provides a refactored version that reads an entire PLC error word at once instead of polling single bits. The target audience is the WinCC V7.x and WinCC TIA (Comfort/Professional) engineer who has just inherited a custom object library and needs to understand, modify, or troubleshoot visibility logic on HMI screens.

Prerequisites

• WinCC V7.4 SP3 / V7.5 SP2 / V7.5 SP4 or TIA Portal WinCC Professional V16-V18 with the C-Script option installed.
• Graphics Designer license with the C-Editor add-in enabled (Options > Settings > C-Script).
• A configured custom WinCC object exposing the user-defined properties Signal, Sig_neg, and NegRes as type BOOL.
• Knowledge of the C-Action trigger model: scripts fire on property change events, not on tag polling unless a trigger tag is explicitly configured.
• Knowledge of the WinCC tag namespace: internal tags, process tags, and structure tags (see the WinCC Information System under Configuration > Tags).

The C-Action Source Under Review

#include "apdefap.h"
void OnPropertyChanged(char* lpszPictureName,
                       char* lpszObjectName,
                       char* lpszPropertyName,
                       BOOL  value)
{
    BOOL Signal, Neg, NegRes, Result;

    Signal  = GetPropBOOL(lpszPictureName, lpszObjectName, "Signal");
    Neg     = GetPropBOOL(lpszPictureName, lpszObjectName, "Sig_neg");
    NegRes  = GetPropBOOL(lpszPictureName, lpszObjectName, "NegRes");

    Result  = ((Neg == NegRes) == Signal);

    SetPropBOOL(lpszPictureName, lpszObjectName, "@On_Vis",  Result);
    SetPropBOOL(lpszPictureName, lpszObjectName, "@Off_Vis", !Result);
}

Three custom properties (Signal, Sig_neg, NegRes) act as configuration inputs. The script computes Result from those inputs and assigns it to the built-in visibility properties @On_Vis and @Off_Vis. The @ prefix is the WinCC convention for system properties; the suffix _Vis marks the visibility attribute of the picture's ON and OFF states.

C Operator Semantics: == vs =

The first source of confusion is operator choice. C has two completely different operators that look almost identical in proportional fonts:

In the line Result = ((Neg == NegRes) == Signal);, the inner and outer == are both comparisons that yield 0 or 1. The single = in the outermost position is the assignment that stores that 0 or 1 into Result. There is no precedence trick: == has left-to-right associativity, so the expression is parsed as ((Neg == NegRes) == Signal) exactly as written, with no implicit grouping surprise.

Decoding the Boolean Expression

The expression ((Neg == NegRes) == Signal) can be expanded into a truth table. The intermediate == produces a 1 when Neg and NegRes match, and a 0 when they differ. The outer == then tests whether that 1-or-0 matches the value of Signal. The two inputs Sig_neg and NegRes together behave like a logical XOR enable: they are typically wired to two separate "invert" configuration flags.

Reading the right-hand column: Result is TRUE only when Signal agrees with the agreement of Neg and NegRes. The pattern is the standard implementation of a configurable inverted logic gate. The four boolean inputs (Signal, Sig_neg, NegRes, Result) cover all 16 possible states of three inputs, of which 8 yield Result = TRUE and 8 yield Result = FALSE. The implementation is a multiplexer that picks between Signal and !Signal based on the XOR of Sig_neg and NegRes.

GetPropBOOL vs GetTagBit vs GetTagWord

The source uses GetPropBOOL, which is the correct choice for configuration data bound to a custom object's user-defined properties. GetTagBit is the right call when the script needs a runtime process value from a tag, and GetTagWord is the right call when many bits live inside a single WORD and the script wants to avoid a per-bit round trip to the data manager.

Every call to GetTagBit enters the WinCC datamanager, acquires the data lock, copies the value, and releases the lock. In a script that runs every 250 ms and reads eight error bits, that is eight locks and copies per cycle. Reading the underlying WORD once and then masking the bits with C bitwise operators (&, |, <<, >>) collapses that into one lookup. The refactored block from the source is reproduced and expanded below.

The Property System Behind the Script

Three custom properties drive the logic, and two built-in system properties carry the output.

User-defined properties are added in the Graphics Designer by opening the object's properties dialog and selecting New under the Properties tab. WinCC stores them in the picture's .pdl file as a serialized structure; GetPropBOOL is the only public C API to read them at runtime. The system properties @On_Vis and @Off_Vis are evaluated by the WinCC Picture Renderer after every cycle; assigning to them in a C-Action takes effect on the next screen update.

Best Practice Refactor: Read the Error Word Once

Where the source mentions the common case of "different error bits of the PLC occupying the same byte, word, or double word," the following pattern should be used. The script reads the entire error WORD from the PLC and tests individual bits with a mask.

#include "apdefap.h"

#define ERR_OVERVOLTAGE   0x0001u   /* bit 0 */
#define ERR_OVERTEMP      0x0002u   /* bit 1 */
#define ERR_OVERCURRENT   0x0004u   /* bit 2 */
#define ERR_COMM_FAULT    0x0008u   /* bit 3 */
#define ERR_SAFETY        0x0010u   /* bit 4 */

BOOL bAnyError = FALSE;
WORD wError    = 0;

/* One datamanager call instead of five GetTagBit() calls */
wError = GetTagWord("PLC_DB100_DBW0_ERRORS");

if (wError & ERR_OVERVOLTAGE)  { /* overvoltage handling  */ }
if (wError & ERR_OVERTEMP)     { /* overtemperature        */ }
if (wError & ERR_OVERCURRENT)  { /* overcurrent            */ }
if (wError & ERR_COMM_FAULT)   { /* comm fault             */ }
if (wError & ERR_SAFETY)       { /* safety chain tripped   */ }

bAnyError = (wError != 0);
SetPropBOOL(lpszPictureName, lpszObjectName, "@On_Vis",  bAnyError);
SetPropBOOL(lpszPictureName, lpszObjectName, "@Off_Vis", !bAnyError);

For a 32-bit status word, use GetTagDWord and DWORD masks with the 0x00000001u notation. For a 64-bit status doubleword (WinCC V7.4 and later), use GetTagDWord on the low and high halves separately and combine. Avoid the deprecated GetTagBitWait / SetTagBitWait family for cyclic scripts, because the Wait variants block the Graphics Designer thread for up to the configured timeout and freeze the HMI when the PLC is offline.

Step-by-Step: Implementing the C-Action on a Custom Object

1. Open the object in Graphics Designer. Right-click the custom object and choose Configuration > Properties. Add three BOOL properties named exactly Signal, Sig_neg, and NegRes (case-sensitive; WinCC matches property names literally).
2. Wire the properties to source tags. For each new property, click the small lightbulb icon, select Tag, and pick the source. For Signal wire a live process tag such as PLC_DB100.DBX0.0. For Sig_neg and NegRes either wire to internal tags _InvertSignal and _InvertResult or set them to constant values in the object default dialog.
3. Open the C-Editor on the @On_Vis property. Right-click @On_Vis in the property list, choose C-Action. The editor opens with the signature void OnPropertyChanged(char*, char*, char*, BOOL) prefilled.
4. Paste the script. Copy the source body, replacing the function signature with the prefilled one if needed. Save and recompile (F7 in V7.x, the hammer icon in TIA Portal).
5. Set the trigger. Under Trigger in the C-Editor, add the tag(s) that should cause this script to re-fire. For visibility logic, trigger on the source Signal tag with cycle 250 ms or on a 1-second standard cycle.
6. Compile and assign. Confirm there are no errors in the output pane. WinCC V7.x will report C1010 "compiler aborted" if apdefap.h is missing; the resolution is to add the WinCC include path under Options > Settings > C-Editor > Include Paths.
7. Runtime check. Start Runtime (RT) and toggle the source Signal tag. The ON-state graphics should appear and the OFF-state should hide, with both transitions completing within one RT cycle (typically 250 ms).

Verification and Debugging

When the C-Action does not behave as expected, work through the following matrix before assuming a logic bug.

For deep debugging, add a temporary printf redirection through the WinCC logging system. WinCC V7.x routes printf output to the WinCC Diagnosis window when the project is started with the Diagnostic option enabled. In TIA Portal, use LCIDebugTrace() if available, or write a temporary log line into an internal text tag and display it on a diagnostics screen.

Edge Cases and Field-Proven Caveats

• Boolean width. C's BOOL in WinCC is a 32-bit integer typedef. Truth tables above used 0/1 notation, but the actual value in memory is 0 or 1, not a single bit. Use the value in integer comparisons if you ever cast to int.
• Property change events are level-triggered, not edge-triggered. If a downstream consumer of Result watches for a transition, set @On_Vis directly from a tag trigger instead of from this C-Action, because assigning the same value twice in a row does not produce a change event.
• Multi-user editing. When two engineers open the same picture in Graphics Designer, the second saver wins and the C-Action they did not modify is overwritten verbatim. The C-Action is stored as a separate .pdl_action record, not as part of the picture body, so diffs are not shown in the standard merge tool. Use WinCC's Project Differencer to compare C-Actions across project branches.
• Trigger cycle vs RT cycle. The script fires on the configured trigger (default 1 s). The picture is redrawn on the RT cycle (default 250 ms). The two are decoupled: it is possible to set @On_Vis faster than the picture redraws, but the user will not see the change. The default values are already chosen to keep CPU load below 20 % on a TIA Runtime PC with a 4-core CPU and 8 GB of RAM.
• Unicode property names. If the project is migrated to WinCC V7.5 with Unicode project names enabled, property names are stored in UTF-16 and the char* pointer in OnPropertyChanged is the ANSI representation. Custom property names should remain ASCII for the lifetime of the project to avoid migration risk.
• Return semantics in void OnPropertyChanged. Some script templates show a return at the end; this is legal in C but unnecessary for a void function. The WinCC C compiler emits warning C4715 "not all control paths return a value" only for non-void functions.

Frequently Asked Questions