WinExec
WinExec is a built-in scripting function that executes a Windows command as if it was entered at the command prompt.
| Function | Group | Execution | Windows | Embedded | Thin Client | Mobile Access |
|---|---|---|---|---|---|---|
| WinExec | Module Activity | Asynchronous | Supported | Supported (see notes) | Supported | Not supported |
Syntax
- strCommand
- The command to be executed.
- optNumState
- The initial state of the program (if any) that is run by the command:
Value Description 0 Hides the program and gives control to another one. 1 Activates and displays the program. 2 Activates the program and displays it as an icon. 3 Activates the program and maximizes it. 4 Shows the program at its recent size. The program is still active. 7 Shows the program as an icon. The program is still active. This is an optional parameter. If no value is specified, then the default value is 1.
Note: This parameter is not supported on Windows Embedded target systems; regardless of what value is actually specified, the function is executed as if the default value is specified. - optNumSync
- A setting that specifies whether the command will execute synchronously or asynchronously:
Value Description 0 Execute asynchronously; the function will return immediately. 1 Execute synchronously; the function will return when the command has finished executing. This is an optional parameter. If no value is specified, then the default value is 0.
Tip: To verify that a command executed asynchronously has finished, use the optTagReturnOrHandle parameter below and the WinExecIsRunning function. - optTagReturnOrHandle
- The name of a project tag that will store feedback about the execution of the command:
- If the command is executed asynchronously, then the tag will receive a handle that can used with the WinExecIsRunning function to determine whether the command is still running.
- If the command is executed synchronously, then the tag will receive the command’s exit code. (This is separate from the function’s own returned value.)
This is an optional parameter, but given its nature, there is no default value.
Note: The tag name should be enclosed in quotes, as shown in the syntax diagram, or else the function will try to use the value of the tag.
Returned value
This function returns the following possible values:
| Value | Description |
|---|---|
| 0 | Command was not executed successfully. |
| 1 | Command was executed successfully. |
Please note that this indicates only whether the command started its execution successfully, particularly if it is executed asynchronously. It does not indicate when or how the command finished its execution.
Examples
Start Notepad, and then immediately continue to the next line of the script:
WinExec( "C:WindowsSystem32notepad.exe", 4 )
Start MS Paint, and then immediately continue to the next line of the script:
WinExec( "C:WindowsSystem32mspaint.exe" )
Call a batch file, execute it in hidden mode, wait until it’s finished before continuing, and then store the exit code in the tag return:
WinExec( "CMD /C call C:TempMyBatch.bat", 0, 1, "return" )
Call a VBScript file, execute it in hidden mode, and then immediately continue, storing the handle in the tag handle:
WinExec( "CMD /C call C:TempMyScript.vbs", 0, 0, "handle" )
Note: Calling VBScript files is not supported on Windows Embedded target systems.