IExternalProcess

IExternalProcess is a mechanism for executing and controlling external processes. It provides the functionality traditionally associated with C RTL functions such as spawn() or exec(), but does so within a fully OpenClass enabled environment. Each instance of IExternalProcess can control a single process. It allows you to start, terminate, wait for, control the priority of, and retrieve the termination code of the process.

This class works in conjunction with IEnvironment, which is used to build the environment passed to the new process. Note that, upon construction, an IExternalProcess has no environment. If you want to pass any environment to your new process, you must create an IEnvironment object and call setEnvironment() to set up the new environment. The IEnvironment class has an optional constructor that will fill itself in with the current environment of the calling process, which is most often what you want to do. Once you have a copy of your own environment, you can add or remove or modify entries in it before setting the environment on the external process object.

Portability Considerations

OS/2 does not allow you to retrieve the priority class of an external process, nor is killing a process necessarily guaranteed to be successful.

OS/2 is not capable of passing UNICode environment variables or command line parameters to the new process. All such text will be converted from their IText format into ASCII text before being passed to the new process.


IExternalProcess - Member Functions and Data by Group

Constructors & Destructor

Construct and destructor external process objects


[view class]
~IExternalProcess
Destroys the external process object.
public:
~IExternalProcess()
The destructor just cleans up any system resources used to refer to the external process and any internal data required to track it. This operation does not imply any attempt to stop the external process. It continues to run until it dies a natural death, you just lose you ability to control it.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
IExternalProcess
Constructs an external process object.
public:
IExternalProcess()
Constructs the external process object and gets it ready for use. This does not start the process, and it does not set the path to the executable to be run. It just gets the object ready to use.
The default constructor is the only available constructor.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Member Access

Access member data of an external process object.


[view class]
getId
Gets the process id of the process if its running.
public:
inline IProcessId getId() const
Returns the process id of the external process. If the process is not running, then the results are undefined.

Return
The process id of the process. The value is undefined if the process is not running.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
getPath
Gets the currently set path
public:
inline IPathName getPath() const
Returns the currently set path of this object. The path refers to the path to the executable program that is to be run. It does not have to be set during construction so it may return an empty path if it has never been set.

Return
The path that is currently set for the process. Since it cannot be changed when the process is running, it will always reflect the path to a currently running process.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
id
Obsoleted, use getId()
public:
inline IProcessId id() const
This is an obsoleted method that is supported for backwards compability. Use getId() instead.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setEnvironment
Sets the new environment for next start()
public:
inline void setEnvironment(const IEnvironment& newEnv)
Sets the environment of the external process. It cannot be called while the process is running. However, before the process is started or after it terminates, this may be called to set up a new environment for the next time the process is started.

Exception

IInvalidRequest if the process is already started.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setPath
Sets the new path for the next start()
public:
inline void setPath(const IPathName& newName)
Sets the path to the external process. It cannot be called while the process is running. However, before the process is started or after it terminates, this may be called to set up a new path for the next time the process is started.

newName
the new path name to set. The next time that start() is called, this will be the default path to execute.

Exception

IInvalidRequest if the process is already started.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Process Control

Control the external process


[view class]
kill
Attempts to kill the process
public:
inline virtual void kill()
This method will attempt to kill the process. This is not a recommended action, as it might stop the process such that data or resources are left in an unpredictable state. It also is not necessarily guaranteed to work on all platforms. Some programs may not be killable.

Exception

IAccessError if the system API used to implement this method fails.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setPriority
Sets the priority of the process
public:
virtual bool setPriority( INonGUIApplication::PriorityClass priority )
Sets the priority class of the process. This only works if the process is actually running.

priority
is the new priority class to set for the process.

Return
true if the priority was successfully set, else false.

Exception

IAccessError if the system API used to implement this method fails.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
start
This method, in all its various flavors, starts up the process. This can only be called if the process is not already started. The version with no parameters assumes that all information required has already been set up.


Overload 1
Starts the process, if not already started.
public:
virtual void start()
Assumes that all of the required information is already set, and starts the program without any parameters.

Exception

IInvalidRequest if the process is already started.

IInvalidParameter if the path currently set is empty or beyond the maximum legal platform length, or does not represent a valid executable file.

IResourceExhausted if the internal environment buffer used to pass environment info to the new process is overflowed by too much environmental variable information.

IAccessError if the system API used to execute the new process fails.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
Sets the path, then starts the process, if not already started.
public:
virtual void start(const IPathName& path)
Sets the path to the process, and then starts the program without any parameters.

path
is the path of the process to start. This overrides any existing path that was previously set, even if the start fails.

Exception

IInvalidRequest if the process is already started.

IInvalidParameter if the path currently set is empty or beyond the maximum legal platform length, or does not represent a valid executable file.

IResourceExhausted if the internal environment buffer used to pass environment info to the new process is overflowed by too much environmental variable information.

IAccessError if the system API used to execute the new process fails.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
Sets the params, then starts the process, if not already started.
public:
virtual void start( const IText* argArray, const unsigned long argCount )
Starts the program with the passed parameters.

argArray
an array of IText objects which contain the command line parameters to pass

argCount is the count of arguments in the argArray parameter.

Exception

IInvalidRequest if the process is already started.

IInvalidParameter if the path currently set is empty or beyond the maximum legal platform length, or does not represent a valid executable file.

IResourceExhausted if the internal environment buffer used to pass environment info to the new process is overflowed by too much environmental variable information.

IAccessError if the system API used to execute the new process fails.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 4
Sets the path and params, then starts the process, if not already started.
public:
virtual void start( const IPathName& path, const IText* argArray, const unsigned long argCount )
Sets the path to the process, and then starts the program with the passed parameters.

path
is the path of the process to start. This overrides any existing path that was previously set, even if the start fails.

argArray an array of IText objects which contain the command line parameters to pass

argCount is the count of arguments in the argArray parameter.

Exception

IInvalidRequest if the process is already started.

IInvalidParameter if the path currently set is empty or beyond the maximum legal platform length, or does not represent a valid executable file.

IResourceExhausted if the internal environment buffer used to pass environment info to the new process is overflowed by too much environmental variable information.

IAccessError if the system API used to execute the new process fails.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
stop
Obsoleted, use kill() instead.
public:
inline void stop()
This is an obsoleted method maintained for backwards compatibility. Use the kill() method instead.

Exception

Same

as kill()

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
wait
public:
inline virtual bool wait(const long timeout = - 1) const
Waits for the process to die. It will wait for up to the passed number of milliseconds. The default value, if no timeout is provided, is -1, which means never timeout. After this call is successfully executed, the exitStatus() method can be called to query the exit status of the process. Also, after a successful wait(), it is guaranteed to be safe to call the other methods that are only valid when the process is not running.

timeout
is the number of milliseconds to wait for the process to die before giving up.

Return
true if the process died within the timeout period, else false if the timeout occured.

Exception

IAccessError if the system wait API used to implement this method fails.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Process Information

Query information about the external process.


[view class]
exitStatus
Returns the process exit status
public:
inline virtual bool exitStatus(unsigned long& status) const
Returns the exit status of the process, if it has terminated. If it has not terminated, then the return value is false and the passed parameter is not changed.

status
is filled with the process exit status if the process is running.

Return
true if the process' exit status was successfully extracted, else false.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
getPriority
Gets the priority of the process
public:
virtual INonGUIApplication::PriorityClass getPriority() const
Queries the priority class of the external process. This method is not supported on all platforms.

Return
The priority of the process, if it is running. If it is not running or the platform is OS/2, then an exception is generated.

Exception

IAccessError if the priority cannot be obtained

IInvalidParameter if the priority returned from the system is not mappable to a standard OpenClass process priority class.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
isRunning
Indicates whether the process is running or not
public:
inline virtual bool isRunning() const
Returns a boolean that indicates whether the process is currently running or not. As in any multiprocess system, this is only advisory as the state can change after this call returns but before any action can be taken based on the results.

Return
true if the program is running, else false.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
isStarted
Obsoleted, use isRunning() instead.
public:
inline bool isStarted() const
This is an obsoleted method maintained for backwards compability. Use isRunning() instead.

Return
true if the process is running, else false.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


IExternalProcess - Inherited Member Functions and Data

Inherited Public Functions

IExternalProcess

Inherited Public Data

Inherited Protected Functions

Inherited Protected Data