SHELL statement

Purpose

Run an executable program synchronously. The SHELLing thread of the calling program is suspended until the SHELLed program ends.

Syntax

SHELL [HANDLES,] CmdString [, WndStyle, EXIT TO exitcode&]

Remarks

The SHELL statement has the following parts:

HANDLES

This option, if present, allows the child process to inherit (and access) the Windows file handles of all open files in the parent process. These are not PowerBASIC file numbers, but system file handles and you must use OPEN HANDLE to access them.

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 program 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

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.

exitcode&

The exit code of the child process (the value returned by the WinMain function) is assigned to the long integer variable specified by exitcode&.

Restrictions

The SHELL statement executes the child process synchronously. That is, SHELL will not return control to your program until the child program finishes.

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.

If the SHELL statement is not executed successfully, an appropriate error is generated. The ERR function can be used to detect it.