Configuring MsgFilterSQL in WinCC AlarmControl to Filter Alarms

Overview

The MsgFilterSQL property of the WinCC AlarmControl accepts a subset of SQL that targets the message archive columns rather than user-defined tables. It lets you limit which rows the control displays by message number (MSGNR), class (Type), priority, state, and several other internal fields exposed by the alarm logging database. The companion property DefaultMsgFilterSQL is evaluated at runtime startup and is the correct location for a static filter; MsgFilterSQL itself is typically dynamized via a tag, a script, or a direct connection so that the filter can change while the screen is active.

The most common field-referenced confusion is the difference between user-defined message columns (such as a custom NR field you may have added to a project-specific database) and the system column MSGNR that the alarm logging service writes for every event. MsgFilterSQL queries the internal alarm view, so NR (or any user column) is not visible to it. Use MSGNR for the configured alarm number on the HMI/PLC side, and reserve NR for SQL queries against your own ODBC archive or reporting database.

Prerequisites

• TIA Portal V16 or later with WinCC Comfort/Advanced or WinCC Professional. The syntax documented here has been verified on TIA Portal V17, V18, and V21 with WinCC Runtime Advanced and WinCC RT Professional.
• An HMI device configured with an AlarmControl on at least one screen. The screen must be reachable from the start screen so the filter can be validated.
• Configured discrete alarms or analog alarms with known message numbers. MSGNR matches the ID assigned in the alarm class configuration (HMI alarms) or the MSG_LOCK/MSG_ACK/MSG_NA numbers used by PLC-side alarm instructions (e.g. S7-1500 Program_Alarm).
• For dynamic filtering: an internal tag of the appropriate data type (typically WString or String) bound to the MsgFilterSQL property, or a VBScript function that rewrites the property on event.
• Optional but recommended: the official Siemens support entry "How to use the MsgFilterSQL property of the WinCC Alarm Control" (SIOS entry 5668269) as a desk reference.

Column Reference for MsgFilterSQL

The following columns are exposed to the internal SQL parser of the AlarmControl. Only the listed columns should be used; user tables and user fields are not reachable from this property.

Supported SQL Operators

WinCC AlarmControl implements a limited SQL dialect. The supported operators are:

• Comparison: =, <>, <, <=, >, >=
• Logical: AND, OR, NOT
• Set: IN ( value, value, ... ), BETWEEN value AND value
• Null: IS NULL, IS NOT NULL
• Wildcard on string columns: LIKE 'pattern' using % for any string and _ for any single character

Functions such as SUBSTRING, DATEADD, CAST, and sub-selects are not supported by the MsgFilterSQL parser. For arithmetic on dates, format your comparison with the literal that WinCC writes into the archive.

Syntax: DefaultMsgFilterSQL vs MsgFilterSQL

Both properties accept the same expression text. The difference is lifecycle:

If you set both, MsgFilterSQL takes precedence at runtime. The control does not concatenate them; it uses whichever property is currently non-empty. To stack conditions, write a complete WHERE-style expression in a single property.

Filter by Alarm ID: Working Examples

Single alarm number

Show only alarm number 17:

Multiple alarm numbers using AND/OR

Showing only alarm 17 OR 21 (note: a single column cannot equal two different values, so use OR, not AND):

Combination of class and number range

Show class 17 (Errors) and class 21 (Diagnostic events), with alarm numbers less than 111:

Equivalent expression using IN for the class set:

Range filter using BETWEEN

Show all alarms with numbers between 100 and 199:

Unacknowledged alarms only

State bits: 1 = raised (came in), 4 = acknowledged. To show raised-but-not-acknowledged alarms use a bitmask test:

Dynamizing MsgFilterSQL with VBScript

For interactive filtering (operator-driven lookups, line-select filters, or PLC-driven scope changes), bind MsgFilterSQL to a VBScript function. The function must return a string. When the returned string is empty, the alarm control shows all messages.

Step-by-step

1. Open the HMI screen that contains the AlarmControl.
2. In the Inspector, select the AlarmControl and navigate to Properties → Miscellaneous.
3. Right-click MsgFilterSQL and choose Dynamic dialog or ... (depends on TIA version), then select VB function.
4. Create a function with the signature Function GetMsgFilterSQL() As String in the project's Scripts folder.
5. Implement the filter logic, concatenating columns, operators, and values as a string.
6. Compile and download. Trigger the function on screen events (e.g., a button's Click event, a tag change) or via a cyclic trigger.

Sample VBScript

Function GetMsgFilterSQL() As String
    Dim sType As String
    Dim sNrFrom As Long
    Dim sNrTo As Long
    Dim sResult As String

    ' Read configured limits from internal tags
    sType   = SmartTags("FilterType")         ' e.g. "17,21"
    sNrFrom = SmartTags("FilterNrFrom")        ' e.g. 100
    sNrTo   = SmartTags("FilterNrTo")          ' e.g. 199

    If sType = "" And sNrFrom = 0 And sNrTo = 0 Then
        GetMsgFilterSQL = ""                  ' no filter, show all
        Exit Function
    End If

    If sType <> "" Then
        sResult = "Type IN (" & sType & ")"
    End If

    If sNrFrom > 0 Or sNrTo > 0 Then
        If sResult <> "" Then sResult = sResult & " AND "
        If sNrTo >= sNrFrom And sNrTo > 0 Then
            sResult = sResult & "MSGNR BETWEEN " & sNrFrom & " AND " & sNrTo
        Else
            sResult = sResult & "MSGNR >= " & sNrFrom
        End If
    End If

    GetMsgFilterSQL = sResult
End Function

Common Errors and Fixes

WinCC Unified (TIA Portal V20/V21)

In WinCC Unified Runtime the alarm control is configured under Inspector → Properties → Miscellaneous → Alarm control. The filter fields are similar but the dynamization interface differs:

• The filter is typically set through JavaScript on the AlarmControl object, e.g. Screen.Items('AlarmControl_1').Filter = "MSGNR > 100".
• Configuration dialogs for cell and row behaviour are described in the TIA Portal help under Alarm control (RT Unified) - WinCC Unified.
• WinCC Unified supports the same column names (MSGNR, Type, State, etc.) for the filter property.

The recommended entry point for documentation is the TIA Portal V21 help portal hosted at docs.tia.siemens.cloud.

Step-by-Step: Implementing the Filter

1. In the project tree, expand HMI → Screens and open the screen containing the AlarmControl.
2. Select the AlarmControl and open the Inspector window.
3. Under Properties → Miscellaneous, locate DefaultMsgFilterSQL and enter a baseline expression, for example Type IN (17, 21).
4. Right-click MsgFilterSQL and select ... (or Dynamic dialog) → VB function. Create GetMsgFilterSQL as shown above.
5. Define internal tags FilterType (WString), FilterNrFrom (Long), FilterNrTo (Long) in the HMI tag table.
6. Add I/O fields or a button on the screen that writes to these tags. For example, a "Apply" button sets the tags then triggers the dynamization by raising the tag change.
7. Compile the HMI and download to the runtime.
8. Verify with a known alarm number: trigger alarm 17 from the PLC, then confirm it appears in the AlarmControl when the filter is set to MSGNR = 17 and disappears when set to MSGNR = 99.

Verification Checklist

• Static filter check: Enter a known alarm number in DefaultMsgFilterSQL, restart runtime, confirm only that alarm appears.
• Dynamic filter check: Change the bound tag value at runtime, confirm the AlarmControl refreshes without a screen reload.
• Empty filter check: Set the script return value to "", confirm all active alarms reappear.
• Operator pre-check: Switch WinCC user class; verify that filtering is not gated by user-rights unless intentional.
• Archive check: The filter affects the on-screen view only. Archived messages in the alarm log remain intact. To filter archived data, use a separate SQL query against the alarm database, not MsgFilterSQL.
• Audit check: In the GHMIs (Operator audit) or WinCC Audit, ensure the filter change is logged if required for GMP/regulated environments.

Diagnostic Tools and Logging

When the filter behaves unexpectedly, enable these diagnostics before contacting support:

1. In the WinCC project, navigate to Runtime settings → Logging and increase the alarm logging verbosity.
2. Use the APDIAG tool (WinCC RT Professional) or the HmiLogViewer (WinCC RT Advanced) to read the runtime log for "MsgFilterSQL" or "AlarmControl" messages.
3. Capture a screenshot of the AlarmControl with the filter property shown in the Inspector.
4. Export the alarm configuration to compare MSGNR values against the filter expression.

Performance Considerations

• MsgFilterSQL is evaluated against the alarm buffer in memory. For systems with very large alarm bursts (> 5000 active alarms), prefer narrow filters at the source (PLC-side MSG_LOCK, MSG_EN) rather than at the display layer.
• Avoid LIKE '%pattern%' leading-wildcard searches; they force full-buffer scans.
• Combine multiple OR conditions into IN (a, b, c, ...) where supported — the parser optimizes IN faster than long OR chains.
• Long expressions (> 256 characters) may hit the property buffer limit on older WinCC versions. Use shorter forms or move logic into the script.

FAQ