Loads and runs a program.
System "file$ [parameters]" [, options]
ret_large = System("file$ [parameters]")
file$:sexp
The System command invokes the program file$. The file$ expression contains the name of the called program. The program name includes the full pathname and the command line which is inserted in the program segment prefix of the called program.
The System(file$) function return a 64-bit integer, which is 0 in case of an error. Otherwise, the low order 32 bits contain the process handle of the program, and the high 32 bits the process ID. The first example shows how to start an external program and wait for it to end.
System is based on the API function CreateProcess, which can take quite some options. Many of these options are implemented in GFA-BASIC 32. There is an option to wait for a program to end, like: System "notepad", Wait. The return values of CreateProcess can be retrieved using the options as well. System "notepad", ProcessID pid% returns the process identification in pid%.
System supports the following options.
| Dir "path" | specifies the current drive and directory for the child process. |
| App "programname" | Statement for the name of the program to start; mostly the usage of a command line will make more sense, but nevertheless, may be useful for someone. |
| Show SW_const | One of the SW_ constants. For GUI processes this specifies the default value the first time ShowWindow is called. |
| Pos x, y | Specifies the x and y offsets, in pixels, of the upper left corner of a window if a new window is created. |
| Size w, h | Specifies the width and height, in pixels, of the window if a new window is created. |
| Full | Full DOS-BOX |
| Fill attrib | Specifies the initial text and background colors if a new console window is created in a console application. This value can be any combination of the following values: FOREGROUND_BLUE, FOREGROUND_GREEN, FOREGROUND_RED, FOREGROUND_INTENSITY, BACKGROUND_BLUE, BACKGROUND_GREEN, BACKGROUND_RED, and BACKGROUND_INTENSITY. |
| Count cx, cy | For console processes, if a new console window is created, cx specifies the screen buffer width in character columns, and cy specifies the screen buffer height in character rows. These values are ignored in GUI processes. |
| Title sexp | For console processes, this is the title displayed in the title bar if a new console window is created. |
| Desktop sexp | string that specifies either the name of the desktop only or the name of both the desktop and window station for this process. A backslash in the string indicates that the string includes both desktop and window station names. |
| FeedOn | Use application starting cursor. |
| FeedOff | Don't use application starting cursor. |
| Wait | The command System waits in a loop with MsgWaitForMultipleObjects(..., 1000,...) until the end of the started process and executes, if necessary DoEvents in such a way that the program remains accessible. |
| ForceWait | Like Wait, but waiting cannot be interrupted. The calling program is actually disabled. |
| hProcess var | Copy the return value of the process handle into var% (the variable var is Long/Int or Handle). |
| hThread var | Copy the primary thread handle into var (Long/Int or Handle). |
| ProcessID var | Copy the process ID into var (Long/Int). |
| ThreadID var | Copy the thread ID into var (Long/Int). |
| ExitCode var | Copy the exit code into var (Long/Int). Without Wait or ForceWait mostly STATUS_PENDING (0x103) |
| StdIn h | Specifies a handle that will be used as the standard input handle to the process. |
| StdOut h | Specifies a handle that will be used as the standard output handle to the process |
| StdErr h | Specifies a handle that will be used as the standard error handle to the process |
| Inherit | Inherits handles from the calling process. Each inheritable open handle in the calling process is inherited by the new process. Inherited handles have the same value and access privileges as the original handles. |
| Advanced options | |
| Debug | The caller is a debugger, the new process is a process being debugged. |
| DebugThis | If not specified and the calling process is being debugged, the new process becomes another process being debugged by the calling process's debugger. If the calling process is not a process being debugged, no debugging-related actions occur. |
| Suspend | The called program is waiting for the ResumeThread (for debugger). |
| Detached | For console processes, the new process does not have access to the console of the parent process. |
| NewConsole | The new process has a new console, instead of inheriting the parent's console. This flag cannot be used with the Detached option. |
| Normal, Idle, High, RealTime | Controls the new process's priority class, which is used in determining the scheduling priorities of the process's threads. (Idle = background process, like a screen saver; High = the process will get 'all' processor time; RealTime = process can get all available processor time. |
| NewPGroup | The new process is the root process of a new process group. |
| Separate, Shared | Only valid when starting a 16-bit Windows-based application. The disadvantage of running Separate 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 them own VDM. Shared overrides the system default setting and runs the new process in the shared Virtual DOS Machine. |
| DOS | Starts the program a real MSDOS application (not Win 95/98/Me). |
| DefErr | The default error mode is valid (not Win 95, 98, Me). |
| ProfUser, ProfKernel, ProfServer | The program is a user program, a kernel, or a server application and should use the appropriate profiles. |
The use of hProcess and hThread require a CloseHandle. ProcessID, ThreadId, hProcess, and hThread aren't very useful together with Wait or ForceWait.
Dim id%, h%
System "notepad", ProcessID id%, hProcess h%
In case of an error (System returns 0) a message box is displayed.
1 - Start notepad and wait.
OpenW Center 1
Local pHdl As Handle, pID As Int
Local l As Large, e%, h%
l = System("Notepad")
If !l Then Message _
"Can't start Notepad" : End
pHdl = LoLarge(l) ' process handle
pID = HiLarge(l) ' process ID
~GetExitCodeProcess(pHdl, V:e)
While e = STATUS_PENDING
~MsgWaitForMultipleObjects(1, V:pHdl, _
0, 1000, QS_ALLINPUT)
Beep -1
DoEvents
~GetExitCodeProcess(pHdl, V:e)
Wend
~CloseHandle(pHdl)
Example 2
OpenW 1
Global a As Large, b$
b$ = " c:\test.dat"
If Exist(WinDir + "\notepad.exe")
a = System(WinDir + "\notepad.exe" & b$)
Message "Return value: " & Format(a)
Else
Message "Program not found"
EndIf
Do
Sleep
Until Me Is Nothing
Shell, ShellExec, Exec, WinExec
{Created by Sjouke Hamstra; Last updated: 24/10/2014 by James Gaite}