WinCC C-Script: Writing Date and Time Values to HMI Tags

Problem Overview

WinCC C-Script projects frequently require the runtime to write the combined date and time picked from a Calendar Control 11.0 ActiveX into a Date/Time internal tag. The Calendar Control exposes only the date component through its Value property, so engineers must concatenate a fixed or computed time string and pass the resulting buffer to a Date/Time tag via the SetTagChar API. Three recurring symptoms appear in the field:

1. The tag updates with the selected date but the time component always shows 12:00:00 in the HMI output.
2. A custom time string such as "23:59:59" writes correctly, but "00:00:00" reverts to 12:00:00 immediately after the SetTagChar call returns.
3. The Calendar Control Value property returns the date in a regional format (DD.MM.YYYY, MM/DD/YYYY, or YYYY-MM-DD) that the WinCC Date/Time tag parser cannot interpret directly, producing tag write failures or default values.

This reference documents the underlying WinCC Date/Time tag format, the C-Script tag I/O APIs involved, a production-ready string concatenation pattern, and the specific workarounds required to write a literal 00:00:00 time. The patterns apply to SIMATIC WinCC V7.0 through V7.5 SP2 and WinCC Professional V13 SP1 through V18 (TIA Portal) C-Script editors that ship the legacy Microsoft Calendar Control 11.0 (MSCAL.OCX) wrapper.

Reference documentation: Siemens Industry Online Support for the SIMATIC WinCC V7.5 manual set, the WinCC Professional scripting manual, and the WinCC option documentation.

Prerequisites and Environment

Confirm the following before adapting the code to a target project:

• WinCC V7.4 SP1, V7.5, V7.5 SP1, V7.5 SP2, or WinCC Professional V15.1 through V18 in TIA Portal with the C-Script runtime option licensed.
• Microsoft Calendar Control 11.0 (MSCAL.OCX) registered on the development PC. Verify with regedit under HKEY_CLASSES_ROOT\TypeLib\{8E27C92B-1264-101C-8A2F-040224009C02} on Windows 7 / Windows 10 / Windows 11 64-bit systems. The CLSID must resolve to mscal.ocx.
• A Date/Time internal tag (for example BeginDate) defined in WinCC Tag Management with the type "Date/Time" and a valid connection assignment.
• An ActiveX wrapper inserted on the target picture with the object name matching the C-Script reference (commonly CalendarBeginDate).
• A project function or local C-Action attached to the Calendar's ValueChanged or Click event.
• Local Administrator rights on the engineering station so that MSCAL.OCX can be re-registered if the Calendar wrapper fails to instantiate.

Cross-reference: Siemens Industry Online Support for the SIMATIC HMI option documentation, WinCC scripting manuals, and the TIA Portal WinCC Professional system manual.

Calendar Control 11.0 ActiveX Properties

The Microsoft Calendar Control 11.0 (programmatic identifier MSComCtl2.Calendar.2 or, in some legacy builds, MSCAL.Calendar.7) exposes several properties accessible from WinCC C-Script via the GetPropChar / SetPropChar wrappers. The properties relevant to date/time tag writes are:

The Value property is the only property that returns a complete date string, and its format depends on the regional settings of the engineering station's Windows installation. Typical outputs include:

• US English locale: MM/DD/YYYY (e.g., 11/25/2024)
• German locale: DD.MM.YYYY (e.g., 25.11.2024)
• ISO 8601 locale (UK English or Swedish): YYYY-MM-DD (e.g., 2024-11-25)
• French locale: DD/MM/YYYY (e.g., 25/11/2024)

WinCC's Date/Time tag parser expects the literal format YYYY-MM-DD HH:MM:SS in both V7.x and WinCC Professional. A regional date string without explicit ISO 8601 reformatting is rejected or misinterpreted, which is why direct passing of the Calendar Value to SetTagChar fails in non-English locales.

WinCC C-Script Tag I/O Functions

WinCC C-Script exposes a flat C API for property and tag access. The relevant calls for this use case are documented in apdefap.h, which ships with the WinCC installation under WinCC\aplib\:

The Calendar Control's Value property can be retrieved with GetPropChar(lpszPictureName, "CalendarBeginDate", "Value"). The function returns a pointer to an internal WinCC buffer; the buffer is reused by subsequent GetPropChar calls in the same thread, so copy the result into a project-owned char array before any other API call executes.

Date/Time Tag Internal Format

WinCC stores Date/Time tags as a 64-bit Windows FILETIME value representing the number of 100-nanosecond intervals since 1601-01-01 00:00:00 UTC. The SetTagChar wrapper converts the string argument to FILETIME using a locale-independent parser that recognizes the exact format YYYY-MM-DD HH:MM:SS with literal hyphen, space, and colon separators. Any deviation from this exact format causes one of three failures:

1. The tag is written but the time component reverts to 12:00:00 because the parser interprets the unrecognized string as a date-only value and substitutes the canonical noon default.
2. The SetTagChar call returns FALSE (zero) and the tag retains its previous value. No event is raised; the failure is silent unless the script logs it explicitly.
3. The tag displays garbage characters in the HMI I/O field because the FILETIME conversion produced an out-of-range value or an invalid UTF-16 surrogate pair in the OPC UA layer.

This is the root cause of the 12:00:00 default. When the Calendar Control returns 11/25/2024 (US locale) and the script concatenates 00:00:00, the resulting string 11/25/2024 00:00:00 is not a valid WinCC Date/Time string. The parser falls back to date-only interpretation and uses 12:00:00 noon as the canonical default. The same mechanism explains why "23:59:59" appears to work in some configurations: if the trailing :59 happens to align with a valid alternative parser path on the runtime machine, the tag is accepted with the literal value; otherwise the same fallback applies.

The string-to-FILETIME parser in WinCC V7.x is implemented in CCAggrTlg.dll and in HMIRTM.exe on WinCC Professional. The parser does not call strptime or VariantChangeType; it uses a hand-written state machine that expects the fixed width pattern. Localized date strings are rejected unless the calling C-Script pre-processes them into ISO 8601.

Concatenating Date and Time Strings

To produce a valid WinCC Date/Time string, the script must reformat the Calendar output to ISO 8601 and append the time literal. The canonical pattern is:

char* dia;
char datebuf[32];
char datetime[40];
int m, d, y;

dia = GetPropChar(lpszPictureName, "CalendarBeginDate", "Value");
if (dia == NULL) return 1;

/* Parse US-locale MM/DD/YYYY. Adjust sscanf format for other locales. */
if (sscanf(dia, "%d/%d/%d", &m, &d, &y) != 3) return 1;

sprintf(datebuf, "%04d-%02d-%02d", y, m, d);
sprintf(datetime, "%s 23:59:59", datebuf);

SetTagChar("BeginDate", datetime);

This pattern handles the locale issue at the source by parsing three integers and rebuilding the string in ISO 8601. The fixed time 23:59:59 is concatenated with a single space separator. The %04d width specifier guarantees a four-digit year, which is required by the parser for years before 1000 AD.

For German locale where the Calendar returns 25.11.2024, replace the sscanf line with:

if (sscanf(dia, "%d.%d.%d", &d, &m, &y) != 3) return 1;

For French locale (25/11/2024):

if (sscanf(dia, "%d/%d/%d", &d, &m, &y) != 3) return 1;

For projects that must handle multiple locales on a single runtime, dispatch on the separator character detected in the dia buffer:

char sep = dia[2];
if (sep == '-')      n = sscanf(dia, "%d-%d-%d", &y, &m, &d);
else if (sep == '/') n = sscanf(dia, "%d/%d/%d", &m, &d, &y);
else if (sep == '.') n = sscanf(dia, "%d.%d.%d", &d, &m, &y);
else return 1;

The separator character is always at offset 2 for the supported regional formats because the day and month components are two-digit zero-padded strings.

Step-by-Step Implementation

The full implementation follows these steps:

1. Open the WinCC picture that contains the Calendar ActiveX wrapper. Confirm the object name matches the property name string passed to GetPropChar. The default object name in WinCC V7.x is Control1; rename it to CalendarBeginDate via the object's Properties dialog for clarity.
2. Open the picture's events list (right-click the object > Properties > Events) and locate the Calendar's ValueChanged or Click event. Right-click the event row and select "C-Action" to attach a C-Script.
3. Paste the canonical C-Script into the editor. The script must declare all local variables at the top of the function block because WinCC's C-Script editor is C89-strict.
4. Compile the picture with F7 or via Graphics Designer > Compile. Resolve any "implicit declaration" warnings by adding missing prototypes; the most common omission is int sscanf(const char*, const char*, ...).
5. Save the picture and start the runtime. Click several dates in the Calendar and observe the configured diagnostic tag.
6. Open the WinCC Tag Simulator (Start > Programs > Siemens Automation > SIMATIC > WinCC > Tools > WinCC Tag Simulator) and verify that BeginDate updates with the selected date and the configured time.
7. Confirm the value round-trips by reading the tag back with GetTagChar("BeginDate") in a second C-Action on a button press, then logging the result to a String tag.

A production-ready version with locale auto-detection and explicit error handling:

#include "apdefap.h"

void OnCalendarChange(char* lpszPictureName, char* lpszObjectName, char* lpszPropertyName)
{
    char* dia;
    char datebuf[32];
    char datetime[40];
    int m = 0, d = 0, y = 0;
    int n = 0;
    char sep;

    dia = GetPropChar(lpszPictureName, "CalendarBeginDate", "Value");
    if (dia == NULL) {
        SetTagWord("DiagCalendarWriteError", 1);
        return;
    }

    sep = dia[2];
    if (sep == '-') {
        n = sscanf(dia, "%d-%d-%d", &y, &m, &d);
    } else if (sep == '/') {
        n = sscanf(dia, "%d/%d/%d", &m, &d, &y);
    } else if (sep == '.') {
        n = sscanf(dia, "%d.%d.%d", &d, &m, &y);
    }

    if (n != 3) {
        SetTagWord("DiagCalendarWriteError", 2);
        return;
    }

    sprintf(datebuf, "%04d-%02d-%02d", y, m, d);
    sprintf(datetime, "%s 23:59:59", datebuf);

    if (!SetTagChar("BeginDate", datetime)) {
        SetTagWord("DiagCalendarWriteError", 3);
    } else {
        SetTagWord("DiagCalendarWriteError", 0);
    }
}

The apdefap.h include is mandatory because it declares the WinCC C runtime prototypes. Without it, the compiler emits "implicit function declaration" errors that corrupt the build. The diagnostic tag DiagCalendarWriteError exposes a numeric status code that maps to 1 = NULL pointer from GetPropChar, 2 = sscanf parse failure, 3 = SetTagChar returned FALSE, and 0 = success.

Handling the 00:00:00 Edge Case

When the time literal changes from 23:59:59 to 00:00:00, the visible tag may still display 12:00:00 because of three distinct issues that interact with each other.

Issue 1 - Leading-zero truncation in the source. If the project was migrated from an older WinCC version (V6.x or earlier), the C-Script source may contain a stray carriage return, line feed, or UTF-8 BOM before the time string literal. Use sprintf to guarantee the exact format:

sprintf(datetime, "%s 00:00:00", datebuf);

Do not concatenate string literals across multiple C statements; some C-Script compilers in WinCC V7.0 SP3 and earlier concatenate adjacent string literals with an inserted space, breaking the format. The single-call sprintf form is portable across all WinCC versions.

Issue 2 - Tag display format. The Date/Time tag is stored correctly as a FILETIME but the I/O field displaying the tag is configured with a custom format string. Open the I/O field properties, switch to the "Output/Input" tab, and confirm the Output format is set to a string that includes "HH:mm:ss". Common format codes:

If the I/O field format omits "HH:mm:ss", the displayed value falls back to 12:00:00 even when the underlying tag FILETIME is exactly midnight. This is the most common cause of the 00:00:00 not appearing in the HMI. Verify by selecting the I/O field and pressing F8 to open the format editor.

Issue 3 - Script re-entry. The Calendar Control fires ValueChanged on each date click. If the script writes the tag from multiple places - for example, both the Calendar event and a separate reset button - an earlier handler may overwrite the 00:00:00 with 12:00:00. Add an internal tag CalendarWriteOwner and gate the write:

if (GetTagWord("CalendarWriteOwner") == 1) return;
SetTagChar("BeginDate", datetime);

Issue 4 - 12-hour vs 24-hour conversion. On runtime stations with US locale and 12-hour clock, the parser may interpret "00:00:00" as a 12-hour-format string (12:00 AM) and display it as "12:00:00 AM". Force 24-hour format by using uppercase HH instead of lowercase hh in the I/O field Output format. Lowercase hh is interpreted as 1-12 with AM/PM suffix; uppercase HH is interpreted as 00-23 without suffix.

Issue 5 - Tag type mismatch. Confirm the internal tag is "Date/Time" and not "String" or "Text tag". A String tag will store the literal text "2024-11-25 00:00:00" without FILETIME conversion, and any I/O field formatted as Date/Time will interpret the string as an invalid date and display 12:00:00. Open Tag Management, right-click the tag, and verify the Type column.

Verification and Diagnostic Logging

After deploying the script, verify with the following checklist:

1. Open the WinCC Tag Management and confirm BeginDate is of type "Date/Time" with a correct update cycle (typically 1 s for tag logging or 500 ms for fast HMI feedback).
2. Launch the runtime and select three different dates in the Calendar ActiveX. The internal tag must update on each click.
3. Open the diagnostics window (Ctrl+Alt+D in WinCC Explorer) and inspect the DiagCalendarWriteError tag value. A nonzero value indicates a SetTagChar or parse failure.
4. Use the WinCC Channel Diagnosis tool (Start > Programs > Siemens Automation > SIMATIC > WinCC > Tools > Channel Diagnosis) to confirm the tag is being broadcast on the configured connection (MPI, PROFIBUS, PROFINET, EtherNet/IP, or TCP/IP).
5. Export the tag value via the WinCC User Archive or OPC UA server and verify the FILETIME value corresponds to the expected date and 23:59:59 / 00:00:00 time. A correct 00:00:00 writes as a FILETIME value with the trailing 24 bits zero (since 23:59:59.9999999 has all bits set).
6. Cross-check with a PLC DATE_AND_TIME block on the S7 side. If the PLC displays a different date or time, the connection mapping is incorrect; verify the tag's address mapping in the Connection properties dialog.

Add temporary logging by writing the constructed string to an internal String tag:

SetTagChar("DiagLastCalendarValue", datetime);

This allows field engineers to inspect the exact string passed to SetTagChar without attaching a debugger. For long-term monitoring, log the diagnostic tag and the constructed string to a WinCC Tag Logging archive with a 1-second acquisition cycle and a 24-hour retention window.

Troubleshooting Matrix

Alternative Implementation in VBScript

On WinCC Professional V15.1 and later, VBScript is the recommended scripting language and is fully supported alongside C-Script. The equivalent VBScript implementation is more concise because VBScript handles type coercion and locale-aware date parsing natively:

Function OnCalendarChange(ByVal lpszPictureName, ByVal lpszObjectName, ByVal lpszPropertyName)
    Dim dia
    Dim dt
    Dim iso

    dia = HMIRuntime.Tags("CalendarBeginDate").Read  ' for SmartTag read
    dia = GetPropChar(lpszPictureName, "CalendarBeginDate", "Value")

    If IsNull(dia) Or Len(dia) = 0 Then
        HMIRuntime.Tags("DiagCalendarWriteError").Write 1
        Exit Function
    End If

    dt = CDate(dia)
    iso = Year(dt) & "-" & Right("0" & Month(dt), 2) & "-" & Right("0" & Day(dt), 2) & " 00:00:00"

    If HMIRuntime.Tags("BeginDate").Write(iso) = False Then
        HMIRuntime.Tags("DiagCalendarWriteError").Write 3
    Else
        HMIRuntime.Tags("DiagCalendarWriteError").Write 0
    End If
End Function

The CDate function performs locale-aware parsing and avoids the manual sscanf dispatch. The downside is that VBScript performance is approximately 5-10x slower than C-Script for high-frequency tag updates; for a calendar click that fires once per user interaction, this is irrelevant.

Integration with S7 PLC DATE_AND_TIME

When the Date/Time tag is mapped to an S7-1500 or S7-1200 PLC, the WinCC tag uses the DTL or DATE_AND_TIME data type on the PLC side. The mapping in WinCC Tag Management requires:

• Tag type: Date/Time
• PLC address: DBx.DBBy or DBx.DBB0 (8 bytes for DTL: year, month, day, hour, minute, second, millisecond, weekday)
• Conversion: WinCC handles the FILETIME-to-DTL conversion automatically when the tag type is Date/Time.

Verify the round-trip by writing 00:00:00 from the HMI and reading the DTL value back via TIA Portal watch table. A correct write shows DTL#2024-11-25-00:00:00.0. An incorrect write shows DTL#2024-11-25-12:00:00.0 confirming the 12:00:00 fallback in the parser.

FAQ