AUDIT - Sprungfolgemodus steuern

Allgemeines

Anwendungsgebiet:	Testhilfe; siehe "Testhilfe"
Makrotyp:	S-Typ, MF-Format 1: Standardform/L-/D-/E-Form; siehe "S-Typ-Makroaufrufe"

Bei MF=L werden im Datenbereich keine symbolischen Namen generiert.

Die Funktion Hardware-AUDIT (siehe unten) ist nur auf /390-Servern verfügbar. Auf anderen BS2000-Servern liefert die Funktion zwar RC=0, wird aber nicht ausgeführt.

Makrobeschreibung

Der Makro AUDIT bietet dem Anwender programmüberwachende Funktionen.

Neben dem Hardware-AUDIT steht auch der Linkage-AUDIT zur Verfügung. Beide ermöglichen die Rückverfolgung des Programmlaufs durch Aufzeichnung der Adressen erfüllter Sprungbefehle (Hardware-AUDIT) bzw. der Zieladressen von Unterprogrammsprüngen (Linkage-AUDIT) und sind unabhängig voneinander.
Während der Hardware-AUDIT die Absprungadressen für jeden ausgeführten Sprungbefehl in eine Sprungfolgetabelle (Hardware-AUDIT-Tabelle) einträgt, schreibt der Linkage-AUDIT bei Ausführung der Befehle BASR, BALR, BASSM und BAKR die Sprungzieladressen in die Linkage-AUDIT-Tabelle. So können mit dem Linkage-AUDIT alle innerhalb des Programmlaufs aufgerufenen Unterprogramme ermittelt werden, sofern sie mit einem der oben genannten Befehle aufgerufen wurden.

Für Hardware- und Linkage-AUDIT werden getrennte AUDIT-Tabellen angelegt, die bei der Ausgabe in der Kopfzeile entsprechend gekennzeichnet werden. Eine AUDIT-Tabelle umfasst 64 Wort-Einträge beim Hardware-AUDIT bzw. 1024 Einträge beim Linkage-AUDIT und wird, wenn nicht anders vereinbart, zyklisch überschrieben. Die Anforderung kann für den gesamten Lauf einer Task oder aller Tasks oder für einen Prozess der eigenen Task (z.B. Contingency-Prozess) spezifiziert werden. Der Linkage-AUDIT kann auch prozessorlokal geschaltet werden.

Hardware-AUDIT und den Linkage-AUDIT können erlaubt oder verboten werden

• für eine ganze Session
  Die Steuerung erfolgt über den Systemparameter AUDALLOW=YES/NO.Ein bereits eingeschalteter prozessorlokaler Linkage-AUDIT wird wieder ausgeschaltet, wenn der Systemparameter AUDALLOW=NO gesetzt wurde.
  Hardware-AUDIT und Linkage-AUDIT können nur gemeinsam gesteuert werden.

• für eine Benutzerkennung
  Die Steuerung erfolgt mit den Operanden HARDWARE-AUDIT bzw. LINKAGE-AUDIT= *UNCHANGED / *NOT-ALLOWED / *ALLOWED der Kommandos MODIFY-USER-AT-TRIBUTES bzw. ADD-USER.

• für eine Task
  Die Steuerung erfolgt mit den Operanden HARDWARE-AUDIT bzw. LINKAGE-AU-DIT=*UNCHANGED / *NOT-ALLOWED / *ALLOWED des Kommandos MODIFY-TEST-OPTIONS.

Der Makro AUDIT wird mit dem Returncode X'81003C' abgewiesen, wenn Hardware- und Linkage-AUDIT nicht erlaubt sind.

Anmerkungen zum prozessorlokalen Linkage-AUDIT

Der Linkage-AUDIT ermöglicht das CPU-spezifische Einschalten des Linkage-AUDIT für alle aktiven CPUs bzw. alle logischen Maschinen einer Server-Konfiguration. Pro CPU wird eine Trace-Tabelle im privilegierten Klasse-3-Speicher angelegt, die während der gesamten Session erhalten bleibt. Der Linkage-AUDIT kann in der Startup-Phase über den Parameterservice eingeschaltet oder ausgeschaltet werden. Zum Ein- bzw. Ausschalten in der laufenden Session stehen dem Systemverwalter die Kommandos /START- bzw. /STOP-LINKAGE-AUDIT sowie der Makro AUDIT zur Verfügung.

Makroaufrufformat und Operandenbeschreibung

AUDIT

FCT=HWA / LNKA

,SCOPE=TASK / FUNCT / ALLTASK / SIHGLOB / SYSGLOB

,STATE=USER / SYS / PROC

,ACTION={ON [,SAVE=n] / OFF / CONT / DISC / GET [,TABLE=adr]}

[, {TID=tid / TSN=tsn }]

[,PARMOD=31]

,MF=S / L / (E,..) / D

,ID=AUD / pre

In der nachfolgenden Operandenbeschreibung sind die Operanden alphabetisch geordnet.

ACTION=
bezeichnet die gewünschte AUDIT-Aktion: Ein-/Ausschalten, Unterbrechen, Fortsetzen oder Ausgeben.

ON
Die 64 bzw. 1024 Worte (256 bzw. 4096 Byte) umfassende AUDIT-Tabelle wird, falls sie nicht schon vorhanden ist, angelegt und auf Anfangszustand gesetzt, indem alle Einträge mit binär Null überschrieben werden. Der laufende Zeiger wird auf den Anfang der Tabelle gesetzt und der AUDIT-Modus aktiviert.

Falls die AUDIT-Tabelle schon vorhanden ist, wird der laufende Zeiger hinter den letzten Eintrag, bei vollgeschriebener Tabelle wieder auf den Anfang der Tabelle (zyklische Überschreibung) gesetzt und der AUDIT-Modus aktiviert.

OFF
Hiermit wird der AUDIT-Modus abgeschaltet und die AUDIT-Tabelle, sowie eine eventuell vorhandene Sicherungstabelle, freigegeben. Wurde die AUDIT-Tabelle über den Operanden GET in einen vom Benutzer angegebenen Speicherbereich kopiert, so bleibt dieser Bereich bis zur Programmbeendigung erhalten. Der Operand SCOPE=FUNCT darf nicht angegeben werden, der Operand SAVE wird ignoriert.

CONT
bewirkt die Reaktivierung des AUDIT nach einem vorangegangenen ACTION=DISC-Aufruf. Die Protokollierung in die AUDIT-Tabelle wird dort fortgesetzt, wo sie durch den ACTION=DISC-Aufruf unterbrochen wurde. Eine eventuell vorhandene
Sicherungstabelle wird weiterhin zur Sicherung der AUDIT-Tabellen benutzt.

Der Operand kann nur zusammen mit SCOPE=TASK angegeben werden. Ist zum Zeitpunkt des CONTINUE-Aufrufs kein AUDIT aktiv, so wird er taskweit für den angegebenen Funktionszustand (USER oder SYS) eingeschaltet. Die Operanden TID und TSN dürfen nicht angegeben werden. Der Operand SAVE wird ignoriert.

DISC
Hiermit wird der AUDIT-Modus abgeschaltet, aber die AUDIT-Tabelle und eine eventuell vorhandene Sicherungstabelle beibehalten. Die DISCONTINUE-Funktion ist nur anwendbar für den ganzen Lauf der eigenen Task (SCOPE=TASK), wobei die Operanden TID und TSN nicht angegeben werden dürfen, der Operand SAVE wird ignoriert.

GET
Nur bei SCOPE=TASK zulässig, der Operand SAVE wird ignoriert.

Für FCT=HWA:
Die 64 Worte umfassende Hardware-AUDIT-Tabelle (ohne Berücksichtigung einer Sicherungstabelle) wird in den Speicherbereich kopiert, den der Benutzer durch die im TABLE-Operanden angegebene virtuelle Adresse bezeichnet hat. Der Inhalt der AU-DIT-Tabelle wird, im Gegensatz zum SHOW-Kommando, in unveränderter chronologischer Reihenfolge (First-in, First-out) übernommen.

Für FCT=LNKA:
Die gesamte Linkage-AUDIT-Traceinformation (AUDIT- und Sicherungstabelle) wird in den Speicherbereich kopiert, den der Benutzer im Linkage-AUDIT-Datenbereich mit der virtuellen Adresse audTAB und der Länge audLBUF bezeichnet hat.
Der Inhalt der AUDIT-Tabelle wird so ausgegeben, dass der letzte Eintrag der AUDIT-Tabelle an den Anfang der Ausgabe kommt (First-in, Last-out).

Beim Linkage-AUDIT müssen Adresse und Länge des Übergabepuffers in den Feldern audTAB bzw. audLBUF abgelegt sein. Dabei ist zu beachten, dass Adresse und Länge des Übergabepuffers nicht direkt beim Makroaufruf angegeben werden können, sondern dass sie mittels Befehlen in den Datenbereich eingetragen werden müssen. Neben der AUDIT-Tabelle wird im Feld audTABE die Adresse des nächsten freien Eintrages im Übergabepuffer zurückgeliefert, bzw. die Endadresse des Puffers, wenn dieser voll geschrieben ist.

Wird die Schnittstelle mit ACTION=GET und dem Wert X'00000000' im Feld audTAB aufgerufen, so wird im Feld audLBUF die benötigte Puffergröße für einen anschließenden GET-Aufruf zurückgeliefert.
Wird im Feld audTAB ein zu kleiner Übergabepuffer angegeben, so wird die Anforderung nur zum Teil erfüllt. Die Übertragung der Linkage-AUDIT-Tabelle erfolgt nur in der im Feld audLBUF angegebenen Länge. Zusätzlich wird der Returncode X'400020' zurückgeliefert.

FCT=

Dieser Operand gibt an, auf welche AUDIT-Funktion sich die folgenden Operanden beziehen.

HWA
Die AUDIT-Anforderung bezieht sich auf den Hardware-AUDIT.

LNKA
Die AUDIT-Anforderung bezieht sich auf den Linkage-AUDIT.

MF
Zur allgemeinen Beschreibung des Operanden MF, der dazugehörenden Operandenwerte und der evtl. nachfolgenden Operanden (z.B. für einen Präfix) siehe Abschnitt „S-Typ-Makroaufrufe“. Die gültigen MF-Werte sind zu Beginn der Makrobeschreibung bei „Makrotyp“ angegeben und aus dem Aufrufformat ersichtlich.

Bei MF=D oder MF=L kann ein Präfix ID (pre = 1..3 Buchstaben), wie im Aufrufformat dargestellt, angegeben werden.

PARMOD=
Dieser Parameter ist unnötig und wird nur noch aus Kompatibilitätsgründen unterstützt. Unabhängig von der Angabe des Operanden wird generell nur noch die 31-Bit-Schnittstelle generiert.

Hinweis: Bereits generiertes 24-Bit-Coding ist natürlich weiterhin ablauffähig.

SAVE=
legt für die AUDIT-Tabelle einen Sicherungsbereich (Sicherungstabelle) im privilegierten Klasse-5-Speicher (bei TU) bzw. im privilegierten Klasse-3-Speicher (bei TPR) derjenigen Task an, die mit AUDIT überwacht werden soll. Dieser Sicherungsbereich nimmt den Inhalt der AUDIT-Tabelle auf, bevor sie im Zyklus überschrieben wird. Er vergrößert damit die abrufbare AUDIT-Informationsmenge.
Der Operand wirkt nur in Verbindung mit ACTION=ON und nur, wenn noch keine AUDIT-Tabelle vorhanden ist (z.B. nach ACTION=OFF).

n
gibt die Anzahl der 4KB-Seiten für den Sicherungsbereich an.

Bei nichtprivilegierter Protokollierung des Funktionszustandes TU können für n ganzzahlige Werte mit 0 <= n <= 16 angegeben werden. Maximal können also 64 KB für den Sicherungsbereich angefordert werden, dies entspricht der Größe von 256 Hardware-AUDIT-Tracetabellen bzw. von 16 Linkage-AUDIT-Tracetabellen.
Bei privilegierter Protokollierung des Funktionszustandes TPR mit dem Hardware-AU-DIT sind für n nur die Werte 0 und 1 sinnvoll, größere Werte (n > 1) werden durch den Wert 1 ersetzt. Maximal können also im Hardware-AUDIT für TPR 4 KB für den Sicherungsbereich angefordert werden, dies entspricht der Größe von 16 Hardware-AUDIT-Tracetabellen.

Im Linkage-AUDIT ist bei privilegierter Protokollierung des Funktionszustandes TPR sowie bei SCOPE=SIHGLOB/SYSGLOB die Angabe dieses Operanden nicht erlaubt.

SCOPE=
bezeichnet den zu protokollierenden Programmbereich.

Hinweis
Ein AUDIT-Auftrag eines größeren Programmbereichs oder eines höheren PCBs ersetzt den eines kleineren Programmbereichs bzw. eines niedrigeren PCBs (z.B. TASK ersetzt FUNCT), jedoch nicht umgekehrt.

TASK
Die anfordernde Task bzw. die im Operanden TID oder TSN angegebene soll protokolliert werden.

FUNCT
Protokolliert werden soll diejenige PCB-spezifische Funktion, die sich auf den höchsten unterbrochenen PCB des im Operanden STATE angegebenen Funktionszustandes bezieht. FUNCT ist nur für die eigene Task und bei ACTION=ON erlaubt. Die Operanden TID und TSN dürfen nicht angegeben werden.

ALLTASK
Alle Sprungbefehlsadressen des Funktionszustandes TPR sämtlicher Tasks sollen protokolliert werden. Die gleichzeitige Angabe der Operanden TID oder TSN führt zu einer Fehlermeldung, die Angabe von SAVE=n wird bei FCT=HWA ignoriert. Bei FCT=LNKA ist die Angabe von SAVE=n nicht erlaubt (siehe Operand SAVE).
Ggf. schaltet ALLTASK in jeder Task einen aktiven taskweiten Hardware-AUDIT zunächst aus und anschließend ohne Sicherungstabelle wieder ein.
Ist für eine Task der taskweite TPR-Linkage-AUDIT schon eingeschaltet, so wird dieser durch die ALLTASK-Funktion nicht verändert.
Ein nicht-aktiver taskweiter AUDIT wird nicht ausgeschaltet; auch die Sicherungstabelle bleibt erhalten. Kommen neue Tasks hinzu, so wird für diese der AUDIT generell ohne Sicherungstabelle eingeschaltet.
Dieser Wert kann nur unter der Kennung der Systemverwaltung (TSOS) angegeben werden.

SIHGLOB
Alle Sprungbefehlsadressen des Funktionszustandes SIH werden in einer prozessorlokalen AUDIT-Tabelle protokolliert. Die Angabe ist nur in Verbindung mit FCT=LNKA, STATE=PROC und ACTION=ON/OFF zulässig. Die Operanden TID, TSN und SAVE dürfen nicht angegeben werden.
Dieser Wert kann nur unter der Kennung der Systemverwaltung (TSOS) angegeben werden.

SYSGLOB

Alle Sprungbefehlsadressen der Funktionszustände SIH und TPR werden in einer prozessorlokalen AUDIT-Tabelle protokolliert. Voraussetzung für die Anwendung von SCOPE=SYSGLOB ist, dass systemweit in keiner Task ein privilegierter Linkage-AUDIT eingeschaltet ist, bzw. dass sich kein TPR-Linkage-AUDIT im Zustand 'DISCONTINUE' befindet.
Die Angabe ist nur in Verbindung mit FCT=LNKA, STATE=PROC und ACTION= ON/OFF zulässig. Die Operanden TID, TSN und SAVE dürfen nicht angegeben werden.
Dieser Wert kann nur unter der Kennung der Systemverwaltung (TSOS) angegeben werden.

STATE=
Funktionszustand (TU, TPR, SIH), auf den sich der im Operanden SCOPE angegebene Wirkungsbereich bezieht. Sollen mehrere Funktionszustände gleichzeitig protokolliert werden, muss der Makro mehrmals aufgerufen werden.

USER
Der im Operanden SCOPE angegebene Wirkungsbereich bezieht sich auf den Funktionszustand TU (USER). Der Operandenwert P1 wird nur noch aus Kompatibilitätsgründen und nur für den Hardware-AUDIT unterstützt. Voreinstellung für SCOPE=FUNCT und SCOPE=TASK.

SYS
Der im Operanden SCOPE angegebene Wirkungsbereich bezieht sich auf den Funktionszustand TPR (SYS). Der Operandenwert P2 wird nur noch aus Kompatibilitätsgründen und nur für den Hardware-AUDIT unterstützt. Voreinstellung und zwingend für SCOPE=ALLTASK.
Dieser Wert kann nur unter der Kennung der Systemverwaltung (TSOS) angegeben werden.

PROC
Der im Operanden SCOPE angegebene Wirkungsbereich bezieht sich prozessorlokal auf den Funktionszustand SIH bzw. auf SIH und TPR. Die Angabe ist nur in Verbindung mit FCT=LNKA zulässig. Voreinstellung und zwingend für SCOPE=SIHGLOB/SYSGLOB.
Dieser Wert kann nur unter der Kennung der Systemverwaltung (TSOS) angegeben werden.

TABLE=
bezeichnet die Adresse eines Bereichs, in den der Inhalt der Hardware-AUDIT-Tabelle übertragen werden soll. Die Angabe ist nur beim Hardware-AUDIT und in Verbindung mit ACTION=GET gültig und obligatorisch.

adr
virtuelle Speicheradresse. Die Adresse muss auf einen zugewiesenen Speicher zeigen. Schreibzugriff muss erlaubt sein. Die Adresse 0 darf nicht angegeben werden.
(adr kann mit 1-8 sedezimalen Ziffern bzw. mit der entsprechenden Anzahl von Dezimalziffern angegeben werden).

Es ist vorteilhaft, den Wert des TABLE-Operanden nur mit einem Dummy-Wert zu besetzen und dann dynamisch im Programm das Feld audTAB mit der entsprechenden Adresse zu überschreiben.

Beim Linkage-AUDIT wird die Übertragung der AUDIT-Trace-Information in einen Benutzerbereich ausschließlich mit dem Operanden GET gesteuert.

TID=
bezeichnet die Task, die mit AUDIT überwacht werden soll, durch ihre interne Tasknummer. Der Operand darf nur zusammen mit SCOPE=TASK angegeben werden (siehe auch Hinweis zum Operanden TSN).

tid
Interne Tasknummer. Sie kann in folgender Form angegeben werden:
h[hhhhhhh]:
1-8 Sedezimalziffern, die das System gegebenenfalls mit führenden Nullen auf 8 Stellen ergänzt.

TSN=
bezeichnet die Task, die mit AUDIT überwacht werden soll, durch ihre Auftragsnummer.

tsn
Auftragsnummer (TSN). Sie kann wie folgt angegeben werden:

n[nnn]: 1-4 Ziffern, die das System ggf. mit führenden Nullen auf 4 Stellen ergänzt,

a[aaa]: 1-4 alphanumerische Zeichen, die das System ggf. mit führenden Nullen auf 4 Stellen ergänzt,

c'a[aaa]': 1-4 Zeichen, die das System ggf. mit führenden Nullen auf 4 Stellen ergänzt (vom Anwender eingegebene führende Blanks bleiben erhalten).

Hinweise

• Wird weder der Operand TID noch TSN angegeben, so gilt die AUDIT-Anforderung für die anfordernde Task selbst.

• Der TID- bzw. TSN-Operand darf nur zusammen mit SCOPE=TASK angegeben werden.

• Bei ACTION=DISC und ACTION=CONT ist die Angabe von TID oder TSN nicht erlaubt.

• Ein nicht-privilegierter Anwender kann die AUDIT-Funktion für eine fremde Task nur einschalten, wenn die fremde Task unter der gleichen Benutzerkennung abläuft wie die aufrufende Task.

Rückinformation und Fehleranzeigen

R15:

+---------------+
|   |   |   |   |
|0|0|a|a|a|a|a|a|
+---------------+

Über die Ausführung des Makros AUDIT wird ein Returncode im Register R15 übergeben.

Der aus Kompatibilitätsgründen im R15 übergebene Returncode wird zusätzlich im Standardheader des Makroaufrufs hinterlegt.

X'aaaaaa'	Erläuterung
X'000000'	a) die geforderte Aktion ist angenommen worden, b) die geforderte Aktion ist ignoriert worden, weil AUDIT bereits läuft (ACTION=ON), c) die geforderte Aktion ist ignoriert worden, weil AUDIT nicht läuft (ACTION=DISC), d) die geforderte Aktion ist ignoriert worden, weil keine AUDIT-Tabelle zugewiesen ist (ACTION=OFF), e) die geforderte Aktion mit SCOPE=FUNCT ist ignoriert worden weil der AUDIT bereits für SCOPE=TASK eingeschaltet ist. f) Die geforderte Aktion wurde ignoriert, weil der Hardware-AUDIT auf dieser Hardware nicht verfügbar ist. g) Ein SAVE- oder TABLE-Operand ist ggf. ignoriert worden.
X'000004'	Operanden-Fehler. Der generierte Datenbereich enthält unzulässige Operandenkombinationen oder der Benutzer bzw. das Programm ist für die geforderte Aktion nicht privilegiert.
X'000008'	Die Adresse des Datenbereichs ist ungültig oder der Datenbereich ist nicht auf Wortgrenze ausgerichtet oder es ist ein interner Fehler aufgetreten.
X'00000C'	Die Adresse im Operand TABLE (Tabellenübergabebereich) ist ungültig oder der Bereich ist nur lesbar (read only).
X'000010'	Es gibt keinen ausreichenden Speicher, entweder für Klasse-3- Originaltabellen oder für Klasse-4-Verwaltungsbereiche oder für Klasse-5-Großtabellen oder Klasse-5-Verwaltungsbereiche. Die AUDIT-Aktion konnte nicht durchgeführt werden.
X'000014'	Task mit bezeichneter TID bzw. TSN existiert nicht.
X'000018'	Der durch SCOPE=FUNCT angesprochene PCB existiert nicht.
X'01FFFF'	Die im Standardheader angegebene UNIT- bzw. FUNCTION-Nummer ist unzulässig. Verarbeitung wird abgebrochen.
X'03FFFF'	Ungültige Versionsnummer im Standardheader.
X'400020'	Der Tabellenübergabebereich für die Linkage-AUDIT-Tabelle (ACTION=GET) ist zu klein. Die Funktion wurde nicht vollständig ausgeführt.
X'400024'	Die Funktion konnte nicht ausgeführt werden, da a) ein prozessorlokaler Linkage-AUDIT läuft (STATE=SYS) oder b) ein Linkage-AUDIT im Funktionszustand TPR läuft (STATE=PROC) oder c) ein prozessorlokaler SIH-Linklage-AUDIT läuft (SCOPE=SYSGLOB) oder d) ein prozessorlokaler SIH- und TPR-Linkage-AUDIT läuft (SCOPE=SIHGLOB).
X'400028'	Die TU-Sicherungstabelle ist wegen internem AUDIT-Fehler nicht im Übergabepuffer enthalten.
X'40002C'	Die mit TID oder TSN bezeichnete Task befindet sich in der Beendigung. Der Auftrag wurde abgelehnt.
X'810030'	Die Makro-Aufruf-Folge AUDIT FCT=HWA,ACTION=ON/-OFF/-ON für eine Fremdtask in TPR bringt beim 2. ACTION=ON diesen RC immer dann, wenn die Fremdtask zwischenzeitlich nicht gelaufen ist. Dies bedeutet, dass der zweite Makro- Aufruf mit ACTION=ON zu einem späteren Zeitpunkt wiederholt werden muss, weil der Makro-Aufruf mit ACTION=OFF sich noch in einer Warteschlange befindet.
X'810034'	Makroaufruf AUDIT FCT=HWA/LNKA,STATE=U Für die aktive Benutzerkennung wurde der Hardware- bzw. Linkage-AUDIT von der Systemverwaltung mit dem Kommando /MODIFY-USER-ATTRIBUTES gesperrt.
X'810038'	Makroaufruf AUDIT FCT=HWA/LNKA,STATE=U Hardware- bzw. Linkage-AUDIT wurde vom Benutzer mit dem Kommando /MODIFY- TEST-OPTIONS für die aktive Task gesperrt.
X'81003C'	Makroaufruf AUDIT FCT=HWA/LNKA Für die aktuelle Session wurden von der Systemverwaltung im STARTUP-Parameterservice mit dem Parameter AUDALLOW=NO alle AUDIT-Makroaufrufe verboten.
X'81FFFF'	Die zentrale Linkage-AUDIT-Verwaltung ist zurzeit gesperrt (bitte warten und den Auftrag nach einiger Zeit wiederholen).