Shell Function

Runs an executable program and returns a Variant (Double) representing the program's task ID if successful, or zero if unsuccessful.

Syntax

Shell(pathname, [windowstyle])

Parameters

pathname - Required. String expression specifying the name of the program to execute, along with any required arguments or command-line switches. May include directory or folder path.
windowstyle - Optional. Variant (Integer) corresponding to the style of the window in which the program is to be run. If omitted, the program is started minimized with focus.

Window Style Values

Constant	Value	Description
vbHide	0	Window is hidden and focus is passed to the hidden window
vbNormalFocus	1	Window has focus and is restored to its original size and position
vbMinimizedFocus	2	Window is displayed as an icon with focus
vbMaximizedFocus	3	Window is maximized with focus
vbNormalNoFocus	4	Window is restored to most recent size and position; currently active window remains active
vbMinimizedNoFocus	6	Window is displayed as an icon; currently active window remains active

Return Value

Returns a Variant (Double) containing the task ID of the started program: - If successful: Returns the task ID (a unique identifier for the process) - If unsuccessful: Returns 0 - Task ID can be used with AppActivate statement to give focus to the window

Remarks

The Shell function runs an executable program asynchronously. This means that a program started with Shell might not finish executing before the statements following the Shell function are executed. Key characteristics: - Executes programs asynchronously (doesn't wait for completion) - Returns immediately after starting the program - Can launch any executable file (.exe, .com, .bat, .cmd, etc.) - Can include command-line arguments in pathname - Task ID can be used with AppActivate to switch focus - If program cannot be started, returns 0 - On error, generates Error 5 (Invalid procedure call) or Error 53 (File not found) The pathname can include: - Full path to executable: "C:\Windows\notepad.exe" - Relative path: "....\tools\mytool.exe" - Program in system PATH: "notepad.exe" - Command with arguments: "notepad.exe C:\readme.txt" Important considerations: - Shell executes asynchronously - use AppActivate or API calls to synchronize - No direct way to know when shelled program terminates from VB6 - Can't capture standard output/error directly (use API or temp files) - Security: Be cautious with user-supplied paths to avoid injection - Long filenames with spaces should be enclosed in quotes

Typical Uses

Launch Applications: Open external programs from your VB6 app
Open Documents: Launch files with associated applications
Run Batch Files: Execute .bat or .cmd scripts
Execute Commands: Run command-line tools
System Tools: Open Windows utilities (calc, notepad, etc.)
Background Tasks: Start processes that run independently
Integration: Interact with other applications
File Operations: Use command-line tools for file manipulation

Basic Examples

' Example 1: Open Notepad
Dim taskId As Double
taskId = Shell("notepad.exe", vbNormalFocus)
If taskId = 0 Then
    MsgBox "Failed to start Notepad"
End If

' Example 2: Open file with Notepad
Dim taskId As Double
taskId = Shell("notepad.exe C:\readme.txt", vbNormalFocus)

' Example 3: Run Calculator maximized
Dim taskId As Double
taskId = Shell("calc.exe", vbMaximizedFocus)

' Example 4: Execute batch file hidden
Dim taskId As Double
taskId = Shell("C:\Scripts\backup.bat", vbHide)

Common Patterns

Pattern 1: `SafeShell`

Execute program with error handling

Function SafeShell(programPath As String, Optional windowStyle As Integer = vbNormalFocus) As Double
    On Error Resume Next
    SafeShell = Shell(programPath, windowStyle)
    If Err.Number <> 0 Then
        MsgBox "Error starting program: " & Err.Description, vbExclamation
        SafeShell = 0
    End If
End Function

Pattern 2: `ShellAndWait`

Execute program and wait for completion (using AppActivate)

Function ShellAndWait(programPath As String, windowStyle As Integer) As Boolean
    Dim taskId As Double
    Dim startTime As Double
    On Error GoTo ErrorHandler
    taskId = Shell(programPath, windowStyle)
    If taskId = 0 Then
        ShellAndWait = False
        Exit Function
    End If
    ' Give the program time to start
    DoEvents
    ' Wait for program window to exist
    startTime = Timer
    Do While Timer - startTime < 30  ' 30 second timeout
        On Error Resume Next
        AppActivate taskId
        If Err.Number = 0 Then Exit Do
        Err.Clear
        DoEvents
    Loop
    ShellAndWait = True
    Exit Function
ErrorHandler:
    ShellAndWait = False
End Function

Pattern 3: `QuotePath`

Ensure path is properly quoted for spaces

Function QuotePath(path As String) As String
    If InStr(path, " ") > 0 And Left(path, 1) <> """" Then
        QuotePath = """" & path & """"
    Else
        QuotePath = path
    End If
End Function
' Usage:
taskId = Shell(QuotePath("C:\Program Files\MyApp\app.exe"), vbNormalFocus)

Pattern 4: `OpenFileWithApp`

Open file with specific application

Function OpenFileWithApp(appPath As String, filePath As String, _
                         Optional windowStyle As Integer = vbNormalFocus) As Boolean
    Dim commandLine As String
    Dim taskId As Double
    ' Quote paths if they contain spaces
    If InStr(appPath, " ") > 0 Then appPath = """" & appPath & """"
    If InStr(filePath, " ") > 0 Then filePath = """" & filePath & """"
    commandLine = appPath & " " & filePath
    On Error Resume Next
    taskId = Shell(commandLine, windowStyle)
    OpenFileWithApp = (taskId <> 0 And Err.Number = 0)
End Function

Pattern 5: `ExecuteCommand`

Execute command-line command

Function ExecuteCommand(command As String, Optional waitSeconds As Integer = 0) As Double
    Dim taskId As Double
    Dim endTime As Double
    On Error GoTo ErrorHandler
    ' Run command via cmd.exe
    taskId = Shell("cmd.exe /c " & command, vbHide)
    If waitSeconds > 0 Then
        endTime = Timer + waitSeconds
        Do While Timer < endTime
            DoEvents
        Loop
    End If
    ExecuteCommand = taskId
    Exit Function
ErrorHandler:
    ExecuteCommand = 0
End Function

Pattern 6: `LaunchAndActivate`

Launch program and bring to front

Function LaunchAndActivate(programPath As String) As Boolean
    Dim taskId As Double
    Dim attempts As Integer
    On Error Resume Next
    taskId = Shell(programPath, vbNormalFocus)
    If taskId = 0 Then
        LaunchAndActivate = False
        Exit Function
    End If
    ' Try to activate window
    For attempts = 1 To 10
        DoEvents
        AppActivate taskId
        If Err.Number = 0 Then
            LaunchAndActivate = True
            Exit Function
        End If
        Err.Clear
    Next attempts
    LaunchAndActivate = False
End Function

Pattern 7: `CheckProgramExists`

Verify program exists before shelling

Function CheckProgramExists(programPath As String) As Boolean
    On Error Resume Next
    CheckProgramExists = (Dir(programPath) <> "")
End Function
' Usage:
If CheckProgramExists("C:\Tools\mytool.exe") Then
    taskId = Shell("C:\Tools\mytool.exe", vbNormalFocus)
Else
    MsgBox "Program not found"
End If

Pattern 8: `ShellWithTimeout`

Execute with timeout detection

Function ShellWithTimeout(programPath As String, timeoutSeconds As Integer) As Boolean
    Dim taskId As Double
    Dim startTime As Double
    On Error GoTo ErrorHandler
    taskId = Shell(programPath, vbNormalFocus)
    If taskId = 0 Then
        ShellWithTimeout = False
        Exit Function
    End If
    startTime = Timer
    Do While Timer - startTime < timeoutSeconds
        DoEvents
    Loop
    ShellWithTimeout = True
    Exit Function
ErrorHandler:
    ShellWithTimeout = False
End Function

Pattern 9: `OpenDocument`

Open document with default application

Function OpenDocument(filePath As String) As Boolean
    Dim taskId As Double
    On Error Resume Next
    ' Use "start" command to open with default app
    taskId = Shell("cmd.exe /c start """" """ & filePath & """", vbHide)
    OpenDocument = (taskId <> 0 And Err.Number = 0)
End Function

Pattern 10: `RunBatchFile`

Execute batch file with parameters

Function RunBatchFile(batchPath As String, parameters As String, _
                      Optional hideWindow As Boolean = True) As Double
    Dim commandLine As String
    Dim windowStyle As Integer
    If InStr(batchPath, " ") > 0 Then
        commandLine = """" & batchPath & """"
    Else
        commandLine = batchPath
    End If
    If Len(parameters) > 0 Then
        commandLine = commandLine & " " & parameters
    End If
    windowStyle = IIf(hideWindow, vbHide, vbNormalFocus)
    On Error Resume Next
    RunBatchFile = Shell(commandLine, windowStyle)
End Function

Advanced Usage

Example 1: `ProcessLauncher` Class

Manage launching and tracking external processes

' Class: ProcessLauncher
Private m_processes As Collection
Private Type ProcessInfo
    TaskId As Double
    ProgramPath As String
    LaunchTime As Date
    Description As String
End Type
Private Sub Class_Initialize()
    Set m_processes = New Collection
End Sub
Public Function LaunchProcess(programPath As String, _
                              Optional description As String = "", _
                              Optional windowStyle As Integer = vbNormalFocus) As Double
    Dim taskId As Double
    Dim procInfo As ProcessInfo
    On Error GoTo ErrorHandler
    taskId = Shell(programPath, windowStyle)
    If taskId <> 0 Then
        procInfo.TaskId = taskId
        procInfo.ProgramPath = programPath
        procInfo.LaunchTime = Now
        procInfo.Description = description
        m_processes.Add procInfo, CStr(taskId)
    End If
    LaunchProcess = taskId
    Exit Function
ErrorHandler:
    LaunchProcess = 0
End Function
Public Function ActivateProcess(taskId As Double) As Boolean
    On Error Resume Next
    AppActivate taskId
    ActivateProcess = (Err.Number = 0)
End Function
Public Function GetProcessCount() As Long
    GetProcessCount = m_processes.Count
End Function
Public Function GetProcessInfo(taskId As Double) As String
    Dim procInfo As ProcessInfo
    On Error Resume Next
    procInfo = m_processes(CStr(taskId))
    If Err.Number = 0 Then
        GetProcessInfo = "Program: " & procInfo.ProgramPath & vbCrLf & _
                        "Description: " & procInfo.Description & vbCrLf & _
                        "Launched: " & procInfo.LaunchTime & vbCrLf & _
                        "Task ID: " & procInfo.TaskId
    Else
        GetProcessInfo = "Process not found"
    End If
End Function
Public Sub ClearProcesses()
    Set m_processes = New Collection
End Sub

Example 2: `CommandExecutor` Module

Execute command-line commands with output capture

' Module: CommandExecutor
Public Function ExecuteCommandWithOutput(command As String, _
                                         ByRef output As String) As Boolean
    Dim tempFile As String
    Dim fileNum As Integer
    Dim commandLine As String
    Dim taskId As Double
    On Error GoTo ErrorHandler
    ' Create temp file for output
    tempFile = Environ("TEMP") & "\cmdout_" & Format(Now, "yyyymmddhhnnss") & ".txt"
    ' Redirect output to temp file
    commandLine = "cmd.exe /c " & command & " > """ & tempFile & """ 2>&1"
    taskId = Shell(commandLine, vbHide)
    If taskId = 0 Then
        ExecuteCommandWithOutput = False
        Exit Function
    End If
    ' Wait for command to complete (primitive wait)
    Sleep 1000  ' Would need to declare Sleep API
    ' Read output file
    fileNum = FreeFile
    Open tempFile For Input As #fileNum
    output = Input(LOF(fileNum), #fileNum)
    Close #fileNum
    ' Clean up
    Kill tempFile
    ExecuteCommandWithOutput = True
    Exit Function
ErrorHandler:
    If fileNum > 0 Then Close #fileNum
    On Error Resume Next
    If Dir(tempFile) <> "" Then Kill tempFile
    ExecuteCommandWithOutput = False
End Function
Public Function RunCommandHidden(command As String) As Boolean
    Dim taskId As Double
    On Error Resume Next
    taskId = Shell("cmd.exe /c " & command, vbHide)
    RunCommandHidden = (taskId <> 0 And Err.Number = 0)
End Function
Public Function RunCommandVisible(command As String) As Double
    On Error Resume Next
    RunCommandVisible = Shell("cmd.exe /k " & command, vbNormalFocus)
End Function

Example 3: `ApplicationLauncher` Class

Launch applications with comprehensive error handling

' Class: ApplicationLauncher
Private m_lastError As String
Private m_lastTaskId As Double
Public Function LaunchApplication(programPath As String, _
                                  Optional arguments As String = "", _
                                  Optional windowStyle As Integer = vbNormalFocus, _
                                  Optional verifyExists As Boolean = True) As Boolean
    Dim fullCommand As String
    On Error GoTo ErrorHandler
    m_lastError = ""
    m_lastTaskId = 0
    ' Verify program exists
    If verifyExists Then
        If Dir(programPath) = "" Then
            m_lastError = "Program not found: " & programPath
            LaunchApplication = False
            Exit Function
        End If
    End If
    ' Build command line
    fullCommand = programPath
    If InStr(fullCommand, " ") > 0 And Left(fullCommand, 1) <> """" Then
        fullCommand = """" & fullCommand & """"
    End If
    If Len(arguments) > 0 Then
        fullCommand = fullCommand & " " & arguments
    End If
    ' Launch
    m_lastTaskId = Shell(fullCommand, windowStyle)
    If m_lastTaskId = 0 Then
        m_lastError = "Shell function returned 0"
        LaunchApplication = False
    Else
        LaunchApplication = True
    End If
    Exit Function
ErrorHandler:
    m_lastError = "Error " & Err.Number & ": " & Err.Description
    LaunchApplication = False
End Function
Public Function LaunchAndActivate(programPath As String, _
                                  Optional arguments As String = "") As Boolean
    Dim success As Boolean
    Dim attempts As Integer
    success = LaunchApplication(programPath, arguments, vbNormalFocus)
    If Not success Then
        LaunchAndActivate = False
        Exit Function
    End If
    ' Try to activate
    For attempts = 1 To 20
        DoEvents
        On Error Resume Next
        AppActivate m_lastTaskId
        If Err.Number = 0 Then
            LaunchAndActivate = True
            Exit Function
        End If
        Err.Clear
    Next attempts
    LaunchAndActivate = False
End Function
Public Property Get LastError() As String
    LastError = m_lastError
End Property
Public Property Get LastTaskId() As Double
    LastTaskId = m_lastTaskId
End Property
Public Function OpenFileWithDefaultApp(filePath As String) As Boolean
    Dim commandLine As String
    ' Use Windows "start" command
    commandLine = "cmd.exe /c start """" """ & filePath & """"
    On Error Resume Next
    m_lastTaskId = Shell(commandLine, vbHide)
    OpenFileWithDefaultApp = (m_lastTaskId <> 0 And Err.Number = 0)
    If Not OpenFileWithDefaultApp Then
        m_lastError = "Failed to open file: " & Err.Description
    End If
End Function

Example 4: `BatchFileRunner` Module

Execute batch files with enhanced functionality

' Module: BatchFileRunner
Public Function ExecuteBatchFile(batchPath As String, _
                                 Optional parameters As String = "", _
                                 Optional visible As Boolean = False, _
                                 Optional workingDir As String = "") As Double
    Dim commandLine As String
    Dim windowStyle As Integer
    Dim originalDir As String
    On Error GoTo ErrorHandler
    ' Verify batch file exists
    If Dir(batchPath) = "" Then
        MsgBox "Batch file not found: " & batchPath, vbExclamation
        ExecuteBatchFile = 0
        Exit Function
    End If
    ' Quote path if needed
    If InStr(batchPath, " ") > 0 Then
        commandLine = """" & batchPath & """"
    Else
        commandLine = batchPath
    End If
    ' Add parameters
    If Len(parameters) > 0 Then
        commandLine = commandLine & " " & parameters
    End If
    ' Change working directory if specified
    If Len(workingDir) > 0 Then
        originalDir = CurDir
        ChDir workingDir
    End If
    ' Execute
    windowStyle = IIf(visible, vbNormalFocus, vbHide)
    ExecuteBatchFile = Shell(commandLine, windowStyle)
    ' Restore directory
    If Len(workingDir) > 0 Then
        ChDir originalDir
    End If
    Exit Function
ErrorHandler:
    If Len(workingDir) > 0 Then
        On Error Resume Next
        ChDir originalDir
    End If
    ExecuteBatchFile = 0
End Function
Public Function RunBatchWithLog(batchPath As String, logPath As String) As Boolean
    Dim commandLine As String
    Dim taskId As Double
    ' Quote paths
    If InStr(batchPath, " ") > 0 Then batchPath = """" & batchPath & """"
    If InStr(logPath, " ") > 0 Then logPath = """" & logPath & """"
    ' Redirect output to log
    commandLine = "cmd.exe /c " & batchPath & " > " & logPath & " 2>&1"
    On Error Resume Next
    taskId = Shell(commandLine, vbHide)
    RunBatchWithLog = (taskId <> 0 And Err.Number = 0)
End Function
Public Function CreateAndRunBatch(commands() As String, _
                                  Optional visible As Boolean = False) As Boolean
    Dim batchPath As String
    Dim fileNum As Integer
    Dim i As Long
    Dim taskId As Double
    On Error GoTo ErrorHandler
    ' Create temp batch file
    batchPath = Environ("TEMP") & "\temp_" & Format(Now, "yyyymmddhhnnss") & ".bat"
    ' Write commands
    fileNum = FreeFile
    Open batchPath For Output As #fileNum
    Print #fileNum, "@echo off"
    For i = LBound(commands) To UBound(commands)
        Print #fileNum, commands(i)
    Next i
    Close #fileNum
    ' Execute
    taskId = Shell(batchPath, IIf(visible, vbNormalFocus, vbHide))
    CreateAndRunBatch = (taskId <> 0)
    Exit Function
ErrorHandler:
    If fileNum > 0 Then Close #fileNum
    CreateAndRunBatch = False
End Function

Error Handling

The Shell function can generate the following errors: - Error 5 (Invalid procedure call or argument): Invalid windowstyle parameter - Error 53 (File not found): Program or path not found - Error 76 (Path not found): Directory in path doesn't exist Always use error handling when executing external programs:

On Error Resume Next
taskId = Shell(programPath, vbNormalFocus)
If Err.Number <> 0 Or taskId = 0 Then
    MsgBox "Error: " & Err.Description
End If

Performance Considerations

Shell executes asynchronously and returns immediately
No performance impact on VB6 app after launch
Multiple programs can be launched simultaneously
Task ID allows tracking and activation
Consider resource usage when launching many programs
Use DoEvents to allow UI updates after Shell

Best Practices

Error Handling: Always wrap Shell in error handling
Path Quoting: Quote paths with spaces using double quotes
Verify Existence: Check file exists before shelling (Dir function)
Security: Validate user input to prevent command injection
Resource Management: Track launched processes
Window Style: Choose appropriate window style for user experience
Wait Strategy: Use AppActivate or API for synchronization if needed
Return Value: Check return value (0 = failure)
Documentation: Document external dependencies
Testing: Test with various paths and edge cases

Method	Purpose	Wait for Completion	Capture Output	Platform
Shell	Execute program	No (async)	No	VB6/VBA
`CreateProcess` API	Execute program	Optional	Optional	Windows API
WScript.Shell.Run	Execute program	Optional	No	WSH
Exec method	Execute program	No	Yes	WSH
`ShellExecute` API	Execute/open files	No	No	Windows API

Platform Considerations

Available in VB6, VBA (Windows only)
Windows-specific function
Task ID is Windows-specific process identifier
Path separators are backslashes ()
Case-insensitive on Windows
Long filename support (use quotes)
Windows versions may affect behavior

Limitations

No built-in way to wait for completion
Cannot capture standard output/error directly
Limited to Windows operating system
Task ID becomes invalid when process terminates
No parent-child process relationship tracking
Cannot pass structured data to launched program
Security risks with user-supplied paths
No control over process priority or environment

AppActivate: Activates a running application window by task ID
CreateObject: Creates automation objects for inter-app communication
SendKeys: Sends keystrokes to active window
Dir: Verifies file existence before shelling
Environ: Gets environment variables for path construction

Shell Function

Syntax

Parameters

Window Style Values

Return Value

Remarks

Typical Uses

Basic Examples

Common Patterns

Pattern 1: SafeShell

Pattern 2: ShellAndWait

Pattern 3: QuotePath

Pattern 4: OpenFileWithApp

Pattern 5: ExecuteCommand

Pattern 6: LaunchAndActivate

Pattern 7: CheckProgramExists

Pattern 8: ShellWithTimeout

Pattern 9: OpenDocument

Pattern 10: RunBatchFile