Natural User Exits

#### Search Results

Search

# Natural User Exits

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:

- NATUEX1 - User Exit für die Berechtigungskontrolle

- NATSREX2 und NATSREX3 - User Exits für die Sortierverarbeitung

- NATUSKnn - User Exit zur Berechnung von Sortierschlüsseln

- NATPM - User Exit für invertierte Ausgabe

- NREXPG - User Exit für NATRJE

- USR0070P - User Exit für Editor-Profile

- USR2002P - User Exit für Textstrings im Hilfefenster

- USR2003P - User Exit für Hauptmenü

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.).

## NATUEX1 - User Exit für die Berechtigungskontrolle

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.

## NATSREX2 und NATSREX3 - User Exits für die Sortierverarbeitung

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.

## NATUSKnn - User Exit zur Berechnung von Sortierschlüsseln

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.

#### Beispiele für User Exit-Programme

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.

## NATPM - User Exit für invertierte Ausgabe

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.

### Invertierungslogik

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.

### Feld-User Exit

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 - User Exit für NATRJE

`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.

## USR0070P - User Exit für Editor-Profile

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.

## USR2002P - User Exit für Textstrings im Hilfefenster

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.

## USR2003P - User Exit für Hauptmenü

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.

### On this page

- NATUEX1 - User Exit für die Berechtigungskontrolle
- NATSREX2 und NATSREX3 - User Exits für die Sortierverarbeitung
- NATUSKnn - User Exit zur Berechnung von Sortierschlüsseln
- NATPM - User Exit für invertierte Ausgabe
- NREXPG - User Exit für NATRJE
- USR0070P - User Exit für Editor-Profile
- USR2002P - User Exit für Textstrings im Hilfefenster
- USR2003P - User Exit für Hauptmenü