Ein Natural User Exit ist ein Objekt, das von Natural, einer Unterkomponente oder einem Unterprodukt aufgerufen wird. In der Regel wird ein Beispiel-User Exit in Quellcodeform geliefert. Die im User Exit enthaltenen Anweisungen müssen vom Benutzer selbst geschrieben oder angepasst werden. Der Zweck eines User Exit besteht darin, Daten zu beeinflussen oder Entscheidungen zu treffen. Die meisten User Exits nutzen die Vorteile der Programmiersprache Natural. Eine kleine Teilmenge muss in Assembler-Sprache geschrieben werden.
Dieses Dokument beschreibt die folgenden Natural User Exits:
Weitere Natural User Exits und Anwendungsprogrammierschnittstellen werden an den entsprechenden Stellen in der Dokumentation der Natural-Unterkomponenten oder Unterprodukte beschrieben (Natural RPC, TP-Monitor-Schnittstellen, Dienstprogramme (Utilities), Add-on-Produkte usw.).
Der User Exit NATUEX1 wird immer dann aufgerufen, wenn eine Benutzersitzung aktiviert wird. Er kann verwendet werden, um festzustellen, ob der Benutzer berechtigt ist, Natural zu benutzen oder nicht. Die Security-Daten, mit denen dies festgestellt wird, können aus dem verwendeten Security-System (z.B. RACF oder ACF2) abgerufen werden.
NATUEX1 wird unter Verwendung von Standardaufrufkonventionen aufgerufen:
| Register | Inhalt |
|---|---|
| 15 | Einsprungadresse von NATUEX1 |
| 14 | Rücksprungadresse von Natural |
| 13 | Adresse eines Speicherbereichs von 18 Worten |
| 1 | Adresse einer Parameterliste |
Die Parameterliste enthält fünf Adressen:
| Adresse | Zeigt auf ein 8-Byte-Feld, das den Wert enthält, der zum Füllen folgender Natural-Systemvariablen verwendet wird: |
|---|---|
| 1 | *INIT-USER |
| 2 | *ETID |
| 3 | *INIT-ID |
| 4 | *INIT-PROGRAM |
| 5 | *USER (Beachten Sie, dass diese Systemvariable
bei einer Natural Security-Anmeldung überschrieben wird.)
|
Diese fünf Werte können durch den User Exit geändert werden.
Für eine normale Beendigung muss der User Exit die Kontrolle mit dem auf 0
gesetzten Register 15 zurückgeben. Wenn Register 15 nicht 0 enthält, wird die
Natural-Sitzung mit dem Condition Code beendet, der dem Wert in Register 15
entspricht.
NATUEX1 kann mit dem umgebungsunabhängigen Nukleus oder mit einem umgebungsabhängigen
Nukleus verlinkt werden. Es ist auch möglich, ihn mit einem alternativen
Natural-Parametermodul oder als separates Modul zu verlinken, wenn Sie mit dem
Profilparameter RCA
arbeiten.
Ein Beispiel für den User Exit ist als Member XNATUEX1 in der Natural Source
Library verfügbar.
Für CICS: Siehe auch NCIUIDEX - Benutzerkennung-Exit-Schnittstelle in der Natural-TP-Monitor-Schnittstellen-Dokumentation.
Natural bietet zwei User Exits für die Sortierverarbeitung: NATSREX2 und
NATSREX3.
Die beiden User Exits können sowohl mit dem Natural-eigenen Sortierprogramm als auch mit
einem externen Sortierprogramm verwendet werden. Die Exits werden automatisch aktiviert,
wenn sie mit dem Nukleus verlinkt sind, so dass ihre Adressen aufgelöst werden. Da viele
externe SORT-Programme bereits mehrere Exit-Funktionen bereitstellen, können die Exits
NATSREX2 und NATSREX3 vor allem mit dem internen
Sortierprogramm von Natural verwendet werden.
NATSREX2 wird immer dann aufgerufen, wenn Natural einen Datensatz an das
Sortierprogramm übergibt. NATSREX3 wird aufgerufen, wenn das Sortierprogramm
nach Beendigung des Sortierlaufs einen Datensatz an Natural übergibt. Das ausgelieferte
Beispiel zeigt, wie Sie Ihre eigene Sortierreihenfolge für einen SORT-Lauf
festlegen können.
Bei der Aktivierung der User Exits müssen die folgenden Registerkonventionen eingehalten werden:
| Register | Inhalt |
|---|---|
| 15 | Einsprungadressen NATSREX2 und NATSREX3 |
| 14 | Rücksprungadresse von Natural |
| 13 | Adresse des 18-Wort-Speicherbereichs |
| 1 | Adresse des Sortiersatzes |
| 3 | Länge des Sortiersatzes |
Die User Exits müssen die Natural-Register sichern und sie bei der Rückgabe der Kontrolle an Natural wiederherstellen.
Da das Sortier-Exit-Modul mit dem Modul NAT2SORT verlinkt ist, muss die
Programmierung reentrant sein. Das Format und die Struktur der Sortiersätze dürfen nicht
verändert werden.
Einige Landessprachen enthalten Zeichen, die von einem Sortierprogramm oder
Datenbanksystem nicht in der richtigen alphabetischen Reihenfolge sortiert werden. Mit der
Systemfunktion SORTKEY
können Sie solche "falsch sortierten" Zeichen in andere Zeichen umwandeln,
die alphabetisch "richtig sortiert" werden.
Wenn Sie die Funktion SORTKEY in einem Natural-Programm verwenden, wird der
User Exit NATUSKnn aufgerufen, wobei
nn der aktuelle Sprachcode ist (d.h. der
aktuelle Wert der Systemvariablen *LANGUAGE).
Ein User Exit NATUSKnn kann in jeder
Programmiersprache geschrieben werden, die eine Standard-CALL-Schnittstelle
bietet. Die mit SORTKEY angegebene Zeichenkette wird an den User Exit
übergeben. Der User Exit muss so programmiert werden, dass er "falsch
sortierte" Zeichen in dieser Zeichenkette in entsprechende "richtig
sortierte" Zeichen umwandelt. Die konvertierte Zeichenkette wird dann im
Natural-Programm zur Weiterverarbeitung verwendet.
Für die Konvertierung kann NATUSKnn die
Umsetzungstabelle NTUTAB1 des Konfigurationsmoduls NATCONFG verwenden, d.h.
NTUTAB1 muss ggf. entsprechend angepasst werden.
NATUSKnn wird mit den Standard-Aufrufkonventionen
aufgerufen:
| Register | Inhalt |
|---|---|
| 15 | Einsprungadresse von NATUSKnn
|
| 14 | Rücksprungadresse von Natural |
| 13 | Adresse eines Speicherbereichs von 18 Vollwörtern |
| 1 | Adresse einer Parameterliste |
Die Parameterliste enthält die folgenden Adressen:
| Offset | Adresse von |
|---|---|
| +0 | Die von Natural übergebene Zeichenkette. |
| +4 | Die Länge der Zeichenkette (Vollwort). |
| +8 | Die aus der Umwandlung resultierende Zeichenkette. |
| +12 | Die Länge der Ergebniszeichenkette (Vollwort). |
| +16 | Die Umsetzungstabelle NTUTAB1.
|
NATUSKnn muss alle Register mit Ausnahme von 14
und 15 sichern und sie bei der Rückgabe der Kontrolle an Natural wiederherstellen.
Für eine normale Beendigung muss der User Exit die Kontrolle mit Register 15 auf Return
Code 0 zurückgeben. Wenn Register 15 nicht 0 enthält, wird ein entsprechender
Natural-Fehler ausgegeben.
Die folgenden Beispiele für User Exits liegen im Quellcode vor:
| Programm | Funktion |
|---|---|
NATUSK01 |
Gilt für Englisch und wandelt alle englischen Kleinbuchstaben in der Zeichenkette in Großbuchstaben um. |
NATUSK02 |
Gilt für Deutsch und wandelt die deutschen Umlaute ä, ö, ü und ß in die entsprechenden Ersatzzeichen ae, oe, ue, ss um, um eine andere Sortierreihenfolge zu erreichen. |
NATUSKnn kann mit dem umgebungsunabhängigen
Nukleus oder mit einem umgebungsabhängigen Nukleus verlinkt werden. Es ist auch möglich,
ihn mit einem alternativen Natural-Parametermodul zu verlinken, oder als separates Modul,
wenn Sie mit dem Profilparameter RCA=NATUSKnn
arbeiten.
Weitere Informationen zu Verlinkungs- und Ladekonventionen sind beim CALL-Statement in der
Natural-Statements-Dokumentation vorhanden.
Das Modul NATPM wird zur Unterstützung von Terminals mit umgekehrter
Schreibrichtung verwendet. Es enthält die User Exit-Routine für die Feld- und
Zeilenumsetzung, die von Natural bei Terminal-Ein-/Ausgaben aufgerufen wird, wenn für
einige Felder der Druckmodus (Profilparameter PM auf I gesetzt wurde.
PM=I steht für inverse Richtung und wird verwendet, um Sprachen zu
unterstützen, die von rechts nach links schreiben (z.B. bidirektionale Sprachen). Siehe
auch die Beschreibung des Profilparameters PM.
Das Modul NATPM wird als Quellcode-Modul ausgeliefert und kann bei Bedarf
geändert werden.
Natural stellt eine User Exit-Routine zur Verfügung, die für jedes Feld, dessen
Ergebnisattribut PM=I ist, und für jede Zeile, die über Hardcopy,
zusätzlichen Report und Primär-Batch-Ausgabe gedruckt werden soll, aufgerufen wird.
Dieser Exit wird mit drei Parametern aufgerufen:
das Quellfeld, das invertiert werden soll,
das Zielfeld, das die invertierten Daten erhalten soll,
ein Längenfeld, das die Länge der Quell- und Zielfelder angibt.
Da diese User Exit-Routine als Quellcode für alle Benutzer verfügbar ist, kann sie als
expliziter Feld-Exit verwendet werden, der durch das Attribut PM=I
ausgelöst wird. Der Benutzer kann dann Zeilen- oder Feldinhalte prüfen und ändern.
Der User Exit in NATPM wird für jedes Feld aufgerufen, für das das
Attribut PM=I gesetzt ist.
Dieses Attribut kann vom Natural-Programmierer gesetzt werden oder wird für numerische
Felder automatisch gesetzt, wenn der globale Druckmodus auf PM=I
eingestellt ist. Dabei spielt es keine Rolle, ob die Ausgabe für das Terminal, für den
Ausdruck, für zusätzliche Reports oder für die Primärausgabe im Batch erzeugt wird.
Bei Druckgeräten erwartet Natural keine automatische Invertierung durch die Hardware,
sondern ruft NATPM erneut für die gesamte Zeile auf. Diese Funktion kann in
Ländern verwendet werden, in denen die Feldinvertierung nicht erforderlich ist, um eine
Schnittstellenlogik mit Natural auf der Grundlage eines Feldattributs einzurichten.
NREXPG ist ein User Exit für Natural Remote Job Entry (NATRJE). Nach Beendigung des Jobs wird
jede JCL-Karte an den Exit übergeben, bevor sie an das Betriebssystem übermittelt wird.
Dem Exit stehen die folgenden Daten zur Verfügung:
die zu übergebende JCL-Karte,
ein Rückgabecode-Feld,
der Name des Natural-Programms, das gerade ausgeführt wird,
die Natural-Benutzerkennung,
ein 240 Byte großer Arbeitsbereich.
Nach jedem Aufruf übergibt der Exit einen Rückgabecode an NATRJE, der eines der folgenden Ereignisse anzeigt:
| Code | Erläuterung |
|---|---|
0 |
Übergabe: Die Karte wird übermittelt; der Exit kann die Karte vor der Übergabe ändern. |
4 |
Beendigung: Die Karte wird übermittelt; der Exit ist für weitere Karten des aktuellen Jobs gesperrt. |
8 |
Einfügung: Die Karte wird übersprungen, da davon ausgegangen wird, dass sie nur ein Einfügezeichen, z. B. das Prozentzeichen (%), enthält; weitere angegebene Karten werden übermittelt. |
10 |
Löschung: Die Karte wird nicht übermittelt. |
12 |
Der aktuelle Job wird geleert (flush). |
Ein Beispiel für den User Exit mit der Bezeichnung NREXPG ist als Member
XNATRJE in der Natural Source Library verfügbar. Der Exit kann nach den
Regeln der als CSTATIC angegebenen Programme assembliert und verlinkt werden. Ein
CSTATIC-Eintrag für NREXPG ist jedoch nicht erforderlich.
Mit der User Exit-Routine USR0070P können Sie die Parametereinstellungen für
den Natural-Programmeditor oder den Natural-Datenbereichseditor (Data Area Editor) im
Standardprofil SYSTEM ändern.
Weitere Informationen zum Editor-Profil finden Sie unter Editoren - Allgemeine Informationen in der Editoren-Dokumentation.
USR0070P liefert eine Liste aller Parameter, die eine Standard-Einstellung
erhalten sollen.
Mit diesem User Exit können Sie auch festlegen, ob Editor-Profile in der Systemdatei FNAT, in der Systemdatei FUSER oder in der Scratch-Pad-Datei abgelegt werden sollen.
Außerdem berücksichtigt USR0070P die DBCS-Unterstützung und setzt die
Editor-Profil-Optionen Editieren in Kleinbuchstaben und
Dynamische Umwandlung von Kleinbuchstaben entsprechend.
Ein Beispiel für diese User Exit-Routine ist in der Library SYSEXT in der
Systemdatei FNAT sowohl in Objekt- als auch in Quellcodeform verfügbar. Informationen zu
ihrer Verwendung sind im Textobjekt USR0070T enthalten.
Die User Exit-Routine USR2002P kann verwendet werden, um die Textstrings für
das Fenster Current Natural Message anzupassen, das durch Drücken der
Hilfetaste aufgerufen wird, während sich der Cursor in der Nachrichtenzeile befindet.
Das Objekt USR2002P selbst enthält die Texte, die im Fenster
Current Natural Message verwendet werden, z.B. den Fenstertitel und die
beschreibenden Texte, wie die Feldnamen Sh (Kurzmeldung), Tx
(Langmeldung), Ex (Erklärung) und Ac (Aktion).
Ein Beispiel für diese User Exit-Routine ist in der Library SYSEXT in der
Systemdatei FNAT sowohl in Objekt- als auch in Quellcodeform verfügbar. Informationen zu
ihrer Verwendung sind im Textobjekt USR2002T enthalten.
Mit der User Exit-Routine USR2003P können die folgenden Einstellungen für
das Natural-Hauptmenü
(Main Menu) und die untergeordneten Menüs angepasst werden:
Position und Farbe der Nachrichtenzeile,
Position und Farbe der PF-Tastenzeilen.
Ein Beispiel für diese User Exit-Routine ist in der Library SYSEXT in der
Systemdatei FNAT sowohl in Objekt- als auch in Quellcodeform verfügbar. Informationen zu
ihrer Verwendung sind im Textobjekt USR2003T enthalten.
