Shell function (LotusScript® Language)

Starts another program.

Syntax

Shell ( program [ , windowStyle ] )

Elements

program

A string expression whose value is the name of the program to run, including arguments. program can be the name of an executable file that uses a file name extension of BAT, COM, PIF, or EXE (for Windows, or whatever is an executable file on the current operating system). You can omit the file name extension, and you can optionally include a complete path specification.

Using an internal DOS command name, or a file that can't be located in the executable paths, generates an error (ErrFileNotFound, defined in lserr.lss).

windowStyle

Optional. A number designating a valid window style, as specified in the following table.

Style

Description

Constant

1, 5, or 9

Normal with focus

SHELL_NORMAL_FOCUS

2

Minimized with focus (default)

SHELL_MIN_FOCUS

3

Maximized with focus

SHELL_MAX_FOCUS

4 or 8

Normal without focus

SHELL_NORMAL_NO_FOCUS

6 or 7

Minimized without focus

SHELL_MIN_NO_FOCUS

The constants are defined in the file lsconst.lss. Including this file in your script allows you to use constant names instead of the numeric values assigned to them.

Return value

If LotusScript® successfully starts program, Shell returns the number 33.

Note: To get the program's task ID, use the Shellid function instead.

If LotusScript® cannot start program, Shell returns an error.

Usage

Shell must be called from within an expression or an assignment statement, so that its return value is used.

In a UNIX or AIX® environment, LotusScript® will resume execution of the script only after the program has completed.

In other environments, after Shell starts a program, LotusScript® continues to execute the script without waiting to make sure the program has completed. You cannot be sure that a program started by Shell has finished running before the rest of your script is executed.

Using a file which is not an executable type, generates an error (ErrIllegalFunctionCall, defined in lserr.lss). To open a file using the program that would be used to edit it, you must supply the filename for that program, not just the filename of the file you want to open. Determining which program this would be, is an OS-specific operation. For instance, on Microsoft Windows, the ShellExecute function of the operating system API could be used. Note that ShellExecute is not a LotusScript® function.

Example