Querying Plant Hierarchy and Picture Windows via Split Screen Manager C-Scripts in WinCC

To dynamically determine picture names and navigate hierarchical levels in SIMATIC PCS 7 WinCC using ANSI-C scripts, use the Split Screen Manager (SSM) API functions declared in apdefap.h and SSMAPI.h. Functions such as SSMGetContainerToPicture, SSMGetContainer, and SSMGetContPict query the runtime Picture Tree database table dbo.TM_Hierarchie. When calling SSMGetContainerToPicture, always allocate a character buffer and pass its maximum length via the len parameter to prevent memory faults. To determine the parent picture window hosting the current display, execute GetParentPictureWindow(lpszPictureName), and resize the window dynamically using SetPropDouble.

Picture Tree Manager Database Architecture and SSM Functions

In SIMATIC PCS 7 Operator Stations (WinCC with Basic Process Control), the technological Plant Hierarchy (TH) configured on the Engineering Station is mapped into the WinCC Picture Tree Manager during OS compilation. The resulting runtime hierarchy is stored in the local SQL Server database table dbo.TM_Hierarchie within the WinCC project database (<ProjectName>RT.mdf).

The dbo.TM_Hierarchie table contains five structural columns:

Ord: An integer representing the sequential display index.
ContainerID: A unique identifier linked to the text library containing the container's language-dependent name.
Bildname: The physical name of the graphic screen (*.pdl) assigned to the hierarchy container.
Vater: The ContainerID of the parent container one level up in the hierarchy.
LinkerBruder: The ContainerID of the sibling container immediately to the left on the same level.

Rather than executing direct SQL SELECT statements within high-speed graphic scripts, Siemens provides the Split Screen Manager (SSM) library to query these relationships cached in memory.

SSM Function Call Signatures and Buffer Safety

A frequent cause of runtime script crashes and WinCC application freezes is improper buffer allocation when calling SSM string extraction functions. The function prototypes require pre-allocated character arrays:

// C-Script function prototype
BOOL SSMGetContainerToPicture(char* lpszPicture, char* lpszContainer, int len);

The parameter len specifies the maximum number of characters that the function is permitted to write into the lpszContainer buffer. If an uninitialized pointer (such as char* ReturnName; without malloc or array declaration) is passed, or if len is set to zero or an unallocated size, the script engine writes into undefined memory, crashing the WinCC script host (script.exe).

The safe implementation requires declaring a fixed stack buffer:

char szContainer[256];
BOOL bSuccess = SSMGetContainerToPicture("WE_FS1_01.Pdl", szContainer, sizeof(szContainer));
if (bSuccess) {
    // szContainer now holds the valid container name
}

Traversing Plant Hierarchy and Sizing Picture Windows in C

To navigate from a parent plant picture (e.g. Filter 1) to a subordinate parameter screen located in a lower-level container (e.g. FS1_01_PARA), combine Picture Tree queries with standard WinCC window management functions:

Identify Parent Context: Use char* szWindow = GetParentPictureWindow(lpszPictureName); to identify the specific picture window hosting the invoking screen.
Determine Host Screen: Use char* szParentPic = GetParentPicture(lpszPictureName); to retrieve the container screen name.
Open Subordinate View: Call SSMOpenTopField(SSMGetScreen(lpszPictureName), szParameterPicture); to display the lower-level screen within the working area.
Dynamic Geometry Sizing: If the subordinate picture has different pixel dimensions, adjust the container picture window properties using SetPropDouble(szParentPic, szWindow, "Width", dTargetWidth); and SetPropDouble(szParentPic, szWindow, "Height", dTargetHeight); or set the window's Adapt Picture (Anpassen) property to TRUE.

Split Screen Manager Function Reference and Return Types

The following table summarizes essential SSM hierarchy navigation functions and their operational parameters:

Function NameReturn TypeKey ArgumentsPurpose / DescriptionSSMGetContainerToPictureBOOLchar* lpszPicture, char* lpszContainer, int lenRetrieves container name containing the specified PDL fileSSMGetContainerIDToPictureDWORDchar* lpszPictureReturns the numeric ContainerID of the picture's containerSSMGetContainerBOOLint area_no, int subarea_no, char* lpszContainerReturns container name for a specific numeric area/subarea coordinateSSMGetContPictBOOLint area_no, int subarea_no, char* lpszPictureReturns the PDL picture name assigned to the given area/subarea coordinateSSMOpenTopFieldBOOLint screen_no, char* lpszPictureOpens the target PDL in the primary working area of the specified monitorGetParentPictureWindowchar*char* lpszPictureNameReturns the object name of the picture window hosting the calling screenGetParentPicturechar*char* lpszPictureNameReturns the full picture name path of the parent window

[!NOTE]
Commercial Accuracy Notice: Split Screen Manager (SSM) functions are built-in components of the SIMATIC PCS 7 Basic Process > Control runtime package (6ES7658-2CX58-0YH5). Utilizing custom C-scripts for Picture Tree navigation consumes no extra > runtime tags, Process Objects, or software add-on licenses.

Verification

Verify custom SSM script execution in WinCC Runtime:

Diagnostics Window Output: Add printf statements in the script and monitor the WinCC APDiag (Output Window). Confirm that container names and picture paths evaluate to non-null strings without buffer overflow exceptions.
Dynamic Screen Navigation: Click the invoking graphic element in runtime. Confirm that the target subordinate screen opens reliably in the assigned split-screen monitor partition.
Picture Window Geometry: Verify that picture windows resize correctly to fit subordinate graphic layouts without scrollbar distortion or truncated controls.

Limitations and Operational Precautions

Observe these precautions when scripting with SSM functions:

Buffer Overrun Hazards: Never pass unallocated pointers to SSMGetContainerToPicture. Always pass a defined array with sizeof(buffer) to prevent memory corruption.
Multilingual Containers: Container names displayed to operators are language-dependent. If your script compares container strings, perform comparisons against static internal tokens or ContainerID integers rather than translated strings.
OS Compilation Overwrites: OS Compile updates the dbo.TM_Hierarchie table. Never manually alter this database table via SQL management studio; always manage hierarchy in the PCS 7 Plant Hierarchy editor.

Engineer FAQ

What header file must be included to use SSM functions in WinCC C-scripts?

Include #include "apdefap.h" at the beginning of the script. apdefap.h automatically includes the Split Screen Manager headers (including SSMAPI.h) and declares standard PCS 7 OS API signatures.

What does the 'len' parameter represent in SSMGetContainerToPicture?

The len parameter specifies the maximum buffer size (in bytes) of the receiving string buffer. It prevents the function from writing past the end of the memory allocated for the container name.

Why does script.exe crash when I execute my SSM navigation script?

The most common cause is passing an unallocated pointer (e.g. char* ReturnName;) into SSMGetContainerToPicture without allocating memory. Declare char ReturnName[256]; on the stack before invoking the function.

Can I determine the screen number dynamically in a multi-monitor client?

Yes. Use int screen_no = SSMGetScreen(lpszPictureName); to retrieve the integer ID (1 to 4) of the monitor currently displaying the invoking picture.