RunWait()
Mfunc.RunWait(Target [, WorkingDir, Max|Min|Hide|UseErrorLevel])
Runs an external program. Unlike Run, RunWait will wait until the program finishes before continuing.
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)
Note: 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). If 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.
When UseErrorLevel is specified, the variable A_LastError is set to the result of the operating system's GetLastError() function. A_LastError is a number between 0 and 4294967295 (always formatted as decimal, not hexadecimal). Zero (0) means success, but any other number means the launch failed. Each number corresponds to a specific error condition (to get a list, search www.microsoft.com for "system error codes"). Like ErrorLevel, A_LastError is a per-thread setting; that is, interruptions by other threads cannot change it. However, A_LastError is also set by DllCall.
Throws MfException throw any errors with InnerException set to the Autohotkey - Run error message.
Mfunc.Run unless UseErrorLevel (above) is in effect, in which case ErrorLevel is set to the word ERROR upon failure or 0 upon success.
Mfunc.RunWait to the program's exit code (a signed 32-bit integer). If UseErrorLevel is in effect and the launch failed, the word ERROR is stored.
Returns 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. RunWait also supports this parameter, though its OuputVarPID must be checked in another thread (otherwise, the PID will be invalid because the process will have terminated by the time the line following RunWait executes).
After the Run command retrieves a PID, any windows to be created by the process might not exist yet. To wait for at least one window to be created, use WinWait ahk_pid %OutputVarPID%.
Wrapper for AutoHotkey Docs - Run/RunWait.
Static method.
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 integer). Some programs will appear to return immediately even though they are still running; these programs spawn another process.
If Target contains any commas, they may ( but not necessary ) be escaped as shown three times in the following example:
Mfunc.Run("rundll32.exe shell32.dll`,Control_RunDLL desk.cpl`,`, 3") ; Opens Control Panel > Display Properties > Settings
; Escape is not necessary with Mfunc.Run()
Mfunc.Run("rundll32.exe shell32.dll,Control_RunDLL desk.cpl,, 3") ; Opens Control Panel > Display Properties > Settings
When running a program via Comspec (cmd.exe) -- perhaps because you need to redirect the program's input or output -- if the path or name of the executable contains spaces, the entire string should be enclosed in an outer pair of quotes and all inner quotes need to be doubled as shown in this example:
Mfunc.Run(comspec . " /c ""C:\My Utility.exe"" ""param 1"" ""second param"" >""C:\My File.txt""")
If Target cannot be launched, an error window is displayed and the current thread is exited, unless the string UseErrorLevel is included in the third parameter or the error is caught by a Try /Catch statement.
Performance may be slightly improved if Target is an exact path, e.g. Mfunc.Run("C:\Windows\Notepad.exe ""C:\My Documents\Test.txt""") rather than Mfunc.Run("C:\My Documents\Test.txt").
Special CLSID folders may be opened via Run. For example:
Mfunc.Run("::{20d04fe0-3aea-1069-a2d8-08002b30309d}") ; Opens the "My Computer" folder.
Mfunc.Run("::{645ff040-5081-101b-9f08-00aa002f954e}") ; Opens the Recycle Bin.
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:
While RunWait is in a waiting state, new threads can be launched via hotkey, custom menu item, or timer.
Any and/or all parameter for this function can be instance of MfString or var containing string.
See Also:AutoHotkey Docs - Run/RunWait.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
Mfunc.Run("Notepad.exe", "C:\My Documents", "max")
Mfunc.Run("mailto:someone@domain.com?subject=This is the subject line&body=This is the message body's text.")
Mfunc.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.
Mfunc.RunWait(comspec . " /c dir c:\ >>c:\DirTest.txt", , "min")
Mfunc.Run("c:\DirTest.txt")
Mfunc.Run("properties c:\DirTest.txt")
Mfunc.Run("http://www.google.com") ; i.e. any URL can be launched.
Mfunc.Run("mailto:someone@somedomain.com") ; This should open the default e-mail application.
Mfunc.Run("::{20d04fe0-3aea-1069-a2d8-08002b30309d}") ; Opens the "My Computer" folder.
Mfunc.Run("::{645ff040-5081-101b-9f08-00aa002f954e}") ; Opens the Recycle Bin.
; To run multiple commands consecutively, use "&&" between each:
Mfunc.Run(comspec. " /c dir /b > C:\list.txt && type C:\list.txt && pause")
; The following can be used to run a command and retrieve its output:
MsgBox % RunWaitOne("dir " A_ScriptDir)
; ...or run multiple commands in one go and retrieve their output:
MsgBox % RunWaitMany("
(
echo Put your commands here,
echo each one will be run,
echo and you'll get the output.
)")
RunWaitOne(command) {
; WshShell object: http://msdn.microsoft.com/en-us/library/aew9yb99
shell := ComObjCreate("WScript.Shell")
; Execute a single command via cmd.exe
exec := shell.Exec(ComSpec " /C " command)
; Read and return the command's output
return exec.StdOut.ReadAll()
}
RunWaitMany(commands) {
shell := ComObjCreate("WScript.Shell")
; Open cmd.exe with echoing of commands disabled
exec := shell.Exec(ComSpec " /Q /K echo off")
; Send the commands to execute, separated by newline
exec.StdIn.WriteLine(commands "`nexit") ; Always exit at the end!
; Read and return the output of all commands
return exec.StdOut.ReadAll()
}
; ExecScript: Executes the given code as a new AutoHotkey process.
ExecScript(Script, Wait:=true)
{
shell := ComObjCreate("WScript.Shell")
exec := shell.Exec("AutoHotkey.exe /ErrorStdOut *")
exec.StdIn.Write(script)
exec.StdIn.Close()
if Wait
return exec.StdOut.ReadAll()
}
; Example:
InputBox expr,, Enter an expression to evaluate as a new script.,,,,,,,, Asc("*")
result := ExecScript("FileAppend % (" expr "), *")
MsgBox % "Result: " result