Task - Programmschnittstelle (API)

Task

	spooler_task.add_pid( pid, timeout )	Macht dem Scheduler einen abhängigen, befristeten Prozess bekannt

	spooler_task.call_me_again_when_locks_available()	Wiederholt spooler_open() oder spooler_process(), sobald Sperren verfügbar

string	spooler_task.changed_directories	Die Verzeichnisse, deren Änderung den Start der Task veranlasst haben

Subprocess	spooler_task.create_subprocess( filename_and_arguments )	Start eines überwachten Subprozesses

	spooler_task.delay_spooler_process = seconds_or_hhmm_ss	Verzögert den nächsten Aufruf von `spooler_process()`

	spooler_task.end()	Beendet die Task

	spooler_task.error = string	Setzt einen Fehler und stoppt den Job
Error	spooler_task.error	Setzt einen Fehler und stoppt den Job

	spooler_task.exit_code = int	Exit-Code
int	spooler_task.exit_code

	spooler_task.history_field( name ) = value	Ein Feld in der Task-Historie

int	spooler_task.id	Die Task-Kennung

Job	spooler_task.job	Der Job, zu dem die Task gehört

Order	spooler_task.order	Der zu verarbeitende Auftrag

Variable_set	spooler_task.params	Die Parameter der Task

	spooler_task.priority = int	Priorität der laufenden Task
int	spooler_task.priority

	spooler_task.priority_class = string	Prioritätsklasse der laufenden Task
string	spooler_task.priority_class

	spooler_task.remove_pid( pid )	Gegenstück zu `add_pid()`

	spooler_task.repeat = double	Startet erneut eine Task nach der eingestellten Zeit

string	spooler_task.stderr_path	Der Pfadname der `stderr`-Ausgabe der Task

string	spooler_task.stderr_text	Der bisher vom Prozess der Task nach `stderr` geschriebene Text

string	spooler_task.stdout_path	Der Pfadname der `stdout`-Ausgabe der Task

string	spooler_task.stdout_text	Der bisher vom Prozess der Task nach `stdout` geschriebene Text

string	spooler_task.trigger_files	Pfade der Dateien in mit regex überwachten Verzeichnissen

boolean	spooler_task.try_hold_lock( lock_path )	Versucht, eine Sperre zu halten

boolean	spooler_task.try_hold_lock_non_exclusive( lock_path )	Versucht, eine Sperre nicht-exklusiv zu halten

Web_service	spooler_task.web_service	Der Webdienst, der der Task zugeordnet ist

Web_service	spooler_task.web_service_or_null	Der Webdienst, der der Task zugeordnet ist, oder `null`.

Eine Task ist eine laufende Instanz eines Jobs.

Eine Task kann wartend in der Task-Warteschlange des Jobs sein oder laufen.

add_pid

Macht dem Scheduler einen abhängigen, befristeten Prozess bekannt

spooler_task.add_pid( int pid, string|double|int timeout (optional) )

Mit dem Aufruf kann die Laufzeit von abhängigen Prozessen eingeschränkt werden. Bei Task-Ende bricht der Scheduler noch laufende abhängigen Prozesse in jedem Fall ab.

Wenn der Scheduler einen Prozess abbricht, gibt es einen Eintrag ins Protokoll. Die Task erfährt davon nichts.

Der Aufruf <kill_task> bricht alle mit add_pid() bekannt gemachten Prozesse ab.

Unter Unix kann eine Prozessgruppen-Id als negative pid übergeben werden. Ein kill bricht dann die ganze Prozessgruppe ab.

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

Parameter

pid
timeout (optional)

Meldungen

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

call_me_again_when_locks_available

Wiederholt spooler_open() oder spooler_process(), sobald Sperren verfügbar

spooler_task.call_me_again_when_locks_available()

Veranlasst den Scheduler, nach erfolglosem spooler_task.try_hold_lock() oder spooler_task.try_hold_lock_non_exclusive() den Aufruf von spooler_open() bzw. spooler_process() zu wiederholen, sobald die angeforderten Sperren verfügbar sind. Der Scheduler wiederholt dann den Aufruf mit gehaltenen Sperren, so dass die erstgenannten Aufrufe Erfolg haben werden.

Nach dem Aufruf hat der Rückgabewert von spooler_open() bzw. spooler_process() (true/false) keine Wirkung. Einen Auftrag spooler_task.order belässt der Scheduler in seinem Zustand.

Exceptions

SCHEDULER-468 Using this call is not possible in this context

changed_directories

Die Verzeichnisse, deren Änderung den Start der Task veranlasst haben

string

spooler_task.changed_directories

Siehe Job.start_when_directory_changed(), Task.trigger_files.

Rückgabe

string

Die Verzeichnisnamen sind durch Semikolon getrennt.

"", wenn kein Verzeichnis geändert ist.

Meldungen

[warn] SCHEDULER-976 This directory path with ';' will not be included in triggered_files: (1)

create_subprocess

Start eines überwachten Subprozesses

Subprocess spooler_task.create_subprocess( string|string[] filename_and_arguments (optional) )

Parameter

filename_and_arguments (optional)

Rückgabe

Subprocess

delay_spooler_process

Verzögert den nächsten Aufruf von spooler_process()

spooler_task.delay_spooler_process = string|double|int seconds_or_hhmm_ss

Wirkt nur in spooler_process().

Parameter

seconds_or_hhmm_ss

end

Beendet die Task

spooler_task.end()

Der Scheduler ruft nicht mehr spooler_process() auf. Statt dessen ruft er spooler_close() auf.

Der Aufruf kann verwendet werden, um beim Task-Ende den Versand des Task-Protokolls zu veranlassen, siehe Log.

Meldungen

[info] SCHEDULER-815 Task should end but it has just been started with an order attached, so one step will be done

error

Setzt einen Fehler und stoppt den Job

	spooler_task.error = string
`Error`	spooler_task.error

Der lesende Aufruf liefert den letzten Fehler dieser Task. Wenn kein Fehler vorliegt, wird ein Error-Objekt zurückgeliefert, dessen Eigenschaft is_error false liefert.

Sie können eine Fehlermeldung auch mit spooler_log.error() ins Task-Protokoll schreiben.

Parameter

string

Rückgabe

Error

exit_code

Exit-Code

	spooler_task.exit_code = int
int	spooler_task.exit_code

Beispiel

spooler_log.error( "This call of spooler_log.error() sets the exit code to 1" );
spooler_task.exit_code = 0;   // Reset the exit code

Der Exit-Code ist anfänglich 0 und wird bei einem Fehler auf 1 gesetzt. Das ist, wenn der Scheduler eine Zeile mit [ERROR] ins Task-Protokoll schreibt:

Aufruf von spooler_log.error()
Setzen von spooler_task.error
Das Skript liefert eine Exception.

Der Job kann anschließend, z.B. in spooler_on_error(), den spooler_task.exit_code neu setzen.

Der Exit-Codes des (Betriebssystem-)Prozesses, der die Task ausführt, ist ohne Belang und wird nicht übernommen, im Gegensatz zu Jobs mit <process> oder <script language="shell">.

Der Exit-Code entscheidet über die anschließend auszuführenden Kommandos. Siehe hierzu <job><commands on_exit_code="…">.

Der Exit-Codes hat keinen Einfluss darauf, ob der Job gestoppt wird (eine Fehlermeldung der Task lässt den Job stoppen).

Parameter

int

history_field

Ein Feld in der Task-Historie

spooler_task.history_field( string name ) = var value

Beispiel

spooler_task.history_field( "extra" ) = 4711;

Die Datenbanktabelle (s. factory.ini (Abschnitt [spooler], Eintrag db_history_table=…) muss eine Spalte mit dem Namen haben und diese Spalte muss in der Datei factory.ini (Abschnitt [job], Eintrag history_columns=…) deklariert sein.

Parameter

name
value

id

Die Task-Kennung

int	spooler_task.id

Jede Task hat eine Scheduler-weit eindeutige numerische Kennung.

job

Der Job, zu dem die Task gehört

Job spooler_task.job

Rückgabe

Job

order

Der zu verarbeitende Auftrag

Order spooler_task.order

Beispiel

var order = spooler_task.order;

spooler_log.info( "order.id=" + order.id + ", order.title=" + order.title );

Rückgabe

Order

null, wenn kein Auftrag vorliegt.

params

Die Parameter der Task

Variable_set spooler_task.params

Beispiel

var value = spooler_task.params.value( "parameter3" );

Beispiel

var parameters = spooler_task.params;
if( parameters.count > 0 )  spooler_log.info( "Parameters given" );

var value1 = parameters.value( "parameter1" );
var value2 = parameters.value( "parameter2" );

Eine Task kann Parameter haben. Die Parameter können gesetzt werden mit

In der Konfigurationsdatei im Element <job> mit <params>,
Job.start() und
<start_job>.

Rückgabe

Variable_set

!= null

priority

Priorität der laufenden Task

	spooler_task.priority = int
int	spooler_task.priority

Beispiel

spooler_task.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 Task.priority_class.

Parameter

int

priority_class

Prioritätsklasse der laufenden Task

	spooler_task.priority_class = string
string	spooler_task.priority_class

Beispiel

spooler_task.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 mangelnden Rechts, 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 Task.priority, Subprocess.priority_class und Microsoft® Windows® Scheduling Priorities.

Parameter

string

remove_pid

Gegenstück zu add_pid()

spooler_task.remove_pid( int pid )

Es gibt keinen Fehler, wenn die Pid nicht mit Task hinzugefügt worden ist.

Siehe Task.add_pid().

Parameter

pid	Kennung der Task, die nicht länger überwacht werden soll.

repeat

Startet erneut eine Task nach der eingestellten Zeit

spooler_task.repeat = double

(Diese Methode gehört eigentlich in die Klasse Job. Sie hat nichts mit der gerade laufenden Task zu tun.)

Wenn nach Ablauf der angegebenen Zeit keine Task des Jobs läuft, startet der Scheduler eine Task. Dabei wird die <run_time> berücksichtigt. <period repeat="…"> der aktuellen Periode wird vorläufig außer Kraft gesetzt.

Job.delay_after_error hat Vorrang, wenn die Task einen Fehler liefert.

Parameter

Siehe Job.start_when_directory_changed(), Task.changed_directories().

Rückgabe

string

Die Dateipfade durch Semikolon getrennt.

"" sonst

Meldungen

[warn] SCHEDULER-975 This file path with ';' will not be included in changed_directory: (1)

try_hold_lock

Versucht, eine Sperre zu halten

boolean

spooler_task.try_hold_lock( string lock_path )

Beispiel

function spooler_process() 
{
    var result = false;
    
    if( spooler_task.try_hold_lock( "Georgien" )  &&
        spooler_task.try_hold_lock_non_exlusive( "Venezuela" ) )
    {
        // Task is holding the two locks. Insert processing code here.
        result = ...
    }
    else
    {
        spooler_task.call_me_again_when_locks_available();
    }
    
    return result;
}

try_lock_hold() versucht, die angegebene Sperre (Lock) zu halten, und kann aufgerufen werden

in spooler_open(): die Sperre wird für die Task gehalten und erst nach Beendigung freigegeben,
in spooler_process(): die Sperre wird für nur für diesen Jobschritt gehalten und nach dessen Beendigung freigegeben, also beim Verlassen von spooler_process().

Wenn die Sperre nicht verfügbar ist, ein Aufruf also false liefert, kann entweder

mit spooler_task.call_me_again_when_locks_available() der Scheduler veranlasst werden, den Aufruf spooler_open() bzw. spooler_process() zu wiederholen, sobald die Sperren verfügbar sind, oder
spooler_open() bzw. spooler_process() ohne vorgenannten Aufruf mit false beendet werden, mit der üblichen Wirkung,
aber nicht mit true beendet werden, das wird als Fehler angesehen und führt zur Warnung SCHEDULER-469.