TATUProcessManager.Run

TATUProcessManager.Run

Execute the program with the given options under this instance of TATUProcessManager class.
Declared in [atuProcess] unit. This method exists in 2 overloaded versions.

Overloaded version #1:

Procedure Run(const ATaskId,AExeName: string; ACommands: array of string; const AOptions : TProcessOptions = []); overload;

Arguments

Argument	Description
ATaskIt: string	TaskId is a user specified string identifier that can be used to identify each process running under the same instance of TATUProcessManager. Imagine that same instance has multiple processes running simultaneously, and each of them calls events. TaskId can help differentiate between them within event code.
AExeName: string	The name of the executable to run. Ideally this is a full path to the executable, but it is not, the default path will be used to try to execute user-specified command.
ACommands: array of string	This is an array of all of the command line parameters to be passed to the executable to be run.
AOptions: TProcessOptions	This is the equivalent of the standard Delphi/FPC type documented here.

Example

var 
  APM : TATUProcessManager;

//(...)

//Querying local IP address on Ubuntu via ACommands:
  APM.Run('UserDefinedTaskId1', '/bin/hostname', ['-I'],[]);
  { The output can be fetched via OnOutput and OnExit events. }

//Run bash to execute a script passed as command line parameter, to print environmental variable:
  APM.Run('UserDefinedTaskId2', 'bash', ['-c', 'echo $HOME',[]);
  { The output can be fetched via OnOutput and OnExit events. }

//Remounting rootfs as read-only via ACommands:
  APM.Run('UserDefinedTaskId3', 'sudo', ['mount','-o','remount,ro','/'],[]);
  { The output can be fetched via OnOutput and OnExit events.
    The sudo prompt for password can be programmed via OnSudoPrompt event.
  }

//On Ubuntu, spawn a native desktop notification with a custom message:
  APM.Run('UserDefinedTaskId4', 'notify-send', ['Hello!'],[]);
  { In this case we don't need to fetch any output, not handle any interaction, just call and forget. }

Overloaded version #2:

Procedure Run(const ATaskId,ACommandLine: string; const AOptions : TProcessOptions = []); overload;

Arguments

Argument	Description
ATaskIt: string	TaskId is a user specified string identifier that can be used to identify each process running under the same instance of TATUProcessManager. Imagine that same instance has multiple processes running simultaneously, and each of them calls events. TaskId can help differentiate between them within event code.
ACommandLine: string	This overloaded version accepts all combined string of the executable and the command line arguments following it.
AOptions: TProcessOptions	This is the equivalent of the standard Delphi/FPC type documented here.

Example

var 
  APM : TATUProcessManager;

//(...)

//Querying local IP address on Ubuntu via ACommandLine:
  APM.Run('UserDefinedTaskId1', 'hostname -I',[]);
  { The output can be fetched via OnOutput and OnExit events. }

//Run bash to execute a script passed as command line parameter, to print environmental variable:
  APM.Run('UserDefinedTaskId2', 'bash -c "echo $HOME"',[]);
  { The output can be fetched via OnOutput and OnExit events. }

//Remounting rootfs as read-only via ACommandLine:
  APM.Run('UserDefinedTaskId3', 'sudo mount -o remount,ro /',[]);
  { The output can be fetched via OnOutput and OnExit events.
    The sudo prompt for password can be programmed via OnSudoPrompt event.
  }

//On Ubuntu, spawn a native desktop notification with a custom message:
  APM.Run('UserDefinedTaskId4', 'notify-send "Hello!"',[]);
  { In this case we don't need to fetch any output, not handle any interaction, just call and forget. }

Thread-safe code in OnOutput and OnSudoPrompt events

The TATUProcessManager executes processes in asynchronous (non-blocking) way, and unlike FPC's Process.RunCommand routine, the Run method will not wait for the program to finish executing before returning with the program's output. To capture output of the program that runs under the instance of [TATUProcessManager] you need to use its events:

• [TATUProcessManager.OnOutput]
• [TATUProcessManager.OnSudoPrompt]

Both of these events are asynchronous, and you should not update GUI from within them. If you need to update gui, for example to print/display the output of a program somewhere in your host application, use some thread-safe mechanism of exchanging the data from asynchronous events to the main thread of the application. Some of such mechanisms are provided in [atuExchange] unit. You can see the [ATUProcess_demo] for a case scenario using [TStringFIFO] class for delegating data to be printed our of the asynchronous events, that is then "consumed" by a TTimer component of the host application, where the data can be received and printed in a thread-safe way.
The advantage of asynchronous events is that you can do data processing without hanging your main application.