How to Read WinCC PictureWindow TagPrefix from C and VBScript

Overview

A Siemens WinCC Picture Window is a reusable faceplate-like container that hosts its own picture plus a configurable TagPrefix. The TagPrefix is the runtime prefix the runtime prepends to every tag configured on the I/O fields placed inside the window, which is what lets one picture display dozens of instance data blocks (e.g. S7$Program/A10T/2., S7$Program/A10T/3., ...) without duplicating screens.

The runtime exposes the TagPrefix value as a property on the Picture Window object. The standard problem field engineers run into is: "I am inside an I/O field event (C or VBS) and need to read which TagPrefix my parent Picture Window is currently using so I can build a fully-qualified tag name." Both classic WinCC (WinCC v7.x with WinCC Explorer / Graphics Designer) and the modern TIA Portal WinCC (WinCC Comfort, WinCC Advanced, WinCC Professional, and the Unified panels) expose this property, but the API to read it differs.

This guide shows both API surfaces:

• C script (ANSI-C, classic WinCC v7.x) using GetParentPictureWindow, GetParentPicture, and GetPropChar.
• VBScript (WinCC v7.x and VBS object model in TIA Portal RT Advanced / RT Professional) using the Parent chain or the direct TagPrefix property.

Prerequisites

Before you wire up a TagPrefix read, confirm the following:

1. Runtime / engineering environment
   • Classic WinCC v7.3 SP3 or later (the VBS object model is mature here), or
   • TIA Portal V16 or later with WinCC Comfort / Advanced / Professional, or a Comfort Panel / Unified Panel running RT Advanced / RT Professional.
2. Project configuration
   • Graphics Designer project compiled and downloaded to the runtime.
   • Picture Window object placed on a base picture, with a valid Picture Name and a non-empty TagPrefix.
   • I/O fields inside the referenced picture configured to use the TagPrefix implicitly (the TagPrefix is what makes the magic work; do not hard-code tags).
3. Scripting permissions
   • For classic WinCC v7.x: enable Global Script Runtime under Computer → Properties → Graphics Runtime.
   • For TIA Portal WinCC: enable Script runtime on the HMI device and confirm the user class allows script execution.
4. Compiler / runtime side-by-side DLLs: For C script, ensure the WinCC apdef.h (function declarations) and the runtime DLLs (PDLrtApi.dll and friends) are linked correctly. A C script that compiles cleanly in the editor but loses the API at runtime usually means missing runtime rights.

WinCC PictureWindow Runtime Object Model

PictureWindows are nested objects. To read TagPrefix from inside a child object you must navigate the hierarchy. The conceptual layout is:

ScreenItem (I/O field, button, ...)
  ↑ Parent (ScreenItem)
PictureWindow (HmiScreenWindow / PDL PictureWindow)
  ↑ Parent (Base Picture)
  ↑ Parent (Screen)

Properties you can read at each level:

The Parent count varies with object depth. In the screen tree shown above, an I/O field is one ScreenItem, its Parent is the PictureWindow, and the PictureWindow's Parent is the base picture. A common field mistake is stopping one level short and reading the picture name instead of the TagPrefix string.

Solution 1 — Classic WinCC C Script

Classic WinCC exposes the API as ANSI-C functions declared in apdef.h. The recommended call chain inside an event on a child I/O field is:

1. Resolve the parent picture name with GetParentPicture.
2. Resolve the parent PictureWindow name with GetParentPictureWindow.
3. Read the TagPrefix string property with GetPropChar.

#include "apdefap.h"

void OnClick(char* lpszPictureName, char* lpszObjectName)
{
    /* 1. Parent picture (base picture that hosts the PictureWindow) */
    char* szParentPic = GetParentPicture(lpszPictureName, lpszObjectName);

    /* 2. PictureWindow object name on that picture */
    char* szPicWin    = GetParentPictureWindow(lpszPictureName, lpszObjectName);

    /* 3. Read the TagPrefix property as ANSI string */
    char* szTagPrefix = GetPropChar(szParentPic, szPicWin, "TagPrefix");

    /* Optional: also read the picture name held inside the window */
    char* szInnerPic  = GetPropChar(szParentPic, szPicWin, "PictureName");

    /* Use the prefix to compose a fully qualified tag */
    char szTag[MAX_DLG_TEXT_LEN + 1];
    sprintf(szTag, "%sField01", szTagPrefix);

    /* Set tag example */
    SetTagChar(szTag, "OK");

    /* Debug trace */
    printf("[TagPrefix] pic=%s win=%s prefix=%s\r\n",
           szParentPic, szPicWin, szTagPrefix);
}

The three function prototypes you need are:

char*  GetParentPicture       (const char* pszPicture, const char* pszObject);
char*  GetParentPictureWindow (const char* pszPicture, const char* pszObject);
char*  GetPropChar            (const char* pszPicture, const char* pszObject, const char* pszPropertyName);

Property names are case-sensitive on the wire. The full set of read-only string properties of a PictureWindow includes TagPrefix, PictureName, WindowType, and the geometry-related numerics (Left, Top, Width, Height) which you fetch with GetPropWord or GetPropDouble.

Solution 2 — VBScript (WinCC v7.x and TIA Portal)

VBScript is the modern runtime scripting path on every Siemens HMI from WinCC v7.0 onward and is the only runtime scripting surface on Unified Panels. The traversal is one-liner once you understand the tree depth.

Variant A — explicit Parent chain (works on WinCC v7.3)

Dim p, pp
Set p  = ScreenItems(1)   ' first ScreenItem on this picture (e.g. an I/O field)
Set pp = p.Parent.Parent ' ↑ Parent: PictureWindow   ↑ Parent: Base Picture
                         '             TagPrefix lives one level ABOVE the I/O field,
                         '             so if your I/O field is one level inside the
                         '             PictureWindow, the TagPrefix is on p.Parent.

MsgBox pp.TagPrefix      ' base picture name (no TagPrefix at this level)
' ↓ Correct level for the TagPrefix:
MsgBox p.Parent.TagPrefix

A frequent typo in the field is reading pp.TagPrefix on the base picture and getting an empty string or a runtime error, because the TagPrefix is on the PictureWindow, not on the picture it sits in.

Variant B — one-line direct read

MsgBox Parent.TagPrefix

Inside an event handler on an I/O field, the implicit Parent resolves to the PictureWindow when the I/O field is hosted by one. This is the cleanest form and matches the same object model documented for TIA Portal RT Advanced / RT Professional.

Variant C — fully qualified traversal for deeper trees

If the I/O field is itself wrapped in a User Control or a sub-PictureWindow, count the parents:

Dim oIof, oPicWin
Set oIof    = HmiRuntime.Screens("Main").ScreenItems("WinA").ScreenItems("Iof_01")
Set oPicWin = oIof.Parent          ' or .Parent.Parent.Parent depending on depth

Dim sPrefix : sPrefix = oPicWin.TagPrefix
Dim sTag    : sTag    = sPrefix & "Field01"
HmiRuntime.Tags(sTag).Write "OK"

Step-by-Step Procedure

1. Open Graphics Designer (WinCC v7.x) or the HMI screen editor (TIA Portal) and place a PictureWindow on a base picture, e.g. Main.pdl.
2. Configure the PictureWindow properties:
   • Picture Name = the picture containing the I/O field group (e.g. IconAna.pdl).
   • TagPrefix = the runtime prefix you want to bind to this instance, e.g. S7$Program/A10T/2..
3. Open the child picture (IconAna.pdl), place a group of I/O fields, and leave their tag fields empty so they inherit the prefix at runtime.
4. Attach the event handler on the I/O field (right-click → Properties → Events → Click → C-action or VBS-action).
5. Paste the script from Solution 1 or Solution 2.
6. Compile the C script (the editor must report 0 errors, 0 warnings); VBS scripts are interpreted at runtime and require no compile step.
7. Activate the runtime and click the I/O field.
8. Inspect the trace: in the WinCC v7.x Diagnostics window (diag.rc) you should see the line printed by the C script; in TIA Portal enable Trace on the panel and observe the MsgBox.

Returning the TagPrefix as a Usable String

The TagPrefix typically ends with a dot (e.g. S7$Program/A10T/2.). Concatenation patterns depend on whether your tags are bit, byte, word, or struct-typed:

Two field-proven pitfalls:

• If the prefix already contains a trailing dot, do not append another dot before the struct member, otherwise you get S7$Program/A10T/2..Status.Running which the tag parser rejects.
• If the prefix is empty (PictureWindow was placed without a TagPrefix), GetPropChar returns an empty string. Treat empty as a hard error in your script and log it; do not silently concatenate.

Verification

Use this quick acceptance test after the wiring:

1. Place two PictureWindows on the same base picture, configured with TagPrefix S7$Program/A10T/2. and S7$Program/A10T/3. respectively.
2. Use the same child picture in both windows.
3. Attach the click event in the child to dump the TagPrefix.
4. Click inside each PictureWindow and confirm the returned prefix differs.
5. Cross-check the returned string against the value shown in Properties → TagPrefix in the editor.

If the prefixes match what you configured in the editor, the API binding is correct. The full returned string for the example in the original question would be S7$Program/A10T/2..

Troubleshooting Matrix

Edge Cases and Compatibility Notes

• Nested PictureWindows. If the I/O field is inside two PictureWindows (window inside window), add one more Parent hop per nesting level.
• User-defined faceplates on TIA Portal. On TIA Portal V17+, the faceplate container exposes the TagPrefix as the Interface tag of the faceplate instance, not as a PictureWindow property. The C-script API does not apply here — read fp.TagPrefix via VBS on the faceplate root.
• Unicode vs ANSI. GetPropChar is ANSI. For Unicode TagPrefixes (Asian languages, Cyrillic), use GetPropText in TIA Portal V17+ or set the project locale to ANSI.
• WinCC v7.3 specifically. The traversal pattern ScreenItems(1).Parent.Parent was confirmed working on WinCC v7.3 SP3. Earlier service packs (SP1, SP2) are not officially covered by the same VBS object model and require the C API path.
• Thread safety. Both APIs run on the graphics thread. Do not call GetPropChar from a timer or a background thread; always read inside the event of an object on the same picture tree.
• Performance. Calling GetPropChar per click is cheap (<1 ms). Avoid polling it in a 100 ms loop — cache the prefix on a project tag if you need it globally, since the prefix rarely changes after a project is downloaded.

Reference: Official Documentation

• TagPrefix property — TIA Portal V20 VBS reference
• Siemens Industry Online Support (manual downloads, KB articles, firmware notes)