WinCC V7 Alarm Logging to External SQL Database via C-Script GMsgFunction

Siemens WinCC V7 exposes a runtime-side hook named GMsgFunction that is invoked whenever a configured alarm changes state. When paired with a small C-Script that shells out to sqlcmd.exe, it becomes a reliable pipeline for writing alarm events, process values, and timestamps to an external SQL Server database. This article documents a complete, field-proven implementation for WinCC V7 SP2 and later, including the SQL schema, the C-Script, the ProgramExecute wrapper, the parameter encoding rules, and a verification procedure that eliminates the VBScript-on-save trigger problem that motivates most users to abandon the VBScript approach.

Problem: VBScript Actions Re-Fire When the Editor Saves

When a tag property action is bound directly to a configured WinCC alarm (for example through Alarm Logging → Message Line → Properties → Tag/Action → Function Name with a VBScript body), the action's body is evaluated not only at runtime on state changes, but also every time the project editor saves the configuration. Each save re-evaluates all attached actions, and any VBScript that issues an INSERT against a database will therefore push stale rows for every active alarm at the moment of the save.

The visible symptom is a flood of duplicate or zombie rows in the SQL table during development: the operator has not triggered any new alarm, yet the row count keeps climbing while the engineer is editing. In production this side effect can also occur on redundancy failover, project reactivation, and HMI restart, all of which re-enter the same save/load path. The cleanest way to remove the noise is to stop using VBScript actions bound to tag events and move the logic to a C-Script registered as the project's user-defined action for messages — the function that WinCC calls only at runtime, only on real state transitions.

Architectural Shift: From VBScript to C-Script GMsgFunction

WinCC V7 reserves the function name GMsgFunction as the standard entry point for a user-defined action that runs whenever a message configured in Alarm Logging fires, acknowledges, or clears. WinCC compiles the C-Script at project compile time, links it into the runtime, and dispatches into it with a fixed parameter list. Because the dispatcher is reached only via the runtime alarm task — never through the editor's action validation path — save cycles do not reach the function body.

For the SQL write path, two implementation strategies are available from C-Script in WinCC:

1. Call an external program (sqlcmd.exe) with the row payload on the command line. The OS process is short-lived, has no state, and uses the standard SQL Server client.
2. Use MSDBLLIB / ODBC32 via a custom DLL. This is faster, but ships a C++ dependency into the project and complicates deployment.

This article covers strategy (1) because it is the only approach that does not require redistributing native libraries, fits inside the WinCC script sandbox, and is officially acknowledged in Siemens support note 23370769 for SQL access from WinCC C-Script.

Prerequisites

• WinCC V7 SP2 or later (SP3, SP4, V7.2, V7.3, V7.4, V7.5 are all valid — the function signature changed slightly between major service packs; see the parameter table below).
• Microsoft SQL Server 2008 R2 or later (Express, Standard, or Enterprise). The procedure works identically against any edition that accepts sqlcmd connections.
• SQL Server Client Tools installed on the WinCC station so that sqlcmd.exe is on %PATH% (or the script is updated to use the full path).
• A 32-bit ODBC System DSN named, for example, WinCC_AlarmLog, pointing at the target database. The DSN is used by sqlcmd through the -S and -d switches or via a DSN alias.
• WinCC administrator rights to compile scripts and to write to the project directory.
• The Windows account running the WinCC Runtime must have permission to INSERT into the target table, and to spawn child processes. On Windows Server, the WinCC service account or the local SYSTEM account (default) is typical.

GMsgFunction: Signature, Parameters, and Trigger Semantics

The exact parameter list of GMsgFunction depends on the WinCC version. Two common forms are listed below; if your installation compiles neither, check the project's C-Script action template in the WinCC Information System under Alarm Logging → Working with Alarms → User-defined Actions.

WinCC V7 SP2 / SP3 form

void GMsgFunction(DWORD dwMsgNr, DWORD dwState, DWORD dwTime,
                  LPCTSTR lpszPictureName, LPCTSTR lpszObjectName,
                  LPCTSTR lpszMsgText, LPCTSTR lpszReserved);

WinCC V7.2 / V7.3 / V7.4 form (extended time)

void GMsgFunction(DWORD dwMsgNr, DWORD dwState,
                  MSG_TIME_STRUCT* pstTime,
                  LPCTSTR lpszPictureName, LPCTSTR lpszObjectName,
                  LPCTSTR lpszMsgText, LPCTSTR lpszReserved);

The state bits are the only reliable way to tell came in from went out from acknowledged. Filter the dwState value before issuing the SQL write to keep one row per logical event.

Step-by-Step: SQL Database Schema

Run the following script on the target SQL Server to create the destination database and the alarm table. The schema separates the structural columns from the dynamic process value blob so that analytical queries can index on time, message number, and state without scanning the text.

-- 1. Database
IF DB_ID('WinCC_AlarmLog') IS NULL
BEGIN
    CREATE DATABASE WinCC_AlarmLog;
END;
GO

USE WinCC_AlarmLog;
GO

-- 2. Table
IF OBJECT_ID('dbo.AlarmEvent', 'U') IS NULL
BEGIN
    CREATE TABLE dbo.AlarmEvent
    (
        EventID        BIGINT IDENTITY(1,1) NOT NULL,
        EventTime      DATETIME2(3)         NOT NULL,
        EventTimeUTC   DATETIME2(3)         NOT NULL,
        MsgNr          INT                  NOT NULL,
        StateCode      INT                  NOT NULL,
        StateText      NVARCHAR(32)         NOT NULL,
        PictureName    NVARCHAR(255)        NULL,
        ObjectName     NVARCHAR(255)        NULL,
        MsgText        NVARCHAR(1024)       NULL,
        ProcessValue   NVARCHAR(255)        NULL,
        HostName       NVARCHAR(64)         NOT NULL
            CONSTRAINT DF_AlarmEvent_HostName DEFAULT HOST_NAME(),
        CONSTRAINT PK_AlarmEvent PRIMARY KEY CLUSTERED (EventID)
    );

    CREATE NONCLUSTERED INDEX IX_AlarmEvent_Time
        ON dbo.AlarmEvent (EventTime);
    CREATE NONCLUSTERED INDEX IX_AlarmEvent_MsgNr
        ON dbo.AlarmEvent (MsgNr) INCLUDE (EventTime, StateCode);
END;
GO

-- 3. Permission for the WinCC service account (replace DOMAIN\svc-wincc)
CREATE USER [DOMAIN\svc-wincc] FOR LOGIN [DOMAIN\svc-wincc];
ALTER ROLE db_datawriter ADD MEMBER [DOMAIN\svc-wincc];
GRANT EXECUTE ON SCHEMA::dbo TO [DOMAIN\svc-wincc];
GO

Step-by-Step: Wiring the C-Script Action

1. Open the WinCC Explorer and double-click Alarm Logging.
2. In the message tree, select either a single message (for one-off cases) or a message class (recommended for the bulk of your alarms).
3. Open Properties (right-click → Properties, or use the menu).
4. Navigate to the Tag/Action tab.
5. Set Function Name to exactly GMsgFunction. The name is case sensitive.
6. Confirm the action type is C-Script. If the project editor prompts for a function body, leave it empty for now; the body is supplied in the next section.
7. Compile the project. Any C-Script compile error will block the project from going online, so fix syntax issues here before activating Runtime.

If you have many message classes, repeat step (2) for each class. Sharing one GMsgFunction across all classes is the recommended pattern — the function dispatches based on the parameters.

Step-by-Step: Implementing the C-Script

Open the global C-Script editor (Global Scripts → C-Editor) and create a new action. Paste the body below, then compile. The function escapes single quotes by doubling them (the standard SQL Server convention) and writes the row by spawning sqlcmd.exe with a single -Q command.

#include "apdefap.h"
#include "msdbllib.h"

// Build a SQL-safe literal from a C string. Doubles single quotes and
// truncates to the maximum length supported by the table.
static void SqlEscape(char *dst, const char *src, size_t dst_size)
{
    size_t j = 0;
    if (src == NULL) { dst[0] = '\0'; return; }
    for (size_t i = 0; src[i] != '\0' && j + 1 < dst_size; ++i)
    {
        char c = src[i];
        if (c == '\'') {
            if (j + 2 >= dst_size) break;
            dst[j++] = '\'';
            dst[j++] = '\'';
        } else if (c == '\n' || c == '\r') {
            // Replace newlines with spaces; the SQL column is NVARCHAR.
            dst[j++] = ' ';
        } else {
            dst[j++] = c;
        }
    }
    dst[j] = '\0';
}

// Convert WinCC time (100 ns ticks since 1601) to ISO 8601 UTC.
static void WinCCDateTimeToIso(DWORD ft_time, char *buf, size_t buf_size)
{
    // Use MSDBLLIB helper: SysTimeToUTC then format as "YYYY-MM-DDTHH:MM:SS.fffZ"
    SYSTEMTIME st_utc;
    FileTimeToSystemTime((FILETIME*)&ft_time, &st_utc);
    // Optionally convert to UTC if local was intended:
    // SystemTimeToTzSpecificLocalTime(NULL, &st_utc, &st_utc) is the inverse.
    _snprintf_s(buf, buf_size, _TRUNCATE,
        "%04u-%02u-%02uT%02u:%02u:%02u.%03uZ",
        st_utc.wYear, st_utc.wMonth, st_utc.wDay,
        st_utc.wHour, st_utc.wMinute, st_utc.wSecond,
        st_utc.wMilliseconds);
}

void GMsgFunction(DWORD dwMsgNr, DWORD dwState, DWORD dwTime,
                  LPCTSTR lpszPictureName, LPCTSTR lpszObjectName,
                  LPCTSTR lpszMsgText, LPCTSTR lpszReserved)
{
    // 1. Filter to "came in" and "went out" only. Drop acknowledgement
    //    transitions; they do not represent new alarm state changes.
    const DWORD wanted_mask = 0x0001 /* CAME */ | 0x0002 /* WENT */;
    if ((dwState & wanted_mask) == 0) return;

    // 2. Format state text.
    const char *state_text =
        (dwState & 0x0001) ? "CAME_IN" : "WENT_OUT";

    // 3. Build SQL-safe literals.
    char esc_text[1024];
    char esc_pic[256];
    char esc_obj[256];
    char esc_iso[40];

    SqlEscape(esc_text, lpszMsgText,  sizeof(esc_text));
    SqlEscape(esc_pic,  lpszPictureName, sizeof(esc_pic));
    SqlEscape(esc_obj,  lpszObjectName,  sizeof(esc_obj));
    WinCCDateTimeToIso(dwTime, esc_iso, sizeof(esc_iso));

    // 4. Compose the SQL command. Use -E for Windows Authentication;
    //    -S server\instance, -d database, -Q for one-shot query.
    char cmd[2048];
    _snprintf_s(cmd, sizeof(cmd), _TRUNCATE,
        "sqlcmd.exe -S .\\SQLEXPRESS -E -d WinCC_AlarmLog -Q "
        "\"INSERT INTO dbo.AlarmEvent "
        "(EventTime, EventTimeUTC, MsgNr, StateCode, StateText, "
        " PictureName, ObjectName, MsgText) "
        "VALUES (SYSDATETIME(), '%s', %lu, %lu, '%s', '%s', '%s', '%s')\"",
        esc_iso, dwMsgNr, dwState, state_text, esc_pic, esc_obj, esc_text);

    // 5. Execute asynchronously to avoid blocking the alarm task.
    ProgramExecute(cmd);
}

Parameter Encoding and Quoting

Three encoding decisions drive the entire C-Script — get them wrong and you will get either SQL syntax errors or worse, successful injection of arbitrary text into the table.

The most common silent failure is the un-escaped ampersand: cmd.exe interprets it as a command separator and the second half of your SQL command becomes a stray executable name. Wrap the entire -Q argument in outer double quotes (as in the example) and also escape any internal double quotes if your project ever includes " inside alarm text.

Configuration in Alarm Logging

The two configuration paths for message actions are not interchangeable:

Setting the function name on the message class is preferred because it survives re-numbering, message copy operations, and class merges. If the class is configured for "single acknowledgment" or "multi acknowledgment" the state bits are the same; only the visibility of the ACK transition changes in the Alarm Control.

Verification Procedure

1. Activate WinCC Runtime in test mode.
2. Trigger a test alarm by setting the configured trigger tag in the WinCC Tag Simulator (or by simulating a real process value change).
3. After one second, open SQL Server Management Studio and run: SELECT TOP 10 * FROM WinCC_AlarmLog.dbo.AlarmEvent ORDER BY EventID DESC;
4. Confirm that a row appeared with StateText = 'CAME_IN' and a non-null EventTimeUTC.
5. Reset the alarm (clear the trigger condition). Verify that a second row appears with StateText = 'WENT_OUT'.
6. Acknowledge the alarm from the Alarm Control. Verify that no new row appears — acknowledgements are intentionally filtered out.
7. Save the project from the WinCC Explorer (Ctrl+S). Verify that no new rows appear in the SQL table. This is the regression test that proves the VBScript-on-save bug is gone.
8. Restart the WinCC service. Verify that no spurious CAME_IN rows are written for alarms that were already active at the moment of restart.

If step (7) still produces rows, the C-Script was not actually registered — check the project compile log for the GMsgFunction action and confirm the editor did not fall back to VBScript because of a missing function name match.

Troubleshooting Matrix

Field-Proven Caveats

Alarm storm throughput

Spawning one sqlcmd.exe per alarm event is acceptable up to roughly 10 events per second on a typical Windows Server. Above that, the cost of process creation, ODBC handshake, and authentication begins to dominate and the WinCC alarm task may begin to throttle. For higher rates, either: (a) buffer rows in a memory-mapped file and flush with a scheduler-driven C action, or (b) embed a native ODBC client in a custom DLL and skip the process boundary.

Redundancy

In a WinCC Redundancy pair, both servers can call GMsgFunction on every state change because the alarm task runs independently. If the destination table is shared, add a HostName column and use a primary key that includes it, or restrict the function to the preferred server via an internal tag. The simpler choice is to use two schemas (dbo.AlarmEvent_Srv1, dbo.AlarmEvent_Srv2) and a view that unions them.

Time zone handling

WinCC stores time internally as FILETIME in UTC. FileTimeToSystemTime returns UTC components, so the YYYY-MM-DDTHH:MM:SS.fffZ string is always UTC. Do not convert to local time inside GMsgFunction; if the operations team needs local time, do it at query time in SQL with EventTimeUTC AT TIME ZONE 'Central European Standard Time'.

Process value extraction

The lpszMsgText parameter arrives fully substituted. If the message text contains a token like @1%s@ or @2%f@, the resolved value is already inside the text and you do not need an extra GetTagXxx call. Avoid calling GetTagXxx from inside GMsgFunction; it can cause re-entrancy in the alarm task and trigger watchdog timeouts.

Licensing

WinCC Runtime licenses are counted per alarm tag, not per side effect. Logging the same alarm to SQL does not require an additional license, but ensure that the SQL write does not run on the configuration station, where it would consume an RT-only seat.

Permissions on the WinCC service account

The default account for the WinCC Runtime service is the local SYSTEM account, which has no network credentials and therefore cannot use -E against a remote SQL Server. Either run the SQL Server on the same host, or change the WinCC service to run as a domain user with the right granted on the SQL Server (the ALTER ROLE db_datawriter line in the schema script above).

Related Siemens Documentation

The official WinCC V7 documentation covers GMsgFunction and the alarm logging action model. Refer to:

• Siemens Support entry 25678075 — "Determining message texts and process values at runtime for GMsgFunction"
• Siemens Support entry 23370769 — "SQL access from WinCC C-Script via ProgramExecute"
• WinCC V7.4 System Manual — section on Alarm Logging and user-defined actions

FAQ