Runs an external program. Unlike Run, RunWait will wait until the program finishes before continuing.
| Run, Target [, WorkingDir, Max|Min|Hide|UseErrorLevel, OutputVarPID] |
Parameters
| Target | A document, URL, executable file (.exe, .com, .bat, etc.), shortcut (.lnk), or system verb to launch (see remarks). If Target is a local file and no path was specified with it, A_WorkingDir will be searched first. If no matching file is found there, the system will search for and launch the file if it is integrated ("known"), e.g. by being contained in one of the PATH folders. To pass parameters, add them immediately after the program or document name. If a parameter contains spaces, it is safest to enclose it in double quotes (even though it may work without them in some cases). |
| WorkingDir | The working directory for the launched item. Do not enclose the name in double quotes even if it contains spaces. If omitted, the script's own working directory (A_WorkingDir) will be used. |
| Max|Min|Hide UseErrorLevel |
If omitted, Target will be launched normally. Alternatively, it can contain one or more of these words: Max: launch maximized Min: launch minimized Hide: launch hidden (cannot be used in combination with either of the above) Some applications (e.g. Calc.exe) do not obey the requested startup state and thus Max/Min/Hide will have no effect. UseErrorLevel: UseErrorLevel can be specified alone or in addition to one of the above words (by separating it from the other word with a space). When the launch fails, this option skips the warning dialog, sets ErrorLevel to the word ERROR, and allows the current thread to continue. If the launch succeeds, RunWait sets ErrorLevel to the program's exit code, and Run sets it to 0. |
| OutputVarPID | The name of the variable in which to store the newly launched program's unique Process ID (PID). The variable will be made blank if the PID could not be determined, which usually happens if a system verb, document, or shortcut is launched rather than a direct executable file. In v1.0.27+, RunWait also supports this parameter, though of course OuputVarPID must be checked in another thread for the PID to still be valid. |
ErrorLevel
The Run command does not set ErrorLevel unless UseErrorLevel (above) is in effect. RunWait sets ErrorLevel to the program's exit code.
Remarks
Unlike Run, RunWait will wait until Target is closed or exits, at which time ErrorLevel will be set to the program's exit code (as a signed 32-bit value). Some programs will appear to return immediately even though they are still running; these programs spawn another process.
If Target contains any commas, they must be escaped as shown three times in the following example:
Run rundll32.exe shell32.dll`,Control_RunDLL desk.cpl`,`, 3 ; Opens Control Panel > Display Properties > Settings
If Target cannot be launched, an error window will be displayed, after which the script will behave as though an Exit command were encountered. To prevent this, include the string UseErrorLevel in the 3rd parameter.
Performance may be slightly improved if Target is an exact path, e.g. Run, C:\Windows\Notepad.exe "C:\My Documents\Test.txt" rather than Run, C:\My Documents\Test.txt
System verbs correspond to actions available in a file's right-click menu in the Explorer. If a file is launched without a verb, the default verb (usually "open") for that particular file type will be used. If specified, the verb should be followed by the name of the target file. The following verbs are currently supported:
| properties | Displays the Explorer's properties window for the indicated file. For example: Run, properties C:\autoexec.bat Note: The properties window will automatically close when the script terminates. To prevent this, use WinWaitClose to have the script wait for the properties window to close. |
| find | Opens an instance of the Explorer's Search Companion or Find File window at the indicated folder. For example: Run, find D:\ |
| explore | Opens an instance of Explorer at the indicated folder. For example: Run, explore %ProgramFiles% |
| edit | Opens the indicated file for editing. It might not work if the indicated file's type does not have an "edit" action associated with it. For example: Run, edit "C:\My File.txt" |
| open | Opens the indicated file (normally not needed because it is the default action for most file types). For example: Run, open "My File.txt" |
| Prints the indicated file with the associate application, if any. For example: Run, print "My File.txt" |
While RunWait is in a waiting state, new threads can be launched via hotkey, custom menu item, or timer.
Related
Examples
Run, Notepad.exe, C:\My Documents, max Run, ReadMe.doc, , Max UseErrorLevel ; Launch maximized and don't display dialog if it fails. if ErrorLevel = ERROR MsgBox The document could not be launched. RunWait, %comspec% /c dir c:\ >>c:\DirTest.txt, , min Run, c:\DirTest.txt Run, properties c:\DirTest.txt Run, www.autohotkey.com ; i.e. any URL can be launched. Run, mailto:support@autohotkey.com ; This should open the default e-mail application.