' +----------------------------------------------------------------------------+
' |                          Jeffrey M. Hunter                                 |
' |                      jhunter@idevelopment.info                             |
' |                         www.idevelopment.info                              |
' |----------------------------------------------------------------------------|
' |      Copyright (c) 1998-2011 Jeffrey M. Hunter. All rights reserved.       |
' |----------------------------------------------------------------------------|
' | FILE       : ExternalCommands.vbs                                          |
' | CLASS      : Miscellaneous Functions                                       |
' | PURPOSE    : Demonstrates how to run external commands from within a       |
' |              script using two different methods:                           |
' |                                                                            |
' |                - Exec()   (WSH Version 5.6 or higher)                      |
' |                - Run()                                                     |
' |                                                                            |
' |              In most cases, you will want to take advantage of the Exec()  |
' |              method as it provides support for standard streams, which     |
' |              makes it easy to capture output from the external commands    |
' |              (command). Keep in mind that the Exec() method is only        |
' |              available in WSH 5.6 or higher.                               |
' | PARAMETERS : None                                                          |
' | USAGE      : cscript ExternalCommands.vbs //NoLogo                         |
' | NOTE       : As with any code, ensure to test this script in a development |
' |              environment before attempting to run it in production.        |
' +----------------------------------------------------------------------------+
 
Option Explicit


' -----------------------------------------------------------------------------
'   - SET GLOBAL VARIABLES AND ANY OBJECTS
'   - CALL MAIN FUNCTION
'   - THEN CLEAN UP OBJECTS AND EXIT SCRIPT
' -----------------------------------------------------------------------------

' Global WSH Objects
Dim g_objShell
Set g_objShell = CreateObject("WScript.Shell")

' Return value for Main. Used to return value to the calling program Or
' operating environment.
Dim g_MAIN_RETURN               

g_MAIN_RETURN = Main

Set g_objShell = Nothing
WScript.Quit(g_MAIN_RETURN)



' //////////////////////////////////////////////////////////////////////////////
' RunExample
'
' This function demonstrates how to call an external command using the
' Run() method. There are several options to the Run() method that controls
' how this script will make the call to the external command. In this
' example method, we will Run the external command and wait for it to 
' complete. Also, while the script is running, it will not pop up a new 
' DOS window to show its output.
'
'     Run(strCommand, [intWindowType], [blnWaitOnReturn]);
'
'          strCommand      - Text string of command to run
'          intWindowType   - How to display window:
'                               0 = Hides the window.
'                               1 = Displays and activates new window with
'                                   original size and position.
'                               2 = Activates window in minimized form.
'                               3 = Activates window in maximized form.
'                               4 = Displays new window (original size and
'                                   position) but keeps active window active.
'                               5 = Activates and displays window in current
'                                   size and position.
'                               6 = Minimizes specified window and activates
'                                   the next window down (in z-order).
'                               7 = Minimizes new window but keeps active
'                                   window active.
'                               8 = Displays window in current state, but keeps
'                                   active window active.
'                               9 = Restores a minimized window to its original
'                                   size and position.
'                               10 =Displays the new window based on the
'                                   current state of the calling programs'
'                                   window.
'          blnWaitOnReturn - Should the script wait until command is complete?
'                               True  = Wait
'                               False = No wait
'
' Returns
'      Integer value returned from the external command.
' //////////////////////////////////////////////////////////////////////////////

Function RunExample
    
    Dim strCommand, errRetValue

    strCommand = "%comspec% /C ping 127.0.0.1"
    errRetValue = g_objShell.Run(strCommand, 0, True)
                                    
    RunExample = errRetValue
    
End Function


' //////////////////////////////////////////////////////////////////////////////
' RunExampleCaptureOutput
'
' This function demonstrates how to call an external command using the
' Run() method while capturing its output. Unlike the WSH Exec() method,
' Run() does not support standard streams able to capture output from
' the external command. This function provides a workaround by creating a
' TextStream object used for reading and writing the commands output to a text
' file.
'
' Returns
'      Integer value returned from the external command.
' //////////////////////////////////////////////////////////////////////////////

Function RunExampleCaptureOutput

    Dim strCommand, strOutput
    Dim strTempEnv, strTempFileName
    Dim errRetValue

    ' Get TEMP Environment variable and Temp file name
    strTempEnv = g_objShell.ExpandEnvironmentStrings("%temp%")
    strTempFileName = strTempEnv & "\runOutput.txt"
    WScript.Echo "Writing output to TEMP file: " & strTempFileName
    
    strCommand = "%comspec% /C ping 127.0.0.1 > " & strTempFileName
    
    errRetValue = g_objShell.Run(strCommand, 0, True)
    
    strOutput = ReadOutput(strTempFileName)
    WScript.Echo strOutput

    RunExampleCaptureOutput = errRetValue
    
End Function


' //////////////////////////////////////////////////////////////////////////////
' ReadOutput
'
' Utility function used to read a text file and return its output.
'
' Returns
'      Text contained in the file.
' //////////////////////////////////////////////////////////////////////////////

Function ReadOutput (strFileName)
    
    Dim objFSO
    Dim objTextFile, strOutput
    
    Set objFSO = CreateObject("Scripting.FileSystemObject")
    
    If (objFSO.FileExists(strFileName)) Then
        Set objTextFile = objFSO.OpenTextFile(strFileName, 1, False)
        strOutput = ""
        Do While objTextFile.AtEndOfStream <> True
            strOutput = strOutput & objTextFile.ReadLine() & VbCrLf
        Loop
        objTextFile.Close
    Else
        strOutput = "ERROR: File not found!"
    End If
                                    
    ReadOutput = strOutput
    
End Function


' //////////////////////////////////////////////////////////////////////////////
' ExecExample
'
' This function demonstrates how to call an external command using the
' Exec() method while capturing its output. The Exec() method was introduced
' in WSH 5.6. For versions of WSH prior to 5.6, you will need to use the Run()
' method.
'
' The Exec() method returns a WshScriptExec object. This object provides 
' support for standard streams (StdIn, StdOut, and StdErr), making it possible
' to "capture" the output of the external command. 
'
' Returns
'      Integer value returned from the external command.
' //////////////////////////////////////////////////////////////////////////////

Function ExecExample
    
    Dim strCommand, objWshScriptExec, objStdOut, strOutput

    strCommand = "%comspec% /C ping 127.0.0.1"
    Set objWshScriptExec = g_objShell.Exec(strCommand)
    
    Set objStdOut = objWshScriptExec.StdOut
    strOutput = ""
    While Not objStdOut.AtEndOfStream
        strOutput = strOutput & objStdOut.ReadLine() & VbCrLf
    Wend
    WScript.Echo strOutput
    
    ExecExample = 0
        
End Function


' //////////////////////////////////////////////////////////////////////////////
' | Main
' |
' | Main function used to enclose the primary script logic.
' | 
' | Returns
' |     Exit code from primary script logic.
' //////////////////////////////////////////////////////////////////////////////

Function Main
    
    Dim errRetValue


    WScript.Echo "-----------------------------------------"
    WScript.Echo "Run Example"
    WScript.Echo "-----------------------------------------"
    
    errRetValue = RunExample

    If (errRetValue = 0) Then
        WScript.Echo "Success!" + VbCrLf
    Else
        WScript.Echo "Error! (Return value = " + errRetValue + ")" + VbCrLf
    End If


    WScript.Echo "-----------------------------------------"
    WScript.Echo "Run Example - (Capture Output)"
    WScript.Echo "-----------------------------------------"
    
    errRetValue = RunExampleCaptureOutput

    If (errRetValue = 0) Then
        WScript.Echo "Success!" + VbCrLf
    Else
        WScript.Echo "Error! (Return value = " + errRetValue + ")" + VbCrLf
    End If


    WScript.Echo "-----------------------------------------"
    WScript.Echo "Exec Example"
    WScript.Echo "-----------------------------------------"
    
    errRetValue = ExecExample

    If (errRetValue = 0) Then
        WScript.Echo "Success!" + VbCrLf
    Else
        WScript.Echo "Error! (Return value = " + errRetValue + ")" + VbCrLf
    End If



    Main = 0

End Function