RunProgram()

Syntax

Result = RunProgram(FileName$ [, Parameter$, WorkingDirectory$ [, Flags [, SenderProgram]]])

Launches an external program. The 'FileName$' should be the executable including its path. 'Parameters$' can specify command line parameters that will be passed to the program. 'WorkingDirectory$' can specify a directory that will be the current directory for the external program.

Flags are optional and can be a combination (using '|' OR operator) of the following values:

  #PB_Program_Wait   : Wait until the launched program quits
  #PB_Program_Hide   : Launch the program in invisible mode
  #PB_Program_Open   : Open the program to communicate with it or get information about it.
  #PB_Program_Read   : Read the programs console output. (stdout)
  #PB_Program_Write  : Write to the input of the program. (stdin)
  #PB_Program_Error  : Read the error output of the program. (stderr)
  #PB_Program_Connect: Connect another programs output to this programs input.

A program executed with #PB_Program_Open must be closed with CloseProgram(). The 'Read', 'Write', 'Error' and 'Connect' flags require the #PB_Program_Open flag to be set as well.

When using the #PB_Program_Connect flag, another program must have been started before with #PB_Program_Open and #PB_Program_Read. The number returned when running this program must be passed as the 'SenderProgram' parameter to RunProgram(). The output of the sender program will be sent directly to the input of the now executed program. Several programs can be connected in this way, to 'pipe' data through several programs.

The following commands can be used with a program executed with the #PB_Program_Open flag:

- IsProgram(): check if a number represents a valid program executed by RunProgram().
- ProgramID(): returns the OS ProcessID for the program.
- ProgramRunning(): check if the program is still running.
- WaitProgram(): wait for the program to end.
- KillProgram(): terminate the program.
- ProgramExitCode(): get the exitcode of the program.
- CloseProgram(): close the connection to the program.

The following commands can be used for programs executed with the 'Read', 'Write' and 'Error' flags:

- AvailableProgramOutput(): check if program output is available.
- ReadProgramString(): read a string from the program output.
- ReadProgramData(): read data from the program output.
- ReadProgramError(): read a string from the programs error output.
- WriteProgramString(): write a string to the programs input.
- WriteProgramData(): write data to the programs input.

Return value

If the program cannot be executed, the returnvalue is zero. If RunProgram() was successful, the returnvalue is nonzero.

If #PB_Program_Open was included in the Flags, the returnvalue is a number that identifies the program. It can be used in calls to get information about the program such as ReadProgramString() or ProgramExitCode() or other commands mentioned above.

Example:

  ; Executes the PB compiler with the /? option and displays the output (windows version)
  ; For Linux/MacOS change the "/?" to "-h" and the "\" to "/" in the compiler path.
  ;
  Compiler = RunProgram(#PB_Compiler_Home+"\Compilers\pbcompiler", "/?", "", #PB_Program_Open|#PB_Program_Read)
  Output$ = ""
  If Compiler  
    While ProgramRunning(Compiler)
      Output$ + ReadProgramString(Compiler) + Chr(13)
    Wend
    Output$ + Chr(13) + Chr(13)
    Output$ + "Exitcode: " + Str(ProgramExitCode(Compiler))     
  EndIf
  MessageRequester("Output", Output$)

Supported OS

All