SHELL function

Purpose

Run an executable program asynchronously (as a separate process), while execution of the original application continues uninterrupted.

Syntax

ProcessId??? = SHELL([HANDLES,] CmdString [, WndStyle])

Remarks

The SHELL function has the following parts:

CmdString

The name of the program to execute ("child process"), along with and any required arguments or command-line switches.

WndStyle

A number corresponding to the style of the window in which the child process is to be executed. If WndStyle is omitted, the program is opened normal with focus, the same as WndStyle = 1.

The following table identifies the values for WndStyle and the resulting style of window:

WndStyle	Window style
0	Hide window
1	Normal with focus (default)
2	Minimized with focus
3	Maximized with focus
4	Normal without focus
6	Minimized without focus

SHELL returns the process id of the child process. The process id is a 32-bit LONG or DWORD value that identifies the child process, if it’s a 32-bit process. If the process id is zero, the child process is not a 32-bit process, or an error occurred. Use ERR to detect the success of the SHELL function. The HANDLES option allows the child process to inherit the file handles opened by your program. This affects only Windows handles, not PowerBASIC file identifiers. It is an advanced option, for those who know it works and why they need it.

Restrictions

Child processes run asynchronously, or independently of the program that SHELLs. So, the child process is, probably, still running after control returns from SHELL to your program. Also, if your program ends before the child process, the child process will continue to run.

To use internal DOS commands like DIR and COPY, you must run the DOS command processor, passing the DOS command as a parameter. See the example below.

If the program name in CmdString does not include an explicit path, Windows will search for the file in the following paths: the directory where the current program is located, the default directory, the 32-bit Windows system directory, the 16-bit Windows system directory, the Windows directory, and any directories listed in the PATH environment variable.