### 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

~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

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.

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

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

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

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

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

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

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

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

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

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.

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

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

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

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

  -     static IExtProcImplBase* makeImplObj()

#### Inherited Public Data

  - None

#### Inherited Protected Functions

  - None

#### Inherited Protected Data

  - None