KC_SHUTDOWN - Anwendungslauf beenden

Mit KC_SHUTDOWN können Sie den aktuellen Anwendungslauf beenden.

In UTM-Cluster-Anwendungen (Unix-, Linux- und Windows-Systeme) können Sie angeben, ob der Anwendungslauf auf allen Knoten beendet wird oder nur auf dem Knoten, an dem der Aufruf erfolgt.

Folgende Möglichkeiten stehen Ihnen zur Verfügung:

• Sie können den Anwendungslauf normal beenden. UTM beendet den Anwendungslauf, sobald alle laufenden Dialog-Schritte beendet sind (KC_NORMAL).

• Sie können den Anwendungslauf zeitgesteuert nach einer angegebenen Zeitspanne beenden (KC_WARN).

• Sie können den Anwendungslauf beenden, nachdem alle UTM-D-Dialoge beendet und alle UTM-D-Verbindungen abgebaut sind, spätestens jedoch nach einer angegeben Zeitspanne (KC_GRACEFUL).

• Sie können den Anwendungslauf abbrechen, d.h. sofort abnormal beenden (KC_KILL).

Zum Beenden eines UTM-Anwendungslaufs siehe auch die openUTM-Handbuch „Einsatz von UTM-Anwendungen“.

Beim Anwendungsabbruch ist Folgendes zu beachten:

Der Anwendungsabbruch (KC_KILL) kann nicht als Asynchron-Vorgang erfolgen, er ist nur im Dialog erlaubt. Der Aufruf mit subopcode1=KC_KILL in einem Asynchron-Vorgang wird von UTM abgewiesen.

Beim Shutdown von Anwendungen mit verteilter Verarbeitung ist Folgendes zu beachten:

Anwendungen mit verteilter Verarbeitung sollten Sie am besten mit KC_GRACEFUL beenden, alternativ mit KC_WARN. Dabei sollten Sie eine Zeit angeben, die größer ist als die Zeit, die eine verteilte Transaktion maximal im Zustand PTC (d.h. Transaktionsstatus P) verbleibt. Damit verringert sich die Wahrscheinlichkeit, dass verteilte Transaktionen beim Anwendungsende noch in diesem Zustand sind und die Anwendung abnormal mit END-PET beendet wird.

Generell gilt:
Eine Anwendung mit verteilter Verarbeitung wird nicht normal beendet, wenn es zum Zeitpunkt des Shutdowns noch Vorgänge mit Transaktionsstatus P 'preliminary end of transaction' gibt, oder wenn für Asynchron-Nachrichten an einen Partner-Server noch keine Quittungen eingetroffen sind. UTM gibt dann die Meldung K060 mit der Abbruchursache ENDPET aus. Es werden keine Dumps erzeugt.

Ablauf / Wirkungsdauer / Transaktionssicherung / Cluster:

Der Aufruf von KC_SHUTDOWN unterliegt nicht der Transaktionssicherung. Er ist nicht durch einen RSET-Aufruf rücksetzbar.

Der Abbruch eines Anwendungslaufs (KC_KILL) wirkt sofort, es wird nicht mehr in das Teilprogramm zurückgekehrt.

Soll die Anwendung beendet werden (KC_NORMAL, KC_WARN und KC_GRACEFUL), dann wird durch den Aufruf ein Auftrag erzeugt, d.h. Aktionen zum Shutdown angestoßen.

Der Ablauf des Shutdown, d.h. wie und wann UTM den Anwendungslauf beendet, ist abhängig von den Angaben für subopcode1 im Parameterbereich. Der Ablauf des Shutdown wird unter Punkt KC_GRACEFUL beschrieben.

Für UTM-Cluster-Anwendungen (Unix-, Linux- und Windows-Systeme) gilt:
Der Aufruf kann sowohl Cluster-global als auch Knoten-lokal wirken, d.h. der aktuelle Anwendungslaufs wird auf allen Knoten beendet, oder der Anwendungslauf wird nur auf dem Knoten beendet, auf dem der Aufruf erfolgte. 

KDCSHUT ("KDCSHUT - Anwendungslauf beenden")

Versorgung der zu übergebenden Bereiche

Funktion des Aufrufs	Angabe im
	Parameterbereich 1	Identifikationsbereich	Selektionsbereich	Datenbereich
Anwendungslauf sofort abbrechen (nur im Dialog)	subopcode1: KC_KILL	——	——	—— bzw. kc_shutdown_str
Anwendungslauf normal beenden	subopcode1: KC_NORMAL	——	——	—— bzw. kc_shutdown_str
Anwendungslauf nach Ablauf eines Timers normal beenden openUTM auf einem BS2000-System gibt Standardmeldung an alle aktiven Benutzer aus	subopcode1: KC_WARN	——	——	kc_shutdown_str
Anwendungslauf auf einem BS2000-Systeme nach Ablauf eines Timers normal beenden und eine Meldung an alle aktiven Benutzer senden	subopcode1 : KC_WARN, subopcode2 : KC_USER_MSG	——	——	kc_shutdown_str
Anwendungslauf normal beenden, wenn alle UTM- D-Verbindungen abgebaut sind, spätestens aber nach Ablauf des Timers	subopcode1 : KC_GRACEFUL	——	——	kc_shutdown_str

¹ In allen Fällen muss im Parameterbereich der Operationscode KC_SHUTDOWN angegeben werden.

Versorgung der Parameter
Parameterbereich
Feldname	Inhalt
version	KC_ADMI_VERSION_1
retcode	KC_RC_NIL
version_data	KC_VERSION_DATA_11
opcode	KC_SHUTDOWN
subopcode1	KC_GRACEFUL / KC_KILL / KC_NORMAL / KC_WARN
subopcode2	KC_USER_MSG / —
id_lth	0
select_lth	0
data_lth	Länge der Daten im Datenbereich / 0
Identifikationsbereich
—
Selektionsbereich
—
Datenbereich
Datenstruktur kc_shutdown_str / —

KDCADMI-Aufruf

KDCADMI (&parameter_area, NULL, NULL, &data_area) oder
KDCADMI (&parameter_area, NULL, NULL, NULL)

Rückgaben von UTM
Parameterbereich
Feldname	Inhalt
retcode	Returncodes

subopcode1
	In subopcode1 geben Sie an, wie UTM die Anwendung beenden soll. Folgende Angaben sind möglich:
	KC_GRACEFUL
		UTM bereitet den Shutdown vor. Die Anwendung wird beendet, sobald alle UTM-D-Dialoge beendet und alle UTM-D-Verbindungen abgebaut sind, spätestens jedoch nach Ablauf des angegebenen Timers. Den Wert des Timers müssen Sie im Datenbereich übergeben. Ist der angegebene Timer abgelaufen, wird die Anwendung auf jeden Fall beendet. Bestehen keine UTM-D-Verbindungen, wird die Anwendung sofort normal beendet. Nach Bearbeitung des KC_GRACEFUL-Aufrufs gilt Folgendes: Es können sich nur noch Benutzer mit Administrationsberechtigung anmelden. Anmeldeversuche anderer Benutzer werden abgelehnt. Es können nur noch Transaktionscodes von Administrationsprogrammen und die UTM-Benutzerkommandos außer KDCOUT aufgerufen werden. Alle anderen Vorgänge werden von UTM nicht mehr gestartet. Alle aktiven Verbindungen zu LPAP- und OSI-LPAP-Partnern werden auf QUIET gesetzt.
	KC_KILL	Der Anwendungslauf wird abgebrochen, d.h. sofort beendet. Offene Vorgänge werden nicht mehr beendet. Von allen Prozessen wird ein UTM-Dump erstellt mit REASON='ASIS99'.
	KC_NORMAL
		Der Anwendungslauf wird normal beendet. Der Shutdown wird sofort eingeleitet. Nach dem KC_SHUTDOWN-Aufruf gilt Folgendes: Benutzer/Clients können sich nicht mehr bei der Anwendung anmelden. Aufträge von Partner-Servern werden nicht mehr angenommen. Bereits angemeldete Benutzer/Clients können keine neuen Vorgänge mehr starten. Neue Dialog-Eingaben werden nicht mehr bearbeitet. Ist die neue Dialog-Eingabe Teil einer Mehrschritt-Transaktion, dann wird die Mehrschritt-Transaktion auf den letzten Sicherungspunkt zurückgesetzt. Alle logischen Verbindungen zu Clients, Druckern und Partner-Anwendungen werden abgebaut. Offene Vorgänge können nach dem nächsten Start der Anwendung weiter bearbeitet werden.
	KC_WARN
		UTM bereitet den Shutdown vor. Die Anwendung wird nach Ablauf des angegebenen Timers beendet. Den Wert des Timers müssen Sie im Datenbereich übergeben. Nach Bearbeitung des KC_SHUTDOWN-Aufrufs gilt Folgendes: Es können sich nur noch Benutzer mit Administrationsberechtigung anmelden. Anmeldeversuche anderer Benutzer werden abgelehnt. Es können nur noch Transaktionscodes von Administrationsprogrammen und die UTM-Benutzerkommandos außer KDCOUT aufgerufen werden. Alle anderen Vorgänge werden von UTM nicht mehr gestartet. Alle aktiven Verbindungen zu LPAP- und OSI-LPAP-Partnern werden auf QUIET gesetzt.
subopcode2
	subopcode2 ist nur relevant, wenn Sie subopcode1=KC_WARN angeben. In allen anderen Fällen darf in subopcode2 nichts angegeben werden. Sie geben subopcode2=KC_USER_MSG an, wenn UTM zur Vorbereitung auf den Shutdown eine Nachricht an alle derzeit aktiven Benutzer senden soll. Die Nachricht, die UTM senden soll, müssen Sie im Datenbereich übergeben. In UTM-Anwendungen auf Unix-, Linux- und Windows-Systemen wird die Nachricht akzeptiert, es werden aber keine Warnmeldungen ausgegeben. Wenn Sie auf BS2000-Systeme subopcode2 bei KC_WARN nicht angeben, dann werden alle aktiven Benutzer durch eine Standardmeldung über den bevorstehenden Shutdown und die bis dahin verbleibende Zeit informiert.
data_lth
	Im Feld data_lth geben Sie die Länge des an UTM übergebenen Datenbereichs an. bei subopcode1=KC_KILL, KC_NORMAL: Im Datenbereich werden keine Daten an/von UTM übergeben (data_lth='0'), oder oder die Länge der Datenstruktur kc_shutdown_str, die Sie im Datenbereich übergeben. bei subopcode1=KC_GRACEFUL, KC_WARN: Im Feld data_lth geben Sie die Länge der Datenstruktur kc_shutdown_str an, die Sie im Datenbereich an UTM übergeben.
Datenbereich
	Im Datenbereich müssen Sie bei subopcode1=KC_GRACEFUL und subopcode1=KC_WARN die Datenstruktur kc_shutdown_str an UTM übergeben. kc_shutdown_str muss die Größe des Timers enthalten und wenn zusätzlich subopcode2=KC_USER_MSG ist, die Nachricht, die als Warnung an alle Terminal-Benutzer gesendet werden soll. Die Datenstruktur kc_shutdown_str wird in der Include-Datei kcadminc.h zur Verfügung gestellt. Bei stand-alone UTM-Anwendungen muss der Datenbereich nur für KC_WARN und KC_GRACEFUL versorgt werden. Das Feld scope in kc_shutdown_str wird nicht ausgewertet. In UTM-Cluster-Anwendungen gilt:  Bei jedem subopcode1: In der Datenstruktur kc_shutdown_str können Sie mit dem Feld scope steuern, ob nur die lokale Knoten-Anwendung beendet werden soll, oder ob Sie die gesamte UTM-Cluster-Anwendung, also alle Knoten-Anwendungen, beenden möchten. Für einen globalen Shutdown der UTM-Cluster-Anwendung müssen Sie die Datenstruktur kc_shutdown_str mit scope='G' versorgen. Wenn Sie im Cluster keine Datenstruktur angeben, wird ein lokaler Shutdown ausgeführt.

Die Datenstruktur ist wie folgt aufgebaut:

struct kc_shutdown_str

char time_min[3];

char user_message[74];

char scope;

time_min	In time_min geben Sie die Zeit in Minuten an, nach der UTM den Anwendungslauf normal beenden soll. Sie sollten eine Zeit angeben, die größer ist als die Zeit, die eine verteilte Transaktion maximal im Zustand PTC (d.h. Transaktionsstatus P) verbleibt. Dies ist in Auftragnehmer-Vorgängen die mit MAX PTCTIME generierte Zeit und in LU6.1-Auftraggeber-Vorgängen die beim verwendeten LTAC generierte Zeit time2 des Operanden WAITTIME. Minimalwert: '1' Maximalwert: '255' Die Angabe time_min='0' wird von UTM abgelehnt. Soll die Anwendung ohne Verzögerung normal beendet werden, dann müssen Sie subop code1=KC_NORMAL angeben. Besonderheiten bei UTM-Anwendungen auf BS2000-Systemen time_min wird immer zusammen mit der Shutdown-Ankündigung an den aktiven Terminals ausgegeben. Bei großen UTM-Anwendungen auf BS2000-Systemen (Konfigurationen mit vielen Clients) benötigt UTM für die Ausgabe der Shutdown-Ankündigung eine gewisse Zeit. Deshalb sollten Sie time_min nicht zu klein wählen. Zusätzlich sollten Sie für den Transaktionscode, über den das Teilprogramm mit diesem KC_SHUTDOWN-Aufruf gestartet wird, einen hinreichend großen Wert für cpu_time_msec definieren bzw. die CPU-Zeit nicht überwachen lassen (siehe kc_tac_str im Abschnitt "kc_tac_str - Transaktionscodes lokaler Services"). cpu_time_msec gibt die CPU-Zeit an, die der Teilprogrammlauf maximal verbrauchen darf. Wird die Zeit zu klein gewählt, dann kann es passieren, dass der Shutdown abgebrochen wird.
user_message	Ist nur bei subopcode2=KC_USER_MESSAGE relevant. Wurde kein subopcode2 angegeben, dann wird der Bereich ignoriert. In user_message können Sie eine eigene Nachricht übergeben, die UTM vor dem Shutdown als Warnung an alle Terminal-Benutzer senden soll. Die Nachricht darf maximal 74 Zeichen lang sein. openUTM auf BS2000-Systemen Übergeben Sie in user_message keine eigene Warn-Nachricht, dann gibt UTM an alle Terminal-Benutzer, die derzeit mit der Anwendung verbunden sind, die Meldung K023 mit den folgenden Inserts aus: 'hour':'minutes':'seconds' APPLICATION 'name' WILL BE TERMINATED IN 'minutes' MINUTES openUTM auf Unix-, Linux- und Windows-Systemen Auf Unix-, Linux- und Windows-Systemen werden keine Warnmeldungen ausgegeben.
scope	steuert, ob nur die lokale Knoten-Anwendung beendet wird, oder ob die gesamte UTM-Cluster-Anwendung, also alle Knoten-Anwendungen, beendet wird. Das Feld scope wird nur für UTM-Cluster-Anwendungen ausgewertet.
	'L'	Nur die lokale Knoten-Anwendung wird beendet.
	'G'	Alle Knoten-Anwendungen des Clusters und damit die gesamte UTM-Cluster-Anwendung werden beendet.

retcode

Im Feld retcode liefert UTM den Returncode des Aufrufs zurück. Neben den im Abschnitt „Returncodes" aufgelisteten Returncodes können zusätzlich folgende Returncodes auftreten. 

Maincode = KC_MC_REJECTED

Der Aufruf wurde von UTM abgewiesen.

Subcode:

KC_SC_NOT_ALLOWED

subopcode1=KC_KILL ist in einem Asynchron-Vorgang verwendet worden.

KC_SC_NO_GLOB_CHANG_POSSIBLE

Die Generierung der Knoten-Anwendungen ist zur Zeit nicht konsistent. Zuerst sollten die Knoten-Anwendungen mit alter Generierung beendet werden.

Maincode = KC_MC_DATA_INVALID

Ein Feld der Datenstruktur im Datenbereich enthält einen ungültigen Wert.

Subcode:

KC_SC_INVALID_MOD

Nur bei subopcode1=KC_GRACEFUL und subopcode1=KC_WARN:
Der Anwendungslauf wurde nicht beendet, weil die Zeitangabe in time_min ungültig ist.

Maincode = KC_MC_REJECTED_CURR

Der Aufruf kann zur Zeit nicht bearbeitet werden.

Subcode:

KC_SC_INVDEF_RUNNING

Nur bei UTM-Cluster-Anwendungen:
Es läuft gerade ein inverser KDCDEF, d.h. der Auftrag kann z.Zt. nicht bearbeitet werden.

Maincode = KC_MC_RECBUF_FULL

Nur bei UTM-Cluster-Anwendungen:

Subcode:

KC_SC_NO_INFO

Der Puffer mit Wiederanlauf-Information ist voll (siehe openUTM-Handbuch „Anwendungen generieren“, KDCDEF-Steueranweisung MAX, Parameter RECBUF).