Reference (Scripting) > Docklight Script Commands - The DL Object > Methods (Advanced)

Starts an external application or executes a Windows Shell operation.

Return Value

Integer

Syntax 1

result = DL.ShellRun(operation, file [, parameters] [, directory] [, showCmd])

The ShellRun method syntax 1 has these parts:

Part	Description
operation	Required. String which specifies the type of action to be performed, corresponding to the Windows ShellExecute lpOperation parameter. Commonly used values are: "open"- opens a file or a folder "print"- prints a file "edit" - launches an editor and opens the file for editing See the Windows ShellExecute documentation for more values and documentation.
file	Required. String with the path to the file on which to execute operation.
parameters	Optional. String value. If file is an executable, command-line arguments can be passed here.
directory	Optional. String value. Defines the working directory for the action. If not used, the current Docklight working directory is used.
showCmd	Optional Integer value. Specifies the application appearance, corresponding to the Windows ShellExecute nShowCmd parameter. Default value is: 10 - SW_SHOWDEFAULT other common values are: 0 - SW_HIDE 1 - SW_SHOWNORMAL 2 - SW_SHOWMINIMIZED 3 - SW_SHOWMAXIMIZED

Remarks (Syntax 1)

result contains the return value of Windows ShellExecute.

result is > 32 if successful.

See the example below for a definition of relevant error constants for result.

Syntax 2

result = DL.ShellRun("wait<timeout>", [, file] [, parameters] [, directory] [, showCmd])

The ShellRun method syntax 1 has these parts:

Part

Description

"wait<timeout>"

Instead of operation as in Syntax 1, use:

"wait" - start an external application and wait for it to quit

"wait<timeout>", e.g. "wait60000" - start an external application and wait for it to quit, or for the specified timeout in milliseconds to expire.

file

parameters

directory

showCmd

same as in Syntax 1

Remarks (Syntax 2):

The "wait<timeout>" starts and monitor an external application via Windows ShellExecuteEx, similar to the "open" command of Syntax 1.

The return values in Syntax 2 are different from Syntax 1:

result	Description
0	successful
-1	error starting the application
-2	timeout

Example

' Example ShellRun

' Here is a list of error codes, according to the original C header file shellapi.h from Windows Kit 8.1:

' regular WinExec() codes */

const SE_ERR_FNF = 2 ' file not found

const SE_ERR_PNF = 3 ' path not found

const SE_ERR_ACCESSDENIED = 5 ' access denied

const SE_ERR_OOM = 8 ' out of memory

const SE_ERR_DLLNOTFOUND = 32

' error values for ShellExecute() beyond the regular WinExec() codes

const SE_ERR_SHARE = 26

const SE_ERR_ASSOCINCOMPLETE = 27

const SE_ERR_DDETIMEOUT = 28

const SE_ERR_DDEFAIL = 29

const SE_ERR_DDEBUSY = 30

const SE_ERR_NOASSOC = 31

' Example for Syntax 2

DL.AddComment "Open notepad and wait for application end. After max 60 sec timeout close forcefully:"

DL.AddComment "DL.AddComment DL.ShellRun(" & Chr(34) & "wait60000" & Chr(34) & ", " & Chr(34) & "notepad.exe" & Chr(34) & ", " & Chr(34) & "test.txt" & Chr(34) & ")"

DL.AddComment "returns = " & DL.ShellRun("wait60000", "notepad.exe", "test.txt")

DL.Pause 1000

' Examples for Syntax 1

DL.AddComment "Ask Windows to open the same file with the default edit application for .txt files, continue immediately:"

DL.AddComment "DL.ShellRun(" & Chr(34) & "edit" & Chr(34) & ", " & Chr(34) & "test.txt" & Chr(34) & ")"

DL.AddComment "returns = " & DL.ShellRun("edit", "test.txt")

DL.Pause 3000

DL.AddComment "Open the Docklight web site in the default browser:"

DL.AddComment "DL.ShellRun(" & Chr(34) & "open" & Chr(34) & ", " & Chr(34) & "https://docklight.de" & Chr(34) & ")"

DL.AddComment "returns = " & DL.ShellRun("open", "https://docklight.de")

DL.Pause 3000

DL.AddComment "Open Windows Device Manager:"

DL.AddComment "DL.ShellRun(" & Chr(34) & "open" & Chr(34) & ", " & Chr(34) & "devmgmt.msc" & Chr(34) & ")"

DL.AddComment "returns = " & DL.ShellRun("open", "devmgmt.msc")

DL.Pause 1000

DL.AddComment "done"