How to Dynamically Read and Display Multilingual Text Library Entries in WinCC Runtime

To dynamically display text entries from the SIMATIC Manager or WinCC Text Library on a process graphic screen based on an error code or status index, engineers can utilize WinCC C-scripting, ODK functions, or SQL queries against the local project database. While WinCC Alarm Logging natively supports the format @3W%t#TextLibName@ for messages, displaying long descriptions (> 16 characters) in static text or combobox controls requires reading the localized string dynamically. The approved implementation utilizes the WinCC C-function TXTLIB_GetText(TextID, LanguageID) or an internal SCL/C-script lookup array that correlates the active runtime language (GetLanguage()) with the numerical code to populate screen text objects cleanly.

The Architecture of Text Libraries in PCS 7 and WinCC

In SIMATIC PCS 7, multi-language internationalization is supported through centralized Text Libraries:

STEP 7 Text Library (SIMATIC Manager): Managed via Options -> Manage Multilingual Texts. Stores block comments, unit descriptions, and user text libraries referenced by AS message instructions.
WinCC Text Library (WinCC Explorer): Stores all operator station static texts, alarm message texts, picture titles, and user dictionary entries in a multilingual relational table within the WinCC SQL Server database (<Project_Name>.mdf).

During OS compilation, user text libraries defined in SIMATIC Manager are mapped and transferred into the WinCC Text Library, assigning a unique 32-bit TextID to each string entry for each supported language (e.g., German 1031, English 1033).

The Message Text Formatting Syntax (@3W%t#TextLib@)

In WinCC Alarm Logging, Siemens provides a native token parser for alarm descriptions:
@<P>W%t#<TextLibName>@

Where:
* <P> is the process value parameter index (e.g., 3 corresponds to PDevVal3).
* W indicates word formatting.
* %t# instructs the alarm engine to look up the value in user text library <TextLibName>.

When an alarm triggers with process value 15, Alarm Logging retrieves entry 15 from <TextLibName> in the current runtime language and displays the description. However, this native token replacement engine is built exclusively into the alarm control and does not automatically extend to standard Graphics Designer static text controls.

Dynamic Screen Retrieval via C-Script and TXTLIB APIs

To display a Text Library entry within a standard process graphic (e.g., a static text box or multiline text control):

Method 1: Using the WinCC Open Development Kit (ODK) API

WinCC exports internal text distributor functions in txtlib.dll:

#include "apdefap.h"
#pragma code ("txtlib.dll")
char* TXTLIB_GetText(DWORD dwTextID, DWORD dwLanguageID);
#pragma code ()

void OnChange(char* lpszPictureName, char* lpszObjectName, long lErrorNo) {
    DWORD dwLangID = GetLanguage(); // Fetches active runtime LCID
    DWORD dwTextID = (DWORD)lErrorNo; // Mapped Text ID
    char* pszText = TXTLIB_GetText(dwTextID, dwLangID);

    if (pszText != NULL) {
        SetPropChar(lpszPictureName, "StaticText_ErrorDesc", "Text", pszText);
    }
}

Method 2: Querying the Local SQL Database via ADO

An alternative VBScript action executes a local SQL query against table TextLib:

Dim conn, rs, strSQL, langID, textID
langID = HMIRuntime.Language
textID = HMIRuntime.Tags("Drive_Fault_Code").Read
Set conn = CreateObject("ADODB.Connection")
conn.Open "Provider=WinCCOLEDBProvider.1;Catalog=" & HMIRuntime.Tags("@DatasourceNameRT").Read
strSQL = "SELECT TextString FROM TextLib WHERE TextID=" & textID & " AND Lcid=" & langID
Set rs = conn.Execute(strSQL)
If Not rs.EOF Then
    ScreenItems("TextBox1").Text = rs("TextString")
End If

The Drive ES Faceplate Pattern: Modular Multi-Language Functions

When developing high-speed, standard faceplates (such as the Siemens Drive ES library for inverters), Siemens engineers avoid dynamic SQL overhead by implementing modular C-functions:

Structured Script Sets: For each supported language, a project function is created (e.g., GetFaultText_ENU.fct, GetFaultText_DEU.fct).
Switch/Case Evaluation:
c char* GetFaultText_ENU(int faultCode) { switch(faultCode) { case 7801: return "Motor overcurrent trip"; case 7900: return "Motor overtemperature warning"; default: return "Unknown drive fault"; } }
Language Dispatcher: A top-level dispatcher reads the active system language (GetLanguage()) and calls the corresponding language function. This delivers instantaneous screen refresh with zero database locks.

Text Library Display Methods and API Reference Matrix

The following table compares the implementation approaches for displaying text library entries on WinCC screens:

MethodPerformanceLanguage SwitchingComplexityBest Suited ForAlarm Token (@3W%t#...)InstantaneousAutomaticLowWinCC Alarm Logging controls onlyTXTLIB_GetText APIHigh (Direct DLL call)Automatic (via LCID)MediumDynamic text boxes, faceplatesADO SQL Database QueryModerate (DB query)Query-drivenMediumLarge external text catalogsDrive ES C-Script ArrayUltra-Fast (RAM)Script-directedLowFixed equipment fault/warning descriptions

Selecting script-based RAM lookup avoids database latency during operator screen navigation.

Verification

To verify dynamic text display:
1. Open the WinCC process picture in Graphics Designer and configure the text display action.
2. In WinCC Runtime, force the fault code tag to a known integer (e.g., 7801).
3. Verify that the static text control immediately displays the corresponding detailed description.
4. Switch the runtime language in WinCC from English to German; confirm that the displayed text updates dynamically to the translated German text.
5. In WinCC_Sys_01.log, confirm that no C-script execution or AP_ERROR exceptions are registered.

Limitations and Operational Precautions

Do not execute heavy SQL queries on fast cyclic triggers (e.g., 250 ms); trigger text retrieval strictly upon tag value change.
Ensure all text IDs exist in the WinCC Text Library for all project languages to avoid displaying blank text fields.
Text Library strings must be exported and imported using the WinCC Text Distributor tool during project translation phases.
Always validate final license quantities, module availability, and MLFBs against the applicable Siemens catalog and authorized distributor quotation.

Engineer FAQ

Why can't I use standard WinCC Text Lists (Enumerations)?

Standard WinCC Text Lists and APL enumerations have character length limitations (typically 16 to 24 characters). Detailed fault troubleshooting descriptions require full multi-sentence text strings.

Where is the WinCC Text Library stored?

The Text Library is stored inside the WinCC SQL Server database (<Project_Name>.mdf) in internal relational tables TextLib and TextDistributor.

How do I export all Text Library texts for external translation?

In WinCC Explorer, open Text Distributor, select Text Library, choose the export file format (CSV/TXT), and export all languages for editing in Microsoft Excel.