Your Browser is not longer supported

Please use Google Chrome, Mozilla Firefox or Microsoft Edge to view the page correctly
Loading...

{{viewport.spaceProperty.prod}}

UPIC-Trace

&pagelevel(4)&pagelevel

Beim Trägersystem UPIC ist es möglich, Verfolgerinformation für sämtliche CPI-C-Schnittstellenaufrufe zu erzeugen. Dies steuern Sie durch das Setzen der Variablen UPICTRACE.

Beim Aufruf Enable_UTM_UPIC wird der Inhalt der Variable ausgewertet. Falls sie gesetzt ist, werden beim Aufruf jeder Funktion die Parameter und die Benutzerdaten bis zu einer Länge von 128 Bytes Prozess-spezifisch in einer Datei protokolliert.
Beim Disable_UTM_UPIC-Aufruf wird die Protokollierung wieder ausgeschaltet.

Falls ein CPI-C-Aufruf einen Returncode ungleich CM_OK oder CM_DEALLOCATED_ABEND liefert, wird auch diese Fehlerursache in die UPIC-Trace-Datei protokolliert. Sie gibt bei der Fehlersuche detaillierte Hinweise zu einem speziellen Returncode.

UPIC-Trace einschalten

Den UPIC-Trace schalten Sie ein, indem Sie die Variable UPICTRACE entsprechend setzen. Der UPIC-Trace wird auf den einzelnen Plattformen wie folgt eingeschaltet:

  • Windows-Systeme:

    Der UPIC-Trace kann eingeschaltet werden, indem die Umgebungsvariable UPICTRACE entsprechend gesetzt wird. Wenn die Umgebungsvariable UPICTRACE gesetzt ist, wird der Wert der Umgebungsvariable verwendet.

    Für UPICTRACE kann folgendes gesetzt werden:

    UPICTRACE=-S[X] [-r wrap ] [-d pfadname ]

  • Unix- und Linux-Systeme:

    Der UPIC-Trace wird eingeschaltet, wenn die Umgebungsvariablen UPICTRACE wie folgt gesetzt wird:

    UPICTRACE=-S[X] [-r wrap ] [-d pfadname ]
    export UPICTRACE

  • BS2000-Systeme:

    Der UPIC-Trace wird wie folgt eingeschaltet:

    /SET-JV-LINK LINK-NAME=*UPICTRA,JV-NAME=UPICTRACE

    /MODIFY-JV JV-CONTENTS=*LINK(LINK-NAME=UPICTRA),SET-VALUE='-S[X] [-R wrap ] [-D präfix ]'

    Die Option -D muss hier als Großbuchstabe angegeben werden.

Die Optionen haben folgende Bedeutung:

-S

Es erfolgt eine ausführliche Protokollierung der CPI-C-Aufrufe, ihrer Argumente und der Benutzerdaten in der maximalen Länge von 128 Bytes (Pflichtangabe).

-SX

Es werden zusätzlich interne Informationen an der Schnittstelle zum Transportsystem protokolliert (siehe auch Erweiterter UPIC Trace). Es wird empfohlen, immer diese Option zu verwenden, da Probleme häufig mit der Transportschnittstelle zusammenhängen.

Der Schalter -SX ist bei PCMX eine Erweiterung zum Schalter -S.
Bei der Kommunikation mit Socket hat dieser Schalter keine zusätzliche Wirkung zum Schalter -S.

-r wrap (Unix-, Linux- und Windows-Systeme)
-R wrap (BS2000-Systeme)

Der durch die Dezimalzahl wrap angegebene Wert wird mit BUFSIZ multipliziert. Dies ergibt die maximale Größe der Trace-Datei in Bytes. BUFSIZ ist ein Wert, der von der Plattform und vom Compiler abhängt.

Maximalwert von wrap: 2 hoch 31 (Maximalwert von einem int)
Standardwert von wrap: 128

-dpfadname (Unix-, Linux- und Windows-Systeme)
-Dpräfix (BS2000-Systeme)

Der Pfadname (bzw. das Präfix) kann mit Leerzeichen angegeben werden. Wenn Leerzeichen verwendet werden, muss der Pfadname (bzw. das Präfix) in doppelte Hochkommata eingeschlossen werden. Sind keine Leerzeichen im Pfadnamen, können doppelte Hochkommata auch verwendet werden.

Windows-Systeme:

Die Trace-Dateien werden in dem mit pfadname angegebenen Dateiverzeichnis eingerichtet.
Wenn Sie -d pfadname nicht angeben, werden die Trace-Dateien in das Verzeichnis geschrieben, das in der Variablen TEMP angegeben ist. Ist TEMP nicht gesetzt, wird dasselbe mit TMP versucht. Sind beide Variablen nicht gesetzt, werden die Trace-Dateien im Dateiverzeichnis \USR\TMP eingerichtet. Dieses Verzeichnis muss dann vorhanden sein und das CPI-C-Programm muss in diesem Dateiverzeichnis schreibberechtigt sein, sonst gehen die Trace-Daten verloren.

Unix- und Linux-Systeme:

Die Trace-Dateien werden in dem mit pfadname angegebenen Dateiverzeichnis eingerichtet.
Wenn Sie -d pfadname nicht angeben, werden die Trace-Dateien im Dateiverzeichnis /usr/tmp eingerichtet. Das CPI-C-Programm muss in diesem Dateiverzeichnis schreibberechtigt sein, sonst gehen die Trace-Daten verloren.

BS2000-Systeme:

Für die Trace-Dateien wird ein Datei-Präfix angegeben, dass keine Leerzeichen haben sollte.
Wenn Sie -D nicht angeben, werden die Namen der Trace-Dateien um das Präfix ##.usr.tmp. erweitert. Die Trace-Dateien werden unter der Kennung abgelegt, unter der das Programm gestartet wird. Das CPI-C-Programm muss die Datei öffnen können, sonst gehen die Trace-Daten verloren.

Beispiel

Bei Angabe von -DTRC wird die Trace-Datei TRC.UPICT tsn geschrieben.

Trace-Dateien

Die Verfolgerinformation wird in einer temporären Datei abgelegt. Diese Datei wird beim Enable_UTM_UPIC-Aufruf eingerichtet. Sie bleibt bis zum Disable_UTM_UPIC-Aufruf geöffnet. Die maximale Größe dieser temporären Datei bestimmen Sie durch die Dezimalzahl wrap.

In die Datei wird solange protokolliert, bis der Wert (wrap * BUFSIZ) Bytes (BUFSIZ wie in stdio.h) überschritten wird. Dann wird eine zweite temporäre Datei angelegt, die genauso behandelt wird.

Jedesmal, wenn der Wert (wrap * BUFSIZ) Bytes in der aktuellen Datei überschritten wird, schaltet der Verfolger auf die andere Datei um. Der alte Inhalt dieser Datei wird dabei überschrieben.

Die Dateinamen der Trace-Dateien sind Plattform-spezifisch. Folgende Dateinamen werden vergeben:

Name der

Windows-Systeme

Unix- und Linux-Systeme

Unix- und Linux-Systeme,
wenn Threads in
Programmen verwendet
werden

BS2000-Systeme

1. Datei

UPICTtid 1.upt

UPICTpid 2

UPICTpid 2.tid 1

UPICTtsn 3

2. Datei

UPICUtid 1.upt

UPICUpid 2

UPIUTpid 2.tid 1

UPICUtsn 3

1tid = Thread ID

2pid = Process ID

3tsn = TSN-Nummer


Erweiterter UPIC-Trace

Beim erweiterten UPIC-Trace werden zusätzlich interne Informationen an der Schnittstelle zum Transportsystem (UPIC <-> PCMX) protokolliert. Zusätzlich zu den UPIC-Aufrufen werden die zugehörigen CMX-Aufrufe protokolliert. Das erweiterte Protokoll ist wie folgt aufgebaut:

Nach der Protokollierung eines UPIC-Aufrufs wird zunächst eine Zeile mit einem ergänzenden Klartext ausgegeben. Danach folgt in zwei Zeilen die Protokollierung der zuletzt aufgerufenen CMX-Funktionen. Die Informationen sind durch Komma bzw. <newline> getrennt.

1. Zeile:

Die erste Zeile enthält folgende Informationen:

  • Name der aufgerufenen CMX-Funktion.

  • Returncode der CMX-Funktion t_error. Der Returncode ist eine hexadezimale Zahl. Ist diese von Null verschieden, dann können Sie ihr die Ursache eines aufgetretenen Fehlers entnehmen.

    Die Hexadezimalzahl kann wie folgt decodiert werden:

    • mit dem Kommando cmxdec -d 0x hexadezimalzahl oder

    • mit Hilfe des Windows-Programms Trace Control im Programm-Fenster PCMX. Wählen Sie im Menü Options den Befehl Error Decoding aus.

  • Returncode der CMX-Funktion als Dezimalzahl (falls die CMX-Funktion einen int-Wert zurückliefert).

Eine wichtige Ausnahme bildet die CMX-Funktion t_event. Ihr Rückgabewert (d.h. das aufgetretene Ereignis) wird immer an erster Stelle der zweiten Zeile ausgegeben.

2. Zeile:

Die zweite Zeile protokolliert einen CMX-Aufruf, der aufgrund eines eingetroffenen Ereignisses (t_event) im Zusammenhang mit der in der 1. Zeile protokollierten CMX-Funktion aufgerufen wurde. Die 2. Zeile enthält nacheinander folgende Informationen:

  • Name des Ereignisses, das die Funktion t_event zurückgeliefert hat.

  • Name der aufgerufenen CMX-Funktion.

  • Returncode von t_error, falls bei der zweiten CMX-Funktion ein Fehler auftrat. Er gibt gegebenenfalls den Grund für einen Verbindungsabbau an. Die Zahl kann wie oben beschrieben mit cmxdec decodiert werden. Der Wert -1 besagt, dass kein Verbindungsabbaugrund vorliegt.

  • Hinter dem letzten Komma dieser Zeile kann ein UPIC-Returncode folgen.

Wurde im Zusammenhang mit der in der 1. Zeile protokollierten CMX-Funktion keine weitere CMX-Funktion aufgerufen, dann wird in der 2. Zeile nur ein Leerzeichen und eine Null ausgegeben.

UPIC-Trace ausschalten

Der UPIC-Trace wird ausgeschaltet, indem die Variable UPICTRACE ohne Parameter gesetzt wird:

  • Windows-Systeme:

    indem Sie das folgende Set-Kommando absetzen:

    SET UPICTRACE=

  • Unix- und Linux-Systeme:

    UPICTRACE=

    export UPICTRACE

  • BS2000-Systeme:

    • mit dem Kommando

      /MODIFY-JV /MOD-JV JV-CONTENTS=*LINK(LINK-NAME=UPICTRA),SET-VALUE=C''

      Der Inhalt der JV wird gelöscht.

    • mit dem Kommando /DELETE-JV
      Die komplette JV wird gelöscht.

    Bei Neustart eines UPIC-Prozesses ist der Trace ausgeschaltet.

UPIC-Trace aufbereiten

Die Verfolgerinformation liegt bereits in abdruckbarer Form vor, sie muss deshalb nicht durch ein Dienstprogramm aufbereitet werden.

Jede Aktion wird mit der entsprechenden Uhrzeit und den übertragenen Werten protokolliert.

Powered by Atlassian Confluence and Scroll Viewport.