Opening CHM and PDF Files from HMI Buttons with VBScript

Overview

Opening operator manuals, machine documentation, and compiled HTML Help (CHM) files from a single click on an HMI/SCADA button is a recurring engineering requirement. The portable mechanism is the Wscript.Shell COM automation object invoked from VBScript. The same pattern works on Siemens WinCC, WinCC Professional (TIA Portal), FactoryTalk View SE/ME, Wonderware InTouch, iFIX, and any runtime that exposes VBScript to graphic events. This reference documents the working script, the CHM security traps (Unblock, ITSS protocol), PDF association failures, the ANSI-C equivalent for WinCC, the asynchronous launch variant, and a field-proven troubleshooting matrix.

Prerequisites

Working VBScript for PDF and CHM

The minimum reliable script uses WScript.Shell.Run with the second argument controlling window style. The constant 1 activates the new window and returns when the spawned process exits:

Dim objWshShell
Set objWshShell = CreateObject("Wscript.Shell")
objWshShell.Run "C:\Manuals\test.pdf", 1
Set objWshShell = Nothing

For CHM files the canonical invocation goes through hh.exe. Explicitly prefixing the executable avoids PATH-search issues on stripped runtime images:

Dim objWshShell
Set objWshShell = CreateObject("Wscript.Shell")
objWshShell.Run "hh.exe ""C:\Help\Operator.chm""", 1
Set objWshShell = Nothing

Note the doubled inner quotes required to embed a quoted path inside a VBScript string literal. The hh.exe prefix is optional on a default Windows install but is the safe choice for industrial runtime PCs that may not include %SystemRoot% in the search path of the runtime account.

Path Handling for Files With Spaces and Special Characters

Unquoted paths break the moment a directory name contains a space, such as Program Files, My Documents, or Operating Manual. The Windows command-line parser splits on whitespace and the Run method returns without spawning the process. Always wrap the path in double quotes, and inside a VBScript string literal each quote must be doubled:

Dim objWshShell
Set objWshShell = CreateObject("Wscript.Shell")
Dim sFile
sFile = """C:\Program Files\MyHMI\Docs\Operator Manual.pdf"""
objWshShell.Run sFile, 1
Set objWshShell = Nothing

For dynamic paths assembled from an HMI tag, sanitize the string and verify the file exists with FileSystemObject before calling Run. This avoids silent failures when the operator selects a non-existent part number:

Dim objFSO, objWshShell
Set objFSO     = CreateObject("Scripting.FileSystemObject")
Set objWshShell = CreateObject("Wscript.Shell")

Dim sPath
sPath = "C:\Manuals\" & SmartTags("DocNumber") & ".pdf"

If objFSO.FileExists(sPath) Then
    objWshShell.Run Chr(34) & sPath & Chr(34), 1
Else
    MsgBox "Documentation file not found:" & vbCrLf & sPath, 48, "Open File"
End If

Set objFSO     = Nothing
Set objWshShell = Nothing

Use FSO.GetAbsolutePathName to defeat ..\ traversal in any path that originates from a user-editable tag. Reject any resolved path that does not begin with your whitelisted root.

CHM File Security and the Unblock Requirement

Files downloaded from the internet or extracted from a ZIP archive carry a Zone Identifier alternate data stream (Zone.Identifier) that marks them as untrusted. Windows blocks navigation inside such CHM files through the ITSS / mk:@MSITStore protocol restriction. The error presents as a blank page, a "Navigation to the webpage was canceled" message, or a non-responsive window that opens and immediately closes when launched from a button script. The Unblock step in Microsoft Q&A for CHM file restrictions is the canonical fix:

1. Right-click the .chm file, choose Properties.
2. On the General tab, click the Unblock button.
3. Click OK. The Zone.Identifier NTFS stream is removed.

For unattended or scripted deployment, clear the stream from a command line:

Unblock-File -Path "C:\Help\Operator.chm"
# or with Sysinternals streams.exe
streams.exe -d "C:\Help\Operator.chm"

PDF File Association Failures

Symptom: the VBScript fires, the Run method returns, no window appears, and the operator sees nothing. In the debug window the script reports no error. This is the classic "no handler registered for .pdf" failure mode, or a per-user handler that the runtime service account cannot see.

Verify and repair the file association on the runtime station:

1. Open Settings → Apps → Default apps → Choose default apps by file type.
2. Locate .pdf and confirm a reader (Adobe, Foxit, Edge, SumatraPDF) is set.
3. From a command prompt, confirm the registry entries:

assoc .pdf
:: .pdf=AcroExch.Document.DC
ftype AcroExch.Document.DC
:: "C:\Program Files\Adobe\Acrobat DC\Acrobat\Acrobat.exe" "%1"

If the runtime runs as a service account (typical for WinCC ServiceMode and FactoryTalk View SE), the per-user default-app settings made in an interactive session are not inherited. Apply a machine-scope default association so the service user sees the same handler:

DISM /Online /Export-DefaultAppAssociations:C:\Temp\Assoc.xml
:: Edit Assoc.xml and set .pdf to the desired handler
DISM /Online /Import-DefaultAppAssociations:C:\Temp\Assoc.xml

ANSI-C Equivalent for WinCC (TIA Portal / WinCC Professional)

On Siemens WinCC, WinCC Professional, and TIA Portal HMI you can also script the launch from a C action using the WinAPI ShellExecute. The ShellExecute reference specifies that the return value is greater than 32 on success, and any value from 0 to 32 indicates a specific error.

#include "apdefap.h"
void OnClick(char* lpszPictureName, char* lpszObjectName, char* lpszPropertyName)
{
    long nResult = (long)ShellExecute(
        NULL,
        "open",
        "C:\\Manuals\\test.pdf",
        NULL,
        NULL,
        SW_SHOWNORMAL);

    if (nResult <= 32)
    {
        // 0  = SE_ERR_OOM
        // 2  = ERROR_FILE_NOT_FOUND
        // 3  = ERROR_PATH_NOT_FOUND
        // 11 = ERROR_BAD_FORMAT
        // 27 = SE_ERR_ASSOCINCOMPLETE
        // 31 = SE_ERR_NOASSOC
        printf("ShellExecute failed, code = %ld\r\n", nResult);
    }
}

The SW_SHOWNORMAL constant is defined in winuser.h and corresponds to value 1. The full list of window-state flags is documented at ShowWindow.

Asynchronous Launch Without Blocking the HMI Page

The Run method's second argument controls whether VBScript blocks until the spawned process exits. To open a PDF without freezing the HMI page while the operator has the reader open, wrap the call in a one-shot cmd /c start with the second argument set to 0 (hide the cmd window) and the third argument False (do not wait):

Dim objWshShell
Set objWshShell = CreateObject("Wscript.Shell")
objWshShell.Run "cmd /c start """" """ & "C:\Manuals\Operator.pdf" & """", 0, False
Set objWshShell = Nothing

The two consecutive empty quotes after start are the title argument to cmd start, not an empty pair. Omitting them causes the path itself to be parsed as the title and the file fails to launch.

Error Handling With On Error Resume Next

Wrap the script in On Error Resume Next and explicitly inspect Err.Number so the operator sees a meaningful message instead of a silent no-op:

On Error Resume Next
Dim objWshShell
Set objWshShell = CreateObject("Wscript.Shell")

If Err.Number <> 0 Then
    MsgBox "Cannot create Wscript.Shell: " & Err.Description, 16, "Open File"
    Exit Sub
End If

objWshShell.Run "C:\Manuals\test.pdf", 1

If Err.Number <> 0 Then
    MsgBox "Run failed: " & Err.Description, 16, "Open File"
End If

On Error Goto 0
Set objWshShell = Nothing

Error 429 ("ActiveX component can't create object") is the most common runtime failure and indicates that Wscript.Shell is disabled via group policy or blocked by AppLocker. The relevant policy path is User Configuration → Administrative Templates → Windows Components → Windows Script Host.

FactoryTalk View SE / ME Equivalent

FactoryTalk View SE exposes VBScript on graphic displays through the Command event of a Button object. The same Wscript.Shell object works without modification because the runtime is a normal Windows process. For PanelView Plus (ME) the sandbox restricts CreateObject; use the Launch External Application action of the Button object with the executable set to the registered PDF reader, or place the file in a known path and invoke it through the global Application object.

Troubleshooting Matrix

Security and Hardening Notes

External-file launch is a known vector for malicious payload delivery, especially when the file path is operator-editable. Apply these controls before deploying to production:

• Whitelist the directory and file extensions (.chm, .pdf) in code; reject any other extension.
• Resolve the canonical path with FSO.GetAbsolutePathName and verify it starts with the whitelisted root before launching.
• Strip Zone.Identifier streams from CHMs at deploy time using Unblock-File in a signed setup script.
• Restrict the runtime account to only the directories that legitimately host manuals (NTFS ACL).
• Prefer PDF over CHM for new content; modern PDF readers are more permissive and easier to sanitize than hh.exe.
• Disable Windows Script Host in the engineering image after the script is in production; the SCADA runtime does not need it for anything other than this action, and removing it shrinks the attack surface.

Verification Checklist

1. Click the button on the HMI; the documentation viewer must open within 1 second.
2. Close the viewer; the HMI page must remain responsive and not show a "not responding" overlay.
3. Click again with the target file missing; the operator must see a clear error message, not a silent no-op.
4. Restart the runtime station and re-test; the file association and the Unblock state must survive a reboot.
5. Run a long-duration soak test (one hour of repeated clicks) and confirm no orphaned hh.exe or Acrobat.exe processes accumulate in Task Manager.
6. Re-deploy the CHM/PDF over a file share and confirm the unblock state is preserved by the deploy script.

Edge Cases and Field Notes

Three situations bite during commissioning more often than the basic case:

1. Network paths and CHM: even with the file unblocked, hh.exe refuses to render a CHM from a UNC path. Symptom is a blank window that closes immediately. Workaround is to mirror the file to C:\Help\ on first access.
2. 32-bit vs 64-bit readers: on 64-bit Windows, a VBScript launched by a 64-bit process spawns 64-bit hh.exe, which then spawns 32-bit AcroRd32.exe. The reader is not the registered default and you may see a "choose application" dialog. Force the reader to be the default at machine scope with DISM.
3. Service-mode runtime with no interactive desktop: WinCC in ServiceMode and FactoryTalk View SE in service mode run under session 0 without an interactive desktop. Wscript.Shell.Run still works (the new process is created in the same session), but the operator cannot see the window if the session is not bridged. Verify the runtime configuration creates a window station the operator can view.