Function RunShell() Foundation
Starts a command shell or executes a program.
RunShell( <cCmdLine> , ;
[<cProgram>] , ;
[<lAsync>] , ;
[<lBackground>],
[<aStdHandles>|<lInherit>] ) --> xReturn
The return value of RunShell() is the return value of the started command shell or program. When a command shell/program is started in asynchronous mode, the return value is always zero. If RunShell() was not able to start <cProgram>, -1 is returned.
The function RunShell() starts a new command shell and passes a character string to it which is executed on the command line. Normally a new window is opened by RunShell() in which the command defined by <cCmdLine> is executed.
At least the parameter <cCmdLine> must be passed to the function RunShell(). At the minimum this can be a null string (""). In this case RunShell() starts the command shell defined as the default command shell in the environment variable OS2_SHELL (OS/2) or COMSPEC (Windows). If <cCmdLine> contains a null string and no command shell can be started, a runtime error occurs.
The parameter <lAsync> determines whether an Xbase++ application is dependent or independent of the newly started command shell or program. When <lAsync> has the logical value .T. (true), the new program is started and the Xbase++ application continues running independent of it. If the value is .F. (false), the Xbase++ application pauses until the newly started program terminates.
The parameter <lBackGround> determines whether the new process is started in the background or in the foreground of the Xbase++ application. By default RunShell() starts new processes in the foreground, meaning they receive input focus and the applicable window is brought to the foreground. If a "Full-Screen" session is started with RunShell(), the function switches automatically to character mode. If the logical value .T. (true) is specified for <lBackGround>, the new process starts in the background of the Xbase++ application which keeps the input focus.
Processes started using RunShell() normally execute completely independent and cannot access resources allocated in the calling process. This behaviour can be overriden via the <aStdHandles> and <lInherit> parameters. If .T. (true) is passed in <lInherit>, the newly started process inherits all inheritable handles from the parent process. These handles correspond to existing operating system objects such as file handles, named pipes or semaphore objects, which have been marked as inheritable. Similarly, the <aStdHandles> parameter can be used to define existing files as the standard I/O devices to be used by the process spawned by RunShell(). This is often used to redirect the output of the process to a file and is demonstrated in an example below.
VIEW Cmdref Start and VIEW Cmdref Cmd
HELP Cmd and START /?
HELP Command and START /?
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.