Reading MsgFilterSQL String from WinCC Alarm Control in TIA

Overview of the MsgFilterSQL Property

The MsgFilterSQL property on the WinCC Alarm Control defines a SQL-style WHERE clause that limits the alarm records displayed in the alarm view at runtime. In WinCC Runtime Professional (RT Professional), the property is exposed through the Alarm Control's runtime object model and accepts a subset of SQL that maps to the underlying alarm logging tables. The TIA Portal help system documents the syntax as "SQL Statements for Filtering the Alarm View" and lists each available filter column, its type, and an example statement (SQL Statements for Filtering the Alarm View, RT Professional).

When an engineer configures an Alarm Control in the TIA Portal editor, the engineering tool generates an internal default filter based on the visible columns, alarm classes, areas, sort order, and selection rules. The active filter string at runtime may differ from the engineering default for three reasons:

• Application code reassigns MsgFilterSQL dynamically through a VB Script or C# action.
• The operator interacts with the column headers or filter row in the alarm view and the control appends ad-hoc predicates.
• A selection-based filter is layered on top of the base filter through the Selection property or the MsgFilterSQL follow-up filter.

Identifying the exact string that is currently applied is a recurring task during commissioning, regression testing, and alarm-log auditing. The remainder of this article documents the procedure that survives every TIA Portal version from V14 through V21.

Problem: DefaultMsgFilterSQL No Longer Exposed in WinCC Professional V14

Siemens Knowledge Base entry 109482844 (5668269) - How to use the "MsgFilterSQL" property of the WinCC Alarm Control historically described a static-property path: Object Properties > Control Properties > DefaultMsgFilterSQL > Static tab. Engineers porting HMI projects from WinCC flexible 2008, WinCC V13, or earlier WinCC V13 SP1 builds to WinCC Professional V14 cannot locate the Static tab in the TIA Portal Inspector.

The root cause is an Inspector reorganization that landed with WinCC Professional V14. The control-property node was renamed, promoted to a runtime-only accessor, and is no longer surfaced as a configurable static value. TIA Portal V15, V15.1, V16, V17, V18, V19, V20, and V21 keep the same accessor-only model. The active filter must therefore be read from the runtime object through a script.

Prerequisites

• TIA Portal V14 SP1 or later with WinCC Professional option package installed.
• WinCC Runtime Professional (RT Professional) license or a WinCC ES simulation runtime on the engineering station.
• A configured WinCC Alarm Control placed on an HMI screen, bound to a valid alarm source (AS symbols, Alarm_8P tags, or logged tags).
• VB Script runtime enabled: Runtime Settings > Scripts > VB > Enable VB scripts.
• User rights sufficient to trigger the script on the operator panel; the technique works in both RT simulation and on a physical Comfort Panel / IPC runtime.

Step-by-Step: Reading the Active Filter via VB Script

1. Open the HMI screen that contains the Alarm Control in the TIA Portal editor.
2. Identify the exact name of the Alarm Control object. The default is Control1; renamed controls are visible in the Properties > General > Name field.
3. From the toolbox, drag a Button onto the same screen and rename it to btnReadFilter for clarity.
4. Right-click the button, select Properties > Events > Click, and create a new VB Script action.
5. Paste the canonical read-and-display script:

   Sub OnClick(ByVal item)
       Dim sFilter
       sFilter = ScreenItems("Control1").MsgFilterSQL
       MsgBox sFilter
   End Sub
   

6. Replace Control1 with the actual name of the Alarm Control if it differs from the default.
7. Compile the HMI project (Project tree > HMI device > Compile > Software (rebuild all)).
8. Start the WinCC Runtime Simulation from the toolbar (or transfer the project to the target device).
9. Click the button. A MsgBox appears with the SQL string that the Alarm Control is currently applying.

Enhanced Script: Logging the Filter for Diagnostics

For commissioning, the filter string is often needed headless (no operator available to dismiss a MsgBox). The script below writes the active filter to both an internal tag and a text file so it can be reviewed after the fact:

Sub OnClick(ByVal item)
    Dim sFilter, oFS, oTS

    sFilter = ScreenItems("Control1").MsgFilterSQL

    ' Mirror to an HMI tag for in-panel display
    SmartTags("FilterString") = sFilter

    ' Append to a log file with a timestamp
    Set oFS = CreateObject("Scripting.FileSystemObject")
    Set oTS = oFS.OpenTextFile("C:\Temp\FilterSQL.log", 8, True) ' 8 = ForAppending
    oTS.WriteLine Now & " | " & sFilter
    oTS.Close

    Set oTS = Nothing
    Set oFS = Nothing
End Sub

Declare the FilterString tag in the HMI tag table as a WSTRING with a length of at least 1000 characters; the runtime filter statement routinely reaches 400-600 characters when multiple column filters are active.

On a Comfort Panel that lacks a writable C:\Temp folder, swap the path for the panel's Storage Card location, e.g. \Storage Card\SIMATIC\FilterSQL.log, and ensure the user "Operator" has write permission to the path.

MsgFilterSQL SQL Syntax Reference (RT Professional)

The MsgFilterSQL parser in RT Professional accepts a SQL SELECT fragment over the internal alarm-log virtual table. The TIA Portal V21 reference pages document the following top-level elements (SQL Statements for Filtering the Alarm View):

Supported Columns, Data Types, and Operators

The filter columns map to alarm-log table columns. The TIA Portal help lists the canonical column identifiers; the table below summarizes the operators that the parser accepts for each column type. String comparisons follow the Microsoft Jet/DASL wildcard conventions (Filtering Items Using a String Comparison - Microsoft Learn): % substitutes for any sequence of characters, _ for a single character.

Common Filter Examples

-- Only unacknowledged alarms raised in the last hour
SELECT * FROM ALOG
WHERE State IN (1, 2)
  AND TimeStamp >= DATEADD(hour, -1, GETDATE())

-- High-priority alarms from a specific area, capped at 500 rows
SELECT TOP 500 * FROM ALOG
WHERE Priority >= 12
  AND Area = 'Plant/Line3'

-- Wildcard match on source symbol
SELECT * FROM ALOG
WHERE Source LIKE 'DB100.DBX%'

-- Time-window filter with explicit ISO-8601 timestamps
SELECT * FROM ALOG
WHERE TimeStamp BETWEEN '2025-01-01T00:00:00' AND '2025-01-31T23:59:59'

These statements can be assigned directly to ScreenItems("Control1").MsgFilterSQL at runtime through VB Script or C# to swap the active filter without re-compiling the project.

Alternative Methods to Inspect the Active Filter

When VB Script execution is disabled (regulated environments) or the runtime is headless (WinCC Operator Station in service mode), three additional methods can be used to surface the active filter:

• CSV export from the Alarm Control: the on-screen toolbar exposes an Export to CSV action. The exported file contains a header line that lists the resolved filter at export time. Inspect ExportOptions.Filter in the editor to pre-configure.
• WinCC OLE DB provider: query the underlying alarm-log table directly through the WinCC OLE DB provider and correlate the row count against the alarm view to verify the filter is effective.
• Project XML inspection: the compiled HMI project contains the configured default filter under the Alarm Control node. This shows the engineering default, not the runtime override, so it is only a starting point.

Supported Platforms and Version Matrix

Troubleshooting Matrix

Verification and Runtime Acceptance Test

1. Configure an Alarm Control with the engineering default filter; do not modify any property.
2. Place the btnReadFilter button on the same screen and load the read-and-display script.
3. Compile the project and start RT simulation.
4. Click the button. Confirm the MsgBox displays a non-empty SELECT ... FROM ALOG ... statement.
5. Add a second action that assigns a known string, e.g. SELECT * FROM ALOG WHERE Priority >= 12, to ScreenItems("Control1").MsgFilterSQL.
6. Click the button again. Confirm the MsgBox now displays the new filter.
7. Reset the alarm view and verify the row count changes as expected when the priority filter is applied.
8. Document the engineering default and any runtime overrides in the project's Functional Specification.

Frequently Asked Questions