Exec function

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

Parameter	Description
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.

Example

&ExitCode = Exec("sh -c " | &scriptFile, %Exec_Synchronous + %FilePath_Absolute);

The following example demonstrates executing a program where the path to the executable contains spaces and a single parameter containing space characters is passed. Suppose the location of the executable is C:\Program Files\App\program.exe and the value of the first parameter is 1 2 3.

Exec("'c:\Program Files\App\program.exe' '1 2 3'", %FilePath_Absolute)

or

Exec("""c:\Program Files\App\program.exe"" ""1 2 3""", %FilePath_Absolute)

This is an example of executing a program with a parameter that contains space and single quote characters. The second parameter is enclosed in double quotes so that the single quote and space characters are passed correctly. Suppose your executable is program.exe. The first parameter is -p and the second parameter is customer's update.

Exec("program.exe -p ""customer’s update""")

This is an example of executing a program with a parameter that contains space, single quote, and double quote characters. The second parameter consists of several adjacent quoted fragments. The first fragment is enclosed in double quotes so that the single quote and space characters are passed correctly and the second fragment is enclosed in single quotes so that the double quote and space characters are passed correctly. Note that there are no spaces between the quoted fragments. Suppose your executable is program.exe. The first parameter is -p and the second parameter is John’s comment: “Hello There”.

Exec("program.exe -p ""John's comment: ""'""Hello There""'")

Command Formatting

The function automatically converts the first token on command_str platform-specific separator characters to the appropriate form for where your PeopleCode program is executing, regardless of the path_constant. On a Windows system, a UNIX "/" separator is converted to "\", and on a UNIX system, a Windows "\" separator is converted to "/".

This is only done for the first token on command_str assuming it to be some sort of file specification. This allows you to put file or program names in canonical form (such as, UNIX style) as the first token on the exec command.

Using an Absolute Path

If you do not specify anything for the second parameter, or if you specify a Boolean value, the path to PS_HOME is prefixed to the command_str.

If you specify constant values for the second parameter, PS_HOME may or may not be prefixed, depending on the values you select.

You can use the GetEnv function to determine the value of PS_HOME.

Creating a File in UNIX

If you try to create a file on a UNIX machine using the Exec function the file might not be created due to permission issues. If you encounter this problem, create a script file that includes the file creation commands and run the script using the Exec function. The script file must have correct privileges.

If you pass an absolute path in the Exec argument you must use the %FilePath_Absolute flag

Restrictions on Use in PeopleCode Events

When Exec is used to execute a program synchronously (that is, if its synch_exec parameter is set to True) it behaves as a think-time function, which means that it can’t be used in any of the following PeopleCode events:

• SavePreChange.

• SavePostChange.

• Workflow.

• RowSelect.

• Any PeopleCode event that fires as a result of a ScrollSelect (or one of its relatives) function calls, or a Select (or one of its relatives) Rowset class method.