Mit KC_SYSLOG können Sie die System-Protokolldatei SYSLOG im laufenden Betrieb administrieren. Der Umfang der Funktionen, die Ihnen zur Administration der SYSLOG zur Verfügung stehen, ist abhängig davon, ob die SYSLOG als einfache Datei oder als Dateigenerationsgruppe (BS2000-Systeme) bzw. Dateigenerationsverzeichnis (Unix-, Linux- und Windows-Systeme) angelegt wurde. Für Dateigenerationsverzeichnis bzw. Dateigenerationsgruppe wird im Folgenden die Abkürzung FGG (File Generation Group) verwendet.
Zu SYSLOG siehe auch das openUTM-Handbuch „Anwendungen generieren“ und das jeweilige openUTM-Handbuch „Einsatz von UTM-Anwendungen“.
Folgende Funktionen stehen Ihnen zur Verfügung, unabhängig davon, ob die SYSLOG als einfache Datei oder als FGG geführt wird:
Den Inhalt des UTM-internen Meldungspuffers in die SYSLOG schreiben.
Diese Funktion ist nützlich, wenn die SYSLOG, die als einfache Datei angelegt wurde, im laufenden Betrieb ausgewertet werden soll. Es werden dann alle Meldungen mit dem Meldungsziel SYSLOG in der Auswertung berücksichtigt, die bis zu diesem Zeitpunkt von UTM erzeugt wurden.
Ist die SYSLOG als FGG angelegt, dann gilt Folgendes:
Beim Umschalten der SYSLOG auf die nächste Dateigeneration schreibt UTM den Meldungspuffer automatisch vor dem Umschalten in die „alte“ Dateigeneration.Sich Information über die SYSLOG-Datei anzeigen lassen.
Folgende Funktionen können Sie zusätzlich nutzen, wenn die SYSLOG als FGG angelegt ist:
Die automatische Größenüberwachung der SYSLOG ein- und ausschalten.
Automatische Größenüberwachung heißt: UTM schaltet die SYSLOG automatisch auf die nächste Dateigeneration der SYSLOG-FGG um, sobald die Größe der aktuellen SYSLOG-Dateigeneration einen vorgegebenen Schwellwert überschreitet.
Den Schwellwert für die Größenüberwachung ändern.
Die SYSLOG auf die nächste Dateigeneration der SYSLOG-FGG umschalten.
Sie können die Größenüberwachung der SYSLOG auch dann einschalten, wenn sie nicht mit KDCDEF generiert wurde.
Ablauf beim Umschalten der SYSLOG auf eine andere Dateigeneration
Vor dem Umschalten auf eine neue Dateigeneration schreibt UTM noch die im internen Meldungspuffer zwischengespeicherten Meldungen in die alte Dateigeneration. Damit werden alle Meldungen, die vor dem Umschalten erzeugt wurden, noch in die „alte“ SYSLOG geschrieben. UTM garantiert, dass Meldungen, die nach dem Umschaltzeitpunkt (erfolgreiches Ausführen des KC_SYSLOG-Aufrufs) erzeugt werden, nicht mehr in die „alte“ SYSLOG-Dateigeneration geschrieben werden.
In UTM-Anwendungen auf BS2000-Systemen ist Folgendes zu beachten:
Nach dem Umschalten (d.h. erfolgreiche Bearbeitung des KC_SYSLOG-Aufrufs) können Sie nicht sofort über die alte Dateigeneration verfügen. Die alte Dateigeneration wird eventuell noch längere Zeit von UTM-Prozessen offengehalten. Das kann vorkommen, wenn ein Teilprogrammlauf, der vor dem Umschalten gestartet wurde, noch nicht abgeschlossen ist, und der zugehörige Prozess noch keine Meldung mit Meldungsziel SYSLOG geschrieben hat.
Sie können mit subopcode1=KC_INFO abfragen, welche SYSLOG-Dateigenerationen bereits von allen UTM-Prozessen geschlossen worden sind. Das sind alle Dateigenerationen mit einer Generationsnummer kleiner lowest_open_gen (siehe kc_syslog_str im Abschnitt "KC_SYSLOG - System-Protokolldatei administrieren").
Wirkungsdauer / Transaktionssicherung / Cluster
Der Aufruf unterliegt nicht der Transaktionssicherung. Er wirkt unmittelbar und die Aktionen, die durch den Aufruf ausgelöst werden, sind bei der Rückkehr in das Teilprogramm bereits durchgeführt. Der Aufruf ist nicht rücksetzbar.
Das Ändern des Größenschwellwerts der SYSLOG-Datei wirkt bis zum Ende des Anwendungslaufes.
Liegt die Basis der SYSLOG-FGG innerhalb des gültigen Bereichs der SYSLOG-FGG (zwischen der ersten und der letzten Dateigeneration), dann protokolliert UTM im nächsten Anwendungslauf zunächst in die Basisdateigeneration. Liegt die Basis außerhalb des gültigen Bereichs, dann legt UTM beim nächsten Start für das Logging eine neue Dateigeneration an. Die Basis wird in der Datenstruktur kc_syslog_str im Feld mit base_gen angegeben.
In UTM-Cluster-Anwendungen gilt (Unix-, Linux- und Windows-Systeme):
Der Aufruf wirkt Cluster-global, d.h. die System-Protokolldatei SYSLOG wird für jede Knoten-Anwendung administriert. Die Größenüberwachung wirkt über den aktuellen Lauf der UTM-Cluster-Anwendung hinaus. Das Umschalten oder das Schreiben des Puffers wirkt nur für den aktuellen UTM-Cluster-Anwendungslauf, d.h. für alle Knoten-Anwendungen, die derzeit laufen.
| KDCSLOG ("KDCSLOG - SYSLOG-Datei administrieren") |
Versorgung der zu übergebenden Bereiche
Funktion des Aufrufs | Angabe im | |||
Parameterbereich 1 | Identifikati-onsbereich | Selektions-bereich | Datenbereich | |
Über die SYSLOG informieren | subopcode1: | —— | —— | —— (Beim Aufruf müssen Sie den Zeiger auf einen Datenbereich für die Rückgaben von UTM (kc_syslog_str) übergeben.) |
Schwellwert für die automatische Größenüberwachung setzen bzw. verändern | subopcode1: | —— | —— | Datenstruktur kc_syslog_str mit dem neuen Schwellwert |
SYSLOG auf die nächste Dateigeneration der FGG umschalten | subopcode1: | —— | —— | —— |
Schwellwert für die automatische Größenüberwachung verändern und SYSLOG auf die nächste Dateigeneration der FGG umschalten | subopcode1: data_lth: | —— | —— | Datenstruktur kc_syslog_str mit dem neuen Schwellwert |
Meldungspuffer in die SYSLOG schreiben | subopcode1: | —— | —— | —— |
1 In allen Fällen muss im Parameterbereich der Operationscode KC_SYSLOG 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_SYSLOG |
KC_INFO / KC_CHANGE_SIZE / KC_SWITCH / KC_SWITCH_AND_CHANGE / KC_WRITE_BUFFER | |
id_lth | 0 |
select_lth | 0 |
Länge der Datenstruktur / Länge des Datenbereichs / 0 | |
Identifikationsbereich | |
— | |
Selektionsbereich | |
— | |
Datenstruktur kc_syslog_str / — | |
KDCADMI-Aufruf |
KDCADMI (¶meter_area, NULL, NULL, &data_area) |
Rückgaben von UTM | |
Parameterbereich | |
Feldname | Inhalt |
Returncodes | |
Länge der im Datenbereich gelieferten Daten | |
Datenstruktur kc_syslog_str | |
subopcode1 | ||
Im Feld subopcode1 müssen Sie angeben, welche Aktion UTM durchführen soll. Folgende Subopcodes können Sie angeben: | ||
KC_WRITE_BUFFER | ||
Alle an das Meldungsziel SYSLOG ausgegebenen Meldungen, die noch im UTM-internen Meldungspuffer zwischengespeichert sind, werden sofort in die aktuelle SYSLOG-Datei geschrieben. Ist der Puffer leer, hat der Aufruf keine Wirkung. | ||
KC_INFO | geben Sie an, wenn UTM Informationen über die SYSLOG-Datei bzw. | |
Folgende Werte für subopcode1 dürfen Sie nur angeben, wenn die SYSLOG als FGG angelegt wurde. | ||
KC_CHANGE_SIZE | ||
geben Sie an, wenn Sie:
| ||
KC_SWITCH | ||
geben Sie an, wenn UTM die SYSLOG-Datei auf die nächste Dateigeneration umschalten soll. Existiert diese Dateigeneration noch nicht, legt UTM sie an. | ||
KC_SWITCH_AND_CHANGE | ||
entspricht einer Zusammenfassung von KC_CHANGE_SIZE und KC_SWITCH. Mit KC_SWITCH_AND_CHANGE können Sie die SYSLOG auf die nächste Dateigeneration umschalten und gleichzeitig den Schwellwert für die automatische Größenüberwachung ändern. Dabei garantiert UTM, dass entweder beide Aktionen erfolgreich ausgeführt werden oder keine. D.h. nur wenn das Umschalten der SYSLOG erfolgreich war, stellt UTM den neuen Schwellwert ein. Kann UTM nicht auf die folgende Dateigeneration umschalten, dann wird der Schwellwert nicht geändert. Die Größenüberwachung wird suspendiert und UTM ignoriert den neuen Schwellwert. Erst durch einen folgenden erfolgreichen Umschaltversuch (erneuter KC_SYSLOG-Aufruf) kann die Größenüberwachung wieder eingestellt werden. Wurde dabei kein neuer Schwellwert angegeben, übernimmt UTM den „alten“ Schwellwert. | ||
data_lth | ||
Im Feld data_lth geben Sie Folgendes an:
| ||
Datenbereich | ||
Die Angaben, die Sie im Datenbereich machen müssen, sind abhängig von subopcode1:
| ||
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_OK Der Aufruf wurde fehlerfrei bearbeitet. Subcodes: |
KC_SC_MIN_SIZE Bei subopcode1=KC_CHANGE_SIZE oder KC_SWITCH_AND_CHANGE: |
KC_SC_BUFFER_EMPTY Bei subopcode1=KC_WRITE_BUFFER: |
KC_SC_SWITCHED Der Meldungspuffer konnte erst auf die SYSLOG geschrieben werden, nachdem auf eine neue Dateigeneration umgeschaltet wurde. |
Maincode = KC_MC_REJECTED Der Aufruf wurde von UTM abgewiesen. Subcodes: |
KC_SC_NO_FGG Die gewünschte Aktion kann nicht durchgeführt werden, da SYSLOG nicht als FGG angelegt ist. |
KC_SC_NO_INFO Die Aktion kann nicht durchgeführt werden. |
KC_SC_NO_GLOB_CHANG_POSSIBLE Nur bei UTM-Cluster-Anwendungen: |
Maincode = KC_MC_DATA_INVALID Ein Feld der Datenstruktur im Datenbereich enthält einen ungültigen Wert. Subcodes: |
KC_SC_INVALID_MOD Bei subopcode1=KC_CHANGE_SIZE oder KC_SWITCH_AND_CHANGE: |
KC_SC_DATA_MISSING Bei subopcode1=KC_CHANGE_SIZE oder KC_SWITCH_AND_CHANGE: |
KC_SC_DATA_NOT_NULL Bei subopcode1=KC_CHANGE_SIZE oder KC_SWITCH_AND_CHANGE: |
Maincode = KC_MC_RECBUF_FULL Subcode: |
KC_SC_NO_INFO Der Puffer mit Wiederanlauf-Information ist voll (siehe openUTM-Handbuch „Anwendungen generieren“, KDCDEF-Steueranweisung MAX, Parameter RECBUF). |
Maincode = KC_MC_REJECTED_CURR Der Aufruf kann zur Zeit nicht bearbeitet werden. Subcode: |
KC_SC_INVDEF_RUNNING Nur bei UTM-Cluster-Anwendungen: |
data_lth_ret
data_lth_ret enthält die Länge der Daten, die UTM im Datenbereich zurückliefert.
- bei subopcode1=KC_INFO liefert UTM die Informationen über die SYSLOG im Datenbereich (kc_syslog_str). Es ist data_lth_ret
!=0. - Ist die Länge in data_lth_ret kleiner als der bereitgestellte Datenbereich (data_lth), dann ist der Inhalt des Datenbereichs nur in der Länge data_lth_ret definiert.
- bei subopcode1
!=KC_INFO ist data_lth_ret = 0
Datenbereich
Im Fall subopcode1=KC_INFO liefert UTM im Datenbereich die Datenstruktur kc_syslog_str mit Informationen über die SYSLOG der Anwendung zurück. Die Datenstruktur hat folgende Felder:
struct kc_syslog_str |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Die Felder der Datenstruktur haben folgende Bedeutung:
file_name | ||
Name der aktuellen SYSLOG-Datei bzw. der Dateigeneration, in die derzeit protokolliert wird. | ||
curr_size_utmpages | ||
enthält die momentane Größe der SYSLOG-Datei bzw. Dateigeneration, in die derzeit protokolliert wird. Die Größe wird angegeben in Anzahl der UTM-Seiten, die von der Datei bzw. Dateigeneration belegt sind. | ||
curr_size_kbyte | ||
enthält die momentane Größe der SYSLOG-Datei bzw. Dateigeneration, in die derzeit protokolliert wird. Die Größe wird angegeben in Kbyte. | ||
curr_size_percent | ||
Falls die automatische Größenüberwachung eingeschaltet ist, enthält curr_size_percent den Füllgrad der SYSLOG-Datei relativ zum eingestellten Größenschwellwert in Prozent. Ist die Größenüberwachung durch UTM suspendiert bzw. durch die Administration ausgeschaltet worden, dann kann der Füllgrad der SYSLOG-Datei auch größer als 100% sein. In diesem Fall liefert UTM in curr_size_percent Leerzeichen zurück. Ist keine Größenüberwachung definiert (weder per Generierung noch per Administration) dann belegt UTM curr_size_percent mit Leerzeichen. | ||
fgg | zeigt an, ob die SYSLOG als FGG oder als einfache Datei angelegt ist. | |
'Y' | Die SYSLOG ist als FGG angelegt. | |
'N' | Die SYSLOG ist als einfache Datei angelegt. | |
Alle folgenden Informationen sind nur relevant, wenn die SYSLOG als FGG angelegt ist. Ist die SYSLOG als einfache Datei angelegt, dann enthalten die folgenden Felder keine relevanten Informationen. | ||
last_switch_ok | ||
gibt an, ob der letzte Versuch von UTM, auf die nächste Dateigeneration umzuschalten, fehlerfrei abgelaufen ist. Die Aussage bezieht sich nur auf Umschaltversuche innerhalb des aktuellen Anwendungslaufs. Folgende Werte sind möglich: | ||
'Y' | Der letzte Umschaltversuch ist fehlerfrei abgelaufen. | |
'N' | Beim letzten Umschaltversuch von UTM ist ein Fehler aufgetreten. | |
' ' | (Leerzeichen) Im aktuellen Anwendungslauf gab es noch keinen Umschaltversuch oder die SYSLOG ist nicht als FGG angelegt. | |
size_control_engaged | ||
gibt an, ob die automatische Größenüberwachung eingeschaltet ist. Folgende Werte sind möglich: | ||
'Y' | Größenüberwachung ist eingeschaltet | |
'N' | Größenüberwachung ist ausgeschaltet | |
size_control_suspended | ||
gibt an, ob die automatische Größenüberwachung durch UTM suspendiert wurde. | ||
'Y' | Der letzte Versuch, auf eine andere Dateigeneration umzuschalten, ist fehlgeschlagen. Aus diesem Grund ist die Größenüberwachung suspendiert. Maßnahme: | |
'N' | Die Größenüberwachung ist nicht suspendiert. | |
size_control_utmpages | ||
enthält den eingestellten Größenschwellwert der automatischen Größenüberwachung. Ausgegeben wird der Schwellwert in Anzahl UTM-Seiten. size_control_utmpages='0' bedeutet, dass die Größenüberwachung ausgeschaltet ist. In size_control_utmpages übergeben Sie bei subopcode1=KC_CHANGE_SIZE und KC_SWITCH_AND_CHANGE den neuen Größenschwellwert. Minimalwert: '0' Geben Sie size_control_utmpages='0' an, dann wird die automatische Größenüberwachung ausgeschaltet. Werte zwischen '1' und '99' werden von UTM automatisch durch '100' ersetzt. | ||
size_control_kbyte | ||
enthält den eingestellten Größenschwellwert der automatischen Größenüberwachung. Ausgegeben wird der Schwellwert in KB. Bei sehr großen Schwellwerten wird der Kilobyte-Wert nicht angezeigt (z.B. bei 231 KB). size_control_kbyte=0 bedeutet, dass der Kilobyte-Wert nicht angezeigt werden kann, da er zu groß ist, oder dass die Größenüberwachung ausgeschaltet ist. | ||
start_gen | enthält die Generationsnummer der ersten SYSLOG-Dateigeneration, die UTM im aktuellen Anwendungslauf beschrieben hat. | |
curr_gen | Generationsnummer der Dateigeneration, in die UTM gerade protokolliert. | |
lowest_open_gen | ||
enthält die Generationsnummer der ältesten SYSLOG-Dateigeneration, die noch von einem Prozess der Anwendung offengehalten wird. | ||
base_gen | Generationsnummer der eingestellten Basis der SYSLOG-FGG. | |
first_valid_gen | ||
Generationsnummer der ersten gültigen Dateigeneration der SYSLOG-FGG. Auf BS2000-Systemen entspricht das der Angabe FIRST-GEN aus dem SHOW-FILE-ATTRIBUTES-Kommando. | ||
last_valid_gen | ||
Generationsnummer der letzten gültigen Dateigeneration der SYSLOG-FGG. Auf BS2000-Systemen entspricht das der Angabe LAST-GEN aus dem Kommando SHOW-FILE-ATTRIBUTES. | ||