User Tools

Site Tools


en:code:system:process

Process

This object allows you to start and manage a process. (program)

Functions

Process

Constructor function.

Syntax

var myObject = new Process();
var myObject = new Process(parameters);

Arguments

  1. parameters - (object) the parameters
    • workingDirectory - (string) the working directory
    • processChannelMode - (ProcessChannelMode) the process's channel mode
    • readChannel - (ProcessChannel) the process's read channel
    • onError - (onError) called when an error has occured
    • onFinished - (onFinished) called when the process has finished
    • onReadyReadStandardError - (onReadyReadStandardError) called when the process has data on the standard error channel
    • onReadyReadStandardOutput - (onReadyReadStandardOutput) called when the process has data on the standard output channel
    • onStarted - (onStarted) called when the process has started
    • onStateChanged - (onStateChanged) called when the process's state has changed

Example

var myObject = new Process();
var myObject = new Process({
	workingDirectory: "/home/user",
	onStarted: function()
	{
		Console.print("Started!");
	},
	onFinished: function()
	{
		Console.print("Finished!");
	}
});

list

Returns an array of ProcessHandle linked to all running processes.

Syntax

Process.list();

Returns

  • (array) an array of ProcessHandle linked to all running processes

thisProcess

Returns a ProcessHandle linked to the Actionaz process.

Syntax

Process.thisProcess();

Returns

startDetached

Starts a process in detached mode and returns a ProcessHandle linked to it. You will have lesser control on the process than in attached mode, but it will be independent of the current execution.

Syntax

Process.startDetached(filename);
Process.startDetached(filename, parameters);
Process.startDetached(filename, parameters, workingDirectory);

Arguments

  1. filename - (string) the filename/command of the process to start
  2. parameters - (array) an array of parameters
  3. workingDirectory - (string) the working directory

Returns

Exceptions

  • (FilenameError) invalid filename
  • (StartProcessError) unable to start the process

Methods

handle

Returns a ProcessHandle linked to the started process

Syntax

myObject.handle();

Returns

id

Returns the process id of the started process.

Syntax

myObject.id();

Returns

  • (integer) the process id of the started process

start

Starts the process.

Syntax

myObject.start(filename);
myObject.start(filename, parameters);
myObject.start(filename, parameters, openMode);

Arguments

  1. filename - (string) the filename/command of the process to start
  2. parameters - (array) an array of parameters
  3. openMode - (OpenMode) the open mode to use (default: read and write)

Returns

  • (Process) this Process

Exceptions

  • (FilenameError) invalid filename

state

Returns the state of the started process.

Syntax

myObject.state();

Returns

error

Returns the error state of the started process.

Syntax

myObject.error();

Returns

exitCode

Returns the process's exit code.

Syntax

myObject.exitCode();

Returns

  • (integer) the process's exit code

exitStatus

Returns the process's exit status.

Syntax

myObject.exitStatus();

Returns

readError

Returns the content of the standard error output as a RawData.

Syntax

myObject.readError();

Returns

read

Returns the content of the standard output as a RawData.

Syntax

myObject.read();

Returns

readErrorText

Returns the content of the standard error output as text.

Syntax

myObject.readErrorText();
myObject.readErrorText(encoding);

Arguments

  1. encoding - (Encoding) the encoding to use

Returns

  • (string) the content of the standard error output as text

readText

Returns the content of the standard output as text.

Syntax

myObject.readText();
myObject.readText(encoding);

Arguments

  1. encoding - (Encoding) the encoding to use

Returns

  • (string) the content of the standard output as text

atEnd

Returns true if the process is not running and if no data can be read.

Syntax

myObject.atEnd();

Returns

  • (boolean) true if the process is not running and if no data can be read

bytesAvailable

Returns the number of bytes that can be read.

Syntax

myObject.bytesAvailable();

Returns

  • (integer) the number of bytes that can be read

bytesToWrite

Returns the number of bytes that are still to be written.

Syntax

myObject.bytesToWrite();

Returns

  • (integer) the number of bytes that are still to be written

canReadLine

Returns true if a line can be read.

Syntax

myObject.canReadLine();

Returns

  • (boolean) true if a line can be read

write

Writes some data to the process.

Syntax

myObject.write(data);

Arguments

  1. data - (mixed) the data to write

Returns

  • (Process) this Process

writeText

Writes text to the process.

Syntax

myObject.writeText(text, encoding);

Arguments

  1. text - (string) the text to write
  2. encoding - (Encoding) the encoding to use

Returns

  • (Process) this Process

setWorkingDirectory

Sets the working directory. This only works when the process is not already started.

Syntax

myObject.setWorkingDirectory(workingDirectory);

Arguments

  1. workingDirectory - (string) the text to write

Returns

  • (Process) this Process

setProcessChannelMode

Sets process's channel mode. This only works when the process is not already started.

Syntax

myObject.setProcessChannelMode(channelMode);

Arguments

  1. channelMode - (ProcessChannelMode) the process's channel mode

Returns

  • (Process) this Process

setEnvironment

Sets the process's environment variables. This only works when the process is not already started.

Syntax

myObject.setEnvironment(environment);

Arguments

  1. environment - (object) the process's environment variable

Returns

  • (Process) this Process

Example

myObject.setEnvironment({
	PATH: "c:\\;c:\\path",
	MYVAR: "hello"
});

updateEnvironment

Updates the process's environment variables. This only works when the process is not already started.

Syntax

myObject.updateEnvironment(environment);

Arguments

  1. environment - (object) the process's environment variable

Returns

  • (Process) this Process

Example

myObject.updateEnvironment({
	PATH: "c:\\;c:\\path",
	MYVAR: "hello"
});

setReadChannel

Sets process's read channel.

Syntax

myObject.setReadChannel(channel);

Arguments

  1. channel - (ProcessChannel) the process's read channel

Returns

  • (Process) this Process

setStandardErrorFile

Sets the standard error file.

Syntax

myObject.setStandardErrorFile(fileName);
myObject.setStandardErrorFile(fileName, openMode);

Arguments

  1. fileName - (string) the filename
  2. channel - (OpenMode) the file's open mode (default: Truncate)

Returns

  • (Process) this Process

setStandardInputFile

Sets the standard input file.

Syntax

myObject.setStandardInputFile(fileName);

Arguments

  1. fileName - (string) the filename

Returns

  • (Process) this Process

setStandardOutputFile

Sets the standard output file.

Syntax

myObject.setStandardOutputFile(fileName);
myObject.setStandardOutputFile(fileName, openMode);

Arguments

  1. fileName - (string) the filename
  2. channel - (OpenMode) the file's open mode (default: Truncate)

Returns

  • (Process) this Process

setStandardOutputProcess

Sets the standard output process.

Syntax

myObject.setStandardOutputFile(process);

Arguments

  1. process - (Process) the output process

Returns

  • (Process) this Process

Exceptions

  • (InvalidProcessError) invalid process

waitForFinished

Freezes the execution until the process has finished.

Syntax

myObject.waitForFinished(waitTime);
myObject.waitForFinished();

Arguments

  1. waitTime - (integer) the time to wait (milliseconds, default: 30000)

Returns

  • (Process) this Process

Exceptions

  • (WaitForFinishedError) wait for finished failed

waitForStarted

Freezes the execution until the process has started.

Syntax

myObject.waitForStarted(waitTime);
myObject.waitForStarted();

Arguments

  1. waitTime - (integer) the time to wait (milliseconds, default: 30000)

Returns

  • (Process) this Process

Exceptions

  • (WaitForStartedError) wait for started failed

waitForBytesWritten

Freezes the execution until the data has been written.

Syntax

myObject.waitForBytesWritten(waitTime);
myObject.waitForBytesWritten();

Arguments

  1. waitTime - (integer) the time to wait (milliseconds, default: 30000)

Returns

  • (Process) this Process

Exceptions

  • (WaitForBytesWrittenError) wait for bytes written failed

waitForReadyRead

Freezes the execution until data is available.

Syntax

myObject.waitForReadyRead(waitTime);
myObject.waitForReadyRead();

Arguments

  1. waitTime - (integer) the time to wait (milliseconds, default: 30000)

Returns

  • (Process) this Process

Exceptions

  • (WaitForReadyReadError) wait for ready read failed

close

Tries to close the process gracefully.

Syntax

myObject.close();

Returns

  • (Process) this Process

kill

Kills the process.

Syntax

myObject.kill();

Returns

  • (Process) this Process

terminate

Terminates the process.

Syntax

myObject.terminate();

Returns

  • (Process) this Process

Events

onError

Called when an error occured.

Syntax

myObject.onError = function(processError) {};

Arguments

  1. processError - (ProcessError) the process error that has occured

Example

myObject.onError = function(processError)
{
	//Event action
};

onFinished

Called when the process has finished.

Syntax

myObject.onFinished = function(exitCode, exitStatus) {};

Arguments

  1. exitCode - (integer) the process's exit code
  2. exitStatus - (ExitStatus) the process's exit status

Example

myObject.onFinished = function(exitCode, exitStatus)
{
	//Event action
};

onReadyReadStandardError

Called when there is data available on the standard error output.

Syntax

myObject.onReadyReadStandardError = function() {};

Example

myObject.onReadyReadStandardError = function()
{
	//Event action
};

onReadyReadStandardOutput

Called when there is data available on the standard output.

Syntax

myObject.onReadyReadStandardOutput = function() {};

Example

myObject.onReadyReadStandardOutput = function()
{
	//Event action
};

onStarted

Called when the process has started executing.

Syntax

myObject.onStarted = function() {};

Example

myObject.onStarted = function()
{
	//Event action
};

onStateChanged

Called when the process's state has changed.

Syntax

myObject.onStateChanged = function(newState) {};

Arguments

  1. newState - (ProcessState) the process's state

Example

myObject.onStateChanged = function(newState)
{
	//Event action
};

Enumerations

ProcessError

A process error.

Values

  1. FailedToStart: the file cannot be found or insufficient permissions
  2. Crashed: the process has crashed after having started successfully
  3. Timedout: the last waitFor… method failed
  4. WriteError: the process is not running or it may have closed it's input channel
  5. ReadError: the process is not running
  6. UnknownError: an unknown error has occured

ExitStatus

The process's exit status.

Values

  1. NormalExit: the process finished normally
  2. CrashExit: the process crashed

ProcessState

The process's status.

Values

  1. NotRunning: the process is not running
  2. Starting: the process is starting
  3. Running: the process is running

ProcessChannel

A process's channel.

Values

  1. StandardOutput: the standard output channel
  2. StandardError: the standard error output channel

ProcessChannelMode

A process's channel mode.

Values

  1. SeparateChannels: the standard error and output channels are separated
  2. MergedChannels: the standard error channel is redirected to the the standard output channel
  3. ForwardedChannels: the output of both channels is redirected to the parent process

OpenMode

A process's channel open mode.

Values

  1. ReadOnly: process channel opened for reading only
  2. WriteOnly: process channel opened for writing only
  3. ReadWrite: process channel opened for reading and writing
  4. Truncate: process channel opened for writing, erases any previous content
  5. Text: process channel opened in text mode
  6. Unbuffered: process channel opened in unbuffered mode
en/code/system/process.txt · Last modified: 2021/02/13 11:23 by 127.0.0.1