Exec or Execute - Execute an Application

Desktop Management Scripting › Desktop Management Scripting Language › Functions › Miscellaneous Functions › Exec or Execute - Execute an Application

Exec or Execute - Execute an Application

Valid on NetWare, Symbian OS, UNIX, Windows and Windows CE

The Exec or Execute function runs the specified application.

Function format:

Execute(cmdline as String, wait as Boolean, style as Integer) as Integer

Execute(cmdline as String, wait as Boolean) as Integer

Execute(cmdline as String) as Integer

cmdline

Identifies the command line (filename plus optional parameters).

Note: On Windows platforms, if the file to be executed does not have the extension .exe, you need to explicitly specify the file extension; for example, on Win9x, specify "command.com" instead of "command".

wait

Specifies whether the script waits until the application terminates or not. (Windows only)

style

Specifies the window style of the application. (Windows only)

Note: If a command in the command line contains a space, enclose the command in quotation marks. For example: Execute("""\temp 1\prgedit.exe""",true,0).

The wait parameter specifies if the function returns to script execution without waiting for the application to terminate. The value TRUE forces the function to wait for the application to terminate. The default is TRUE.

On a UNIX platform, the wait and the style parameters are ignored. The function always waits for the application to terminate before returning to script execution.

The style parameter specifies how to display a Windows based application main window. This parameter can be any of the following values:

Value: 0: Hides the window and passes activation to another window.
Value: 1: Activates a window and displays it in its default size and position. This is the default.
Value: 2: Activates a window and displays it as an icon.
Value: 3: Activates a window and displays it as a maximized window.
Value: 7: Displays a window as an icon. The window currently active remains active.

On Windows, if the function succeeds, a non-negative return code indicates the return code of the specified command invoked by the execute() function. If the interpreter fails to start the command, the following return codes are returned to indicate the problem:

Return Code: -1: The system is out of memory or out of resources.
Return Code: -2: The specified file was not found.
Return Code: -3: The specified path was not found.
Return Code: -4: The .exe file is invalid.
Return Code: -5: Unknown error.

On UNIX, the system function "system()" invokes the specified command. Therefore, the returned code corresponds to the return code of "system()". In other words, when the system() fails, it returns -1. When system() is successful, the return value corresponds to the "waitpid()" return code format. A script must analyze the return code to determine the success or failure of the invoked commands. This can be achieved by using the following functions:

'
' Execute() return code evaluation support for Unix
'
 
' ******************************************************************************************************
'
' Name
'   DMS_ExecExit(retVal As Integer) As Boolean
'
' Description
'   Determines whether the process started by Execute() has terminated normally or not.
'
' Arguments
'   retVal	return code to be evaluated
'
' Returns
'   TRUE	if normally terminated
'   FALSE	else.
'
' Comment
'  The function corresponds to the waitpid(5) description of the macro WIFEXITED
'	#define WIFEXITED(stat)     ((int)((stat)&0xFF) == 0)
'
Function DMS_ExecExit(retVal As Integer) As Boolean
	If (retVal And 255) Then
		DMS_ExecExit = FALSE
	Else
		DMS_ExecExit = TRUE
	End If
End Function
 
' ******************************************************************************************************
'
' Name
'   DMS_ExecExitStatus(retVal As Integer) As Integer
'
' Description
'   Determines the shell exit code from the return value of the Execute() call, i.e. the return code of 
'   the invoked process.
'
' Arguments
'   retVal	Retrun code retuned from Execute()
'
' Returns
'   If the Execute() has terminated normally the reported status of the child is returned, otherwise 
'   retVal is returned.
'
' Comment
'  The function corresponds to the waitpid(5) description of the macro WEXITSTATUS
'	#define WEXITSTATUS(stat)   ((int)(((stat)>>8)&0xFF))
'
Function DMS_ExecExitStatus(retVal As Integer) As Integer
	If Not(DMS_ExecExit(retVal)) Then
		DMS_ExecExitStatus = retVal
	Else
		DMS_ExecExitStatus = retVal / 256
		DMS_ExecExitStatus = DMS_ExecExitStatus And 255
	End If
End Function

If the function succeeds, the return value is non-negative (the exit code of the application when WAIT specifies that the function should wait for the application to terminate). Otherwise, the function returns one of the following error values:

Value: -1: The system is out of memory or resources.
Value: -2: The specified file was not found.
Value: -3: The specified path was not found.
Value: -4: The .exe file is invalid.
Value: -5: Unknown error.

Example:

Dim Tempname as string  ' Holds filename of temporary file
Dim hFile as integer   ' Handle of temporary file

' First obtain temporary filename and create file...
Tempname=EnvGetString("TEMP")
if TempName="" then
	TempName="MyFile.txt"
else
	Tempname=Tempname+"\MyFile.txt"
end if
hfile=CreateFile(Tempname)

if hFile<0 then
	 ' An error occured while creating file, inform user and exit.
	 MsgBox("Could not create temporary file...")
	 goto end
end if

' Store some text in the file and close it...
WriteFile(hFile,"This text is shown using notepad")
WriteFile(hFile,"")
WriteFile(hFile,"Please exit notepad to resume script execution")
Closefile(hFile)

'Launch notepad with the file...
if Execute("notepad "+Tempname,TRUE)<0 then MsgBox("Could not launch notepad...")

'remember to Erase the temporary file before leaving...
DeleteFile(Tempname)

end: