Zur Diagnose der Kommunikationskomponente CMX(BS2000) steht das Diagnose-Tool DCM-DIAG zur Verfügung.
DCM-DIAG ist ein Subsystem und besteht im Wesentlichen aus einer Kommandoschnittstelle (SET-COMMUNICATION-TRACE) und einem Trace-Modul. In CMX ist der Trace-Modul eingebunden. Für externe Anwendungen wird der Trace-Modul zum Einbinden in die jeweilige Anwendung angeboten. Voraussetzung für die Verwendung des Trace-Moduls in externen Anwendungen ist die Nutzung der Kommunikationskomponente CMX durch diese externen Anwendungen.
Der Trace-Modul bietet Funktionen zum Öffnen und Schließen sowie Schreiben der Trace-Datei. Sie steuern das Trace-Modul über das Kommando SET-COMMUNICATION-TRACE. Das Kommando SET-COMMUNICATION-TRACE ist kein Konsolkommando und steht sowohl dem Administrator als auch dem Anwender zur Verfügung. Der Administrator benötigt zur Nutzung des vollen Funktionsumfangs von SET-COMMUNICATION-TRACE das TSOS-Privileg bzw. das NET-ADMINISTRATION-Privileg. Der Anwender kann nur auf Trace-Dateien zugreifen, die seine Kennung betreffen. Eine ausführliche Beschreibung bezüglich Aufbau und Einsatz des Trace-Moduls finden Sie auf den folgenden Seiten.
Die Beschreibung des Kommandos SET-COMMUNICATION-TRACE finden Sie im Abschnitt „SET-COMMUNICATION-TRACE: DCM-DIAG steuern".
Trace-Datei
Die Trace-Datei wird vom Trace-Modul erzeugt und kann vom Anwender mit Hilfe des Diagnoseprogramms TEDDY ausgewertet werden. Trace-Dateien werden bei jedem Aktivieren (Einschalten) des Traces neu erzeugt, bestehende Dateien werden nicht fortgeschrieben.
Der Trace-Modul ist unter dem Namen YDTLNK abgelegt und existiert für TU und TPR getrennt. Hinzu kommt der Modul YDTTOOL für die von YDTLNK verwendeten Assemblerroutinen. Diese Module befinden sich in folgenden Bibliotheken:
Für mit C-Compiler >= V2.0 und CRTE V2.0 erstellte Anwendungen (beispielsweise steht 011 als Wert für nnn im Fall der DCM-DIAG Version V1.1):
für TU
für TPR
in SYSLIB.DCM-DIAG.nnn.TU
in SYSLIB.DCM.DIAG.nnn.TP
Für mit C-Compiler >= V2.0 und CRTE V1.0 erstellte Anwendungen befindet sich der Modul YDTLNK in SYSLIB.DCM-DIAG.nnn.COMPV2.
Für mit C-Compiler V1.0 erstellte Anwendungen:
für TU
in SYSLIB.DCM-DIAG.nnn.COMPV1
Für Anwendungen auf X86:
für TPR
in SKMLIB.DCM-DIAG.nnn.TP
Zum Bearbeiten einer Trace-Datei bietet der Trace-Modul vier Funktionen:
Öffnen einer Trace-Datei Schließen einer Trace-Datei Schließen aller offenen Trace-Dateien Schreiben eines Trace-Satzes in die Trace-Datei | TraceFileOpen TraceFileClose AllTraceFileClose TraceFileWriteRecord |
Trace-Datei öffnen
int TraceFileOpen(int *handle, char *KompName, char *KompVer);
Diese Funktion eröffnet eine neue Trace-Datei. Der Name der Trace-Datei hat folgenden Aufbau:
<$userid>.SYS.DIA.<komponente>.<tsn>.<laufende nummer>
<$userid> | die Datei wird unter derjenigen Kennung angelegt, unter der der Task läuft. |
<komponente> | ist der Name der Anwendung (CMX oder z.B. eigene Anwendung) |
<tsn> | TSN des Anwenders |
<laufende nummer> | um den Namen der Trace-Datei eindeutig zu halten, wird eine laufende Nummer angehängt. |
Die Dateiattribute der Trace-Datei sind: FCBTYPE=SAM, RECFORM=V, BLKCTRL=PAMKEY, BLKSIZE=(STD,14)
Call Parameter:
int *handle: | Zeiger auf integer für die Datei-Id, die in allen nachfolgenden Aufrufen angegeben werden muss. |
char *KompName:
| Einer der folgenden Komponentennamen: |
char *KompVer: | Versionsangabe für die ausgewählte Komponente in der Länge 4 |
Returnwert:
#define FILE_OPENED_SUCCESSFULLY 0 #define FILE_NAME_CONSTRUCTION_ERROR 1 #define FILE_OPEN_DMS_ERROR 2 #define REQUEST_MEMORY_ERROR 3 #define WRITE_HEADER_RECORD_ERROR 4 #define FILE_COMMAND_ERROR 5
Bei erfolgreicher Durchführung der Funktion wird ein Headersatz für TEDDY in die Trace-Datei geschrieben.
In die Trace-Datei schreiben
int TraceFileWriteRecord(int handle,char *identifier, char *typ, char *target,char *TraceInfo, int TraceLen);
Diese Funktion schreibt einen Trace-Satz in die durch handle identifizierte Trace-Datei. Um die Performance zu verbessern, werden die Trace-Sätze zunächst in einem Puffer gesammelt. Der Puffer wird in die Trace-Datei geschrieben, wenn er voll ist oder bei Trace-FileClose / AllTraceFileClose.
Call Parameter:
int handle: | Datei-Id, definiert in der TraceFileOpen Function | |
char *identifier:
| Trace-Identifier (Länge 1) z.B. | |
C | für CMX | |
X | für External User | |
char *typ: | Typ der Trace-Information (max. Länge 2) z.B. | |
C | für Aufruf einer Funktion | |
R | für Rückkehr aus einer Funktion | |
D | für Daten usw. | |
char *target: | frei wählbarer Wert (max. Länge 2) z.B. | |
I | Funktionsaufruf oder Signal von einer anderen Komponente an die tracende Komponente | |
O | Funktionsaufruf von der tracenden Komponente an eine andere Komponente. | |
char *TraceInfo: | zu speichernder Trace-Satz | |
int TraceLen: | Länge der Trace-Info oder 0 (implizite Stringlänge) | |
Returnwert:
#define RECORD_WRITE_SUCCESSFULLY 0 #define RECORD_WRITE_DMS_ERROR 1 #define INVALID_FILE_ID 2 #define FOREIGN_FILE_ID 3 #define IDENTIFIER_TOO_LONG 4 #define TYP_TOO_LONG 5 #define TARGET_TOO_LONG 6 #define TRACE_INFO_TOO_LONG 7
Bei erfolgreicher Durchführung der Funktion wird der Trace-Satz mit einem Header für TEDDY in den Speicherpuffer geschrieben.
Trace-Datei schließen
int TraceFileClose(int handle);
Diese Funktion schließt die mit int handle definierte Trace-Datei.
Call Parameter:
int handle: | wird von der TraceFileOpen Function geliefert |
Returnwert:
#define FILE_CLOSED_SUCCESSFULLY 0 #define FILE_CLOSE_DMS_ERROR 1 #define INVALID_FILE_ID 2 #define FOREIGN_FILE_ID 3
Bei erfolgreichem Schließen der Trace-Datei werden alle noch nicht gesicherten Trace-Sätze in die Trace-Datei geschrieben.
Alle Trace-Dateien schließen
void AllTraceFileClose();
Call Parameter: | keine |
Returnwert: | keine |
Beispiel
/* Beispiel für eine Anwendung mit den Funktionsaufrufen des Trace-Moduls */
#include "stdio.h"
#include "stdlib.h"
#include "string.h"
#include "ydtlnk.h"
void main () {
/* ----------------------- Werte für das Testbeispiel ------------------ */
int ret;
int handle; *)
char *identifier = "S";
char *typ = "TY";
char *target = "TA";
char *TraceInfo = "THIS-IS-THE-TRACEINFO";
char *version = "V14";
char *KompNam = "TESTPROG";
*) internes Kennzeichen einer Tracedatei; wird von der Trace-Funktion geliefert
/* -------------------- Trace-Datei eröffnen -------------------------- */
if ((ret = TraceFileOpen(&handle,KompNam,version)) ==
FILE_OPENED_SUCCESSFULLY)
printf ("open succeeded, FileId=%d\n", handle);
else {
printf ("open failed:%d\n", ret);
goto fehler;
}
.
.
.
.
/* ------------------------- Trace-Satz schreiben -------------------- */
if ((ret = TraceFileWriteRecord(handle,identifier,
typ,target,TraceInfo,0)) == RECORD_WRITE_SUCCESSFULLY)
printf ("write succeeded\n");
else {
printf ("write failed:%d\n", ret);
goto fehler;
}
.
.
.
/* ----------------------------- Trace-Datei schließen ------------------ */
if ((ret = TraceFileClose(handle)) == FILE_CLOSED_SUCCESSFULLY)
printf ("close succeeded\n");
else {
printf ("close failed:%d\n", ret);
goto fehler;
}
return;
fehler: printf ("Fehlerhafter Lauf\n");
}