Programming Guide:xppguide

Start multiple processes - multi-tasking Foundation

The function RunShell() executes any program from within an Xbase++ application as a new process. The number of processes that can be started depends on available memory (including free space on the hard disk), but is limited by the operating system. To take full advantage of RunShell(), a comprehensive knowledge of the command START and of the commands associated with the command processor are required. When commands are passed to the command processor, the switch /C should always be considered. Detailed information is given in the online help of the operating system.

The function RunShell() starts a new instance of the command processor and passes a character string to it that is executed on the command line. Under Windows 95 the default command processor is COMMAND.COM and for OS/2 and Windows NT it is CMD.EXE. The function RunShell() must receive at least one parameter to be passed on to the command processor, which can be a null string (""):

xResult := RunShell( "" ) 

In the line above, RunShell() starts a new instance of the command processor, a new window is opened and the Xbase++ application is stopped until the window is closed. This is a result of the default values for other parameters that can be passed to RunShell(). These additional parameters can specify whether an Xbase++ application is dependent on or independent of the newly started command processor.

// calling a program without specifying 
// command line parameters (""), but specifying 
// asynchronous execution (.T.) 

RunShell( "", "PROGRAM.EXE", .T.) 

This line of code starts a program asynchronously in a new window. The program name is specified as the second parameter and no command line arguments are passed. The execution of the Xbase++ application which invoked RunShell() is continued by clicking on the Xbase++ application window with the mouse. When the third parameter contains the logical value .T. (true), the new program is started and the Xbase++ application continues to execute independently. If the value is .F. (false), the Xbase++ application waits until the newly started program has terminated before it continues executing.

The program can also be started as a background process and, in such case, the Xbase++ application remains active.

// Calling a program without specifying 
// command line parameters (""). 
// Use asynchronous execution (.T.) 
// and run it as a background process (.T.) 

RunShell( "", "PROGRAM.EXE", .T., .T.) 

The fourth parameter determines whether the new process is started in the background or foreground of the Xbase++ application. By default, RunShell() starts new processes in the foreground. This means that the new window is brought to the front and receives input focus. If a "full screen" session is started using RunShell(), the function automatically switches to character mode. When the logical value .T. (true) is specified as the fourth parameter, the new process starts in the background of the Xbase++ application and the Xbase++ application keeps input focus.

The examples of calling a program show how an application can be started by passing the file name. The file name can also be passed to the function RunShell() as a command line parameter. The following two lines are equivalent:

RunShell( "", "PROGRAM.EXE", .T.) 
RunShell("/C PROGRAM.EXE", , .T.) 

In both cases, the program is started asynchronously. In the second line, the file name is contained in the command line parameter for the command processor. For this to work, the command line must begin with "/C". The following code shows additional examples for using the function RunShell():

// execute the program REVERSI.EXE asynchronously in 
// the background 

   RunShell( "", "REVERSI.EXE", .T., .T. ) 

// DOS session (/DOS) in the foreground (/F) in a window (/WIN) 
// with the window title "DOS session" under OS/2 

   RunShell( '/C START "DOS session" /F /WIN /DOS' ) 

// Full-Screen DOS session (/DOS) in the background (/B) under OS/2 

   RunShell( '/C START /B /DOS' ) 

// Indirekt call of the Windows program EXPLORER.EXE 
// using the START command. 
// The explorer displays the current directory 

   ? RunShell( "/C START EXPLORER.EXE ." ) 

The command START invokes a new command processor and passes a command line to it. This allows for the execution of any program including passing of parameters. When used with START, RunShell() offers tremendous flexibility in starting any program from an Xbase++ application and passing parameters to it.

Enter "Help Start" or "Start /?" on the command line to get detailed information about the START command from the operating system's online help.


If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.