SYSRDC Utility

Mit dem Dienstprogramm ("Utility") SYSRDC können Sie Monitoring- und Abrechnungsdaten über den internen Prozessablauf innerhalb einer Natural-Anwendung aufzeichnen und für die Auswertung von Natural-Session-Aktivitäten in externen oder Natural-Programmen verwenden. Die Daten werden bei innerhalb von Natural auftretenden Ereignissen gesammelt

Folgende Themen werden behandelt:

• Funktionsbausteine von SYSRDC

• Datenerfassung auslösende Ereignisse

• Gesammelte Daten

• Natural Data Collector aktivieren und konfigurieren

• Trace Recording-Funktion

• User Exits für externes Monitoring/Accounting

• Aufruf des CMRDC-Interface

• Beispiel-Programme

Verwandte Themen:

• Profiler Utility, ein menügesteuertes Werkzeug zum Erzeugen und Auflisten von Trace-Datensätzen

• RDC - Konfiguration des Natural Data Collector in der Profilparameter-Dokumentation.

Funktionsbausteine von SYSRDC

Im Folgenden werden die Funktionsbausteine der SYSRDC Utility beschrieben, mit denen Daten gesammelt und zur Weiterverarbeitung zur Verfügung gestellt werden können.

• Natural Data Collector als Teil des Natural-Nukleus:
  Sammelt Daten und steuert die Datenaufzeichnung im Natural Data Collector Buffer.

• User Exits:
  Übergibt Daten an externe Monitoring- und Abrechnungsprogramme.

• CMRDC Interface:
  Wertet Daten in einem Natural-Programm für die aktuelle Natural-Session aus.

Datenerfassung auslösende Ereignisse

Ereignisse (Events) geben Aktivitäten innerhalb von Natural an. Die folgende Tabelle enthält eine Liste der Ereignisse, bei denen Daten innerhalb von Natural gesammelt werden, und der zur Verfügung stehenden Ereignistypen.

Jedem Ereignistyp ist ein ein- oder zweistelliger Code zugeordnet, wobei der erste Buchstabe die Gruppe des Ereignisses und der zweite Buchstabe den Untertyp darstellt, zum Beispiel:

Ereignistyp PL

P steht für die Ereignisgruppe program und L für den Untertyp load.

Um ein internes Trace-Aufruf-Ereignis zu aktivieren:

1. Setzen Sie den Natural-Profilparameter ITRACE=ON.

2. Definieren Sie die Natural-Komponenten, die interne Trace-Aufrufe absetzen sollen:

   • Benutzen Sie dazu das Makro NTTRACE im Natural-Parametermodul.

     Oder setzen Sie den dynamischen Natural-Profilparameter TRACE.

Um ein Natural-Statement-Ereignis zu aktivieren:

• Setzen Sie die Natural-Profilparameter ITRACE=ON und TRACE=NATPROX.

Informationen zu den oben genannten Profilparametern und dem Parameter-Makro siehe Parameter-Referenz-Dokumentation.

Gesammelte Daten

Die Daten, die der Natural Data Collector sammelt, werden in den folgenden Abschnitten beschrieben:

Informationen zum Layout der Daten können Sie dem Natural Source Dataset (Datei) NAMRDC oder dem lokalen Datenbereich RDCDATA entnehmen, der sich in der Natural-System-Library SYSRDC befindet.

Die gesammelten Daten können in zwei Kategorien unterteilt werden: allgemeine und ereignisspezifische Daten:

• Allgemeine Daten

• Ereignisspezifische Daten

Allgemeine Daten

Die folgenden allgemeinen Daten werden bei jedem Ereignis gesammelt:

• Software AG-Produktname

• Produktversion

• Betriebssystem

• TP-Monitor

• Laufmodi, z.B. Adressierungs- und Residenzmodus des Natural-Nukleus und des Natural Buffer Pool

• TP-Benutzername oder Batch-Jobname

• TP-Terminalkennung (ID)

• Aktuelle Natural-Benutzerkennung (ID)

• Aktuelle Natural Security-Benutzergruppenkennung (ID)

• Aktuelle Natural-Library

• Aktuelles Natural-Programm

• Aktuelle Programmebene

• Zeilennummer des zurzeit ausgeführten Programm-Statements

• Session CPU Time (gleiches Format wie *CPU-TIME)

Ereignisspezifische Daten

Die folgenden Daten werden nur bei den folgenden Ereignissen gesammelt:

Natural Data Collector aktivieren und konfigurieren

Der Natural Data Collector wird mit Hilfe des Natural-Profilparameters RDC aktiviert und konfiguriert (siehe RDC - Konfiguration des Natural Data Collector in der Parameter-Referenz-Dokumentation).

Die Standardeinstellung ist RDC=OFF. Das bedeutet, der Natural Data Collector ist deaktiviert und die Trace Recording-Funktion muss separat aktiviert werden. Um die Einstellungen zu ändern, können Sie im Natural-Parametermodul das Makro NTRDC des Profilparameters RDC benutzen (siehe RDC - Konfiguration des Natural Data Collector in der Parameter-Referenz-Dokumentation).

Folgende Werte und Schlüsselwort-Parameter stehen zur Verfügung:

Trace Recording-Funktion

Die gesammelten Ereignisdaten werden immer an User Exits geliefert, die, wie an anderer Stelle beschrieben, von externen Monitoring/Accounting-Programmen benutzt werden sollen. Sie können unabhängig von den User Exits die Ereignisdaten der aktuellen Natural Session im Natural Data Collector-Puffer aufzeichnen. Dies kann für Testzwecke nützlich sein. In diesem Abschnitt wird das Aufzeichnen von Daten im Natural Data Collector-Puffer als Trace Recording-Funktion bezeichnet.

Wenn Sie eine Natural Session starten, ist die Trace-Recording-Funktion standardmäßig nicht aktiv. Damit die Trace-Recording-Funktion beim Start einer Session (ohne Trace-Aufzeichnung) aktiviert wird, können Sie den Natural-Profilparameter RDC auf ON setzen, siehe auch RDC - Konfiguration des Natural Data Collector. Um außerdem die Trace-Aufzeichnung zu aktivieren, müssen Sie den RDC-Subparameter SIZE auf einen Wert größer als 2 setzen.

Sie können auch eine der folgenden Option nutzen, um die Trace-Aufzeichnung zu starten:

• Systemkommando RDC ON

• Terminalkommando %<RDC+

• Natural-Statement CALL 'CMRDC' 'S'

Anmerkungen:

1. Der Natural Data Collector-Puffer wird im Wrap-Around-Modus gefüllt, d. h. der älteste Datensatz wird überschrieben, wenn der Puffer voll wird. Am Ende der Sitzung wird der Inhalt des Puffers gelöscht.
2. Die Trace-Aufzeichnung umfasst standardmäßig nicht die Systemdatei FNAT. Um auch die Systemdatei FNAT in die Aufzeichnung einzubeziehen, müssen Sie den RDC-Subparameter FNAT=ON setzen.

Die Trace-Aufzeichnung wird beendet durch:

• Systemkommando RDC OFF

• Terminalkommando %<RDC-

• Natural-Statement CALL 'CMRDC' 'P'

• Beenden einer Session

User Exits für externes Monitoring/Accounting

Die Ereignisdaten können an externe Monitoring- und Accounting-Programme zur Auswertung der Aktivitäten in Natural Sessions übergeben werden. Dies wird erreicht mit den User Exits und den mitgelieferten Beispielen für User-Exit-Programme. User-Exit-Programme sind in Assembler geschrieben.

Der Natural Data Collector unterstützt eine beliebige Anzahl an User Exits. User Exits können mit dem Natural-Profilparameter RDCEXIT definiert werden (siehe Parameter-Referenz-Dokumentation). Mit jedem User Exit kann ein externes Monitoring- und Accounting-Programm verknüpft werden.

Es sind drei vordefinierte Exit-Namen vorhanden: RDCEX1, RDCEX2 and RDCEX3. Wenn Sie einen dieser Namen als Einstiegspunkt für Ihren Exit (der mit dem Natural-Nukleus verlinkt ist) benutzen, ist der Natural-Profilparameter RDCEXIT nicht erforderlich.

Bei jedem der unter Datenerfassung auslösende Ereignisse aufgelisteten Ereignisse übernehmen die User Exits die Steuerung. Dazu benutzen sie die in der folgenden Tabelle aufgeführten Standard Linkage-Aufrufkonventionen:

Ein User-Exit-Programm muss die gleichen Attribute wie Natural haben, d.h., es muss den gleichen Adressierungsmodus haben und muss ablaufinvariant (reentrant) sein. Es muss mit dem Natural-Nukleus gemäß den Konventionen für statisch verlinkte Nicht-Natural-Programme verlinkt sein. Siehe auch Natural-Profilparameter CSTATIC und RCA in der Parameter-Referenz-Dokumentation.

Standardmäßig wird für jeden User Exit ein 400-Byte großer exklusiver Arbeitsbereich (pro Session) zur Verfügung gestellt (das Feld RDCGWRKA). Sollte für einen User Exit ein größerer Arbeitsbereich erforderlich sein, kann er im Natural-Profilparameter RDCEXIT (s. Parameter-Referenz-Dokumentation) nach dem Namen des User Exit angegeben werden. Die Übergabe der Länge des Arbeitsbereichs an die User Exits erfolgt im Feld RDCGWRKL. Sie kann zur Verifizierung genutzt werden. Der Standort dieses Arbeitsbereichs kann sich aufgrund einer Natural-Standortverlagerung ändern, sein Inhalt bleibt jedoch erhalten.

In TP-Monitor-Umgebungen wird die TP-Ankeradresse geliefert (das Feld RDCGANCH), z.B. die CSA-Adresse unter CICS. Sie kann benutzt werden, um Zugang zu Systeminformationen zu erhalten.

Falls während der Ausführung eines User Exit-Programms ein Program Check auftritt, wird die weitere Datenerfassung für den Rest der Session deaktiviert, um rekursive Abbruchsituationen zu vermeiden.

Anschließend werden folgende Themen behandelt:

• Rückgabecodes

• Beispiele für User-Exit-Programme

Rückgabecodes

Rückgabecodes ungleich Null werden nur für zwei Ereignisse unterstützt:

• Vor einem Datenbankaufruf, bei dem das Register 15 einen Adabas-Antwortcode enthalten kann, der im Steuerblock gespeichert ist. Der Adabas-Aufruf wird nicht ausgeführt.

• Beim Programmstart, wobei Register 15 einen Natural-Fehlermeldungscode enthalten kann. Das Programm wird nicht ausgeführt, sondern es tritt eine Fehlerbedingung mit der angegebenen Nummer auf.

Beispiele für User-Exit-Programme

Die folgenden Beispiele für User-Exit-Programme werden in den folgenden Natural-Source-Datasets (Dateien) zur Verfügung gestellt:

Aufruf des CMRDC-Interface

Die Anwendungsprogrammierschnittstelle CMRDC wird verwendet, um die im Natural Data Collector-Puffer aufgezeichneten Trace-Daten abzurufen und zu steuern. Dies kann für Testzwecke von Nutzen sein.

Um das CMRDC Interface aufzurufen:

• Setzen Sie in dem Natural-Programm ein CALL-Statement ab.

Die vom CMRDC Interface zur Verfügung gestellten Funktionen und die Syntax, die bei den entsprechenden Natural-CALL-Statements gilt, werden im folgenden Abschnitt behandelt.

Zusätzlich enthält die Natural-System-Library SYSRDC Beispielprogramme und den dazu passenden lokalen Datenbereich (LDA) RDCDATA, in dem die Struktur der Trace-Aufzeichnungen definiert ist. Gemäß dieser Definition hat jede Trace-Aufzeichnung zwei Hauptbestandteile: einen für die allgemeinen Daten und einen für ereignisspezifische Daten.

Folgende Themen werden behandelt:

• Trace-Aufzeichnungen abrufen

• Trace-Aufzeichnung stoppen und erneut starten

• Ereignistypen für Trace-Aufzeichnung auswählen

• Benutzerdefinierte Ereignisse

• Trace-Status abfragen

• CMRDC-Rückgabecodes

Trace-Aufzeichnungen abrufen

Um Daten aus dem Natural Data Collector-Puffer zu lesen, müssen Sie CMRDC mit dem folgenden Natural-Statement aufrufen:

Folgende Parameter werden übergeben:

Die Abruf-Funktionen stoppen das Aufzeichnen von Daten im Natural Data Collector-Puffer implizit.

Trace-Aufzeichnung stoppen und erneut starten

Um das Aufzeichnen von Trace-Daten im Natural Data Collector-Puffer zu stoppen und erneut zu starten, müssen Sie CMRDC mit dem folgenden Natural-Statement aufrufen:

Folgende Parameter werden übergeben:

Ereignistypen für Trace-Aufzeichnung auswählen

Standardmäßig werden alle Ereignisse für die Trace-Aufzeichnung ausgewählt. Sie können diese Funktion benutzen, wenn nur bestimmte Ereignisse aufgezeichnet werden sollen.

Anmerkungen:

1. Diese Funktion dient nur zum Auswählen von Ereignissen, die im Natural Data Collector-Puffer aufgezeichnet werden sollen. Sie hat keine Auswirkung auf die Daten, die an User Exits übergeben werden, und beeinflusst auch nicht den Status (gestartet/gestoppt) der Trace-Aufzeichnung.
2. Ereignisse können auch mit dem Subparameter EVENT des Profilparameters RDC angegeben werden, siehe Natural Data Collector aktivieren und steuern.
3. Diese Funktion bewirkt, dass jegliche früher erfolgte Ereignisdefinition ersetzt wird,

Um die aufzuzeichnenden Ereignistypen auszuwählen, müssen Sie CMRDC mit dem folgenden Natural-Statement aufrufen:

Folgende Parameter werden übergeben:

Benutzerdefinierte Ereignisse

Um ein benutzerdefiniertes Ereignis auszuwählen, müssen Sie CMRDC mit dem folgenden Natural-Statement aufrufen:

Folgende Parameter werden übergeben:

Trace-Status abfragen

Um den Trace-Status und den zurzeit gesetzten Ereignistyp abzufragen, müssen Sie CMRDC mit dem folgenden Natural-Statement aufrufen:

Folgende Parameter werden übergeben:

CMRDC-Rückgabecodes

Beispiel-Programme

Die Natural-System-Library SYSRDC enthält folgende Beispiel-Programme:

Beispiel-Ausgabe des Programms RDCDISP

Der folgende Beispiel-Bildschirm zeigt einen Auszug aus einem Ausgabe-Report, der vom Beispiel-Programm RDCDISP erstellt wurde.

 ETIME1   TY  GCUID   LV   GPGM   T  GCAPL    PRLIB    PRNAM   CO  DB   FN  RC
--------- -- -------- -- -------- - -------- -------- -------- -- ---- ---- ---

   0.0000 SI SAG                    SYSTEM
   0.0002 DB SAG                    SYSTEM                     OP   10
   0.0002 DA SAG                    SYSTEM                     OP   10
   0.0000 DB SAG                    SYSTEM                     S1   10 1640
   0.0005 DA SAG                    SYSTEM                     S1   10 1640
   0.0001 PL SAG                    SYSTEM   SYSLIB   MAINMENU
   0.0001 PS SAG       1 MAINMENU F SYSTEM   SYSLIB   MAINMENU      10 1640
   0.0001 PL SAG       1 MAINMENU   SYSTEM   SYSLIB   NAT00029
   0.0000 DB SAG       1 MAINMENU   SYSTEM                     S1   10 1640
   0.0002 DA SAG       1 MAINMENU   SYSTEM                     S1   10 1640
   0.0000 PS SAG       2 NAT00029 N SYSTEM   SYSLIBS  NAT00029      10 1640
   0.0000 CB SAG       2 NAT00029   SYSTEM            CMMPP    S
   0.0000 CA SAG       2 NAT00029   SYSTEM            CMMPP    S
   0.0000 PT SAG       2 NAT00029 N SYSTEM   SYSLIBS  NAT00029
   0.0000 PL SAG       1 MAINMENU   SYSTEM   SYSLIB   USR2003P
   0.0000 PS SAG       2 USR2003P N SYSTEM   SYSLIB   USR2003P      10 1640
   0.0001 PT SAG       2 USR2003P N SYSTEM   SYSLIB   USR2003P
   0.0000 CB SAG       1 MAINMENU   SYSTEM            CMUB     S

In der folgenden Tabelle werden die Spaltenüberschriften im Beispiel-Bildschirm und die Variablen erklärt, auf die sie sich beziehen. Bei einigen Ereignissen haben die zu PRLIB angezeigten Daten eine andere Bedeutung. Für weitere Informationen siehe die Kommentare in der Programm-Source und dem lokalen Datenbereich (LDA) RDCDATA. Erläuterungen zu den nachfolgend erwähnten Systemvariablen können Sie der Systemvariablen-Dokumentation entnehmen.

Interne Gültigkeitsprüfung und Tracing nach E/A-bezogenen Statements

Um NAT1132-Fehler festzustellen und das Debugging zu erleichtern, können durch Trace Recording Informationen gesammelt werden, die sich auf den Fehlertyp beziehen (z.B. Zeilen- und Feldlängen oder Puffer-Offsets). Nach der Verarbeitung eines Ein-/Ausgabe-Statements (z.B. WRITE, DISPLAY) wird eine Validierungsroutine ausgeführt, um die Puffer IOPAGE und IOPATTR auf Gültigkeit und Konsistenz zu prüfen, z.B. hinsichtlich des Vorhandenseins eines Zeilentrennungszeichens. Wenn ein möglicher Fehler entdeckt, wird die Meldung (NAT1132 condition detected) sowie Informationen zum Lokalisieren des Fehlers in den Natural Data Collector-Puffer geschrieben und die Trace-Aufzeichnung wird gestoppt, um zu vermeiden, dass dieses Ergebnis durch nachfolgende, irrelevante Daten verborgen wird.

Um das Aufzeichnen des Tracing nach NAT1132 zu aktivieren, geben Sie die folgenden Natural-Profileparameter an:

Wenn ein Trace für ein von Ihnen ausgeführtes Programm erstellt wurde, können Sie die I/O-bezogenen Datensätze anzeigen, indem Sie RDCDISIO in der Library SYSRDC ausführen.

Beispiel-Ausgabe des Programms RDCDISIO

Der folgende Beispiel-Bildschirm zeigt einen Auszug aus einem Ausgabe-Report, der vom Beispiel-Programm RDCDISIO erstellt wurde. In der folgenden Tabelle werden die Spaltenüberschriften im Beispiel-Bildschirm erklärt.

 GCUID   LV   GPGM    GCAPL                       NDATA
-------- -- -------- -------- ---------------------------------------------
MK        1 LOGON    SYSTEM   INO2  08 F 005041700618 (R6)
MK        1 MYDEMO   MK       INO2  00 F 001A00200609 (R6)
MK        1 MYDEMO   MK       IOIPR    F 001A00200609 50 50 0050 0050
MK        1 MYDEMO   MK       INO2  04 F 001A00200609 (R6)
MK        1 MYDEMO   MK       INO2  00 F 001A00200609 (R6)
MK        1 MYDEMO   MK       IOIPR    F 001A00200609 50 50 0050 0050
MK        1 MYDEMO   MK       INO2     F 10C000C8C9C5 (R6) BEG OF  IOPRI
MK        1 MYDEMO   MK       IOEUP    F 000000A0 0F  (PATTRADF/LNG)
MK        1 MYDEMO   MK       IOEUP    F 000000A0 0F  (PATTRADF/LNG)
MK        1 MYDEMO   MK       IODRU    F 000000B0 3F  (PATTRADF/LNG)
MK        1 MYDEMO   MK       INO2     F 000A00301804 (R6) END OF  IOPRI
MK        2 MYDEMON  MK       INO2  00 N 001801700609 (R6)
MK        2 MYDEMON  MK       IOIPR    N 001801700609 4F 50 004F 0050
MK        2 MYDEMON  MK       IOIPR    N LINE SIZE HAS CHANGED
MK        2 MYDEMON  MK       INO2     N 058000800104 (R6) BEG OF  IOPRI
MK        2 MYDEMON  MK       IOEUP    N 000000F0 08  (PATTRADF/LNG)
MK        2 MYDEMON  MK       IOEUP    N 000000F0 08  (PATTRADF/LNG)
MK        2 MYDEMON  MK       IOEUP    N 000000F9 32  (PATTRADF/LNG)
MK        2 MYDEMON  MK       IOEUP    N 000000F9 32  (PATTRADF/LNG)
MK        2 MYDEMON  MK       IOEUP    N 0000012C 12  (PATTRADF/LNG)
MK        2 MYDEMON  MK       IOEUP    N 0000012C 12  (PATTRADF/LNG)
MK        2 MYDEMON  MK       IOPRI    N NAT1132 CONDITION DETECTED
MK        2 MYDEMON  MK       IOEUP    N 0000013F 32  (PATTRADF/LNG)
MK        2 MYDEMON  MK       IOEUP    N 0000013F 32  (PATTRADF/LNG)
MK        2 MYDEMON  MK       IOEUP    N 00000172 32  (PATTRADF/LNG)
MK        2 MYDEMON  MK       IOEUP    N 0000018F 1E  (PATTRADF/LNG)
MK        2 MYDEMON  MK       IOEUP    N 0000018F 1E  (PATTRADF/LNG)
MK        2 MYDEMON  MK       IODRU    N 000001AE 30  (PATTRADF/LNG)
MK        2 MYDEMON  MK       INO2     N 00060180FF08 (R6) END OF  IOPRI
MK        2 MYDEMON  MK       INO2     N NAT1132 CONDITION 1 DETECTED