WinCC C Scripting: SetTagBit and GetTagBit for Button Control

Overview

Siemens WinCC exposes the full runtime HMI API to ANSI-C, VBScript, and (in WinCC Professional) VBA. For a beginner the most common requirement is simple: a button on a picture toggles a tag, an I/O field shows the resulting state, and the tag can be routed onward to the PLC. The C-language entry point for this is the pair of functions SetTagBit() and GetTagBit(), both declared in the project header apdefap.h and dispatched automatically by the WinCC Graphics Runtime when an event fires.

This reference consolidates the correct procedure for a first WinCC C project: declaring the internal tag, attaching a C action to a button's OnClick event, reading the tag back into an I/O field, and verifying behaviour in Runtime. It also covers the start sequence in WinCC Runtime Professional, common compile-time mistakes, and the cross-reference between classic WinCC V7.x and the TIA Portal WinCC Professional editors.

Prerequisites

Why the First Script Fails

A typical first attempt looks like the snippet below, copied from the original forum exchange:

#include "apdefap.h"
void OnClick(char* lpszPictureName, char* lpszObjectName, char* lpszPropertyName)
{
    int start;
    start = 1;
}

Three things are wrong with this code from the perspective of the WinCC C runtime:

1. Local variable, not a tag. The integer start lives on the C stack and is destroyed when OnClick returns. WinCC tags are stored in the tag image and only the API functions move values in or out of them.
2. No apdefap.h semantics needed for the function body, but the header is still required so that the project-specific macro expansions and the standard tag-function prototypes are visible to the compiler.
3. Wrong prototype. When the C action is attached to a mouse event such as OnClick, the function must match the signature void OnClick(char*, char*, char*). The signature above is correct, but the developer must not declare a local int that shadows the tag name — it confuses the reader and produces a no-op at runtime.

The correct primitive for writing a boolean tag from a C action is SetTagBit(); the matching read primitive is GetTagBit(). Both are members of the standard WinCC ANSI-C tag API described in the Siemens scripting manual.

Internal Tag Configuration

Before any C code runs, declare a tag in the WinCC Tag Management. For a stand-alone, PLC-free exercise, the tag is an internal tag — its value is held in WinCC memory and not exchanged with any controller.

1. Open the WinCC Explorer (WinCC V7) or the TIA Portal project tree (WinCC Professional).
2. Expand HMI Tags and open the default tag table (WinCC V7: Internal Tags; TIA Portal: Default tag table of the HMI device).
3. Add a new tag with the following parameters:

   Parameter	Value
   Name	start
   Data type	BOOL
   Connection	Internal tag (no PLC connection)
   Update cycle	1 s (sufficient for the exercise; tighten to 100 ms only if needed)
   Initial value	0

4. Compile and save the tag table.

C Script Anatomy: apdefap.h and the Action Signature

Every C action generated by the Graphics Designer is wrapped in a project-specific header called apdefap.h. The header lives in the project's library directory (\<project>\library\apdefap.h in WinCC V7; \<project>\<HMI>\Sources\apdefap.h in TIA Portal) and is regenerated on every compile. The header aggregates:

• The tag-function prototypes (SetTagBit, GetTagBit, SetTagByte, GetTagWord, SetTagFloat, GetTagDouble, …).
• Project-global constants declared in the Project Properties.
• User-defined function prototypes from the project function library.

For a mouse-event action, the function signature is fixed by the Graphics Designer. The three parameters are the picture name, the object name, and the property name; they are passed by the runtime and can be used for context (for example to log which button was clicked). A minimal, idiomatic OnClick body is:

#include "apdefap.h"
void OnClick(char* lpszPictureName, char* lpszObjectName, char* lpszPropertyName)
{
    /* lpszPictureName, lpszObjectName, lpszPropertyName are supplied by WinCC */
    SetTagBit("start", (BOOL)1);
}

SetTagBit and GetTagBit — the Boolean API

Step-by-Step: Button → Internal Tag → I/O Field

The exercise has three deliverables: a button that sets the internal tag, an I/O field that displays the tag, and verification in Runtime.

Step 1 — Place the graphics objects

1. In the Graphics Designer, open a process picture (or create a new one, e.g. NewPdl0.PDL).
2. From the Standard palette, drag a Button onto the picture. Set its label to Start.
3. Drag an I/O Field next to the button. Set its type to Output (read-only) for visualisation, or Input/Output if you want to write from the HMI as well.

Step 2 — Bind the I/O field to the tag

1. Select the I/O field and open Properties → Output/Input → Output Value (or Process → Tag in WinCC Professional).
2. Assign the tag start.
3. For the field format, select Binary or Decimal. Decimal is recommended for the first build because binary displays are zero-padded and can confuse a beginner.

Step 3 — Configure the button's C action

1. Select the button. In the property list, scroll to Events → Mouse → Click.
2. Right-click the action icon and choose C action…. The C editor opens with a stub body.
3. Replace the body with the canonical write snippet:

#include "apdefap.h"
void OnClick(char* lpszPictureName, char* lpszObjectName, char* lpszPropertyName)
{
    SetTagBit("start", 1);
}

4. Compile the action with OK. The Graphics Designer prompts to attach the action — confirm.

Step 4 — Read the tag back from another action (optional)

The I/O field already polls the tag each cycle, so a separate read is not strictly required. To prove that GetTagBit() works, attach a second C action to the button's Mouse → Press event:

#include "apdefap.h"
void OnPress(char* lpszPictureName, char* lpszObjectName, char* lpszPropertyName)
{
    BOOL val;
    val = GetTagBit("start");
    /* val now holds the current value of the internal tag */
    /* for diagnostic output write it to another internal tag or trigger a log */
    SetTagBit("int_dbg_lastRead", val);
}

This second snippet also documents the correct usage of GetTagBit in a member function context: declare a BOOL, call the function with the tag name as a string literal, and consume the return value.

Event Types and Property Cross-Reference

Not every interaction is a click. WinCC exposes a hierarchy of event hooks, each with its own C signature. The ones most often used in first projects are listed below.

Start Sequence and Runtime Activation (WinCC Runtime Professional)

For WinCC Runtime Professional, the C action and the internal tag are useless until the runtime is actually running and the picture is loaded. The Start sequence on the HMI device controls which WinCC applications launch when the project is activated. The official TIA Portal V20 documentation describes the setting as follows:

Select "Start sequence of WinCC Runtime" to specify the applications that will be started on activation of a project. "Graphics in Runtime" is always started automatically.

Source: Setting up the start sequence (RT Professional) — TIA Portal V20.

For this tutorial, ensure that the following applications are ticked in the start sequence:

• Graphics in Runtime — required (cannot be disabled).
• Tag Management Runtime — required for the internal tag to be loaded.
• Global Script Runtime — required for the C action to be executed.

If the project is started on the engineering station via the TIA Portal Start Runtime button, these components are launched by default. When the project is deployed to a target device, verify the start sequence on the target's Runtime settings page, otherwise the C action will not fire even though the picture loads.

Cross-Platform Notes: WinCC V7.x vs WinCC Professional (TIA Portal)

The C API has not changed materially between the two product lines, so a snippet written for WinCC V7 compiles and runs in TIA Portal WinCC Professional and vice versa. The only practical difference is the deployment path: TIA Portal stores screens in a different container but compiles to the same runtime format on the target.

Common Errors and How to Read Them

The GSC Runtime window (WinCC V7) and the diagnostics pane (TIA Portal WinCC Professional) are the only reliable places to see these messages. Open them via the Tools → Diagnostics menu or by holding Ctrl+Shift+F5 in the running picture.

Verification Checklist

1. Open the project in the TIA Portal or WinCC Explorer, compile the project, and start Runtime.
2. Confirm the picture loads with the button and the I/O field visible.
3. Click the button. The I/O field's value must change from 0 to 1 within the configured update cycle.
4. Open Tag Management Runtime (WinCC V7) or the HMI Tag Diagnostics view (TIA Portal) and confirm the value of start is 1 after the click.
5. Click the button again. If the C action is a setter (not a toggler), the value will remain 1 until another action clears it — add a Reset button with SetTagBit("start", 0); to complete the loop.
6. Close and re-open the picture. The tag should retain its last value because the runtime keeps internal tags across picture changes; if the picture is part of a different process, internal tag state is lost only when the runtime stops.

From Internal Tag to a Real Output

The original question's intent was to "start a light." With an internal tag the exercise is decoupled from the PLC. To drive a real output:

1. Add a second tag, e.g. PLC_Start_Light, with the appropriate connection (S7-1500, S7-1200, OPC UA, etc.) and the correct DB / output address.
2. Wire an internal tag-to-tag connection in the tag management, or use a direct connection from the button's tag to the PLC address. The simplest path is to make the C action write the PLC tag directly:

#include "apdefap.h"
void OnClick(char* lpszPictureName, char* lpszObjectName, char* lpszPropertyName)
{
    /* write the internal tag for HMI display */
    SetTagBit("start", 1);
    /* write the PLC tag to drive the output */
    SetTagBit("PLC_Start_Light", 1);
}

3. Rebuild and re-download. Confirm the output on the controller side using the TIA Portal online view or a watch table on the S7 CPU.

Further Project Patterns

Once the basic toggle works, the same primitives scale to common industrial patterns:

• Edge detection (rising edge). Read the previous value with GetTagBit(), compare to the new state, and fire the side effect only on the transition from 0 to 1.
• Toggle (latching). Use SetTagBit("start", !GetTagBit("start")); in the OnClick event for a single-button start/stop pattern.
• Interlock. Check one or more GetTagBit() values (e.g. int_Permissive, int_Stop) before writing the start tag; if the interlock is open, write to a diagnostic tag and skip the start.
• Confirmation dialog. Use the WinCC function MsgBox in VBScript for a confirm step, or call the C equivalent via a project function. The C language does not provide a native modal dialog; route confirmations through VBS or through a popup picture.

All four patterns fit on a single OnClick action body and require no additional runtime components beyond the start sequence defined earlier.