Home > Language Reference > System Functions > ShellWait

ShellWait

The ShellWait function launches the specified program (.exe, .com, .bat, etc.) and waits for its termination before running the next statement.

Usage

Used to start a Dos application, a batch file or a console application and to wait until the application has finished before moving to next step. For example, using ShellWait, you can launch a Dos command such as xcopy and next step will be executed only when the filecopy has finished.

Syntax

ret = ShellWait(<application_name>, 1|2|3|4|5, <timeout> [, <processExitCode> [, <output>]])

Parameters

<application_name>. string, name of the application to launch (case insensitive), including its parameters if any (see remarks).

1|2|3|4|5. If 1, the application is opened at its standard size. If 2 the application is launched minimized. If 3, the application is opened at its maximum size. If 4, the application is launched hidden (character-mode application). If 5, the application is launched hidden and if after the <timeout>, the application is still running, the application is killed.

<timeout>, integer. The <processexitcode> value is set to -1 if the application has not finished after <timeout> seconds. If <timeout> is 0, there is no timeout limitation.

<processExitCode>, optional integer variable only. It contains the return code of the application at its termination. If <timeout> has been reached before program termination, <ProcessExitCode> is set to -1.

<output>, optional string variable only. It contains the two outputs stdout and stderr (only if the second parameter is set to 4 or 5). It contains the text displayed during character-based or Dos programs execution. If the program does not output anything to the console, this last parameter must not be specified.

Return value

ret, optional integer return value. If the application has been launched successfully, the return value is 0. If the function fails, the return value is a nonzero value (see System Functions Error Codes).

Remarks

If <application_name> contains a space, you must surround it with the double-quote character CHR$(34). For example:
Shell(Chr$(34)+"C:\Program Files (x86)\Microsoft Office\Office12\EXCEL.EXE"+Chr$(34),1)

See also

Shell

Example

shellwait("xcopy c:\*.* d:\save /S",1,1000)
msgbox("Dos command end")
'Dos box is opened, the automation script execution suspends and the following message box is displayed either when job in Dos box is finished,
' or when the specified timeout of 1000 seconds has been reached.