Platforms to show: All Mac Windows Linux Cross-Platform

WindowsExecuteMBS(ApplicationName as string, CommandLine as string, CurrentDirectory as string, byref PID as integer, Flags as integer = 0, ShowWindow as Integer = -1) as integer

Type Topic Plugin Version macOS Windows Linux iOS Targets
global method Windows MBS Win Plugin 11.0 ❌ No ✅ Yes ❌ No ❌ No Desktop, Console & Web
Creates a new process and its primary thread. The new process runs in the security context of the calling process.
Example
dim error, pid as Integer

pid = 0

error = WindowsExecuteMBS("", "explorer.exe", "", pid)
if error = 0 then
MsgBox "Launched explorer with process id: "+str(pid)
else
MsgBox "Error: "+str(error)
end if

pid = 0

error = WindowsExecuteMBS("", "notepad.exe ""C:\boot.ini""", "", pid)
if error = 0 then
MsgBox "Launched Notepad with process id: "+str(pid)
else
MsgBox "Error: "+str(error)
end if

ApplicationName:
The name of the module to be executed. This module can be a Windows-based application. It can be some other type of module (for example, MS-DOS or OS/2) if the appropriate subsystem is available on the local computer.

The string can specify the full path and file name of the module to execute or it can specify a partial name. In the case of a partial name, the function uses the current drive and current directory to complete the specification. The function will not use the search path. This parameter must include the file name extension; no default extension is assumed.

The ApplicationName parameter can be empty. In that case, the module name must be the first white space–delimited token in the CommandLine string. If you are using a long file name that contains a space, use quoted strings to indicate where the file name ends and the arguments begin; otherwise, the file name is ambiguous. For example, consider the string "c:\program files\sub dir\program name". This string can be interpreted in a number of ways. The system tries to interpret the possibilities in the following order:

  • c:\program.exe files\sub dir\program name
  • c:\program files\sub.exe dir\program name
  • c:\program files\sub dir\program.exe name
  • c:\program files\sub dir\program name.exe

If the executable module is a 16-bit application, ApplicationName should be empty, and the string pointed to by CommandLine should specify the executable module as well as its arguments.

To run a batch file, you must start the command interpreter; set ApplicationName to cmd.exe and set CommandLine to the following arguments: /c plus the name of the batch file.

CommandLine:
The command line to be executed. The maximum length of this string is 32,767 characters.. If ApplicationName is empty, the module name portion of CommandLine is limited to MAX_PATH (256) characters.

The CommandLine parameter can be empty. In that case, the function uses the string pointed to by ApplicationName as the command line.

If both ApplicationName and CommandLine are non-empty, the ApplicationName string specifies the module to execute, and the CommandLine string specifies the command line. The new process can use GetCommandLine to retrieve the entire command line. Console processes written in C can use the argc and argv arguments to parse the command line. Because argv[0] is the module name, C programmers generally repeat the module name as the first token in the command line.

If ApplicationName is empty, the first white space–delimited token of the command line specifies the module name. If you are using a long file name that contains a space, use quoted strings to indicate where the file name ends and the arguments begin (see the explanation for the ApplicationName parameter). If the file name does not contain an extension, .exe is appended. Therefore, if the file name extension is .com, this parameter must include the .com extension. If the file name ends in a period (.) with no extension, or if the file name contains a path, .exe is not appended. If the file name does not contain a directory path, the system searches for the executable file in the following sequence:

  • The directory from which the application loaded.
  • The current directory for the parent process.
  • The 32-bit Windows system directory. Use the GetSystemDirectory function to get the path of this directory.
  • The 16-bit Windows system directory. There is no function that obtains the path of this directory, but it is searched. The name of this directory is System.
  • The Windows directory. Use the GetWindowsDirectory function to get the path of this directory.
  • The directories that are listed in the PATH environment variable. Note that this function does not search the per-application path specified by the App Paths registry key. To include this per-application path in the search sequence, use the ShellExecute function.
  • The system adds a terminating null character to the command-line string to separate the file name from the arguments. This divides the original string into two strings for internal processing.

CurrentDirectory:
The full path to the current directory for the process. The string can also specify a UNC path.

If this parameter is empty, the new process will have the same current drive and directory as the calling process. (This feature is provided primarily for shells that need to start an application and specify its initial drive and working directory.)

pid:
The variable to store the process ID of the new process.

Returns 0 for success or a windows error code for any error.

Note that the function returns before the process has finished initialization. If a required DLL cannot be located or fails to initialize, the process is terminated. To get the termination status of a process, call GetExitCodeProcess.

Possible Flags:

ConstantValueDescription
CREATE_BREAKAWAY_FROM_JOB&h01000000The child processes of a process associated with a job are not associated with the job. If the calling process is not associated with a job, this constant has no effect. If the calling process is associated with a job, the job must set the JOB_OBJECT_LIMIT_BREAKAWAY_OK limit.
CREATE_DEFAULT_ERROR_MODE&h04000000The new process does not inherit the error mode of the calling process. Instead, the new process gets the default error mode. This feature is particularly useful for multi-threaded shell applications that run with hard errors disabled. The default behavior is for the new process to inherit the error mode of the caller. Setting this flag changes that default behavior.
CREATE_NEW_CONSOLE&h00000010The new process has a new console, instead of inheriting its parent's console (the default). For more information, see Creation of a Console. This flag cannot be used with DETACHED_PROCESS.
CREATE_NEW_PROCESS_GROUP&h00000200The new process is the root process of a new process group. The process group includes all processes that are descendants of this root process. The process identifier of the new process group is the same as the process identifier, which is returned in the lpProcessInformation parameter. Process groups are used by the GenerateConsoleCtrlEvent function to enable sending a CTRL+BREAK signal to a group of console processes. If this flag is specified, CTRL+C signals will be disabled for all processes within the new process group. This flag is ignored if specified with CREATE_NEW_CONSOLE.
CREATE_NO_WINDOW&h08000000The process is a console application that is being run without a console window. Therefore, the console handle for the application is not set. This flag is ignored if the application is not a console application, or if it is used with either CREATE_NEW_CONSOLE or DETACHED_PROCESS.
CREATE_PROTECTED_PROCESS&h00040000The process is to be run as a protected process. The system restricts access to protected processes and the threads of protected processes. For more information on how processes can interact with protected processes, see Process Security and Access Rights. To activate a protected process, the binary must have a special signature. This signature is provided by Microsoft but not currently available for non-Microsoft binaries. There are currently four protected processes: media foundation, audio engine, Windows error reporting, and system. Components that load into these binaries must also be signed. Multimedia companies can leverage the first two protected processes. For more information, see Overview of the Protected Media Path. Windows Server 2003 and Windows XP/2000: This value is not supported.
CREATE_PRESERVE_CODE_AUTHZ_LEVEL&h02000000Allows the caller to execute a child process that bypasses the process restrictions that would normally be applied automatically to the process. Windows 2000: This value is not supported.
CREATE_SEPARATE_WOW_VDM&h00000800This flag is valid only when starting a 16-bit Windows-based application. If set, the new process runs in a private Virtual DOS Machine (VDM). By default, all 16-bit Windows-based applications run as threads in a single, shared VDM. The advantage of running separately is that a crash only terminates the single VDM; any other programs running in distinct VDMs continue to function normally. Also, 16-bit Windows-based applications that are run in separate VDMs have separate input queues. That means that if one application stops responding momentarily, applications in separate VDMs continue to receive input. The disadvantage of running separately is that it takes significantly more memory to do so. You should use this flag only if the user requests that 16-bit applications should run in their own VDM.
CREATE_SHARED_WOW_VDM&h00001000The flag is valid only when starting a 16-bit Windows-based application. If the DefaultSeparateVDM switch in the Windows section of WIN.INI is TRUE, this flag overrides the switch. The new process is run in the shared Virtual DOS Machine.
CREATE_SUSPENDED&h00000004The primary thread of the new process is created in a suspended state, and does not run until the ResumeThread function is called.
CREATE_UNICODE_ENVIRONMENT&h00000400If this flag is set, the environment block pointed to by lpEnvironment uses Unicode characters. Otherwise, the environment block uses ANSI characters.
DEBUG_ONLY_THIS_PROCESS&h00000002The calling thread starts and debugs the new process. It can receive all related debug events using the WaitForDebugEvent function.
DEBUG_PROCESS&h00000001The calling thread starts and debugs the new process and all child processes created by the new process. It can receive all related debug events using the WaitForDebugEvent function. A process that uses DEBUG_PROCESS becomes the root of a debugging chain. This continues until another process in the chain is created with DEBUG_PROCESS. If this flag is combined with DEBUG_ONLY_THIS_PROCESS, the caller debugs only the new process, not any child processes.
DETACHED_PROCESS&h00000008For console processes, the new process does not inherit its parent's console (the default). The new process can call the AllocConsole function at a later time to create a console. For more information, see Creation of a Console. This value cannot be used with CREATE_NEW_CONSOLE.
EXTENDED_STARTUPINFO_PRESENT&h00080000The process is created with extended startup information; the lpStartupInfo parameter specifies a STARTUPINFOEX structure. Windows Server 2003 and Windows XP/2000: This value is not supported.
INHERIT_PARENT_AFFINITY&h00010000The process inherits its parent's affinity. If the parent process has threads in more than one processor group, the new process inherits the group-relative affinity of an arbitrary group in use by the parent. Windows Server 2008, Windows Vista, Windows Server 2003, and Windows XP/2000: This value is not supported.
ABOVE_NORMAL_PRIORITY_CLASS&h00008000Process that has priority above NORMAL_PRIORITY_CLASS but below HIGH_PRIORITY_CLASS.
BELOW_NORMAL_PRIORITY_CLASS&h00004000Process that has priority above IDLE_PRIORITY_CLASS but below NORMAL_PRIORITY_CLASS.
HIGH_PRIORITY_CLASS&h00000080Process that performs time-critical tasks that must be executed immediately for it to run correctly. The threads of a high-priority class process preempt the threads of normal or idle priority class processes. An example is the Task List, which must respond quickly when called by the user, regardless of the load on the operating system. Use extreme care when using the high-priority class, because a high-priority class CPU-bound application can use nearly all available cycles.
IDLE_PRIORITY_CLASS&h00000040Process whose threads run only when the system is idle and are preempted by the threads of any process running in a higher priority class. An example is a screen saver. The idle priority class is inherited by child processes.
NORMAL_PRIORITY_CLASS&h00000020Process with no special scheduling needs.
REALTIME_PRIORITY_CLASS&h00000100Process that has the highest possible priority. The threads of a real-time priority class process preempt the threads of all other processes, including operating system processes performing important tasks. For example, a real-time process that executes for more than a very brief interval can cause disk caches not to flush or cause the mouse to be unresponsive.

ShowWindow can be values for ShowWindow function to define how first window of new application is shown. Available values:

ConstantsValueMeaning
SW_FORCEMINIMIZE11Minimizes a window, even if the thread that owns the window is not responding. This flag should only be used when minimizing windows from a different thread.
SW_HIDE0Hides the window and activates another window.
SW_MAXIMIZE3Maximizes the specified window.
SW_MINIMIZE6Minimizes the specified window and activates the next top-level window in the Z order.
SW_RESTORE9Activates and displays the window. If the window is minimized or maximized, the system restores it to its original size and position. An application should specify this flag when restoring a minimized window.
SW_SHOW5Activates the window and displays it in its current size and position.
SW_SHOWDEFAULT10Sets the show state based on the SW_ value specified in the STARTUPINFO structure passed to the CreateProcess function by the program that started the application.
SW_SHOWMAXIMIZED3Activates the window and displays it as a maximized window.
SW_SHOWMINIMIZED2Activates the window and displays it as a minimized window.
SW_SHOWMINNOACTIVE7Displays the window as a minimized window. This value is similar to SW_SHOWMINIMIZED, except the window is not activated.
SW_SHOWNA8Displays the window in its current size and position. This value is similar to SW_SHOW, except that the window is not activated.
SW_SHOWNOACTIVATE4Displays a window in its most recent size and position. This value is similar to SW_SHOWNORMAL, except that the window is not activated.
SW_SHOWNORMAL1Activates and displays a window. If the window is minimized or maximized, the system restores it to its original size and position. An application should specify this flag when displaying the window for the first time.

Blog Entries

The items on this page are in the following plugins: MBS Win Plugin.


The biggest plugin in space...