createExternalProcess

createExternalProcess(directory:  String;
                      command:    String;
                      args:       StringArray;
                      alias:      String;
                      thinClient: Boolean;
                      modal:      Boolean;
                      result:     Integer output): Integer;

The createExternalProcess method of the Node class initiates an external process from within JADE logic. The parameters of the createExternalProcess method are listed in the following table.

Parameter Usage
directory

Specifies the directory that you require for the working directory when you run the external process application specified in the command parameter. The current directory is used if this parameter contains an empty string.

command

Specifies the fully qualified path of the application (that is, the external process) that you want to run.

To ensure that the expected executable is started, specify the full path to the executable. If the path includes spaces, the value should be in double quotes.

args

Specifies the external process parameters, or arguments. Each string in the array is passed as a separate argument to the command. This can be null if there are no arguments. If an argument contains white space, you will need to protect it by using quote marks; for example:

args[2] := 'ini="c:\Program files\jade\jade.ini"';
alias Not currently implemented (that is, this parameter is ignored).
thinClient If running in a JADE thin client environment, specifies whether the external process is executed on a presentation client workstation or the application server. If this parameter is set to true, the process is initiated on the presentation client workstation, or thin client.
modal When true, specifies the suspension of the JADE application until the external process terminates, or when false, specifies that the JADE application is to run in parallel with the process.
result Returns the exit value from the external process. This has meaning only when the modal parameter is set to true.

The values that are returned by this method are listed in the following table.

Node Class Constant Integer Value Description
ExternalProcess_Failed 3 External process failed, due to an exception (modal parameter is set to true)
ExternalProcess_InitiateFailed 2 External process failed to initiate
ExternalProcess_InitiateOK 0 External process initiated successfully (modal parameter is set to false)
ExternalProcess_InvalidParam 1 Invalid parameter in the external process
ExternalProcess_Successful 4 External process was successful (modal parameter is set to true)

The following example shows the use of the createExternalProcess method.

vars
    command, alias : String;
    args           : StringArray;
    exitValue      : Integer;     // random value if modal = false
    result         : Integer;
begin
    command := "mycommand";
    alias   := command;
    create args transient;
    args[1] := "first";
    args[2] := '"white space"';
    result  := node.createExternalProcess(".", command, args, alias,
                                          false, false, exitValue);
    if result = node.ExternalProcess_InvalidParam then
       write "Something is wrong with node.createExternalProcess arguments";
    elseif result = node.ExternalProcess_InitiateFailed then
       write "Could not start " & command;
    elseif result = node.ExternalProcess_InitiateOK then
       write "Non-modal command '" & command & "' started successfully";
    elseif result = node.ExternalProcess_Failed then
       write "Modal command '" & command & "' started, but died under
                      abnormal conditions";
    elseif result = node.ExternalProcess_Successful then
       write "Modal command '" & command & "' started, and exited with " &
                      exitValue.String;
    endif;
epilog
    delete args;
end;