peoplecodeapi

Syntax

Exec(command_str [, parameter])

where parameter has one of the following formats:

Boolean constant

Exec_Constant + Path_Constant

Description

Exec is a cross-platform function that executes an external program on either UNIX or Windows.

This function has two parameter conventions in order to maintain upward compatibility with existing programs.

Note: All PeopleCode is executed on the application server. So if you're calling an interactive application, you receive an error. There shouldn't be any application interaction on the application server console.

The function can make either a synchronous or asynchronous call. Synchronous execution acts as a "modal" function, suspending the PeopleSoft application until the called executable completes. This is appropriate if you want to force the user (or the PeopleCode program) to wait for the function to complete its work before continuing processing. Asynchronous processing, which is the default, launches the executable and immediately returns control to the calling PeopleSoft application.

If Exec is unable to execute the external program, the PeopleCode program terminates with a fatal error. You may want to try to catch these exceptions by enclosing such statements in a try-catch statement (from the Exception Class).

Parameters

Field or Control	Definition
`command_str`	The `command_str` parameter consists of a series of tokens that together make up the name of the executable to run and the parameters to be passed to it. Tokens are separated by unquoted space characters. Single or double quote characters can be used for quoting. Both types of quotes are treated equivalently, but the starting and ending quotes for a quoted portion of a token must match. A quoted string may not contain quotes of the same type but a single quoted string can contain double quote characters and vice versa. A single token may consist of multiple adjacent quoted characters (There must be no spaces between the quoted fragments). Unterminated quoted fragments will result in an error. Note: PeopleCode strings will require two double quote characters within a string to embed a double quote character.
`Boolean` \| `Constants`	If you specify a Boolean value, it indicates whether to execute the external program synchronously or asynchronously. Values are: True - Synchronous False - Asynchronous (default) If you do not specify a value, the program executes asynchronously. If you use this style, PS_HOME is always prefixed to `command_str.` If you specify constant values, you're specifying a numeric value composed of an `exec_constant` and a `path_constant` . The `exec_constant` specifies whether to execute the external program synchronously or not. The `path_constant` specifies how the path name is to be treated. The value specified is made up of the addition of these predefined constants. Values are:

Field or Control

Definition

command_str

The command_str parameter consists of a series of tokens that together make up the name of the executable to run and the parameters to be passed to it. Tokens are separated by unquoted space characters. Single or double quote characters can be used for quoting. Both types of quotes are treated equivalently, but the starting and ending quotes for a quoted portion of a token must match. A quoted string may not contain quotes of the same type but a single quoted string can contain double quote characters and vice versa. A single token may consist of multiple adjacent quoted characters (There must be no spaces between the quoted fragments). Unterminated quoted fragments will result in an error.

Note: PeopleCode strings will require two double quote characters within a string to embed a double quote character.

Boolean | Constants

If you specify a Boolean value, it indicates whether to execute the external program synchronously or asynchronously. Values are:

True - Synchronous
False - Asynchronous (default)

If you do not specify a value, the program executes asynchronously.

If you use this style, PS_HOME is always prefixed to command_str.

If you specify constant values, you're specifying a numeric value composed of an exec_constant and a path_constant . The exec_constant specifies whether to execute the external program synchronously or not. The path_constant specifies how the path name is to be treated. The value specified is made up of the addition of these predefined constants.

Values are:

Exec Constant	Description
%Exec_Asynchronous	Program executes asynchronously (the default)
%Exec_Synchronous	Program executes synchronously.

Path Constant	Description
%FilePath_Relative	PS_HOME is prefixed to `command_str` .
%FilePath_Absolute	Nothing is prefixed to `command_str` .

Returns

What is returned depends on what you specified for the second parameter.

If you specified a Boolean, a Number value equal to the process ID of the called process is returned.

If you specify constant values, the returned value contains the value of the exit code of the program executed using this function, unless you have executed the program asynchronously.