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.
