Process class

The Process class is used to start external programs and to communicate with them. It can start programs in one of three modes, as described in the following table:

Static properties

stdout : String

Contains the data sent to stdout during the last call to Process.execute(). This property is read-only.

stderr : String

Contains the data sent to stderr during the last call to Process.execute(). This property is read-only.

Static functions

execute( command : String, stdin : String ) : int

Executes command synchronously and passes stdin to its standard input if specified. When the program ends its output is accessible through Process.stdout and Process.stderr. command can contain both the program and command line arguments, separated by spaces. The function returns the executed command's return code on exit.

Process.execute("help cd");//executes help command with cd arg
job.log(1, Process.stdout); //help output

execute( command : String[ ], stdin : String ) : int

Same as above, except that command is an Array of strings, where the first item is the name of the program and the following items are command line arguments. This version is useful if you have arguments that contain spaces or other characters that would need to be quoted if you just passed a single string command line, since it takes care of the quoting for you.

var comm = new Array("help", "cd");
Process.execute(comm); //executes help command (with cd arg)
job.log(1, Process.stdout); //help output

startDetached ( command : String ) : bool

Starts command in a new process and detaches from it. command can contain both the program and command line arguments, separated by spaces. The function returns 1 on success; otherwise returns 0. The detached process will continue to live even if the calling process exits.

var started = Process.startDetached("help");
job.log(1, started); //"1" if command was started

var started = Process.startDetached("help");
job.log(1, Boolean(started)); //"true" if command was started

Constructors

Process( command : String )

Creates a Process object that will execute command. This does not start the process.

var p = new Process("help cd");

Process( command : String[ ] )

Same as above, except that command is an Array of strings, where the first item is the name of the program and the following items are command line arguments. This version is useful if you have arguments that contain spaces or other characters that would need to be quoted if you just passed a single string command line, since it takes care of the quoting for you.

var comm = new Array("help", "cd");
var p = new Process(comm);

Examples of common mistakes

Example 1: A python script is used

Process.execute( "aws --version" ); <-- WRONG -->

In this example, the use of "aws" is incorrect: this is a python script, which cannot be used with the execute commmand. Alternatively, you can try prefixing the aws command with the path to 'python' or find the preferable executable that will start your command, as in the example below:

Process.execute( "/usr/bin/python /usr/local/bin/aws --version" ); <-- RIGHT -->

There will be no problem if your command starts with a binary executable. For example, the following script should work correctly:

Process.execute( "curl --version" ); <-- RIGHT -->

Example 2: Quotes are missing

var theCommand = "cmd /C dir c:\\folder\\inner folder"; 
Process.execute( theCommand ); <-- WRONG -->

In this example, the path is not enclosed in quotes. This is corrected in the example below.

var theCommand = "cmd /C dir \"c:\\folder\\inner folder\""; 
Process.execute( theCommand ); <-- RIGHT -->

For more information, refer to the documentation about the Execute command tool in the Switch Reference Guide.

Properties

arguments : String[ ]

Contains an Array of strings where the first item is the program to execute and the following items are the command line arguments.

//with p initialized as above
var args = p.arguments;  
job.log(1, args[1]); //"cd"

workingDirectory : String

Contains the working directory for the process.

running : Boolean

True if the process is currently running; otherwise false. This property is read-only.

exitStatus : Number

Contains the exitStatus of the program when it has finished. This property is read-only.

Member functions

start( env : String[ ] )

Tries to run a process for the command and arguments that were specified with the argument property or that were specified in the constructor. The command is searched for in the path for executable programs; you can also use an absolute path in the command itself. If env is not specified, the process is started with the same environment as the starting process. If env is specified, then the values in the Array of strings are interpreted as environment settings of the form VARIABLE=VALUE and the process is started with these environment settings. If the program could not be started, an exception is thrown.

launch( stdin : String, env : String[ ] )

Runs the process and writes the data stdin to the process's standard input. If all the data is written to standard input, standard input is closed. The command is searched for in the path for executable programs; you can also use an absolute path in the command itself. If env is unspecified, the process is started with the same environment as the starting process. If env is specified, then the values in the Array of strings are interpreted as environment settings of the form VARIABLE=VALUE and the process is started with these environment settings. If the program could not be started, an exception is thrown.

waitForStarted ( seconds : Number )

Blocks until the process has started or until the specified time (in seconds) has passed. Returns true if the process was started successfully; returns false if the operation timed out or if an error occurred. The default value for the argument is 30 seconds. If the value -1 is used, the method will wait infinitely.

waitForFinished ( seconds : Number )

Blocks until the process has finished or until the specified time (in seconds) has passed. Returns true if the process finished; returns false if the operation timed out or if an error occurred. The default value for the argument is 30 seconds. If the value -1 is used the method will wait infinitely.

Note:

It is required to call waitForStarted() before calling waitForFinished().

Example:

theProcess.start();
if( !theProcess.waitForStarted( 60 ) ) // 1 minute to start
{
    job.fail( "Failed to start process with the arguments: %1", theProcess.arguments );
    return;
}
if( !theProcess.waitForFinished( 600 ) ) // 10 minutes to finish
{
    job.log( 3, "Cannot finish the process: %1", theProcess.arguments );
}

readStdout() : String

Reads what is currently available on the process's standard output.

readStderr() : String

Reads what is currently available on the process's standard error.

canReadLineStdout() : Boolean

Returns true if a line can be read from the process's standard output.

canReadLineStderr() : Boolean

Returns true if a line can be read from the process's standard error.

readLineStdout() : String

Reads one line of text from the process's standard output if available; otherwise returns an empty string.

readLineStderr() : String

Reads one line of text from the standard error stream of this process if available; otherwise returns an empty string.

writeToStdin( buffer : String )

Writes the data buffer to the standard input stream of this process. The process may or may not read this data.

closeStdin()

Closes the standard input stream of the process.

tryTerminate()

Asks the process to terminate. Processes can ignore this if they wish. If you want to be certain that the process really terminates, you can use kill() instead.

kill()

Terminates the process. This is not a safe way to end a process since the process will not be able to do any cleanup. tryTerminate() is safer, but processes can ignore tryTerminate().