Resolving Empty APL Faceplate Tag Reads with GetPropChar in PCS 7

When attempting to read dynamic process tags or block attributes inside an Advanced Process Library (APL) faceplate using GetPropChar in SIMATIC PCS 7, the function returns an empty string because the faceplate container picture (@PG_[blocktype].pdl) operates as an asynchronous passthrough frame where tag connections are not yet initialized when the container script executes. In APL architecture, relative tags (e.g., .SelFp1#Jump) are expanded into full process tag names asynchronously during faceplate opening by APL_OpenFaceplate. To read attributes reliably, access properties from sub-view pictures (@PG_[blocktype]_Standard.pdl) after initialization, or pass properties through the @Faceplate dataset using standard APL scripting conventions.

APL Faceplate Multi-Window Architecture

The SIMATIC PCS 7 Advanced Process Library (APL) utilizes a modular, hierarchical graphic architecture for faceplates. Rather than creating a single monolithic window, an APL faceplate consists of several layered picture components:

@PG_[blocktype].pdl: The master container frame. It manages window geometry, title bars, pin/unpin buttons, faceplate views (Standard, Limits, Trend, Parameter), and global datasets (@Faceplate).
@PG_[blocktype]_Standard.pdl (and sub-views): The content pictures loaded into embedded picture windows inside the container.
@PG_[blocktype]_Overview.pdl: The upper toolbar managing alarm state, mode selection, and operational badges.

When engineers attempt to customize faceplates by adding custom C-scripts or VBScripts to read automation tags, executing scripts in the wrong container level leads to timing race conditions and blank property returns.

Why GetPropChar Returns Empty Strings in Container Pictures

The classic WinCC function pszTag = GetPropChar(lpszPictureName, lpszObjectName, "BinText2"); queries the static property cache of a graphic object. When applied to custom attributes in @PG_[blocktype].pdl, it fails for two specific reasons:

Asynchronous Tag Binding: When APL_OpenFaceplate launches, it instantiates the container picture first and binds the active process tag asynchronously. During the initial picture generation event, dynamic tag links have not completed their handshake with the WinCC Data Manager (CCDataServer.exe). Consequently, querying the property returns an empty string.
Static vs Dynamic Property Evaluation: GetPropChar reads the static configuration string unless dynamic tag evaluation has resolved. In the forum case, filling in text in the 'Static' property returned a value, proving that the dynamic tag connection was never resolved at that hierarchy level.

Relative Tag Resolution and Asynchronous Faceplate Opening

In APL block icons and faceplates, tags are parameterized with a leading dot (e.g., .SelFp1#Jump, .SelFp1#OS_Text).

Prefix Expansion: When the faceplate opens, the APL runtime engine strips the leading dot and prepends the full plant hierarchy path of the block instance (e.g., converting .SelFp1#Jump to Plant/Area/Unit/Valve.SelFp1#Jump).
Dataset Storage: The master container @PG_[blocktype].pdl does not execute field calculations; it stores resolved references in internal dataset structures (@Faceplate, ObjCollection, BlockIconCollection). Custom scripts must read from these collections rather than intercepting raw container properties.

Comparison of APL Faceplate Scripting Execution Contexts

The table below contrasts script execution locations across the APL faceplate hierarchy.

Script Execution ContextPicture FileTag Availability at LoadRecommended Use CaseMaster Frame Initializer@PG_[blocktype].pdlUnresolved (Empty string)Window sizing, dataset setup, view registrationSub-View Picture Load@PG_[blocktype]_Standard.pdlResolved & ActiveReading process values, button states, limitsFaceplate Button ClickButton in Standard viewFully ResolvedExecuting operator actions, jumping to user faceplatesCustom Global ScriptProject C-Script / VBS ModuleContext-dependentReusable technological math or navigation functionsBlock Icon Collection@Faceplate/BlockIconCollectionPre-initialized from block iconPassing custom parameters from block icon to faceplate

Step-by-Step Procedure to Implement Custom Faceplate Attributes

Follow this procedure to reliably pass and read custom tags in APL faceplates:

Add Custom Attribute to Block Icon:
- In the block icon template (@PCS7Typicals_Custom.pdl), add a user-defined attribute (e.g., UserTag) to the block icon group.
- Connect UserTag to the desired relative tag (e.g., .SelFp1#Jump).
Pass Attribute During Faceplate Open:
- In the script that opens the faceplate (APL_OpenFaceplate), copy the value of UserTag into the @Faceplate dataset property collection on the master frame picture.
Read Property in Sub-View Picture (Standard.pdl):
- Open @PG_[blocktype]_Standard.pdl in Graphics Designer.
- In the button or display object, place the script on an event that fires after initialization (e.g., Open Picture event of the sub-view or a button Click event).
- Use the standardized APL function to retrieve the property from the parent dataset:
c char* pszTag = GetPropChar("..", "@Faceplate", "UserTag");
- Alternatively, read the full tag value directly using GetTagChar(pszTag).
Compile and Test Runtime:
- Save all modified PDL files in the project GraCS directory.
- Test in WinCC Runtime: verify that printf output displays the resolved tag name.

Verification

Verify custom faceplate tag reading through the following diagnostic steps:
1. Insert a diagnostic trace statement in the C-script: printf("Custom Tag Name: %s\r\n", pszTag);.
2. Open the WinCC apdiag.exe Output Window on the OS station.
3. Click the block icon to open the APL faceplate: verify that apdiag prints the fully resolved tag name (e.g., Area1/SubArea/Valve1.SelFp1#Jump) rather than an empty string.
4. Click the custom faceplate button: confirm that the secondary faceplate or navigation window opens smoothly.

Limitations and Operational Precautions

Never modify standard Siemens APL faceplates directly in C:\Program Files (x86)\Siemens\WinCC\Options\PDL\.... Always copy the target @PG_*.pdl into your local project GraCS directory before customizing. Direct modifications to installation templates will be overwritten during PCS 7 library updates or Service Pack installations. Furthermore, keep custom C-scripts non-blocking; lengthy synchronous database queries in faceplate scripts freeze the WinCC user interface thread.

Engineer FAQ

Why did the script work on an APL button but fail on the container object?

Buttons evaluate their scripts inside the sub-picture (Standard.pdl) upon user interaction after all tags and datasets are fully bound. Scripts in @PG_*.pdl execute prematurely during initial frame generation before tag binding completes.

What does the leading dot '.' represent in APL tag properties?

The leading dot signifies a relative tag reference. During runtime faceplate generation, the APL engine automatically substitutes the dot with the full technological tag hierarchy prefix of the calling block.

Can I use VBScript instead of ANSI-C in APL faceplates?

Yes, VBScript can be used. However, APL core architecture is written in ANSI-C; utilizing standard APL C-functions ensures maximum performance and compatibility with Siemens script libraries.