BCAM-Trace in openUTM

Mit der Funktion BCAM-Trace von openUTM können alle Verbindungs-bezogenen Aktivitäten innerhalb einer UTM-Anwendung protokolliert werden.

Inhalt des BCAM-Trace

Es werden folgende Typen von Trace-Records geschrieben:

• Parameterblock: Die BCAM-Parameterblöcke der Aufrufe REQCON, ACCON, REJCON, DISCON sowie die BCAM-Parameterblöcke der Aufrufe RECLET und SENDLET, die einen Returncode lieferten, oder die RSO-Parameterblöcke der Aufrufe der RSO-Schnittstelle.

• Announcement: Alle Verbindungs-bezogenen Announcements

• Connection-Letter

• Kommunikation mit TS-Anwendung vom Typ Socket: Parameterblöcke der Funktionen connection request, connection response und disconnect request der Socket-Schnittstelle

• Nachricht: Alle Ein-/Ausgabe-Nachrichten

Jeder Trace-Record enthält folgende Einträge in der angegebenen Reihenfolge:

1. Zeitstempel

2. BCAMAPPL-Name

3. PTERM/MUX/CON-Name

4. PROCESSOR-Name

5. LTERM/LPAP-Name

6. USER-Name

7. Typ des Trace-Records (s.o.):

   • Announcement

   • Parameterblock

   • Connection-Letter

   • TCP/IP-Record

   • Nachricht (Ein-/Ausgabe-Nachricht)

8. Bis zu 32624 Byte Daten (abhängig vom Recordtyp und vom Wert des Operanden length beim Startparameter BTRACE).

   Bei längeren Datenelementen (z.B. Ein-/Ausgabe-Nachrichten) ist das Verhalten abhängig von der eingestellten maximalen Länge der Daten, die mitgeschnitten werden:

   • Ist ein Wert kleiner als das Maximum 32624 eingestellt, enthält der Trace-Record die ersten length/2 Bytes und die letzten length/2 Bytes des Datenelements.

   • Ist der Maximalwert 32624 eingestellt, wird versucht, die Daten komprimiert zu schreiben. Falls die Daten nicht auf eine Länge von 32624 Bytes komprimiert werden können, wird der Trace-Record nur mit den ersten 16312 Bytes und den letzten 16312 Bytes der Daten geschrieben.

Vorbereitende Tätigkeiten

In der UTM-Startprozedur muss für jede Task eine Trace-Datei eingerichtet und dieser mit dem Kommando SET-FILE-LINK der LINK-Name KDCBTRC zugewiesen werden.

Jede Task einer UTM-Anwendung schreibt die Trace-Sätze in eine eigene Datei. Daher müssen die Trace-Dateien in der Startprozedur so eingerichtet werden, dass sie unterschiedliche Dateinamen erhalten. Zu diesem Zweck kann z.B. die TSN der Task an den Dateinamen angehängt werden.

/CREATE-FILE FILE-NAME = &(FILEBASE//'.BTRC.'//TSN()) - 
/ , SUPPORT=*PUBLIC-DISK(SPACE=*RELATIVE - 
/ (PRIMARY-ALLOCATION=<integer_1..2147483647> - 
/ ,SECONDARY-ALLOCATION=<*STD or integer_0..32767>)) 
/ADD-FILE-LINK FILE-NAME = &(FILEBASE//'.BTRC.'//TSN()) - 
/ ,LINK-NAME = KDCBTRC [, BUFFER-LEN = *STD(SIZE=<1..16>) ]

Dabei sollte der Prozedurparameter FILEBASE den <filebase>-Namen der UTM-Anwendung enthalten.

Ab einer maximalen Länge der Trace-Sätze von 1960 müssen Sie zusätzlich den Parameter BUFFER-LENGTH mit der passenden Anzahl Blöcke angeben. Berücksichtigen Sie dabei, dass die Primärzuweisung mindestens doppelt so groß sein muss wie die Blockgröße, und dass die Sekundärzuweisung Null oder mindestens so groß sein muss wie die Blockgröße.

Maximale Trace-Länge	BUFFER-LENGTH=
> 1960	STD(2)
> 4008	STD(4)
> 8104	STD(8)
> 16296	STD(16)

Steht SDF-P nicht zur Verfügung, dann kann dasselbe mittels Job-Variablen oder EDT-Prozeduren erreicht werden.

Ein-/Ausschalten BCAM-Trace

Der BCAM-Trace kann per Startparameter oder per Administrationskommando ein- und ausgeschaltet werden. Standardmäßig ist die Funktion beim Start der Anwendung ausgeschaltet.

• Ein-/ Ausschalten über Startparameter

  .UTM START,BTRACE = { ON  | (  ON, length ) }

  .UTM START,BTRACE = { OFF | ( OFF, length ) }

  Damit wird die Trace-Funktion beim Start der Anwendung eingeschaltet (ON) bzw. bleibt ausgeschaltet (OFF).

  Außerdem können Sie die maximale Länge der Daten, die aufgezeichnet werden, angeben.
  Minimum: 32
  Maximum: 32624
  Standardwert: 256

  Diese Maximallänge kann nur über Startparameter festgelegt werden.

  Wenn Sie den BCAM-Trace für die Funktion UPIC Capture einsetzen (siehe openUTM-Handbuch„Einsatz von UTM-Anwendungen auf BS2000-Systemen“), dann wird empfohlen, den Maximalwert zu verwenden.

• Ein-/ Ausschalten über Administrationskommando

  KDCDIAG BTRACE=ON/OFF[,LTERM=lterm-name/LPAP=lpap-name / USER=user-name/ MUX=(mux-name,prozessor-name,bcamappl)]

  Damit wird die Trace-Funktion im Betrieb der Anwendung ein- bzw. ausgeschaltet. Bei Angabe eines LTERM-, LPAP- oder MUX-Namens werden nur die zu dieser Verbindung gehörenden Ereignisse aufgezeichnet.  Bei Angabe eines USER-Namens werden nur die zu dieser Benutzerkennung gehörenden Ereignisse aufgezeichnet.

• Ein-/ Ausschalten über Programmschnittstelle zur Administration (z.B. über WinAdmin oder WebAdmin)

  Im Objekt-Typ KC_DIAG_AND_ACCOUNT geben Sie an:

  bcam_trace=’Y’ bzw. ’N’ (Datenstruktur kc_diag_and_account_par_str)

Nach dem Einschalten der BCAM-Trace Funktion werden die durch die SET-FILE-LINK-Kommandos zugewiesenen Trace-Dateien (SAM-Datei) mit EXTEND geöffnet.
Wird der BCAM-Trace mit dem Kommando KDCDIAG eingeschaltet, ohne dass Trace-Dateien mit SET-FILE-LINK-Verknüpfung zugewiesen sind, wird das Kommando zwar erfolgreich ausgeführt, aber die Anwendungstask läuft beim Schreiben der Trace-Informationen auf einen DMS-Fehler und der BCAM-Trace wird daraufhin wieder ausgeschaltet.

Nach dem Ausschalten der BCAM-Trace-Funktion werden die Trace-Dateien geschlossen und können danach ausgewertet werden. Da das Schließen der Dateien von allen Tasks der Anwendung ausgeführt werden muss, kann es einige Zeit erfordern, bis alle Trace-Dateien geschlossen sind. Mit Hilfe des Kommandos SHOW-FILE-ATTRIBUTES können die eröffneten Dateien abgefragt werden.
Tritt für eine der Trace-Dateien ein DMS-Fehler auf, beendet openUTM die Trace-Funktion.

Auswerten des BCAM-Trace

Die Trace-Dateien können nach Ausschalten der BCAM-Trace Funktion bzw. dem Beenden der UTM-Anwendung ausgewertet werden. Dazu steht das Tool KDCBTRC zur Verfügung. Mit dem Tool KDCBTRC können nur Trace-Dateien der gleichen openUTM-Version ausgewertet werden.

Vor dem Aufruf des Tools KDCBTRC müssen die Trace-Dateien der einzelnen Tasks in eine Datei gemischt werden.

Es gibt eine Beispielprozedur BTRACE für das Mischen der einzelnen Trace-Dateien und das Auswerten der gemischten Datei mit dem Dienstprogramm KDCBTRC. 
Die SDF-P-Prozedur BTRACE wird in der Bibliothek SYSPRC.UTM.070 mit ausgeliefert.

Im Allgemeinen wertet KDCBTRC die Datei mit dem Linknamen KDCBTRC aus. Das Ergebnis wird in die Datei mit dem Linknamen LISTFILE geschrieben. Die Steueranweisung wird von SYSDTA gelesen.

Die Steueranweisung im Format
[Argument-1, ..., Argument-n]
erlaubt die Eingabe von optionalen Argumenten zur Steuerung der Aufbereitung. Die Argumente sind im folgenden Abschnitt beschrieben. Wenn Sie eine „leere“ Steueranweisung (Leerzeichen) eingeben, wird die gesamte Trace-Datei aufbereitet.

Argumente des Aufbereitungsprogramms

LT=ltn / (ltn1, ..., ltn5)	Mit diesem Operanden können ein bis fünf LTERM-Namen oder LPAP-Namen angegeben werden. Damit werden nur die Trace-Records aufbereitet, die einen der angegebenen LTERM/LPAP-Namen enthalten. Voreinstellung: alle Trace-Records werden aufbereitet.
PT=ptn / (ptn1, ..., ptn5)	Mit diesem Operanden können ein bis fünf PTERM-Namen, CON-Namen oder MUX-Namen angegeben werden. Damit werden nur die Trace-Records aufbereitet, die einen der angegebenen PTERM/MUX/CON-Namen enthalten. Voreinstellung: alle Trace-Records werden aufbereitet.
BC=bcn / (bcn1, ..., bcn5)	Mit diesem Operanden können ein bis fünf BCAMAPPL-Namen oder ACCESS-POINT-Namen angegeben werden. Damit werden nur die Trace-Records aufbereitet, die einen der angegebenen BCAMAPPL/ACCESS-POINT-Namen enthalten. Voreinstellung: alle Trace-Records werden aufbereitet.
PR=prn / (prn1, ..., prn5)	Mit diesem Operanden können ein bis fünf Prozessornamen angegeben werden. Damit nur die Trace-Records aufbereitet, die einen der angegebenen PROCESSOR-Namen enthalten. Voreinstellung: alle Trace-Records werden aufbereitet.
US=usr / (usr1, ..., usr5)	Mit diesem Operanden können ein bis fünf Benutzerkennungen (USER) angegeben werden. Damit werden nur die Trace-Records aufbereitet, die den Namen einer der angegebenen Benutzerkennungen enthalten. Voreinstellung: alle Trace-Records werden aufbereitet.
AN=Y/N	Bei Angabe von AN=Y werden die Trace-Records aufbereitet, die Announcements enthalten. Bei AN=N wird die Aufbereitung unterdrückt. Voreinstellung: AN=N
PB=Y/N	Bei Angabe von PB=Y werden die Trace-Records aufbereitet, die BCAM- oder RSO-Parameterblöcke enthalten. Bei PB=N wird die Aufbereitung unterdrückt. Voreinstellung: PB=N
CL=Y/N	Bei Angabe von CL=Y werden die Trace-Records aufbereitet, die Connection-Letters enthalten. Bei CL=N wird die Aufbereitung unterdrückt. Voreinstellung: CL=Y
IN=Y/N	Bei Angabe von IN=Y werden die Trace-Records aufbereitet, die Eingabe-Nachrichten enthalten. Bei IN=N wird die Aufbereitung unterdrückt. Voreinstellung: IN=Y
OUT=Y/N	Bei Angabe von OUT=Y werden die Trace-Records aufbereitet, die Ausgabe-Nachrichten enthalten. Bei OUT=N wird die Aufbereitung unterdrückt. Voreinstellung: OUT=Y
DVC=T/P/B	Mit dem DVC-Operanden wird das Format der Ausgabedatei bestimmt. DVC=T: Zeilenbreite max. 79 Zeichen, keine Druckersteuerzeichen DVC=B: Zeilenbreite max. 79 Zeichen, mit Druckersteuerzeichen DVC=P: Zeilenbreite max. 132 Zeichen, mit Druckersteuerzeichen Voreinstellung: DVC=T
SOCKET=Y/N	Bei Angabe von SOCKET=Y werden die Trace-Records, die Traces für Funktionen zur Kommunikation mit dem Protokoll TCP/IP enthalten, aufbereitet. Bei SOCKET=N wird die Aufbereitung unterdrückt.  Voreinstellung: SOCKET=Y