Locking WinCC Alarms via VBS and C-Action: V6 vs V7 Methods

Overview

Operators regularly require the ability to lock, suppress, or inhibit individual WinCC messages for a defined window — typically during startup, maintenance transitions, or recipe changes — without deleting the underlying alarm configuration. The challenge is that WinCC V6 and WinCC V7 expose two different scripting surfaces for alarm manipulation, and the runtime behavior of Alarm Control ActiveX methods diverges between releases. A VBS solution that works under WinCC V7 SP3 may compile but fail at runtime in WinCC V6.2 because the WinCC Alarm Control OCX in V6 does not implement GetRowCollection, Lock, or Unlock on its row-iteration object the same way.

This reference documents the complete set of approaches to lock a specific alarm by its message number using VBS, C-Action, and the WinCC Open Development Kit (ODK). It also covers a deployment-grade alternative for time-based inhibition (2-minute startup window, for example) that does not require writing a single line of script.

WinCC Message State Architecture

Every WinCC message traverses a deterministic state machine managed by the alarm logging service. A message can hold multiple orthogonal states at once; the runtime OR's them into a 32-bit DWORD value readable through the ODK and the alarm logging COM interface. The bit layout is fixed and must be used in all locking logic.

Architecture: Where the Lock Actually Lives

WinCC alarm locking is server-side. When a VBS script or C-Action calls MSRTLockMsg (or its VBS equivalent), the request is dispatched to the alarm logging service on the WinCC server. The lock is persisted in the alarm logging database tables and survives the closing of any single client session. This is why locking is the right mechanism for the operator's "inhibit for 2 minutes after runtime start" requirement — it is enforced centrally, not on the HMI client.

Three call paths exist for the same end state:

1. VBS via HMIRuntime.AlarmLogging — WinCC V7 only. Direct COM call from any picture or global action.
2. C-Action via ODK — Both V6 and V7. Calls MSRTLockMsg from apdefap.h glue. Requires ODK installed and licensed on the runtime node.
3. WinCC Scheduler + message class disable — Both V6 and V7. No scripting; uses time-based configuration to disable the message class for a defined window.

Prerequisites

• WinCC V7.0 SP3 or later for the VBS path, or WinCC V6.2 SP2 / V7 for the ODK path.
• WinCC Open Development Kit installed and licensed on the runtime machine. Verify via Start → SIMATIC → WinCC → ODK Readme.
• For VBS: the picture must contain a WinCC Alarm Control OCX with a known name (e.g., Control1, AlarmWindow_1). Read the property name from the configuration dialog.
• For C-Action: the project must be compiled with the ODK include path set. In WinCC Explorer → Computer → Properties → Graphics Runtime → C-Script tab, add %WINCC_OAP_DIR%\include to the include directories.
• The message number (e.g., 1, 1000042) must be known. Locate it in WinCC Explorer → Alarm Logging → the message row.

Method 1 — VBS Path (WinCC V7 Only)

WinCC V7 exposes a clean VBS object model on the alarm logging runtime. The full canonical pattern for locking a specific alarm by its message number from a global action, a button click, or a picture-level event is shown below.

Lock a single message

' WinCC V7 — Lock a specific alarm by tag-name + message number
' Trigger: button click, scheduled action, or picture event

Sub OnClick(ByVal Item)
    Dim sTagName
    Dim lMsgNr
    Dim oAlarmLog

    sTagName = "MyAlarmTag"        ' <-- Logical message tag, NOT the trigger tag
    lMsgNr   = 1                    ' <-- Message number from Alarm Logging editor

    Set oAlarmLog = HMIRuntime.AlarmLogging

    ' Hide: removes from visible list
    oAlarmLog.HideAlarm sTagName, lMsgNr, 0, True

    ' Lock: keeps in list but disables operator action
    oAlarmLog.Lock sTagName, lMsgNr
End Sub

Unlock the same message

Sub OnClick_UnLock(ByVal Item)
    HMIRuntime.AlarmLogging.Unlock "MyAlarmTag", 1
    HMIRuntime.AlarmLogging.HideAlarm "MyAlarmTag", 1, 0, False
End Sub

Iterate the alarm list and lock all visible messages

This is the V7 equivalent of the GetRowCollection pattern attempted in the V6 field report. Note that V7 returns an ICollection, not a RowCollection; iteration is index-based and 1-based.

Sub OnClick_LockAllVisible(ByVal Item)
    Dim oCtrl, oMessages, oMsg, i

    Set oCtrl = ScreenItems("Control1")    ' name of the WinCC Alarm Control
    Set oMessages = oCtrl.GetMessageCollection(0)  ' 0 = all statuses

    For i = 1 To oMessages.Count
        Set oMsg = oMessages.Item(i)
        ' Lock every message that is currently "came in" and not yet acknowledged
        If (oMsg.State And 1) = 1 And (oMsg.State And 4) = 0 Then
            HMIRuntime.AlarmLogging.Lock oMsg.MsgTag, oMsg.Number
        End If
    Next
End Sub

Method 2 — C-Action Path with ODK (V6 and V7)

For WinCC V6 sites, or for V7 projects that need to read and react to message state from inside a C function (typical for arithmetic-heavy logic), use the ODK directly. The ODK ships with header msrtapi.h and an import library that must be linked into the WinCC graphics runtime.

C-Action: lock by message number

// WinCC C-Action — lock a specific alarm by number
// Trigger: button click on a WinCC Alarm Control toolbar button

#include "apdefap.h"
#include "msrtapi.h"

void OnClick(char* lpszPictureName, char* lpszObjectName)
{
    DWORD dwState = 0;
    const char* szTagName = "MyAlarmTag";   // Logical message tag
    const DWORD dwMsgNr   = 1;              // Message number

    // Read current state (server call — synchronous)
    MSRTGetMsgState(szTagName, dwMsgNr, &dwState);

    // If the message is currently visible (bit 0x0010 set) and not
    // already locked (bit 0x0008), lock it.
    if ((dwState & MSG_STATE_ENABLE) && !(dwState & MSG_STATE_LOCK))
    {
        MSRTLockMsg(szTagName, dwMsgNr);
    }

    // Optionally also hide the row from the visible list
    MSRTHideMsg(szTagName, dwMsgNr);
}

C-Action: scheduled unlock after delay

#include "apdefap.h"
#include "msrtapi.h"

// Trigger: configured on a 1-Hz timer; tracks the lock-expiry timestamp
static DWORD g_dwUnlockAt = 0;

void OnTimer(char* lpszPictureName, char* lpszObjectName)
{
    DWORD dwNow = GetTickCount();

    if (g_dwUnlockAt != 0 && dwNow >= g_dwUnlockAt)
    {
        MSRTUnlockMsg("MyAlarmTag", 1);
        MSRTShowMsg("MyAlarmTag", 1);
        g_dwUnlockAt = 0;
    }
}

// Called once from a button or startup event to start the 2-min inhibit window
void OnClick_StartInhibit(char* lpszPictureName, char* lpszObjectName)
{
    MSRTLockMsg("MyAlarmTag", 1);
    MSRTHideMsg("MyAlarmTag", 1);
    g_dwUnlockAt = GetTickCount() + 120000UL;  // 120 s = 2 minutes
}

ODK linkage checklist

1. Install ODK from the WinCC setup disk: WinCC Setup → Select Components → ODK.
2. Confirm the environment variable WINCC_OAP_DIR resolves to C:\Program Files\Siemens\Automation\WinCC\OAP (path varies by version).
3. In WinCC Explorer, open the computer properties, navigate to Graphics Runtime → C-Script, and verify the include path contains %WINCC_OAP_DIR%\include.
4. Link with apdefap.c and the import library aplib.lib found under %WINCC_OAP_DIR%\lib. WinCC performs this step automatically for project-internal C-Actions.
5. License the ODK runtime on every engineering and runtime station. Without a valid license, MSRTLockMsg returns MSRT_E_NOLICENSE (-16).

Method 3 — Scheduler-Based Inhibit (No Scripting)

For a deterministic, auditable 2-minute inhibit window after runtime start, use the WinCC Scheduler to disable the message class or specific message numbers for a time range. This is the only method that survives a WinCC client crash and that does not require an ODK license.

1. In WinCC Explorer, open Alarm Logging → Message Classes.
2. Right-click the target class → Properties → Disable via Scheduler.
3. Add a time event: type = Once, trigger time = runtime start time (use @CurrentTime + 2 min for relative offset if WinCC version supports it; otherwise hardcode a wall-clock window).
4. Action = Disable message class.
5. Add a second event 2 minutes later: action = Enable message class.

This is also the correct method if the requirement is to inhibit all alarms of a class (e.g., all process alarms during a recipe load) rather than individual message numbers.

Method 4 — Source-Side Delay (Recommended for Plant Architecture)

The most robust pattern, used in plant installations with both local SCADA and a remote control center, is to delay the alarm at its source — typically a CFC chart or an S7 block output. The alarm bit is held false for 2 minutes after the controlling tag transitions to a stable state, then released. WinCC is unaware of the inhibit and reports the exact moment it is allowed to act. This approach is recommended by experienced SCADA integrators because the same logic is enforced in both the local WinCC and any remote control center receiving the same tag.

Implementation in S7 CFC: use a TON (on-delay timer) with PT = 2 min on the alarm enable signal, so the alarm only becomes visible after the controlled value has been stable for the full window.

Cross-Version Compatibility Matrix

Troubleshooting Matrix

Verification Procedure

1. Trigger the alarm in the test system by forcing the trigger tag to a value that causes the message condition. Confirm the alarm appears in the WinCC Alarm Control.
2. Execute the lock call (button click, scheduled action, or C-Action). Expected: the alarm either disappears from the visible list (if hidden) or appears with a lock icon and cannot be acknowledged.
3. Cross-client check: open a second WinCC client. The locked state must be visible there too — this confirms the lock is server-side, not local.
4. Query state directly via the WinCC ODK sample application ODK_Example (installed with the ODK). Call MSRTGetMsgState and confirm the returned DWORD has bit 0x0008 set (MSG_STATE_LOCK).
5. Operator action test: attempt to acknowledge or process the locked alarm in the WinCC Alarm Control. The button must be grayed out or return "Operation not permitted".
6. Time-based release: if the lock is scheduled to release after 2 minutes, verify by waiting and re-querying state. After release, the alarm (if still active) returns to the visible list and can be acknowledged normally.
7. Persistence test: restart the WinCC runtime. The lock state must be retained if it was server-side via ODK / AlarmLogging.Lock. A purely client-side lock (rare, but possible with a misconfigured script) will be lost.

Field-Commissioning Checklist

• Confirm ODK is licensed on every runtime node, not just the engineering station.
• For multi-server / redundant WinCC pairs, the lock must be applied to the server that owns the alarm — usually the master. Verify the script is running on the correct machine context.
• Document the message tag and number in the project functional specification, not just in the script. Auditors require this mapping.
• If the project uses both WinCC V6 and V7 (mixed fleet, e.g., during a migration), segregate scripts into V6_ODK and V7_VBS folders to avoid accidental cross-deployment.
• Add a global VBS OnError handler around the lock call to log failures to a diagnostic tag, so support engineers can see in WinCC itself if the lock failed.
• For the 2-minute startup inhibit pattern, prefer the scheduler approach over a runtime timer — the scheduler survives a WinCC runtime crash, a timer does not.

Safety and Operational Considerations

Alarm locking is a temporary, operator-visible state. It is not a substitute for proper alarm management per ISA-18.2 / IEC 62682. A locked alarm must be reviewed for deadbands, priorities, and shelving policy. Operators must be trained to recognize the lock icon and to escalate if a critical alarm is unexpectedly suppressed. Never use a 2-minute startup inhibit as a workaround for poor alarm rationalization — the inhibit should be the exception, not the default.

FAQ