Subprocess - Programmschnittstelle (API)

Subprocess

void	subprocess.close()	Gibt die System-Ressourcen frei

Variable_set	subprocess.env()	Umgebungsvariablen als Variable_set

void	subprocess.set_environment( name, value )	Umgebungsvariablen

int	subprocess.exit_code()

void	subprocess.set_ignore_error( boolean )	Verhindert, dass bei `exit_code != 0` der Job stoppt
boolean	subprocess.ignore_error()

void	subprocess.set_ignore_signal( int )	Verhindert, dass bei einem Abbruch des Prozesses mit Signal der Job stoppt
int	subprocess.ignore_signal()

void	subprocess.kill( signal )	Bricht den Subprozess ab

void	subprocess.set_own_process_group( boolean )	Subprozess als Prozessgruppe
boolean	subprocess.own_process_group()

int	subprocess.pid()	Prozesskennung

void	subprocess.set_priority( int )	Prozess-Priorität
int	subprocess.priority()

void	subprocess.set_priority_class( String )	Prioritätsklasse
String	subprocess.priority_class()

void	subprocess.start( command_line )	Startet den Prozess
void	subprocess.start( filename_and_arguments )

boolean	subprocess.terminated()

int	subprocess.termination_signal()	Signal, mit dem sich der Prozess beendet hat (nur Unix)

void	subprocess.set_timeout( seconds )	Frist für den Subprozess

void	subprocess.wait_for_termination()
boolean	subprocess.wait_for_termination( seconds )

Beispiel system() - Einfache Ausführung eines Kommandos, in javascript

exit_code = my_system( "backup /" );            

function system( cmd, timeout )
{
    var subprocess = spooler_task.create_subprocess();
    
    try
    {
        if( timeout )  subprocess.timeout = timeout;
        subprocess.start( cmd );
        subprocess.wait_for_termination();
        return subprocess.exit_code;
    }
    finally
    {
        subprocess.close();
    }
}

Beispiel in javascript

var subprocess = spooler_task.create_subprocess();

subprocess.environment( "test1" ) = "one";
subprocess.environment( "test2" ) = "two";
subprocess.ignore_error = true;

subprocess.start( "sleep 20" );

spooler_log.info( "pid=" + subprocess.pid );
subprocess.timeout = 10;

spooler_log.info( "wait_for_termination ..." );
var ok = subprocess.wait_for_termination( 10 );
spooler_log.info( "wait_for_termination ok=" + ok );

if( subprocess.terminated )
{
    spooler_log.info( "exit code=" + subprocess.exit_code );
    spooler_log.info( "termination signal=" + subprocess.termination_signal );
}

Ein Subprozess ist irgendein Prozess, der mit Task.create_subprocess() oder Subprocess.start() gestartet werden kann.

close

Gibt die System-Ressourcen frei

void	subprocess.close()

Sollte in Sprachen mit Garbage Collector (Java, JavaScript) gerufen werden, außer die Task beendet sich sofort.

Der Subprocess ist danach unbrauchbar.

env

Umgebungsvariablen als Variable_set

Variable_set subprocess.env()

Beispiel in javascript

var subprocess = spooler_task.create_subprocess();
subprocess.start( subprocess.env.substitute( "${MY_HOME}/my_program" ) );
subprocess.wait_for_termination();

Liefert ein Variable_set der Umgebungsvariablen.

Anfänglich ist die Umgebung mit den Umgebungsvariablen des startenden Prozesses gefüllt. Umgebungsvariablen können entfernt werden, indem sie auf "" gesetzt werden. Der Aufruf Subprocess.start() übergibt die Umgebungsvariablen dem Subprozess.

Unter Unix werden groß und klein geschriebene Umgebungsvariablen unterschieden.

Nach dem Start des Subprozesses haben Änderungen an den Umgebungsvariablen keine Wirkung. Auch können vom Prozess geänderte Umgebungsvariablen nicht gelesen werden.

Das Objekt lässt sich nicht anderen Objekten übergeben (denn es befindet sich im Prozess der Task, während die meisten anderen Objekte sich im Prozess des Schedulers befinden).

Rückgabe

Variable_set

environment

Umgebungsvariablen

void	subprocess.set_environment( String name, String value )

Beispiel

// The following two statements have the same effect
subprocess.set_environment( "my_variable", "my_value" )
subprocess.env().set_value( "my_variable" ) = "my_value"

Die hier gesetzten Variablen werden zusammen mit den übrigen Umgebungsvariablen des laufenden Prozesses dem neuen Subprozess übergeben.

Unter Unix werden groß und klein geschriebene Umgebungsvariablen unterschieden.

Siehe auch Subprocess.env.

Parameter

name
value

exit_code

int	subprocess.exit_code()

Erst aufrufen, wenn Subprocess.terminated == true.

ignore_error

Verhindert, dass bei exit_code != 0 der Job stoppt

void	subprocess.set_ignore_error( boolean )
boolean	subprocess.ignore_error()

Verhindert, dass der Job stoppt, wenn der Subprozess bei Task-Ende mit Subprocess.exit_code != 0 geendet hat.

Wenn das Ende des Subprocesses nicht mit Subprocess.wait_for_termination abgewartet worden ist, tut das der Scheduler bei Task-Ende. Wenn dann der Subprocess mit Subprocess.exit_code != 0 endet, stoppt der Job mit Fehler.

Mit ignore_error kann das verhindert werden.

Parameter

boolean

ignore_signal

Verhindert, dass bei einem Abbruch des Prozesses mit Signal der Job stoppt

void	subprocess.set_ignore_signal( int )
int	subprocess.ignore_signal()

Wirkt nicht unter Windows, weil es hier keine Signale gibt.

Parameter

int

kill

Bricht den Subprozess ab

void	subprocess.kill( int signal (optional) )

Parameter

signal (optional)

Nur unter Unix: Das Signal für kill(). 0 wird als 9 (SIGKILL, sofortiges Ende) interpretiert.

own_process_group

Subprozess als Prozessgruppe

void	subprocess.set_own_process_group( boolean )
boolean	subprocess.own_process_group()

Nur unter Unix.

Der Default kann mit factory.ini (Abschnitt [spooler], Eintrag subprocess.own_process_group=…) eingestellt werden.

own_process_group lässt den Subprozess in einer eigenen Prozessgruppe starten, indem der Systemaufruf setpgid(0,0) ausgeführt wird. Wenn der Scheduler den Subprozess abbricht, bricht er die ganze Prozessgruppe ab.

Parameter

boolean

pid

Prozesskennung

int	subprocess.pid()

priority

Prozess-Priorität

void	subprocess.set_priority( int )
int	subprocess.priority()

Beispiel in javascript

subprocess.priority = +5;    // Unix: Priorität etwas verschlechtern

Unix: Die höchste Priorität ist -20, die niedrigste 20. Üblicherweise kann die Priorität nur gesenkt, nicht erhöht werden.

Windows kennt die Prioritätsklassen 4 "idle", 6 "below_normal", 8 "normal", 10 "above_normal" und 13 "high" (andere Werte werden abgerundet). Siehe auch Task.priority_class.

Wenn die Priorität nicht gesetzt werden kann, führt das nicht zu einem Fehler.

Ein Prozess mit hoher Priorität kann Ihren Rechner blockieren.

Die Priorität kann betriebsystem-unabhängig eingestellt werden mit Subprocess.priority_class. Siehe auch Task.priority.

Parameter

int

priority_class

Prioritätsklasse

void	subprocess.set_priority_class( String )
String	subprocess.priority_class()

Beispiel in javascript

subprocess.priority_class = "below_normal";

Gesetzt werden können folgende Prioritätsklassen, die verschiedenen Prioritäten unter Windows und Unix entsprechen:

Prioritätsklasse	Windows	Unix
`"idle"`	4	16
`"below_normal"`	6	6
`"normal"`	8	0
`"above_normal"`	10	-6
`"high"`	13	-16

Wenn die Priorität nicht gesetzt werden kann, z.B. wegen mangelndem Recht, führt das nicht zu einem Fehler. Dagegen führt das Setzen einer nicht hier aufgeführten Prioritätsklasse zu einem Fehler.

Ein Prozess mit hoher Priorität kann Ihren Rechner blockieren.

Siehe auch Subprocess.priority, Task.priority_class und Microsoft® Windows® Scheduling Priorities.

Parameter

String

start

Startet den Prozess

void	subprocess.start( String command_line )
void	subprocess.start( String[] filename_and_arguments )

Windows erkennt sofort, wenn das Programm nicht ausführbar ist. Die Methode liefert dann einen Fehler.

Unter Unix wird stattdessen Subprocess.exit_code auf 99 gesetzt. Vorher muss das Ende des Prozesses abgewartet werden mit Subprocess.wait_for_termination().

Shell-Operatoren wie |, && und > werden nicht interpretiert. Verwenden Sie dazu die Programme /bin/sh bzw. c:\windows\system32\cmd.exe (das Verzeichnis ist installations-abhängig).

Der Prozess wird unter Unix mit execvp() und unter Windows mit CreateProcess() gestartet.

Parameter

command_line

terminated

boolean

subprocess.terminated()

Prüft, ob der Prozess geendet hat. Wenn er geendet hat, kann anschließend Subprocess.exit_code und Subprocess.termination_signal gerufen werden.

termination_signal

Signal, mit dem sich der Prozess beendet hat (nur Unix)

int	subprocess.termination_signal()

Erst aufrufen, wenn Subprocess.terminated == true.

timeout

Frist für den Subprozess

void	subprocess.set_timeout( double seconds )

Nach Ablauf der Zeit bricht der Scheduler den Subprozess ab (Unix: mit SIGKILL).

Bei Ausführung auf einem entfernten Rechner mit <process_class remote_scheduler="…"> wirkt die Frist nicht.

Parameter

seconds

Meldungen

[warn] SCHEDULER-849 Timeout is not possible for a subprocess running on a remote host (it cannot be killed), pid=(1)

wait_for_termination

void	subprocess.wait_for_termination()
boolean	subprocess.wait_for_termination( double seconds )

Parameter

seconds

Wartezeit. Fehlt der Parameter, dann wartet der Aufruf bis der Subprozess geendet hat.

Rückgabe

boolean

true, wenn der Subprozess geendet hat.
false, wenn der Subprozess nach Ablauf der Wartezeit noch läuft.

Software- und Organisations-Service GmbH

Zuletzt geändert von Joacim Zschimmer, 2007-10-25