WinCC Picture Window: Extract Local Picture Name in I/O Field

WinCC Picture Window: Extract the Local Picture Name into an I/O Field

In Siemens WinCC V7 (Classic) and TIA Portal WinCC Runtime Advanced/Professional, picture windows are the standard mechanism for embedding a reusable process screen inside a parent mimic. The runtime hands every C and VBS action attached to a picture a fully qualified picture name parameter, lpszPictureName, which encodes the entire container hierarchy. A field engineer who simply writes that string back to an I/O field gets MainMimic.pdl:PW_Main:PictureTypicals1 rather than the readable PictureTypicals1 the operator actually sees. This reference documents three production-tested techniques for stripping the parent mimic and picture window name away, the events on which each technique must be bound, the buffer-safety rules for ANSI-C, and the differences between WinCC V7 and TIA Portal WinCC Professional scripting models.

1. Overview: The Picture Window Naming Hierarchy

A picture window is a graphics object whose Picture Name property references a compiled .pdl file (WinCC V7) or a screen from the project tree (TIA Portal). When the runtime resolves the dynamic display, it builds a colon-delimited path that records the call chain of picture windows used to reach the currently rendered picture. The format is:

<ParentPictureName>:<PictureWindowObjectName>:<LocalPictureName>

For a project structure where the main mimic MainMimic.pdl hosts a picture window named PW_Main which in turn displays PictureTypicals1.pdl, the runtime hands scripts the string:

MainMimic.pdl:PW_Main:PictureTypicals1.pdl

If a third picture window PW_Sub is embedded inside PictureTypicals1 and is currently showing PictureDetailA.pdl, the string passed to scripts inside PictureDetailA is:

MainMimic.pdl:PW_Main:PictureTypicals1.pdl:PW_Sub:PictureDetailA.pdl

The : separator is fixed and contains no spaces. This is important when implementing manual string parsing. The runtime will never return a path with a trailing or leading colon, but it will return the full path even if a picture window is invisible, deactivated, or layered behind another object.

2. Prerequisites

Before implementing any of the three methods, confirm the following in the engineering station:

• WinCC V7.4 SP1 or later (V7.5 SP2 recommended for current support). TIA Portal V16 or later for VBS-only projects.
• Graphics Designer licensed and the target picture compiled successfully (red/yellow dots in the project tree must be absent).
• If using ANSI-C methods: the C editor is enabled in the project properties (default on) and the WinCC Global Script Runtime is installed and started on the RT target.
• The internal tag used to display the picture name must be of type Text tag 8-bit character set (WinCC V7) or WString (TIA Portal), with a length of at least 30 characters to accommodate .pdl extensions and nested names.
• Knowledge of which picture event should host the script: Open Picture is the canonical trigger; Picture In / Picture Out events can be used when nested picture windows are involved.

3. How lpszPictureName Is Composed

The lpszPictureName pointer passed to ANSI-C actions and the equivalent PictureName property in VBS always reference a runtime-internal, read-only buffer. You must copy its contents into your own buffer before the action returns; the pointer is invalid once the script exits. The full grammar is:

lpszPictureName := picture { ':' picture_window ':' picture }

Where picture is the file name without directory and picture_window is the configured object name in the Graphics Designer. The runtime never returns a leading colon, never an empty segment, and always uses lowercase extensions on case-insensitive file systems. The first segment is always the top-level mimic that is loaded by the screen window manager, not necessarily the process picture the operator sees on the monitor.

This composition means a parser that walks the string from the right looking for the last : is more robust than one that walks from the left: picture window object names can contain underscores and digits but cannot contain :, so the last colon is always the separator between the deepest picture window and the picture that fills it.

4. Method 1: GetLocalPicture() in ANSI-C

The WinCC Scripting System Manual documents GetLocalPicture() as the canonical way to recover the local picture name from a fully qualified string. The function signature is:

char* GetLocalPicture(const char* lpszPictureName);

It returns a pointer to an internal static buffer that holds the local picture name (the segment after the last colon). Because the buffer is reused on subsequent calls, the caller must copy the string before the next call to any WinCC API function that returns a string. The buffer is at least _MAX_PATH (260) bytes long on Windows, so copying up to that length is safe.

Recommended action script bound to the Open Picture event of any picture that may be displayed inside a picture window:

// WinCC V7 ANSI-C - Return only the local picture name
#include <string.h>
#include <stdlib.h>

char* pszPicName = NULL;
char  szPicName[_MAX_PATH + 1];

// Step 1: ask the runtime to resolve the local segment
pszPicName = GetLocalPicture(lpszPictureName);

// Step 2: defensively copy into a caller-owned buffer
if (pszPicName != NULL)
{
    strncpy(szPicName, pszPicName, _MAX_PATH);
    szPicName[_MAX_PATH] = '\0';   // guarantee null-termination
}
else
{
    strcpy(szPicName, "UNKNOWN");
}

// Step 3: return the local picture name to the calling property
return szPicName;

Bind this script as the Output Value of the I/O field that should display the name. WinCC calls the action every cycle that the picture is open; the runtime cost is negligible because the API function is implemented in the same process and reads a pre-parsed slot.

5. Method 2: Manual String Parsing in ANSI-C

When GetLocalPicture() is not available (older WinCC versions, restricted scripting mode, or projects that compile against a custom C runtime), the local picture name can be recovered by walking the string and locating the final colon. The corrected C implementation, avoiding the off-by-one and array-bound pitfalls of the original example circulated in the community, is:

// WinCC V7 ANSI-C - Manual parse of lpszPictureName
#include <string.h>

char  m[_MAX_PATH + 1];
char* p       = NULL;
int   iLen    = 0;
int   iLast   = -1;
int   i       = 0;

if (lpszPictureName == NULL)
{
    strcpy(m, "");
    return m;
}

iLen = (int)strlen(lpszPictureName);

// Walk left to right, remembering the index of the last colon
for (i = 0; i < iLen; ++i)
{
    if (lpszPictureName[i] == ':')
        iLast = i;
}

// No colon found: the whole string is the local picture name
if (iLast < 0)
{
    strncpy(m, lpszPictureName, _MAX_PATH);
    m[_MAX_PATH] = '\0';
}
else
{
    // Copy one character past the last colon up to the terminator
    p = (char*)&lpszPictureName[iLast + 1];
    strncpy(m, p, _MAX_PATH);
    m[_MAX_PATH] = '\0';
}

return m;

This method has the advantage of zero dependence on internal WinCC API behaviour and produces byte-identical results to GetLocalPicture() on every release from WinCC V6.2 onward. The performance is dominated by a single strlen call (O(n) over a typically short string) and is therefore in the microsecond range on a modern HMI IPC.

If the engineer prefers a one-liner using the C standard library and accepts a temporary heap allocation, the equivalent is:

// Locate the local segment with strrchr and copy it
char* pSep = strrchr(lpszPictureName, ':');
if (pSep != NULL)
    SetTagChar("PictureName_Tag", pSep + 1);

Bind this to the Open Picture event of the screen if the I/O field is on the parent picture and reads the local name of whatever the picture window displays.

6. Method 3: Parent.PictureName in VBS

In VBS-based projects, both WinCC V7 and TIA Portal WinCC, every picture window exposes the picture it currently displays through the Parent.PictureName property. From inside a script located in a child picture, Parent refers to the picture window that hosts it. From a script in the parent mimic, the same expression evaluated against a specific picture window object name returns that object's current picture name. The complete, drop-in action for a TIA Portal WinCC VBS action bound to the Open Picture event is:

' TIA Portal / WinCC V7 VBS - write the local picture name into a tag
Dim sLocalName
sLocalName = Parent.PictureName

' Optional: strip the .pdl extension for a cleaner display
If Right(sLocalName, 4) = ".pdl" Then
    sLocalName = Left(sLocalName, Len(sLocalName) - 4)
End If

SmartTags("PictureName_Tag") = sLocalName

For projects where the I/O field sits in the parent mimic and must display the name of the picture window's current contents, use the qualified object path:

' Reference the picture window by its configured object name
Dim sLocalName
sLocalName = Parent.GetObject("PW_Main").PictureName

If Right(sLocalName, 4) = ".pdl" Then
    sLocalName = Left(sLocalName, Len(sLocalName) - 4)
End If

SmartTags("PictureName_Tag") = sLocalName

Parent.PictureName returns the configured picture name as it appears in the Graphics Designer, including the file extension. The strip-extension block is optional but recommended for operator-facing screens because the extension has no diagnostic value and can confuse operators who navigate the mimic by name.

7. Method Comparison

8. Implementing in WinCC V7 (Classic) Step-by-Step

1. Open the Graphics Designer and navigate to the picture that should display the local name (typically the parent mimic that contains the picture window).
2. Insert an I/O field from the Smart Objects palette. Configure:
   • Output/Input: Output
   • Tag: Select or create a Text tag 8-bit set, e.g. PictureName_Tag, length 64.
   • Field type: String
   • Update: On change (default) or cyclic 1 s if the picture window may switch pictures without an Open Picture event firing on the parent.
3. Open the WinCC Explorer and select Global Script → C-Editor. Create a new action named e.g. actGetLocalPictureName.
4. Paste the Method 1 or Method 2 source above. Confirm the function signature is void* actGetLocalPictureName(char* lpszPictureName) — the return type must match the I/O field output value type (text).
5. Compile with F7. Resolve any warnings; a missing #include <string.h> shows up as an implicit declaration of strncpy.
6. Return to the Graphics Designer, right-click the I/O field, choose Properties → Output/Input → Output Value, and select the new action. Pass the standard parameter lpszPictureName — Graphics Designer exposes this as the "Picture name" parameter in the action selection dialog.
7. Bind the same action (or a separate VBS action if Method 3 is preferred) to the picture window's Picture In event if the local name must update when the picture window switches pictures without a parent redraw.
8. Save the project, regenerate the server (right-click the server name in WinCC Explorer → Generate Server Data), and activate Runtime.

9. Implementing in TIA Portal WinCC Step-by-Step

1. In the TIA Portal project tree, expand HMI tags and create a tag PictureName_Tag of data type WString with length 64.
2. Open the parent screen in the HMI screen editor. Insert an I/O field and bind it to PictureName_Tag; configure the field as Output, String, mode Output only.
3. Open the Events configuration of the screen and select the Loaded event (corresponds to WinCC V7's Open Picture).
4. Add a VBS function with the body from Method 3 above. Use the qualified object path if the I/O field sits in the parent and the picture window is the only one in the screen; use bare Parent.PictureName if the I/O field is itself inside the picture window's contents.
5. Compile the HMI station (Compile → Software (rebuild all)). Resolve any VBS errors reported in the output window; the most common is a typo in the picture window object name.
6. Download to the target panel or PC runtime. Simulate with the TIA Portal simulator to verify the tag updates within one cycle of the Loaded event.

10. Verification and Field Testing

After implementation, run the following acceptance checks before sign-off:

1. Static case: Start the parent mimic with the picture window showing PictureTypicals1.pdl. The I/O field must read exactly PictureTypicals1 (or PictureTypicals1.pdl if the strip-extension block was omitted).
2. Dynamic switch: Trigger a button that changes the picture window's Picture Name property to a different process screen, e.g. PictureTypicals2.pdl. The I/O field must update within one cycle (250 ms default, 100 ms with the fast cycle option enabled).
3. Nested case: From the parent, open a picture inside PictureTypicals1 that itself hosts a picture window. The action inside the deepest picture must return only that picture's file name, not the parent's.
4. Null safety: Force lpszPictureName = NULL in a test script and confirm the I/O field shows UNKNOWN (Method 1) or empty (Method 2 with the if NULL branch), not a memory access violation.
5. Buffer upper bound: Create a picture window with a configured object name of 240 characters and a picture file name of 254 characters. The Method 1 buffer of 261 bytes must still null-terminate correctly. The Method 2 strncpy with explicit terminator handles this case; verify in the runtime diagnostic view that no 0xC0000005 access violation is logged in the WinCC diagnostic file WinCC_Sys_<date>.log.
6. Cycle load: With ten picture windows in the active screen, confirm in the WinCC performance monitor that the additional action calls add no more than 2 % CPU on a typical IPC227G-class target.

11. Troubleshooting Matrix

12. Edge Cases and Production Considerations

Multilingual projects. Picture file names in WinCC are language-independent; PictureTypicals1.pdl is the same name in every language. If the I/O field is meant to show a translated screen title, the picture name must be mapped through a text list and the result written to the I/O field. The lookup is typically performed in the same action that resolves the local name, by switching on the current runtime language obtained from GetLanguage() in ANSI-C or HMIRuntime.Language in VBS.

Redundant server pairs. On a WinCC Redundancy pair, the picture name action runs on the preferred server; after a failover, the standby takes over and the action re-binds automatically. The I/O field may briefly display the value from the previous picture for one to three seconds while the new server recompiles the screen; this is normal and does not indicate a script bug. To suppress the flash, set the tag's initial value to the empty string in the project and bind the I/O field update to the Loaded event with a 100 ms cycle.

Nested picture windows of depth greater than 2. A depth of three or more is unusual but legal. The runtime returns the full colon-delimited path; the last segment is always the deepest picture. Methods 1, 2, and 3 all return the deepest segment, which is what operators expect.

WebNavigator and Unified clients. VBS actions run server-side. The client receives the rendered output and the I/O field text, but the script itself never executes on the client. When upgrading a project to TIA Portal Unified, the VBS body from Method 3 must be ported to JavaScript and the SmartTags() accessor replaced with Tags(); the conceptual structure is identical.

Audit and operator-action logging. Some plants log which process screen the operator was viewing at the time of an alarm or command. The picture name action can be paired with an alarm-acknowledgement or command-triggered action to record the local picture name into a string archive tag, which provides a forensic trail during incident review.

Security and the engineering workstation. ANSI-C actions in WinCC V7 can call any function exposed in the scripting API, including file I/O and registry access. A picture-name extraction action does not need these, and best practice is to keep the action body limited to string.h functions to minimize the attack surface if the project is later deployed in a process network.

13. Performance Notes

The extraction itself is a few hundred nanoseconds. The dominant cost is the WinCC action dispatch (script lookup, parameter marshalling, and the I/O field tag write) which is on the order of 50 µs per call on a modern HMI IPC. A 1 Hz update on 20 picture windows therefore consumes roughly 0.1 % of a single CPU core and is invisible in normal load. Avoid binding the action to a 100 ms cycle unless the picture window switches pictures several times per second; the default Open Picture event trigger is sufficient for the vast majority of operator-screen use cases.

For very large projects (several hundred picture windows in a single screen, common in steel and power), consider hoisting the extraction into a single project-wide global action and using tag multiplexing to reduce script dispatch overhead. This is rarely necessary but eliminates measurable CPU load on the oldest IPC227 hardware that some plants still operate.

14. References to Siemens Documentation

For the authoritative description of GetLocalPicture, the lpszPictureName parameter, and the picture window object model, consult the following Siemens manuals available on the Siemens Industry Online Support portal:

• SIMATIC WinCC V7.5 SP2 — Scripting: VBS, ANSI-C, VBA (WinCC Scripting System Manual), sections on picture object model and string functions.
• SIMATIC WinCC V7.5 SP2 — WinCC Information System, graphics designer reference for picture window properties.
• SIMATIC TIA Portal WinCC Professional — Programming and Operating Manual, VBScript reference for HMIRuntime and picture objects.

Search the Siemens support portal at support.industry.siemens.com with the document titles above to obtain the latest revision for the installed WinCC version.

FAQ