Dynamically Binding Tags to WinCC I/O Fields via Script

Overview: The Runtime Tag Binding Problem

Operators in many WinCC screens need to inspect or modify the value of an arbitrary process tag whose identity is decided at runtime - commonly driven by a listbox, combobox, or selection tree of parameter names. The naive approach of writing a value through SetOutputValue only pushes the current value once; the I/O Field does not track subsequent tag changes, and the operator cannot edit the live tag value through the field.

The correct solution is to create a tag connection (a dynamic link) between the I/O Field's OutputValue (WinCC V7) or ProcessValue (WinCC Unified) property and the chosen process tag. In WinCC this is exposed as a script-callable API:

• WinCC V7 (Classic) C-Editor: SetLink / GetLink functions.
• WinCC V7 VBS Editor: Direct write to the screen-item property via the HMIRuntime / ScreenItems object model.
• WinCC Unified V20 (TIA Portal): Tag dynamization through ProcessValue.SetTagName(...) and configuration-side tag binding under Properties → General → Process value.

This document walks through each environment with verified function signatures, complete code, update-cycle handling, and field-proven commissioning checks.

Architecture: How an I/O Field Tag Link Works

An I/O Field is a normal screen object with three relevant properties:

A link is the runtime container that binds the property to (a) a tag name, (b) an acquisition/refresh cycle, and (c) the data type interpretation. Once a link exists, the visualization reflects the tag value every cycle, and operator edits are written back through the same link - identical behavior to a statically-configured link.

Environment Prerequisites

Verify the C-Editor and VBS-Editor are activated under Project → Properties → Options. On WinCC Unified, scripting must be enabled under Runtime settings → Scripting.

WinCC V7 C-Script: SetLink and GetLink

The C-Editor exposes two internal C functions that mutate and inspect an object-property tag link. Both are documented in the WinCC V7 Help under Internal Functions → Graphics → Link.

Function signatures

BOOL SetLink(  LPCTSTR lpszPictureName,
                LPCTSTR lpszObjectName,
                LPCTSTR lpszPropertyName,
                LPCTSTR lpszTagName);

DWORD GetLink( LPCTSTR lpszPictureName,
                LPCTSTR lpszObjectName,
                LPCTSTR lpszPropertyName,
                DWORD   dwSize,
                LPTSTR  lpszVariable,
                LPDWORD lpdwResult);

Complete C example - listbox-driven parameter selection

/* OnClick event handler of a listbox that triggers a re-link */
void OnClick(char* lpszPictureName, char* lpszObjectName)
{
    BOOL bRet;
    char szSelText[256] = "";

    /* Retrieve the currently selected text item from the listbox */
    bRet = GetText(lpszPictureName, "ListBox1", "Text", 256, szSelText);
    if (bRet == FALSE) { printf("GetText failed: %s\r\n", GetLastError()); return; }

    /* Bind the I/O Field's OutputValue to the chosen tag */
    bRet = SetLink(lpszPictureName, "IOField_Param", "OutputValue", szSelText);
    if (bRet == FALSE) { printf("SetLink failed: %s\r\n", GetLastError()); return; }

    /* Confirmation - read back the link state */
    DWORD dwResult = 0;
    char  szLinkedTag[256] = "";
    GetLink(lpszPictureName, "IOField_Param", "OutputValue", 256, szLinkedTag, &dwResult);
    printf("Link=%s state=%lu\r\n", szLinkedTag, dwResult);
}

The I/O Field immediately begins displaying the new tag and refreshes on every acquisition cycle of the tag's configured cycle (see section Update Cycle Management).

Update Cycle Management

Both screen-object links and tags carry an update cycle. Without configuring the cycle, the runtime falls back to the picture's standard cycle (default 1 s).

Available update cycles

Setting the cycle programmatically

The C-Editor cycle API includes:

/* Set cycle of an existing tag link on a screen-object property */
bRet = SetLink(lpszPictureName, "IOField_Param", "OutputValue", "MyTagName", "500 ms");

/* Where supported (WinCC 7.5+), pass cycle name as 5th argument. If unsupported,
   the cycle is inherited from the tag's configured acquisition cycle in the
   tag manager. */

When changing cycles at runtime the script must re-issue SetLink; the cycle parameter is part of the link descriptor and is not edited in place.

WinCC V7 VBScript: Direct Property Assignment

The VBS script equivalent avoids SetLink/GetLink because the VBS object model permits direct write to the OutputValue property with a tag-name string. The runtime implicitly calls the underlying link creation routines.

Complete VBS example

' OnClick of the parameter listbox
Sub OnClick(ByVal Item, ByVal value)
    Dim szTagName
    szTagName = ""

    ' Read selected text from the listbox
    Dim lb
    Set lb = ScreenItems("ListBox1")
    szTagName = lb.Text

    ' Validate non-empty
    If Len(szTagName) = 0 Then
        ShowSystemAlarm("No parameter selected")
        Exit Sub
    End If

    ' Bind I/O Field
    Dim iof
    Set iof = ScreenItems("IOField_Param")
    iof.OutputValue = szTagName        ' dynamic link created automatically
End Sub

Reading back the link in VBS

Dim iof, szLinked, bLink
Set iof = ScreenItems("IOField_Param")
szLinked = iof.OutputValue         ' returns the linked tag name string
bLink    = iof.IsLinked("OutputValue")   ' True / False

VBS offers no direct handle on the update cycle; the field inherits the tag's configured cycle. The standard cycle of the picture object can be edited via Properties → Misc → Update Cycle before the tag is linked.

WinCC Unified V20 (TIA Portal): Configuration-Based Binding

WinCC Unified uses the ProcessValue property of I/O Field-like screen objects. Static binding through TIA Portal is the documented primary path; the official V20 example walks the inspector procedure:

1. Select the I/O Field on the canvas.
2. In the Inspector window, expand Properties → General → Process value.
3. In the Dynamization column, click the empty stub next to the value field.
4. Select the entry Tag from the dropdown list.
5. Pick an HMI tag from the tag selector.

The full official procedure is documented at Example: Configuring an IO field (RT Unified) - TIA Portal V20.

Configuration parameters visible in Inspector

WinCC Unified V20 Scripting: ProcessValue Mutators

Unified provides object handles via Screen.Items and item-typed mutators on ProcessValue. The runtime supports both JavaScript (ES2017) and VB.

JavaScript example (RT script action triggered by parameter listbox onClick)

// Exports function "OnSelectParameter" linked via event-mapping
import { Screen } from 'M_HMI/RT/Classes';

export function OnSelectParameter(selectedName) {
    if (!selectedName || typeof selectedName !== 'string') {
        import('M_HMI/RT/Functions').then(F => F.ShowSystemAlarm("No parameter selected"));
        return;
    }
    const iof = Screen.Items.Element("IOField_Param");
    if (iof === null) { throw new Error("I/O Field not found"); }

    // Property assignments on Unified invoke the dynamization engine.
    iof.ProcessValue.Tag = selectedName;
    iof.ProcessValue.Cycle = '500 ms';   // optional cycle override
    iof.ProcessValueMode = 1;            // 1 = tag binding
}

VB example

Public Sub OnSelectParameter(sTag As String)
    If Len(sTag) = 0 Then
        ShowSystemAlarm("No parameter selected")
        Exit Sub
    End If

    Dim iof = Screen.Items.Element("IOField_Param")
    If iof Is Nothing Then Throw New System.Exception("I/O Field not found")

    iof.ProcessValue.Tag = sTag
    iof.ProcessValue.Cycle = "500 ms"
End Sub

Reading back the link

// JavaScript
const iof = Screen.Items.Element("IOField_Param");
const linkName   = iof.ProcessValue.Tag;
const linkCycle  = iof.ProcessValue.Cycle;
const linkState  = iof.ProcessValueMode;   // 0 constant, 1 tag, 2 script

Pattern: RT Parameter Listbox + I/O Field (Step-by-Step Procedure)

This procedure builds a complete runtime-switchable parameter viewer using the V7 C-Editor; the VBS and Unified equivalents share the same event flow.

1. Configure the I/O Field. In Graphics Designer drop a Bar IO Field named IOField_Param. Under Properties → Output, set Data format to decimal or hex as required; cycle is initially 1 s.
2. Configure the parameter listbox. Drop a List Box named ListBox1. Populate Selection entries with the tag names the operator may choose, for example Motor1_Speed, Motor1_Torque, Tank_Level.
3. Bind listbox events. Select the listbox, open Properties → Events → Selection changed, set action to C Action and open the script editor.
4. Paste the C script from the section WinCC V7 C-Script above. Compile with F7.
5. Tag-side setup. In Tag Manager confirm each candidate tag has an Acquisition cycle matching the desired refresh (250 ms for active control loops, 1-2 s for diagnostic values).
6. Compile the picture (Right-click the picture → Compile) and download to the RT-PC.
7. Activate Runtime and verify by selecting different parameters; the IO Field must show their values and accept operator entries that immediately write back.

Common Errors and Diagnostics Matrix

Verification Procedure

1. Open Graphics Designer in simulated Runtime (Tools → Runtime Simulator).
2. Switch each listbox entry; visually confirm the IO Field value updates within one cycle.
3. Edit the IO Field and confirm the underlying PLC tag updates by triggering a read in TIA Online / S7-PCT / PLC browse.
4. Log the link state with a debug printf / ShowSystemAlarm on the first frame to confirm the link, then disable logs.
5. Cycle test: change the parameter choice rapidly (1 s cadence) and confirm no exception dialogs in WinCC_SysLog.
6. Final validation: power-cycle the RT-PC; on reboot, the IO Field should restore its last linked tag (Unified: persist via ProcessValueMode tag, V7: configure persistent RT storage for the parameter name).

Security, Performance, and Best Practices

• Validate any tag name supplied by an operator or external file. SetLink with an arbitrary string is a method for unauthenticated tag access; in safety-related screens, restrict the candidate list to a hard-coded array and reject strings not in the array.
• Avoid OnClick spam. Put a 250 ms debounce on the parameter change event to prevent the link engine from re-binding on every selection click.
• Group multiple links into one script - re-linking all ten I/O Fields on screen to switch from "View Alarms" mode to "View Diagnostics" mode is more efficient in one C action than ten event handlers.
• Watch CPU. Each high-frequency cycle tag costs IO. If the operator's selection changes a high-rate tag, the picture cycle should be raised or the high-rate tag should be assigned a different cycle after link.
• Centralize tag-name maps. Maintain a mapping table of display-string to internal tag name in C/VBS or in a script-side dictionary; never concatenate raw screen objects. Raw concatenation enables injection ("MyTag;ERP_CONNECTION").