A Fujitsu Technology Solutions ============================ Information on this document ---------------------------- On April 1, 2009, Fujitsu became the sole owner of Fujitsu Siemens Computers. This new subsidiary of Fujitsu has been renamed Fujitsu Technology Solutions. This document from the document archive refers to a product version which was released a considerable time ago or which is no longer marketed. Please note that all company references and copyrights in this document have been legally transferred to Fujitsu Technology Solutions. Contact and support addresses will now be offered by Fujitsu Technology Solutions and have the format ...@ts.fujitsu.com. The Internet pages of Fujitsu Technology Solutions are available at http://ts.fujitsu.com/... and the user documentation at http://manuals.ts.fujitsu.com. Copyright Fujitsu Technology Solutions, 2009 Hinweise zum vorliegenden Dokument ---------------------------------- Zum 1. April 2009 ist Fujitsu Siemens Computers in den alleinigen Besitz von Fujitsu uebergegangen. Diese neue Tochtergesellschaft von Fujitsu traegt seitdem den Namen Fujitsu Technology Solutions. Das vorliegende Dokument aus dem Dokumentenarchiv bezieht sich auf eine bereits vor laengerer Zeit freigegebene oder nicht mehr im Vertrieb befindliche Produktversion. Bitte beachten Sie, dass alle Firmenbezuege und Copyrights im vorliegenden Dokument rechtlich auf Fujitsu Technology Solutions uebergegangen sind. Kontakt- und Supportadressen werden nun von Fujitsu Technology Solutions angeboten und haben die Form ...@ts.fujitsu.com. Die Internetseiten von Fujitsu Technology Solutions finden Sie unter http://de.ts.fujitsu.com/..., und unter http://manuals.ts.fujitsu.com finden Sie die Benutzerdokumentation. Copyright Fujitsu Technology Solutions, 2009 A --------------------------------- Readme-Datei zu CMX(BS2000) V1.2A --------------------------------- Oktober 1997 Die vorliegende Readme-Datei zu CMX(BS2000) V1.2A enthaelt Aenderungen zu folgendem Handbuch: CMX (BS2000) V1.0 Kommunikationsmethode im BS2000 Benutzerhandbuch Ausgabe September 1992 (CMX V1.0) Bestellnummer U9583-J-Z125-1 A Seite 1 ------------------ Inhaltsverzeichnis ------------------ 1 Trace- und Diagnosebaustein DCM-DIAG 1.1 Ueberblick 1.2 SDF-Kommando /SET-COMMUNICATION-TRACE: DCM-DIAG steuern 1.2.1 Funktion 1.2.2 Syntax 1.2.3 Beschreibung der Operanden 1.2.4 Sicherheitsrelevante Einschraenkungen 1.2.5 Reaktionen des Kommandos 1.2.5.1 Meldungsausgabe 1.2.5.2 Meldungen 1.3 Trace-Modul 1.3.1 Funktion 1.3.2 Trace-Datei 1.3.3 Beschreibung der Schnittstelle 1.3.4 Beispiel 1.3.5 Fehlerbehandlung 1.4 Komponenten der Datenkommunikation 1.4.1 CMX 1.4.1.1 Steuerung des CMX-Trace Steuerung ueber /SET-COMMUNICATION-TRACE Beendigung der CMX-Anwendung 1.4.1.2 Tracekriterien 1.4.1.3 Steuerung des Trace der CMX-Anwendung im Hinblick auf externe Anwender 1.5 Darstellung der Trace-Datei 1.5.1 Headersatz 1.5.2 Trace-Datei-Satz 1.5.3 Trace-Satz 1.5.3.1 Layout des Trace-Satzes fuer CMX ATTACH-DETACH NAME-ADDRESS CONNECT TRANSPORT OTHERS INTERN 2 Aenderungen in CMX(BS2000) V1.1A 2.1 Subsysteme, Bibliotheken und Dateien 2.2 Uebersetzen und Binden 2.3 Allgemeine Korrekturen 2.4 Unterschiede von CMX(BS2000) zu CMX(SINIX) 2.5 CMX-Fehlermeldungen A Seite 2 1 Trace- und Diagnosebaustein DCM-DIAG 1.1 Ueberblick Zur Diagnose der Kommunikationskomponenten SOCKETS und CMX steht ab BCAM V14 das Diagnose-Tool DCM-DIAG zur Verfuegung. Fuer externe Anwendungen, beispielsweise DPRINT, wird ein Trace-Modul angeboten, der vom Anwender in die jeweilige Anwendung eingebunden werden muss. Voraussetzung fuer die Verwendung des Trace-Moduls in externen Anwen- dungen ist die Nutzung der Kommunikationskomponenten SOCKETS bzw. CMX durch diese externen Anwendungen. Die Steuerung des Trace-Moduls erfolgt ueber das SDF-Kommando SET-COMMUNICATION-TRACE. Aufgabe von DCM-DIAG ist es, die Diagnosehilfe fuer die Kommunika- tionskomponenten SOCKETS und CMX im BS2000 gemeinsam zu steuern. Auch soll es externen Anwendern (z.B. DPRINT) moeglich sein, mit dem Diagnosebaustein DCM-DIAG eine Nachricht fuer deren Anwendungen zu erzeugen. Voraussetzung dafuer ist, dass die entsprechenden Programme, die Trace-Informationen empfangen wollen, ueber CMX bzw. SOCKETS kommunizieren. Grundsaetzlich muessen die diversen Trace- Einstellungen, die der Anwender gewaehlt hat, an die zu tracende Komponente weitergeleitet werden. Dazu hat der Anwender die Moeglich- keit, seine gewuenschten Trace-Informationen mittels des BS2000- Kommandos (/SET-COMMUNICATION-TRACE) einzugeben. Eine Auswertroutine (Steuer-Modul), die hinter dem Kommando steht, wertet die Angaben des Anwenders aus. Sie erzeugt daraus eine Datenstruktur (Parameterliste) und reicht diese an BCAM weiter. BCAM waehlt anhand der uebergebenen Daten die entsprechende(n) Task(s) aus und reicht die Daten an sie weiter. Damit die zu tracenden Komponenten das Schreiben der Trace- Information nicht selbst realisieren muessen, wird von DCM-DIAG ein eigener Trace-Modul angeboten, der zu den jeweiligen Anwendungs- programmen dazuzubinden ist. Dieser Trace-Modul uebernimmt von der zu tracenden Anwendung die Trace-Informationen und schreibt sie als Trace-Saetze in eine Trace-Datei. Der Trace-Modul bietet Funktionen zum Oeffnen und Schliessen der Trace-Datei. Diese Trace-Datei kann mit dem Trace-Auswertprogramm TEDDY weiterverarbeitet werden. A Seite 3 1.2 SDF-Kommando /SET-COMMUNICATION-TRACE: DCM-DIAG steuern 1.2.1 Funktion Mit dem Kommando /SET-COMMUNICATION-TRACE wird das Diagnose-Tool DCM-DIAG gesteuert. Voraussetzung fuer die Verwendung von SET-COMMUNICATION-TRACE ist der erfolgreiche Start des Subsystems DCM-DIAG. Mit dem SDF-Kommando /SET-COMMUNICATION-TRACE kann der Anwender folgende Entscheidungen treffen: - Angabe einer TSN oder UID, fuer die Trace-Einstellungen gemacht werden sollen - Kommunikation-Komponente(n) oder eine externe Komponente, die getraced werden soll(en) - Angabe von Trace-Kriterien /SET-COMMUNICATION-TRACE ist kein Konsolkommando. A Seite 4 1.2.2 Syntax Hinweis Fuer die folgende Syntax- bzw. Operandenbeschreibung gilt der Abschnitt 5.26 des BCAM-Referenzhandbuches V14.0. --------------------------------------------------------------------- /SET-COMMUNICATION-TRACE --------------------------------------------------------------------- SELECT = *TSN(...) / *UID(...) *TSN(...) | | TSN = *OWN / *ALL / < alphanum-name 1 .. 4 > ---- *UID(...) | | UID = *OWN / ---- , SOCKETS = *UNCHANGED / *NONE / SOC-ERR / SOC-ICO / REC-SEND / ---------- ICO-PAR / ICO-DATA , CMX = *UNCHANGED / *NONE / *ALL / list-poss (6): ATTACH-DETACH / ---------- NAME-ADDRESS / CONNECT / TRANSPORT / OTHERS / INTERN , EXTERNAL-USER = *NONE / *USER-ATTRIBUTES(...) ----- *USER-ATTRIBUTES(...) | | NAME-OF-USER = < alphanum-name 1 .. 8 > | ,TRACE-INFORMATION = < c-string 1 .. 30 > / | < x-string 1 .. 60 > --------------------------------------------------------------------- A Seite 5 1.2.3 Beschreibung der Operanden SELECT=*TSN(...) / *UID(...) Angabe des Selektionskriteriums *TSN(...) Selektionskriterium ist die TSN *OWN / *ALL / ---- gibt die TSN der Task an, fuer die die Trace-Kriterien fuer eine oder mehrere Kommunikations-Komponenten geaendert werden sollen. *OWN ---- bedeutet, dass fuer die eigene Task getraced wird (Defaultwert). *ALL ist speziell fuer Systemverwalter vorgesehen (alle TSN's --> das Ereignis wird dann an alle BCAM-Anwender verteilt) Angabe einer speziellen TSN (fuer Tasks, die unter der eigenen Userid laufen, ist kein Privileg noetig, sonst TSOS oder NET-ADMINISTRATION). *UID(...) Selektionskriterium ist die UID *OWN / ---- gibt die Userid an, fuer die die Trace-Kriterien fuer eine oder mehrere Kommunikations-Komponenten geaendert werden sollen. *OWN ---- fuer die eigene Userid sollen die Trace-Kriterien fuer eine oder mehrere Kommunikations-Komponenten geaendert werden fuer alle TSN's unter dieser UserID sollen die Trace- Kriterien fuer eine oder mehrere Kommunikations-Komponenten geaendert werden (Privileg TSOS oder NET-ADMINISTRATION fuer fremde Userids). A Seite 6 SOCKETS= Es soll die Komponente SOCKETS getraced werden. *UNCHANGED / *NONE / SOC-ERR / SOC-ICO / REC-SEND / ICO-PAR / ICO-DATA ---------- Es werden die Trace-Kriterien festgelegt. *UNCHANGED ---------- Die Trace-Einstellungen bleiben unveraendert. *NONE Trace wird ausgeschaltet. SOC-ERR Fehlermeldungen der Socketsfunktionen (Aufruf+Returncode) SOC-ICO Sockets-Funktionsaufrufe mit Parametern insyc-Routine(SOLSIG): welches Ereignis ist eingetroffen' BCAM-Funktionen + BCAM-Returncode REC-SEND datagram-sockets:Partner-Info stream-sockets:noch nicht abgeholter Rest UDP-receive:warning bei "truncated" interne Sockets-Funktionen(Aufruf+Parameter) ICO-PAR BCAM-Parameterliste nach dem BCAM-Aufruf ICO-DATA BCAM-Parameterliste vor und nach dem BCAM-Aufruf gesendete und empfangene Daten vor und nach dem BCAM-Aufruf Diese Einstellungen sind in dieser Reihenfolge als Tracelevels zu interpretieren: Hoehere Levels beinhalten auch die Aktionen fuer die niedrigeren Levels. Aenderungen der Trace-Einstellung werden erst nach der naechsten Aktion der entsprechenden Anwendung wirksam. A Seite 7 CMX= Es soll die Komponente CMX getraced werden. *UNCHANGED / *NONE / *ALL / list-poss(6): ATTACH-DETACH / ---------- NAME-ADDRESS / CONNECT / TRANSPORT / OTHERS / INTERN Legt die Trace-Kriterien fest (bei welchen CMX-Kommandos Trace-Saetze erstellt werden). *UNCHANGED ---------- Die Trace-Einstellungen bleiben unveraendert. *NONE Es werden keine Trace-Saetze mehr ausgegeben, die Trace-Datei wird geschlossen. *ALL Es werden alle Traces erzeugt. ATTACH-DETACH Funktionen, die das An- und Abmelden an CMX betreffen. NAME-ADDRESS Aufrufe an die Namens- und Adressverwaltung. CONNECT Funktionen, die Verbindungen aufbauen, abbauen oder umlenken. TRANSPORT Aufrufe zum Senden und Empfangen von Normal- und Vorrangdaten. OTHERS Funktionen, die nicht zu einer der obigen Gruppen gehoeren. INTERN Die Aufrufe von BS2000-Funktionen werden mit Uebergabeparame- tern und Returncode als Trace-Saetze ausgegeben. Aenderungen der Trace-Einstellung werden erst nach der naechsten Aktion der entsprechenden Anwendungen wirksam. A Seite 8 EXTERNAL-USER=... Einstellungen der Trace-Informationen eines externen Anwenders EXTERNAL-USER=*NONE ----- Keine Traceeinstellungen fuer externen Anwender angegeben EXTERNAL-USER=*USER-ATTRIBUTES (...) Traceeinstellungen fuer externen Anwender angegeben NAME-OF-USER=< alphanum-name 1..8 > Der externe Anwender gibt hier einen bis zu 8 alphanumeri- schen Zeichen langen Namen an. Dieser Name wird zur Bildung des Dateinamens der Trace-Datei herangezogen. Ausserdem dient er als TRACE-Name fuer TEDDY (LIST / TRACE). Der Name wird auch verwendet, um zu erkennen, ob die betreffende Komponente auch wirklich gemeint ist. TRACE-INFORMATION= / In diesen 30 Zeichen (C-String oder X-String) langen Bereich traegt der externe Anwender seine Trace-Informationen ein. Fuer den Inhalt dieser Informationen ist der Anwender selbst verantwortlich, das Kommando /SET-COMMUNICATION-TRACE reicht diese Informationen lediglich weiter ohne sie auszuwerten. Kommando-Returncodes SC2 SC1 Maincode Bedeutung --------------------------------------------------------------------- 0 0 CMD0001 NO ERROR 0 32 YDT1001 siehe Meldung YDT1001 0 1 YDT1002 siehe Meldung YDT1002 0 64 YDT1003 siehe Meldung YDT1003 0 64 YDT1004 siehe Meldung YDT1004 0 1 YDT1005 siehe Meldung YDT1005 0 1 YDT1006 siehe Meldung YDT1006 0 1 YDT1007 siehe Meldung YDT1007 0 1 YDT1008 siehe Meldung YDT1008 Die Meldungen finden Sie in Abschnitt 1.2.5.2. A Seite 9 1.2.4 Sicherheitsrelevante Einschraenkungen Um sicherzustellen, dass ein "normaler" Benutzer die Trace-Einstel- lungen fremder oder aller Userid's nicht aendern kann, wird bereits bei der Kommandoauswertung eine dahingehende Pruefung durchgefuehrt. Ein Benutzer kann daher nur Aenderungen innerhalb seiner eigenen Userid durchfuehren. Aenderungen ueber Userid-Grenzen hinaus kann nur ein Benutzer mit TSOS- oder NET-ADMINISTRATION-Privileg. In der nachfolgenden Tabelle sind die Moeglichkeiten aus dem SELECT- Parameter naeher angefuehrt: ja: diese Kombination ist erlaubt nein: diese Kombination ist nicht erlaubt, es wird eine dement- sprechende Meldung ausgegeben. Benutzer-Userid TSOS -------------------------------------------------------------------- SELECT=*TSN(TSN=*OWN) ja ja SELECT=*TSN(TSN=tsn) ja, falls es die eigene TSN ja ist, oder die Task unter der eigenen Userid laeuft SELECT=*TSN(TSN=*ALL) nein ja SELECT=*UID(UID=userid) ja, falls es sich um die eigene Userid handelt ja SELECT=*UID(UID=*OWN) ja ja A Seite 10 1.2.5 Reaktionen des Kommandos 1.2.5.1 Meldungsausgabe Laeuft das Kommando /SET-COMMUNICATION-TRACE erfolgreich ab, wird eine positive Meldung ausgegeben, sowie Meldungen, die ueber ein erfolgtes Weiterleiten der Trace-Parameter der betreffenden Komponenten infor- mieren. Nach der Meldungsausgabe verzweigt das Kommando wieder in den Schraegstrichmodus des BS2000. Warnungen und Fehlermeldungen werden ausgegeben, wenn es nicht moeg- lich ist, den BCAM-Aufruf abzusetzen oder wenn ein Returncode (ungleich 0) zurueckgeliefert wird. Bleiben alle Parameter auf ihren Defaultwerten (also keine Aenderungs- wuensche), wird der BCAM-Aufruf nicht abgesetzt und eine entsprechende Warnung ausgegeben. A Seite 11 1.2.5.2 Meldungen YDT0000 SET-COMM-TRACE ERFOLGREICH AUSGEFUEHRT FUER (&&00) YDT0001 SET-COMM-TRACE HAT KEINE AUSWIRKUNG YDT0002 TRACEKRITERIEN FUER KOMPONENTE (&&00) GEAENDERT YDT0003 TRACEKRITERIEN FUER EXTERNEN ANWENDER (&&00) GEAENDERT YDT1001 BCAM-FEHLER: (&&00) BEI T-DIAGDATA-SEND YDT1002 FEHLER BEI PARAMETER (&&00) YDT1003 ANGABE EINER FREMDEN TSN ((&&00)) IST NICHT MOEGLICH YDT1004 ANGABE EINER FREMDEN UID ((&&00)) IST NICHT MOEGLICH YDT1005 NUR SCHLUESSELWORT (&&00) IST ERLAUBT YDT1006 KEINE EVENTGRUPPE FUER (&&00) GEFUNDEN YDT1007 KEIN TASK FUER TSN (&&00) GEFUNDEN YDT1008 USERID (&&00) EXISTIERT NICHT A Seite 12 1.3 Trace-Modul 1.3.1 Funktion Der Trace-Modul wird zu den jeweiligen Komponenten dazugebunden, die die Trace-Funktionalitaet nutzen wollen. Der Modul legt die Trace- Datei an, oeffnet und schliesst diese und schreibt die Trace-Saetze. Er ist in CMX ab BCAM V14 schon eingebunden. Der Trace-Modul ist mit dem Namen YDTLNK abgelegt. Der Modul existiert fuer TU und TPR getrennt. Hinzu kommt der Modul YDTTOOL fuer die von YDTLNK verwendeten Assemblerroutinen. Diese Module befinden sich in folgenden Bibliotheken: Fuer mit C-Compiler >= V2.0 und CRTE V2.0 erstellte Anwendungen: fuer TU in SYSLIB.DCM-DIAG.010.TU fuer TPR in SYSLIB.DCM.DIAG.010.TP Fuer mit C-Compiler >= V2.0 und CRTE V1.0 erstellte Anwendungen befindet sich der Modul YDTLNK in SYSLIB.DCM-DIAG.010.COMPV2. Fuer mit C-Compiler V1.0 erstellte Anwendungen: fuer TU in SYSLIB.DCM-DIAG.010.COMPV1 Fuer Anwendungen auf RISC: fuer TU in SRMLIB.DCM-DIAG.010.TU fuer TPR in SRMLIB.DCM-DIAG.010.TP A Seite 13 1.3.2 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, ein Fortschreiben in bestehenden Dateien geschieht nicht. Der Name der Trace-Datei hat folgenden Aufbau: <$userid>.SYS.DIA... Die Datei wird unter jener Kennung angelegt, unter welcher die Task laeuft. ist der Name des Anwenders (SOCKETS, CMX, DPRINT,.....) TSN des Anwenders um den Namen der Trace-Datei eindeutig zu halten, wird eine laufende Nummer angehaengt. Die Dateiattribute der Trace-Datei sind: FCBTYPE=SAM, RECFORM=V, BLKCTRL=PAMKEY, BLKSIZE=(STD,14) A Seite 14 1.3.3 Beschreibung der Schnittstelle Der Trace-Modul bietet vier Funktionen zum Bearbeiten einer Trace- Datei: - TraceFileOpen Oeffnen einer Trace-Datei - TraceFileClose Schliessen einer Trace-Datei - AllTraceFileClose Schliessen aller offenen Trace-Dateien - TraceFileWriteRecord Schreiben eines Trace-Satzes in die Trace- Datei Die Beschreibung der Funktionen ist im C++-Include YDTLNK.H enthalten. Dieses befindet sich in der Bibliothek SYSLIB.DCM-DIAG.010. A Seite 15 1.3.4 Beispiel /* Beispiel fuer eine Anwendung mit den Funktionsaufrufen des Trace-Moduls */ #include "stdio.h" #include "stdlib.h" #include "string.h" #include "ydtlnk.h" void main () { /* ----------------------- Werte fuer das Testbeispiel ------------ -------------------- */ int ret; int handle; *) char *identifier = "S"; char *typ = "TY"; char *target = "TA"; char *TraceInfo = "DAS-IST-DIE-TRACEINFO"; char *version = "V14"; char *KompNam = "TESTPROG"; *) internes Kennzeichen einer Tracedatei; wird von der Trace- funktion geliefert A Seite 16 /* -------------------- Trace-Datei eroeffnen --------------------- ------------ */ 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; } . . . A Seite 17 /* ------------------------- Trace-Satz schreiben ----------------- ----------- */ if ((ret = TraceFileWriteRecord(handle,identifier, typ,target,TraceInfo)) == RECORD_WRITE_SUCCESSFULLY) printf ("write succeeded\n"); else { printf ("write failed:%d\n", ret); goto fehler; } . . . A Seite 18 /* -----------------------------Trace-Datei schliessen -------------- -------------- */ 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"); } A Seite 19 1.3.5 Fehlerbehandlung Es wird bei jedem Funktionsaufruf des Trace-Moduls ein Returncode zurueckgeliefert (auch im OK-Fall). Die Auflistung der moeglichen Return-Codes ist im Include YDTLNK.H (Beschreibung der Schnittstelle) enthalten. A Seite 20 1.4 Komponenten der Datenkommunikation 1.4.1 CMX CMX ist ein Transportzugriffssystem. Zweck von CMX ist es, Anwendungen unabhaengig vom zugrundeliegenden Kopplungsmechanismus erstellen zu koennen. Die Unterschiede in den Kopplungsmechanismen, wie Groesse der Dateneinheit, die uebertragen werden kann, Format der Transportadresse der Partneranwendung und Format der Adresse im lokalen System sind dabei an der Schnittstelle nicht sichtbar, sie werden ausserhalb der Anwendung verwaltet. CMX stellt eine einheitliche Schnittstelle fuer die Dienste des Transportsystems zur Verfuegung. CMX ist sowohl in TU als auch in TPR verfuegbar und setzt auf BCAM auf. Es ist eine Unterprogrammschnittstelle und wird als Komponente zur Anwendung hinzugebunden. Bisher ist fuer CMX auf BS2000 keine Diagnosemoeglichkeit vorhanden. CMX ermoeglicht es, Anwendungen zu erstellen, bei denen Verbindungen eines TSAP von verschiedenen Tasks bearbeitet werden koennen. Die daran beteiligten Tasks sind zu einer CMX-Anwendung zusammengeschlos- sen. Eine Task kann hierbei auch mehreren CMX-Anwendungen zugeordnet sein. CMX ermoeglicht es dem Programm, Verbindungen an andere Tasks der CMX-Anwendung weiterzugeben. A Seite 21 1.4.1.1 Steuerung des CMX-Trace Der CMX-Trace kann durch die folgenden Mechanismen gesteuert werden: - Kommando /SET-COMMUNICATION-TRACE - Beendigung der CMX-Anwendung A Seite 22 Steuerung ueber /SET-COMMUNICATION-TRACE Alle durch das Kommando ausgewaehlten Tasks werden von BCAM benachrichtigt. Einstellungen fuer CMX-Anwendungen werden an die Anwender weitergereicht. Wie bereits oben beschrieben, kann eine CMX-Anwendung mehrere Tasks verwenden. Die erste Task, die sich an einer CMX-Anwendung beteiligt, oeffnet einen TSAP, weitere Tasks, die sich an der CMX-Anwendung beteiligen, haengen sich an diesen TSAP an. BCAM meldet eine Aenderung der Trace-Kriterien somit immer an alle beteiligten Tasks. A Seite 23 Abhaengig von der Aenderung fuehrt CMX folgende Aktionen durch: - Keine Aenderung Es sind keine Aktionen notwendig. - Erste Aktivierung Unabhaengig vom Umfang der Aktivierung werden folgende Aktionen durchgefuehrt: A) Oeffnen der Trace-Datei: Hierzu ist die Funktion TraceFileOpen() mit den Parametern (Handle, "CMX", CMXVersion) aufzurufen. B) Schreiben des 1.Trace-Satzes mit: 1. Trace-Kriterien 2. fuer alle aktiven CMX-Anwendungen der Task: Globaler Name, lokaler Name, Transportadresse - Aenderung des Umfanges Hier wird ebenfalls ein Trace-Satz geschrieben und zwar mit den neuen Trace-Kriterien als Inhalt. A Seite 24 Beendigung der CMX-Anwendung Vor der Beendigung der CMX-Anwendung hat sich diese bei CMX abzumel- den. Dies kann auch dann erfolgen, wenn weitere Dienste von CMX nicht mehr verwendet werden, aber das Programm weiterlaeuft. Aufgabe von CMX ist es nun, gegebenfalls seine eigene Trace-Datei zu schliessen. CMX schaut bei jeder Abmeldung mittels t_detach(), ob die Task noch an anderen CMX-Anwendungen beteiligt ist. Ist das der Fall, so sind keine Aktionen notwendig. Meldet sich die Task jedoch von der letzten CMX-Anwendung ab, so schliesst CMX die Trace-Datei, falls sie geoeff- net war. Der CMX-Anwender sollte am Ende seines Programms t_trace(0,"CMX",NULL) aufrufen, damit der im Buffer enthaltene, aber noch nicht geschriebene Teil der Trace-Daten in die Datei geschrieben und diese ordnungsge- maess geschlossen wird. A Seite 25 1.4.1.2 Trace-Kriterien Jeder von CMX erzeugte Trace-Satz ist einer Gruppe zugeordnet. Der Anwender kann jene Gruppe angeben, deren Trace-Saetze er protokol- liert haben will. Zur Mitteilung der Trace-Kriterien an CMX steht das BS2000-Kommando /SET-COMMUNICATION-TRACE zur Verfuegung. Es kann/ koennen eine Gruppe oder mehrere Gruppen angegeben werden. Beschreibung der Gruppen: siehe 1.2.3 A Seite 26 1.4.1.3 Steuerung des Trace der CMX-Anwendung im Hinblick auf externe Anwender Die internen Algorithmen einer externen Anwendung zum Verarbeiten der empfangenen Trace-Informationen ist Sache des externen Anwenders und werden hier nicht beschrieben. Diese Trace-Informationen, die ein externer Anwender beim Kommando /SET-COMMUNICATION-TRACE angibt, werden von DCM-DIAG nicht analysiert oder verarbeitet, sie werden lediglich weitergeleitet. Anwender muessen CMX mit dem neuen Aufruf t_trace() mitteilen, dass sie ueber Trace-Einstellungen benachrichtigt werden wollen. Der Aufruf hat drei Parameter: - int mode 0=off, 1=on - char *type Name des Anwenders - char *info Adresse eines Bereichs, in den die Trace- Einstellungen uebertragen werden. Nach dem Absetzen des Kommandos /SET-COMMUNICATION-TRACE werden die Einstellungen in den Anwenderbereich uebertragen, falls der Anwender benachrichtigt werden will. Beim naechsten t_event() wird der Aufruf mit dem neuen Event T_DIAGEVENT beendet. Der Anwender muss diesen Bereich dann auswerten und entsprechend reagieren. Dieser Bereich ist im C-Include ydtglob.h beschrieben (ydt struct_usr_info). A Seite 27 1.5 Darstellung der Trace-Datei 1.5.1 Headersatz Der Headersatz ist der erste Satz in einer Trace-Datei. Er beinhaltet Informationen, die fuer die gesamte Trace-Datei gelten. Das Format enthaelt fuer jede Komponente ein Versionsfeld, das zu versorgen ist. Die Felder CMX-Version, Socket-Version, FTP-Version, Telnet-Version und Ext-Version enthalten die Versionsnummern der Komponenten als Zeichenkette mit fixer Laenge ohne abschliessende binaere 0 mit Blanks als Fuellzeichen. Da die hier erwaehnten Komponenten keine gemeinsame Trace-Datei verwenden, sind nur zwei Felder auszufuellen. Erstens die Satzlaenge (entspricht der Strukturgroesse) und zweitens die Version der Komponente, die Trace-Saetze in die Datei schreibt, die verbleiben- den Eintraege werden mit binaer 0 versorgt. --------------------------------------------------------------------- | Distanz | Laenge in Byte | Bedeutung | | (hex) | (dez) | | --------------------------------------------------------------------- | 0 | 2 | Laenge des Header-Satzes | --------------------------------------------------------------------- | 2 | 2 | reserviert fuer DMS | --------------------------------------------------------------------- | 4 | 40 | diese 10 Worte sind reserviert | | | | fuer BCAM | --------------------------------------------------------------------- | 2C | 4 | CMX-Version | --------------------------------------------------------------------- | 30 | 4 | Socket-Version | --------------------------------------------------------------------- | 34 | 4 | FTP-Version | --------------------------------------------------------------------- | 38 | 4 | Telnet-Version | --------------------------------------------------------------------- | 3C | 8 | Name des externen Anwenders | --------------------------------------------------------------------- | 44 | 4 | Version des externen Anwenders | --------------------------------------------------------------------- A Seite 28 1.5.2 Trace-Datei-Satz Die Trace-Dateisaetze sind jene Saetze der Trace-Datei, die auf den ersten Satz folgen. Die Verwendung von Trace-Dateisaetzen wird von TEDDY vorgeschrieben. Fuer die hier beschriebenen Komponenten sind folgende Felder relevant: Die Groesse des Puffers enthaelt die gesamte Satzlaenge (also die Summe der Laengen der einzelnen Trace-Saetze und die Laenge des Trace- Datei-Satzes). Dieses Feld wird von DMS ausgewertet. Die Maximallaenge eines Trace-Dateisatzes betraegt 650 Byte. Das Feld Trace-Name wird mit SOCKETS, FTP, TELNET, CMX oder dem Namen eines externen Anwenders versorgt, wobei mit Blanks auf 24 Zeichen ergaenzt wird. Die restlichen Felder werden mit binaer 0 versorgt. --------------------------------------------------------------------- | Distanz | Laenge in Byte | Bedeutung | | (hex) | (dez) | | --------------------------------------------------------------------- | 0 | 2 | Groesse des Puffers | --------------------------------------------------------------------- | 2 | 2 | reserviert fuer DMS | --------------------------------------------------------------------- . . . . . . . . . --------------------------------------------------------------------- | 20 | 24 | Trace-Name | --------------------------------------------------------------------- | 38 | | Beginn der Trace-Saetze | --------------------------------------------------------------------- A Seite 29 1.5.3 Trace-Satz Trace-Saetze sind jene Saetze, die nach den Trace-Dateisaetzen ver- packt sind. Sie sind fuer DMS nicht sichtbar und koennen nicht einzeln in die Datei geschrieben werden. Ihr Inhalt ist folgendermassen gegliedert. Am Beginn steht ein Header mit bestimmten fixen Informationen, die von TEDDY erwartet werden. Anschliessend folgen die Daten der Komponenten. Diese koennen einen beliebigen Aufbau haben. Allgemeiner Aufbau: Distanz Laenge in Bedeutung (hex) Byte (dez) --------------------------------------------------------------------- 0 *) 2 Satz-Laenge --------------------------------------------------------------------- 2 2 reserviert fuer DMS (aus Komatibilitaetsgruenden, DMS greift hier nicht zu) --------------------------------------------------------------------- 4 6 Zeit-Stempel --------------------------------------------------------------------- A 1 Identifier. Enthaelt ein Zeichen, welches beim Funktionsaufruf "TraceFileWriteRecord" explizit mitgegeben wird und zwar ueber alle Komponenten, die Traces erzeugen. Vorbelegt sind: S fuer SOCKETS, F fuer FTP, T fuer Telnet, C fuer CMX und X fuer einen externen Anwender --------------------------------------------------------------------- B 1 Markierung, wird von YDTLNK immer mit ':' (Doppelpunkt) versorgt --------------------------------------------------------------------- C 2 Typ kennzeichnet: - den Aufruf einer Funktion - den Ruecksprung von einer Funktion - ein Signal - Daten --------------------------------------------------------------------- E 2 Ziel kennzeichnet: - Funktionsaufruf oder Signal von einer anderen Komponente an die Komponente - Funktionsaufruf oder Signal von der Komponente an eine andere Komponente --------------------------------------------------------------------- 10 Beginn der Trace-Information --------------------------------------------------------------------- *) der erste Trace-Satz beginnt innerhalb des Blocks auf der Distanz X'38' A Seite 30 1.5.3.1 Layout des Trace-Satzes fuer CMX Distanz Laenge in Bedeutung (hex) Byte (dez) --------------------------------------------------------------------- 0 2 Satz-Laenge ---------------------------------------------------------------------- 2 2 reserviert fuer DMS (aus Kompatibilitaetsgruenden, DMS greift hier nicht zu) --------------------------------------------------------------------- 4 6 Zeit-Stempel --------------------------------------------------------------------- A 1 "C" --------------------------------------------------------------------- B 1 ":" --------------------------------------------------------------------- C (0) 2 "C-" : Aufruf einer Funktion "R-" : Ruecksprung von einer Funktion "E" : Signal (Event) "D" : Daten --------------------------------------------------------------------- E (2) 2 "I:" : Funktionsaufruf oder Signal von einer anderen Komponente an die Komponente "O:" : Funktionsaufruf oder Signal von der Komponente an eine andere Komponente "E:" : Fehler bei Rueckkehr aus einer Funktion ---------------------------------------------------------------------- 10 (4) 1 "C" : CMX-Aufruf "I" : intern ---------------------------------------------------------------------- 11 (5) 3 Funktion (siehe Tabellen in den entspr. Kapiteln) ---------------------------------------------------------------------- 14 (8) n Parameter, die beim Aufruf mitgegeben wurden --------------------------------------------------------------------- A Seite 31 ATTACH-DETACH Die Trace-Punkte der CMX-Funktionen sind paarweise zu verstehen: Einerseits der Aufruf der Funktion, andererseits die Rueckkehr aus der Funktion (nachfolgende Beispiele). Das gilt generell fuer alle Funktionen. Beispiel: Aufruf der Funktion t_attach() 0 2 4 5 8 --------------------------------------------------------------------- C- | I: | C | ATT | --------------------------------------------------------------------- (1) Beispiel: Rueckkehr aus der Funktion t_attach() 0 2 4 5 8 --------------------------------------------------------------------- R- | | C | ATT | --------------------------------------------------------------------- (2) (1) (1) interne Routine : Interne Routine Bedeutung ----------------------------------------- ATT t_attach - Aufruf ATT t_attach - Rueckkehr DET t_detach - Aufruf DET t_detach - Rueckkehr (2) "E:" bei Rueckkehr mit Fehler A Seite 32 NAME-ADDRESS Beispiel: Aufruf der Funktion t_getaddr 0 2 4 5 8 --------------------------------------------------------------------- C- | I: | C | GAD | --------------------------------------------------------------------- (1) (1) interne Routine : Interne Routine Bedeutung ------------------------------------------ GAD t_getaddr - Aufruf GAD t_getaddr - Rueckkehr GLO t_getloc - Aufruf GLO t_getloc - Rueckkehr GNA t_getname - Aufruf GNA t_getname - Rueckkehr GTS t_gettsel - Aufruf GTS t_gettsel - Rueckkehr A Seite 33 CONNECT Beispiel: Aufruf der Funktion t_concf 0 2 4 5 8 --------------------------------------------------------------------- C- | I: | C | CCF | --------------------------------------------------------------------- (1) (1) interne Routine : Interne Routine Bedeutung ---------------------------------------- CCF t_concf - Aufruf CCF t_concf - Rueckkehr CIN t_conin - Aufruf CIN t_conin - Rueckkehr CON t_conrq - Aufruf CON t_conrq - Rueckkehr CRS t_conrs - Aufruf CRS t_conrs - Rueckkehr DIS t_disin - Aufruf DIS t_disin - Rueckkehr DIR t_disrq - Aufruf DIR t_disrq - Rueckkehr RED t_redin - Aufruf RED t_redin - Rueckkehr RER t_redrq - Aufruf RER t_redrq - Rueckkehr A Seite 34 TRANSPORT Beispiel: Aufruf der Funktion t_datago 0 2 4 5 8 --------------------------------------------------------------------- C- | I: | C | DGO | --------------------------------------------------------------------- (1) (1) interne Routine : Interne Routine Bedeutung ------------------------------------------ DGO t_datago - Aufruf DGO t_datago - Rueckkehr DAI t_datain - Aufruf DAI t_datain - Rueckkehr DAR t_datarq - Aufruf DAR t_datarq - Rueckkehr DAS t_datastop - Aufruf DAS t_datastop - Rueckkehr VDI t_vdatain - Aufruf VDI t_vdatain - Rueckkehr VDR t_vdatarq - Aufruf VDR t_vdatarq - Rueckkehr XDG t_xdatgo - Aufruf XDG t_xdatgo - Rueckkehr XDI t_xdatin - Aufruf XDI t_xdatin - Rueckkehr XDR t_xdatrq - Aufruf XDR t_xdatrq - Rueckkehr XDS t_xdatstop - Aufruf XDS t_xdatstop - Rueckkehr A Seite 35 OTHERS Beispiel: Aufruf der Funktion t_error 0 2 4 5 8 --------------------------------------------------------------------- C- | I: | C | ERR | --------------------------------------------------------------------- (1) (1) interne Routine : Interne Routine Bedeutung ------------------------------------------------- ERR t_error - Aufruf ERR t_error - Rueckkehr EVE t_event - Aufruf EVE t_event - Rueckkehr INF t_info - Aufruf INF t_info - Rueckkehr PER t_perror - Aufruf PER t_perror - Rueckkehr PRE t_preason - Aufruf PRE t_preason - Rueckkehr SER t_strerror - Aufruf SER t_strerror - Rueckkehr SRE t_strreason - Aufruf SRE t_strreason - Rueckkehr WAK t_wake - Aufruf WAK t_wake - Rueckkehr A Seite 36 Moegliche Events: 01 TSAP-TERMINATION-IN 02 REDIRECT-IN 03 CONN-REQ-IN 04 CONN-RSP-IN 05 DISCON-IN 06 DISCON-REQ-IN 07 DATA-IN 08 EXPDATA-IN 09 UNITDATA-IN 10 DATA-GO-IN 11 EXPDATA-GO-IN 12 TRANSPORT-ACK-IN 13 XAF-MSG-IN 14 XAF-RECONF-END-IN 15 ERROR-REPORT-IN 16 DIAGDATA A Seite 37 INTERN Beispiel: Aufruf der Funktion check_name 0 2 4 5 8 --------------------------------------------------------------------- C- | I: | I | CHK | chain" Seite 100: Beim letzten Satz in der Erklaerung von "opt" (t_disin) muss das Wort "Typ" wie folgt eingefuegt werden: "..., sie haengt vom Typ der zugrundeliegenden Transportverbindung ab." A Seite 41 2.4 Unterschiede von CMX(BS2000) zu CMX(SINIX) (Ergaenzung zm Handbuch auf Seite 152) Nach dem ersten Absatz ". Ein Wartezustand beim t_event() ... ist folgender Abschnitt hinzuzufuegen: . Ein t_event()-Aufruf ist auch ohne t_attach() erlaubt. A Seite 42 2.5 CMX-Fehlermeldungen (verschiedene Ergaenzungen und Korrekturen) Seite 154: Folgender Abschnitt mit Bild ist hinzuzufuegen: "Abbildung des BCAM-Returncodes auf den CMX-Returnwert: BCAM-Returncode CMX-Returnwert 31 24 16 8 0 31 24 16 8 0 ------------------------- ------------------------- | SC2 | SC1 | MC2 | MC1 | | | | | | ------------------------- ------------------------- | | | ^ ^ ^ ^ | | | | | | | | | ------------- | | CMX- | ------------------------- | Fehler- ------------------------------------------- wert Die Returncodes sind nicht als garantierte Schnittstelle freigegeben und sollen nur als Diagnoseinformationen betrachtet werden. Sie duerfen nicht durch das CMX- Anwendungsprogramm interpretiert werden." Seite 155: Bei dem Wert 255 muss "Bedeutung" ergaenzt werden durch: "t_error() liefert den Returncode des BCAM-Aufrufs. Dieser wird wie auf oben beschrieben auf den CMX- Returnwert abgebildet." Seite 157 und 160: Der BCAM-Returncode "10 00 00 20" tritt bei T_APPLICATION auf, nicht bei T_NOCCP. Seite 159: Der BCAM-Returncode "0C 00 01 1C" muss durch den Returncode "0C 00 02 1C" ersetzt werden. Seite 162: Vor "60 00 00 24" ist ein neuer Returncode einzufuegen: T_SEQUENCE 5C 00 00 24 Der Austausch von Expedited Data wurde fuer diese Verbindung nicht vereinbart.