NAME

Process::SubProcess - Library to manage Sub Processes as objects

DESCRIPTION

Process::SubProcess implements a class to manage a Sub Process and read its Output and Errors

The Idea of this API is to launch Sub Processes and keep track of all Output on STDOUT, STDERR, the EXIT CODE and possible System Errors at Launch Time in an object oriented manner. This allows an easy aggregation and thus the creation of Sub Process Groups and Sub Process Pools for simultaneous execution of multiple Sub Processes while keeping the execution logs separated.

STATIC METHODS

runSubProcess ( [ COMMAND | OPTIONS ] )

This creates adhoc an Process::SubProcess Object and runs the command given as string.

COMMAND - is a single scalar parameter will be interpreted as command to executed without any additional options.

OPTIONS - are passed in a hash like fashion, using key and value pairs. Combining the command with additional OPTIONS also requires the hash key command to be set.

See Method setArrProcess()

CONSTRUCTOR

new ( [ CONFIGURATIONS ] )

This is the constructor for a new SubProcess.

Parameters:

CONFIGURATIONS are passed in a hash like fashion, using key and value pairs.

See Method setArrProcess()

Administration Methods

setArrProcess ( CONFIGURATIONS )

This Method will asign Values to physically Data Fields.

Parameters:

CONFIGURATIONS - is a list are passed in a hash like fashion, using key and value pairs.

Recognized Configurations:

name - is a string that will be assigned as the process name. This is useful when there are several processes with the same command running and a more prettier readable name is desired.

command - The command that has to be executed. It only can be set if the process is not running yet

timeout - Time in seconds to wait for the process to finish. After this time the process will be terminated

check | read | readtimeout - Time in seconds to wait for the process output. If the process is expected to run longer it is useful to set it to avoid excessive checks. It is also important for multiple process execusions, because other processes will not be checked before the read has not timed out.

debug - show internal processing information

quiet - do not print any warnings or errors

See Method setName()

See Method setCommand()

See Method setTimeout()

See Method setReadTimeout()

set ( CONFIGURATIONS )

Shorthand for setArrProcess()

See Method setArrProcess()

setName ( NAME )

This Method will asign a Name to the process.

The NAME of the Process::SubProcess object will reflect in the logs.

This is useful when there are several processes with the same command running and a more prettier readable name is desired.

Parameters:

NAME - is a string that will be assigned as the process name.

setCommand ( COMMAND )

This method sets the COMMAND property as string that represents the command to be executed.

It can only be set when the Sub Process is not running.

Parameters:

COMMAND - is a single scalar parameter that will be interpreted as command to executed

See Method Launch()

setReadTimeout ( TIMEOUT )

This method sets the READTIMEOUT property as numeric value that represents the time in seconds to wait for the command output. If the process is expected to run longer it is useful to set it to avoid excessive checks. It is also important for multiple process execusions, because other processes will not be checked before the read has not timed out. It can only be set when the Sub Process is not running.

Parameters:

TIMEOUT - is an integer that specifies how long the manager will be waiting for output.

See Method Launch()

setTimeout ( TIMEOUT )

This method sets the EXECUTIONTIMEOUT property as numeric value that represents the Time in seconds to wait for the process to finish. After this time the process will be terminated.

The EXECUTIONTIMEOUT property must be a positive numeric value. Setting it to a negative value -1 will disable the Execution Timeout

See Method Launch()

See Method Terminate()

Launch ()

This method starts the process. It will create a Sub Process from the defined COMMAND Property.

Per default this the process runs asynchronously. The Wait() method is used to monitor its execution and read its outputs

Returns: It returns 1 when the process was launched correctly. otherwise it returns 0 .

See Method Check()

Check ()

This method checks whether the process is finished and calls the Read() method to read its output.

Returns: It returns 1 when the process is still running otherwise it returns 0 .

See Method Launch()

Read ()

This method reads the STDOUT and STDERR outputs from a running process which was started with the Launch() method.

When the process is not started yet it does not do anything.

If a TIMEOUT is set through the setReadTimeout() method the Manager Process keeps waiting for output until the TIMEOUT is fulfilled.

See Method setReadTimeout()

See Method Launch()

Wait ()

This method calls the Check() method continuously for a started process which was started with the Launch() method until the Check() method tells that the process is finished.

If a TIMEOUT is set through the setTimeout() method the Manager Process will terminate the process after the TIMEOUT is fulfilled. When a process times out an Error Code of 4 will be set.

Returns: It returns 1 when the process has finished correctly. It returns 0 when the process had to be terminated.

See Method Check()

See Method Launch()

See Method Terminate()

See Method setTimeout()

Run ()

This method starts the process calling the Launch() method and then calls the Wait() method to wait until the process is finished.

Returns: It returns 1 when the process was started and finished correctly. It returns 0 when the process could not be started or had to be terminated.

See Method Launch()

See Method Wait()

Terminate ()

This method sends a TERM signal to the process if it is running. And then checks the process with the Check() method.

It is used by the EXECUTIONTIMEOUT functionality to ensure that the process does not run longer than required.

This will include an Error Message "Process terminating ..." and set the Process ERROR CODE to 4 .

Enabling the DEBUG option will additionally include an Activity Information from which method Terminate() was called.

See Method Check()

See Method setTimeout()

Kill ()

This method sends a KILL signal to the process if it is running.

It is used by the EXECUTIONTIMEOUT functionality to ensure that the process does not run longer than required.

Any not yet read output will get lost.

This will include an Error Message "Process killing ..." and set the Process ERROR CODE to 4 and the EXIT CODE to 9 .

Enabling the DEBUG option will additionally include an Error Message from which method Kill() was called.

See Method Check()

See Method setTimeout()

getProcessID

This Method will return the ProcessID of the process which was assigned by the system at launch time.

If the process was not launched yet it will return -1 .

Returns: The ProcessID of the process assigned by the system.

See Method Launch()

getName

This Method will return the Name to the Process::SubProcess object if any was assigned with the setName() method.

Returns: The NAME of the Process::SubProcess object as string.

See Method setName()