xHarbour Reference Documentation > Function Reference

HB_OpenProcess()

Opens a child process.

Syntax

HB_OpenProcess( <xExeFile>   , ;
              [@<nStdIN>]    , ;
              [@<nStdOUT>]   , ;
              [@<nStdERR>]   , ;
              [<lBackGround>], ;
              [@<nProcessID>   ) --> nProcessHandle

Arguments

<xExeFile>

This is a character string holding the name of the executable file to run in the child process. It must be specified as a full qualified file name, including path and file extension. When the path is omitted, the file is searched in the current directory.

@<nStdIN>, @<nStdOUT>, @<nStdERR>

Three optional parameters can be passed by reference. They receive standard file handles for STDIN, STDOUT and STDERR. These file handles can be used to exchange data with the child process.

<lBackGround>

This parameter defaults to .F. (false). When set to .T. (true), the child process is started asynchronously as a background process.

<nProcessID>

If a sixth parameter is passed by reference, it receives the numeric identifier of the child process as assigned by the operating system. It is of informational nature.

Return

The function returns the process handle (similar to a file handle) of the new child process as a numeric value, or -1 if an error occurs. Use function FError() to identify the cause of failure.

Description

Function HB_OpenProcess() opens a new child process and executes the program <cExeFile> in the new process. The program is executed synchronously (<lBackGround>==.T.) or asynchronously (<lBackGround>==.F.).

When the parent process needs to exchange data with the child process, it can use the standard handlers STDIN, STDOUT and STDERR. Numeric handles for them are assigned to the reference parameters <nStdIN>, <nStdOUT> and <nStdERR>.

The parent process can wait for the end of a synchronously started child process with function HB_ProcessValue(), or it can terminate the child process explicitely with function HB_CloseProcess().

When the child process is complete, its process handle and the standard handles, if obtained, must be closed with FCLose().

Info

See also:	HB_CloseProcess(), HB_ProcessValue(), RUN, StartThread()
Category:	Process functions , xHarbour extensions
Source:	rtl\philes.c
LIB:	xhb.lib
DLL:	xhbdll.dll

Examples

Parent process

// This example implements a parent process launching a child process
// (it is shown in the next example).

   PROCEDURE Main()
      LOCAL cData  := "Hello World"
      LOCAL cEXE   := "ChildProc.exe"
      LOCAL nBytes, nChild, nError, nStdIN, nStdOUT, nStdERR

      CLS
      ? "Opening child process:", cEXE

      nChild := HB_OpenProcess( cEXE, @nStdIN, @nStdOUT, @nStdERR )

      IF nChild < 0
         ? "Error:", FError()
         QUIT
      ENDIF

      ? "Sending data         :", FWrite( nStdIN, cData )

      ? "Receiving data       : "
      cData := Space( 1000 )
      nBytes := Fread( nStdOUT, @cData, Len(cData) )
      ?? Left( cData, nBytes )

      ? "Reading errors       : "
      cData := Space( 1000 )
      nBytes := Fread( nStdERR, @cData, Len(cData) )
      ?? Left( cData, nBytes )

      ? "Waiting for end      :", HB_ProcessValue( nChild )

      FClose( nChild )
      FClose( nStdIN )
      FClose( nStdOUT )
      FClose( nStdERR )
   RETURN

Child process

// This example is the child process lauched by the first exemple.
// Both must be compiled and linked as separate EXE files.

   // definition of standard file handles available
   // in a child process:

   #define  FH_STDIN   0
   #define  FH_STDOUT  1
   #define  FH_STDERR  2

   #include "Fileio.ch"

   #define BUFF_SIZE   1024

   PROCEDURE Main
      LOCAL nBytes, cBuffer, cData, nError

      cBuffer := Space( BUFF_SIZE )

      nBytes  := FRead( FH_STDIN, @cBuffer, Len( cBuffer ) )

      cBuffer := "Child process received "    + ;
                        LTrim( Str( nBytes) ) + ;
                 " bytes [" + Trim( cBuffer ) + "]"

      nBytes  := FWrite( FH_STDOUT, cBuffer, Len(cBuffer) )

      nError  := FError()

      cBuffer := "Error code: " + LTrim( Str( nError ) )

      nBytes  := FWrite( FH_STDERR, cBuffer, Len(cBuffer) )
   RETURN