ShellWait – System Function

Usage

The ShellWait function executes a program (.exe, .com, .bat, .doc, .txt, …) and waits for its termination before running the next statement.

The main usage of the ShellWait function is to start a DOS application, a batch file, or a console application and to wait until the application has finished before moving to the next step. Using ShellWait, you can launch a DOS command such as xcopy and the next step will be executed only when the file copy has finished.

Syntax

ShellWait (<command$>, <mode>, <timeout>[, <processExitCode>[, output$]])

or

ret = ShellWait (<command$>, <mode>, <timeout>[, <processExitCode>[, output$]])

Parameters

• <command$>: string, name of the program to be run with any parameters (parameters must be strings).
• <mode>: specifies window size during execution: 1 for normal execution, 2 for minimized execution, 3 for maximized execution, 4 for hidden (character-mode applications), 5 for hidden and when <timeout> is elapsed, the process is killed (in mode 4, the process is not killed).
• <timeout>: specifies the timeout in seconds. If after <timeout> seconds, the program launched by <command$> is not terminated, return code ret is set to -1. If <timeout> is set to 0, there is no limitation for execution duration.
• <processExitCode>: optional integer variable; it gives the return code of the program launched by <command$> at its termination. If <timeout> has been reached before program termination, <processExitCode> is set to -1.
• output$: optional string containing the two outputs stdout and stderr (only if <mode> is set to 4 or 5). It is the text displayed during character-based or DOS program execution. If the program does not output anything to the console, this parameter must not be present.

Return Value

ret, numeric return code. When the program has been launched successfully, the function returns 0; otherwise, use this return code for Error Handling.

See Also

Shell

Examples

ShellWait("xcopy c:\\*.* d:\\save /S", 1, 1000)
msgbox("DOS command end")

DOS box is opened, WinTask script execution suspends and the following message box is displayed either when the job in the DOS box is finished, or when the specified timeout of 1000 seconds has been reached.