Reading Tags from CSV Files in WinCC Runtime via VBScript

WinCC Runtime (TIA Portal) exposes a VBScript host in which user scripts can read external CSV or TXT files, parse the values, and write them directly into HMI/PLC tags. This article documents the two field-proven methods, the FSO (FileSystemObject) line-by-line reader and the ADODB OLE DB provider, and ties them to Siemens' official scripting model, diagnostic utilities, and the WinCC Unified CSV export path introduced in TIA Portal V17 and refined in V21.

1. Overview

On a WinCC Runtime PC station (RT Professional, RT Advanced, or Unified), tags in the tag management are normally sourced from a connected PLC (S7-1200, S7-1500, S7-300/400) or from internal tag memory. In some machine applications the engineering requirement is the opposite: WinCC must consume data generated by an external system, a MES export, a recipe file, a barcode scanner log, or a third-party tool, where that data is delivered as a comma- or semicolon-separated text file on the local file system.

Because WinCC Runtime is built on a Windows process (CCEServer / CCAgent) and embeds a VBScript engine, any standard Windows COM automation object is available to a script. The two COM libraries most often used for CSV consumption are:

2. Prerequisites

1. WinCC Runtime installed on the PC station (RT Professional V13 SP1+ or RT Advanced V13 SP1+; for the Unified workflow described in section 7, TIA Portal V17+ with the WinCC Unified PC Runtime installed).
2. The HMI tag that will receive the imported value must exist in the project tag table. External tags pointing to a non-existent internal variable will produce a Tag not found runtime error.
3. The CSV/TXT file must be reachable from the WinCC Runtime user account (default: the user that started CCEServer / CCAgent). A UNC path requires read permission for that account; a local path under the project folder is preferred.
4. The Filename tag configured in the tag table should be an internal String tag, used by the script to receive the target file path at runtime.
5. VBScript debugging should be enabled. In TIA Portal, under Project > Runtime settings > Scripts, enable Activate global script diagnostics so that HMIRuntime.Trace output is captured.

3. Architecture: How the Script Talks to the Tag System

The WinCC Runtime VBScript host exposes a single root automation object, HMIRuntime, plus optional HMIRuntime aliases depending on the TIA version. The relevant child collections are:

Each tag object returned by HMIRuntime.Tags("Name") exposes .Value (read/write), .Read, .Write, .Name, .QualityCode, and .LastError. The .Value property is a Variant; conversions to CStr, CDbl, CLng must be explicit to avoid type-mismatch runtime errors.

4. Method 1 - Scripting.FileSystemObject (FSO)

The FSO approach is the simplest and is the recommended starting point when the CSV has a known, stable column order and a single delimiter. The reference script below is the canonical example that has shipped across multiple Siemens Knowledge Base and forum threads and remains the baseline pattern in V13 SP1 through V17 projects.

4.1 Reference script

Sub OnClick(Byval Item)
    Dim tagName, tagValue, tagFilename
    Dim strFilename, strLine, arrItems
    Dim fso, objFile, objTag

    Set tagFilename = HMIRuntime.Tags("Filename")
    Set fso = CreateObject("Scripting.FileSystemObject")

    strFilename = tagFilename.Read

    If fso.FileExists(strFilename) Then
        HMIRuntime.Trace "VB-Script: read file: " & strFilename & vbCrLf

        Set objFile = fso.OpenTextFile(strFilename, 1)  ' 1 = ForReading
        Do
            strLine = objFile.ReadLine
            arrItems = Split(strLine, ";", -1, 1)
            tagName  = CStr(arrItems(0))
            tagValue = CDbl(arrItems(1))

            HMIRuntime.Trace tagName & "   Value: " & tagValue & vbCrLf

            Set objTag = HMIRuntime.Tags(tagName)
            objTag.Value = tagValue
            objTag.Write
        Loop Until objFile.AtEndOfStream

        objFile.Close  ' close AFTER the Else branch falls through
    Else
        HMIRuntime.Trace "File: " & strFilename & " not found!" & vbCrLf
    End If
End Sub

4.2 Step-by-step explanation

1. Get the file path. The internal tag Filename is read with tagFilename.Read. The full path can be a local absolute path (D:\Project\Tags.csv) or a UNC path (\\MES-SRV\Export\Tags.csv).
2. Create the FSO. CreateObject("Scripting.FileSystemObject") instantiates the Microsoft Scripting Runtime. The reference is held in fso and is used only for FileExists and OpenTextFile.
3. Verify the file. fso.FileExists(strFilename) returns False for directories and for files the WinCC user has no read access to. The Else branch logs to HMIRuntime.Trace and exits the Sub.
4. Open for reading. OpenTextFile(path, 1) opens the file in ForReading mode (Unicode or ASCII, depending on the file's BOM). OpenAsTextStream is an alternative for an existing File object.
5. Read and parse. objFile.ReadLine returns a line without the newline character. Split(strLine, ";", -1, 1) uses -1, 1 for the limit and compare arguments: -1 means "return all substrings", and 1 means TextCompare (case-insensitive), which is irrelevant for the delimiter but harmless.
6. Type-cast values. CStr and CDbl are required because the FSO returns Variants. CDbl honours the system locale: on a German engineering station CDbl("3,14") returns 3.14, but CDbl("3.14") returns 314 because the decimal separator is locale-specific. See section 8.
7. Write to the HMI tag. The .Value = tagValue assignment updates the in-memory copy; .Write commits the value to the runtime database so connected PLCs / consumers see the new value.
8. Close the file. objFile.Close must be reached on the success path. The Loop Until objFile.AtEndOfStream form means the loop body executes at least once, so always close the file after the loop ends.

4.3 Common file-format considerations

5. Method 2 - ADODB Connection to the CSV

When the CSV file is large, has many columns, or contains quoted fields with embedded delimiters, the FSO loop becomes fragile. WinCC VBScript can host the standard ADODB stack, allowing the script to treat the CSV directory as an OLE DB data source and execute SQL queries against it.

5.1 Required file: Schema.ini

The Microsoft Text Driver (ACE.OLEDB or JET.OLEDB) reads column types from a Schema.ini file placed in the same directory as the CSV. Example:

[Tags.csv]
Format=Delimited(;)
CharacterSet=ANSI
ColNameHeader=True
Col1=TagName Char Width 64
Col2=TagValue Double
Col3=Timestamp Char Width 30

5.2 Reference ADODB script

Sub OnClick(Byval Item)
    Dim sPath, sFile, conn, rs
    Dim objTag

    sPath = HMIRuntime.Tags("CsvFolder").Read   ' e.g. D:\Project\CSV
    sFile = "Tags.csv"

    Set conn = CreateObject("ADODB.Connection")
    conn.Open "Provider=Microsoft.ACE.OLEDB.12.0;" & _
              "Data Source=" & sPath & ";" & _
              "Extended Properties="text;HDR=YES;FMT=Delimited(;);";"

    Set rs = CreateObject("ADODB.Recordset")
    rs.Open "SELECT TagName, TagValue FROM Tags.csv", conn, 3, 1

    Do Until rs.EOF
        Set objTag = HMIRuntime.Tags(rs.Fields("TagName").Value)
        objTag.Value = CDbl(rs.Fields("TagValue").Value)
        objTag.Write
        rs.MoveNext
    Loop

    rs.Close
    conn.Close
    Set rs   = Nothing
    Set conn = Nothing
End Sub

5.3 Notes on the provider

• On a 32-bit WinCC Runtime (the default for V13-V17 PC RT), the 32-bit ACE provider Microsoft.ACE.OLEDB.12.0 must be installed. The 64-bit provider cannot be loaded into a 32-bit process.
• On a 64-bit WinCC Unified Runtime, install the matching 64-bit ACE provider.
• The legacy Microsoft.Jet.OLEDB.4.0 provider is 32-bit only and is no longer shipped with current Windows builds; avoid it for new projects.
• The Extended Properties string is case-sensitive on some driver versions. Use text;HDR=YES;FMT=Delimited(;); exactly as shown.

6. Reading the HMIRuntime.Trace Output

Trace output is essential for debugging a CSV reader. There are three reliable ways to see HMIRuntime.Trace messages in WinCC RT Advanced V13 SP1+:

1. Global Script Diagnostics window (RT Professional only): add an Application Window of type Global Script / GSC-Diagnose to a WinCC picture. This option is not available on RT Advanced panels.
2. apdiag.exe - Output Window: launch apdiag.exe from the WinCC installation, then choose Output Window > Open. The default install path on a V13 SP1 PC station is C:\Program Files (x86)\Siemens\Automation\SCADA-RT_V11\WinCC\uTools\apdiag.exe; on V17 it is C:\Program Files\Siemens\Automation\WinCC RT Advanced\uTools\apdiag.exe.
3. apdiag.exe - OnFile: in the same tool, choose Diagnostics > OnFile and enable printf to file. Trace messages are written to rolling text files named onprintfX.txt in C:\Program Files (x86)\Siemens\WinCC\diagnose\ (or the equivalent path on a newer installation).

7. WinCC Unified - Native CSV Export of Runtime Data

If the goal is not to read a CSV into WinCC but to write WinCC Runtime data out to a CSV (for analytics, MES handover, or post-processing), TIA Portal V17 introduced a native control in the Unified UI, refined further in V19, V20, and V21. The official Siemens documentation describes the workflow as follows:

1. Add a control from the My controls toolbar category onto a Unified screen.
2. Bind the control to the HMI tag(s) whose values should be exported.
3. Use the Export to CSV action on the toolbar of the control at Runtime to save the current values of the bound tag to a CSV file on the local file system.
4. The exported file uses the standard Unicode CSV encoding and respects the configured column order from the control's tag binding.

For the full step list, screenshots, and the supported tag types, see the Siemens TIA Portal Help for WinCC Unified: Further processing RT data via CSV (RT Unified) - WinCC Unified. The same article exists in the V17, V18, V19, and V20 documentation sets under the equivalent menu path.

8. Tag Type Handling and Locale Pitfalls

The most common runtime failure on a CSV import script is a type mismatch. Tag the column types in your CSV ahead of time and match them to the HMI tag data type.

9. Error Handling Pattern

Wrap each block that touches the file system or the tag database with On Error Resume Next + Err.Number checks. The reference block below covers the four most common failures (file missing, file locked, tag not found, type mismatch):

Sub OnClick(Byval Item)
    On Error Resume Next
    Dim fso, objFile, strLine, arrItems
    Dim strFilename, tagName, tagValue, objTag

    Set fso = CreateObject("Scripting.FileSystemObject")
    strFilename = HMIRuntime.Tags("Filename").Read

    If Err.Number <> 0 Then
        HMIRuntime.Trace "ERR read Filename tag: " & Err.Description & vbCrLf
        Exit Sub
    End If

    If Not fso.FileExists(strFilename) Then
        HMIRuntime.Trace "File not found: " & strFilename & vbCrLf
        Exit Sub
    End If

    Set objFile = fso.OpenTextFile(strFilename, 1)
    If Err.Number <> 0 Then
        HMIRuntime.Trace "ERR opening file (locked?): " & Err.Description & vbCrLf
        Exit Sub
    End If

    Do Until objFile.AtEndOfStream
        strLine = objFile.ReadLine
        If Len(strLine) > 0 Then
            arrItems = Split(strLine, ";", -1, 1)
            If UBound(arrItems) >= 1 Then
                tagName  = CStr(arrItems(0))
                tagValue = CDbl(arrItems(1))
                Set objTag = HMIRuntime.Tags(tagName)
                If Err.Number = 0 Then
                    objTag.Value = tagValue
                    objTag.Write
                Else
                    HMIRuntime.Trace "ERR tag " & tagName & ": " & Err.Description & vbCrLf
                    Err.Clear
                End If
            End If
        End If
    Loop
    objFile.Close
End Sub

10. Performance and File I/O Best Practices

• Avoid polling. Do not put a tight Do ... Loop with a fixed sleep in a cyclic script. Trigger the import on a button click, on a value change of a tag, or with a once-per-minute scheduler tag driven by the PLC.
• Cache the FSO. Create the FileSystemObject once per Sub and set it to Nothing at the end. Re-creating it on every call adds ~5-20 ms of overhead.
• Limit the file size. FSO ReadLine on a 50,000-line CSV will block the VBScript thread for seconds and freeze the screen. For large imports, use the ADODB method with a SELECT TOP N clause.
• Disable screen updates during bulk writes. On RT Professional, call HMIRuntime.Screens.Item("Main").ScreenItems(...).Visible = False on heavy-import tags whose faceplates would otherwise repaint per value change.
• Validate before write. Add a small whitelist check (If tagName = "Recipe.MaxPressure" Then ...) to prevent an attacker who can write to the CSV from injecting arbitrary tag names.

11. Step-by-Step Implementation (Tia Portal V17 example)

1. In the TIA Portal project, open the HMI device (PC station with RT Professional or RT Advanced).
2. In the project tree, expand HMI tags and add an internal String tag named Filename. Add a second internal tag CsvFolder if you are using the ADODB method.
3. Add the destination tags (e.g. Recipe.SetpointPressure, Recipe.SetpointFlow) and ensure their data type matches the CSV columns.
4. Open a screen, add a button, and configure the Click event to call a VBScript action.
5. Paste the FSO reference script (section 4.1) or the ADODB reference script (section 5.2) into the action editor.
6. Compile and download the project to the PC station.
7. Start WinCC Runtime. Click the button. The script reads the configured CSV and writes the values to the HMI tags, which are then available to the connected S7-1200 via area pointers or to faceplates via tag bindings.
8. For verification, open apdiag.exe as described in section 6 and confirm the trace lines appear in order.

12. Verification Procedure

1. File reachability: confirm the Filename tag holds a valid path. A typo silently falls into the Else branch and the only symptom is "File not found" in the trace.
2. Tag existence: check that every tagName in the CSV exists in the project tag table. An unknown tag raises Err.Number 0x8004271A (tag not found).
3. Type match: confirm each value converts cleanly. Add a try/catch with CDbl wrapped in On Error Resume Next to catch type mismatches.
4. Trace log: confirm the trace output shows one <tag> Value: <value> line per imported row.
5. PLC feedback: if the imported tag is connected to the S7-1200 (e.g. via a connection in Connections), watch the corresponding DB on the PLC in TIA Portal's Monitor & Force to confirm the value reached the controller.
6. HMI display: bind an I/O field to the imported tag and confirm the value updates on screen after the button click.

13. Troubleshooting Matrix

14. FAQ