Betrieb einer Natural RPC-Umgebung

#### Search Results

Search

# Betrieb einer Natural RPC-Umgebung

In diesem Abschnitt werden überwiegend Aufgaben beschrieben, die für den Betrieb einer Natural RPC-Umgebung relevant sind.

Einige dieser Aufgaben werden mit der Utility `SYSRPC` ausgeführt. Weitere Informationen siehe Dokumentation zur SYSRPC Utility.

In diesem Kapitel werden die folgenden Themen behandelt:

- RPC-Server-Adressen festlegen

- Interface-Objekte und automatische RPC-Ausführung

- RPC-Profilparametern während einer Natural-Sitzung abfragen/ändern

- Server-Kommandos ausführen

- Kommando an einen RPC-Server senden

- Anmeldung bei einer Server Library

- Logon-Option benutzen

- Komprimierung verwenden

- Secure Socket Layer verwenden

- Den Status einer RPC-Sitzung überwachen

- Laufzeiteinstellungen eines Servers abrufen

- Parameter für EntireX setzen/abfragen

- Message ID und Correlation ID von EntireX verwalten

- Behandlung von Fehlern

- Benutzer-Exits vor und nach der Ausführung von Diensten

## RPC-Server-Adressen festlegen

Jeder Remote-`CALLNAT`-Anforderung muss ein Server zugewiesen werden (identifiziert durch `servername` und `nodename`), bei dem das `CALLNAT`-Statement ausgeführt werden soll. Daher müssen alle Subprogramme, auf die remote zugegriffen werden soll, wie folgt definiert werden:

- in einem lokalen Service Directory auf der Client-Seite,

- oder in einem Remote Directory, auf das über einen Remote Directory Server zugegriffen wird,

- oder über die Standard-Server-Adressierung mit dem Schlüsselwort-Subparameter `DFS` des Profilparameters `RPC` oder des Parameter-Makros `NTRPC`,

- oder innerhalb der Client-Anwendung selbst über die Standard-Serveradressierung.

Zusätzlich zu den oben genannten Methoden können Sie auch alternative Server angeben.

Nachfolgend finden Sie Informationen zu:

- Lokale Verzeichniseinträge verwenden

- Remote Directory-Einträge benutzen

- Standard-Serveradresse beim Start von Natural Operations festlegen

- Festlegen einer Standard-Serveradresse innerhalb einer Natural-Sitzung

- Alternativen Server benutzen

### Lokale Verzeichniseinträge verwenden

Alle Daten des lokalen Service Directory eines Clients werden in dem Subprogramm `NATCLTGS` gespeichert. Zur Ausführungszeit wird dieses Subprogramm verwendet, um auf den Ziel-Server aufzusuchen. Folglich muss `NATCLTGS` in der Client-Anwendung oder in einer der für die Anwendung definierten Natural Steplibs vorhanden sein.

Wenn `NATCLTGS` nicht in eine Steplib generiert wurde oder sich auf einem anderen Rechner befindet, verwenden Sie die entsprechende Natural-Utility (`SYSMAIN` oder den Natural Object Handler), um `NATCLTGS` in eine der für die Anwendung definierten Steplibs zu verschieben.

Wenn Sie ein `NATCLTGS`-Subprogramm zur gemeinsamen Nutzung verwenden, müssen Sie es allen Client-Umgebungen zur Verfügung stellen, z.B. indem Sie es in die Library `SYSTEM` kopieren, oder, wenn eine einzelne Kopie für einen Client verwendet wird, muss es für diesen Client mit der Funktion Service Directory Maintenance der `SYSRPC` Utility gepflegt werden.

Zur Definition und Bearbeitung von RPC-Service-Einträgen siehe Kapitel Service Directory Maintenance in der SYSRPC Utility-Dokumentation.

### Remote Directory-Einträge benutzen

Ein Remote Directory enthält Diensteinträge (Service Entries), die mehreren Natural-Clients zur Verfügung gestellt werden können. Die Natural-Clients können diese Diensteinträge von Remote Directory-Servern abrufen. Informationen über den Zweck und die Installation von Remote-Directory-Servern finden Sie unter Verwendung eines Remote Directory Servers.

### Standard-Serveradresse beim Start von Natural Operations festlegen

Anstatt einen Server über ein lokales oder entferntes Service Directory zu adressieren, können Sie mit dem Schlüsselwort-Subparameter `DFS` des Profilparameters `RPC` oder des Parameter-Makros `NTRPC`, wie in Ihrer Natural-Parameter-Referenz-Dokumentation beschrieben, einen Standard-Server voreinstellen. Diese Serveradresse wird verwendet, wenn das Subprogramm weder im lokalen noch im entfernten Service Directory gefunden werden kann.

Die `DFS`-Einstellung bestimmt den Standard-Server für die gesamte Sitzung oder bis sie dynamisch überschrieben wird.

Wenn keine `DFS`-Einstellung vorhanden ist und die Serveradresse eines bestimmten Remote Procedure Call nicht im Service Directory gefunden werden konnte, wird eine Natural-Fehlermeldung zurückgegeben.

Eine in einer Client-Anwendung definierte Standard-Serveradresse bleibt auch dann aktiv, wenn Sie sich bei einer anderen Library anmelden oder wenn ein Natural-Fehler auftritt.

### Festlegen einer Standard-Serveradresse innerhalb einer Natural-Sitzung

Die Client-Anwendung selbst kann zur Laufzeit dynamisch eine Standard-Serveradresse angeben. Dazu gibt es in Natural die Anwendungsprogrammierschnittstelle `USR2007N`. Über diese Schnittstelle können Sie eine Standard-Serveradresse festlegen, die immer dann verwendet werden soll, wenn ein entferntes Programm nicht über das Diensteverzeichnis (Service Directory) angesprochen werden kann.

Um `USR2007N` zu vernwenden:

1. Kopieren Sie das Subprogramm `USR2007N` aus der Library `SYSEXT` in die Library `SYSTEM` oder in die Steplib Library oder in eine beliebige Anwendung in der Serverumgebung.

2. Geben Sie mit dem `DEFINE DATA`-Statement im Structured Mode oder dem `RESET`-Statement im Reporting Mode die folgenden Parameter an:

   Parameter | Format | Beschreibung
   --- | --- | ---
   `function` | A1 | Funktion. Mögliche Werte:
   `P` (Put) | Legt fest, dass die Serveradresse (bestehend aus den Parametern `nodename` und `servername`, siehe unten) die Standardadresse für alle nachfolgenden Remote-Prozeduraufrufe ist, die nicht im Diensteverzeichnis (Service Directory) definiert sind. Um eine Standard-Serveradresse zu entfernen, geben Sie ein Leerzeichen für `nodename` und `servername` an.
   `G` (Get) | Ruft die aktuelle Standard-Server-Adresse ab, die mit der Funktion `P` festgelegt wurde.
   `nodename` | A192 | Gibt den Namen des zu adressierenden Serverknotens an bzw. zurück. Anmerkung Aus Kompatibilitätsgründen wird `nodename` mit der Option `BY VALUE` oder `BY VALUE RESULT` definiert (siehe Abschnitt parameter-data-definition in der Beschreibung des `DEFINE DATA`-Statement), um bestehende Aufrufer zu unterstützen, die ein A32-Feld für `nodename` übergeben. Das in der Library `SYSEXT` enthaltene Beispiel `USR2072P` unterstützt bis zu 32 Zeichen.
   `servername` | A32 | Gibt den Namen des Servers, der angesprochen werden soll, an oder zurück. Anmerkung Aus Kompatibilitätsgründen wird servername mit der Option `BY VALUE` oder `BY VALUE RESULT` definiert (siehe Abschnitt parameter-data-definition in der Beschreibung des `DEFINE DATA`-Statement), um bestehende Aufrufer zu unterstützen, die ein A8-Feld für `servername` übergeben.
   `logon` | A1 | Gibt die Logon-Option zurück, siehe Logon-Option benutzen.
   `protocol` | A1 | Gibt das Transportprotokoll an bzw. zurück. Gültiger Wert: `B` (=EntireX Broker).
   `noservdir` | A1 | Gibt die Service Directory-Option an bzw. zurück, siehe Schlüsselwort-Subparameter `DFS` des Profilparameters `RPC` oder Parametermakro `NTRPC`.
   `Y` | Das Service Directory muss nicht vorhanden sein.
   `N` | Das Service Directory muss vorhanden sein.

3. Geben Sie im aufrufenden Programm auf der Client-Seite das folgende Statement an:

       CALLNAT 'USR2007N' function nodename servername logon protocol [noservdir]

Anmerkung
Das Natural-Subprogramm `NATCLTPS` in der Library `SYSRPC` wird nur noch aus Kompatibilitätsgründen gepflegt.

### Alternativen Server benutzen

Um Verbindungsfehlschläge zu vermeiden, können Sie mehrere alternative Server für ein Remote-`CALLNAT` definieren. Wenn Sie solche alternativen Server angeben, geht Natural wie folgt vor:

- Der Client unternimmt einen ersten Versuch, die Verbindung herzustellen.

- Wenn dieser Versuch fehlschlägt, wird anstelle einer Fehlermeldung ein zweiter Versuch unternommen, diesmal jedoch nicht bei demselben Server. Stattdessen wird das Diensteverzeichnis (Service Directory) ab dem aktuellen Eintrag erneut durchsucht, um herauszufinden, ob ein anderer Server verfügbar ist, der den gewünschten Dienst anbietet.

- Wird ein zweiter Eintrag gefunden, versucht Natural, die Verbindung zu diesem Server herzustellen. Wenn der Remote Procedure Call erfolgreich durchgeführt wird, läuft die Client-Anwendung weiter. Der Benutzer merkt nicht, ob die Verbindung zum ersten Server oder zum alternativen Server zum Ergebnis geführt hat.

- Wenn kein weiterer Eintrag gefunden wird oder die Verbindung zu alternativen Servern fehlschlägt, gibt Natural eine entsprechende Fehlermeldung aus.

Um die Verwendung eines alternativen Servers zu ermöglichen:

1. Definieren Sie im Diensteverzeichnis (Service Directory) mehr als einen Server für denselben Dienst.

2. Setzen Sie den Schlüsselwort-Subparameter `TRYALT` des Profilparameters `RPC` oder des Parameter-Makros `NTRPC` auf `ON`, um die Benutzung eines alternativen Servers zu ermöglichen.

Dieser Parameter kann auch dynamisch für die aktuelle Sitzung mit der Parameter Maintenance-Funktion gesetzt werden (siehe SYSRPC Utility-Dokumentation).

## Interface-Objekte und automatische RPC-Ausführung

Interface-Objekte werden nicht mehr benötigt, wenn die automatische Natural RPC-Ausführung verwendet wird, wie unter Mit automatischer Natural RPC-Ausführung arbeiten weiter unten beschrieben.

Die Generierung von Interface-Objekten bietet jedoch den Vorteil, dass die remote ausgeführten CALLNAT(s) kontrolliert werden können und die Fehlerdiagnose erleichtert wird. Sollte ein Remote-Aufruf aufgrund eines falschen CALLNAT-Namens fehlschlagen, hilft die ausgegebene Natural-Fehlermeldung dabei, die Problemursache sofort zu identifizieren. Ohne ein Interface-Objekt erhalten Sie bei einem fehlerhaften `CALLNAT` möglicherweise Folgefehler von der Transportschicht oder dem Natural-Server zurück.

Wenn Sie ein Remote-`CALLNAT`-Statement verwenden wollen, um ein Subprogramm auf einem EntireX-RPC-Server auszuführen, empfehlen wir Ihnen dringend, den Schlüsselwort-Subparameter `AUTORPC` auf `OFF` zu setzen und ein Interface-Objekt zu verwenden. Wenn die IDL (Interface Definition Language) des Subprogramms, das Sie auf einem EntireX RPC-Server aufrufen möchten, eine Gruppenstruktur enthält, müssen Sie dieselbe Gruppenstruktur während der Generierung des Interface-Objekts in der `SYSRPC`-Funktion Interface Object Generation definieren oder das Interface-Objekt aus der EntireX IDL-Datei (nur Windows) generieren oder die EntireX Workbench (nur Linux und Windows) verwenden.

Nachfolgend finden Sie Informationen zu:

- Interface-Objekte erstellen

- Mit automatischer Natural RPC-Ausführung arbeiten

### Interface-Objekte erstellen

Mit der `SYSRPC`-Funktion Interface Object Generation können Sie Natural Interface-Objekte generieren, die verwendet werden, um das aufrufende Programm des Clients mit einem Subprogramm auf einem Server zu verbinden. Das Interface-Objekt besteht aus einem Parameterdatenbereich (PDA) und der Server-Aufruflogik. Siehe Interface-Objekte generieren - Allgemeine Aspekte in der SYSRPC Utility-Dokumentation.

Der PDA enthält dieselben Parameter, die in dem `CALLNAT`-Statement des aufrufenden Programms verwendet werden, und muss in der `SYSRPC`-Funktion Interface Object Generation definiert werden. Wenn bereits ein kompiliertes Natural-Subprogramm mit demselben Namen existiert, wird der von diesem Subprogramm verwendete PDA als Vorbelegung im Bildschirm verwendet. Die Logik für den Serveraufruf wird von der Interface Object Generation-Funktion automatisch generiert, nachdem der PDA definiert wurde.

Zur Ausführungszeit muss das Natural-Anwendungsprogramm, das das `CALLNAT`-Statement und das Interface-Objekt enthält, auf der Client-Seite vorhanden sein. Das Natural-Anwendungsunterprogramm muss auf der Server-Seite vorhanden sein. Das Subprogramm des Schnittstellenobjekts und das Server-Subprogramm müssen denselben Namen haben.

### Mit automatischer Natural RPC-Ausführung arbeiten

Dieser Abschnitt gilt nur, wenn Sie keinen EntireX-RPC-Server aufrufen möchten.

Sie müssen keine Natural RPC Interface-Objekte generieren, sondern können mit automatischer Natural RPC-Ausführung arbeiten (d.h. ohne Verwendung von Natural Interface-Objekten). Um mit automatischer Natural RPC-Ausführung zu arbeiten, setzen Sie den Schlüsselwort-Subparameter `AUTORPC` des Profilparameters `RPC` oder des Parameter-Makros `NTRPC` wie folgt:

    AUTORPC=ON

In diesem Fall können Sie bei Ihren Vorbereitungen für die RPC-Nutzung auf die Generierung des Client-Interface-Objekts verzichten. Wenn die automatische Natural RPC-Ausführung aktiviert ist (`AUTORPC=ON`), verhält sich Natural wie folgt:

- Wenn ein Subprogramm lokal nicht gefunden werden kann, versucht Natural, es remote auszuführen (ein Interface-Objekt ist nicht erforderlich),

- der Parameterdatenbereich wird dann dynamisch zur Laufzeit generiert.

Da es Interface-Objekte nur für Client-Programme gibt, hat diese Funktion keine Auswirkungen auf das `CALLNAT`-Programm auf dem Server.

Wenn der Schlüsselwort-Subparameter `AUTORPC` des Profilparameters `RPC` oder des Parameter-Makros `NTRPC` auf `ON` gesetzt ist und ein Natural-Interface-Objekt existiert, wird es trotzdem verwendet.

## RPC-Profilparametern während einer Natural-Sitzung abfragen/ändern

- Schlüsselwort-Subparameter mit der Utility SYSRPC ändern

- TIMEOUT-Wert mit API USR2076N abfragen/setzen

### Schlüsselwort-Subparameter mit der Utility SYSRPC ändern

Sie können die `SYSRPC` Utility-Funktion Parameter Maintenance benutzen, um dynamisch (innerhalb einer Sitzung) einige Schlüsselwort-Subparameter des Profilparameters `RPC` oder des Parameter-Makros `NTRPC`, die im Natural-Parametermodul für die aktuelle Sitzung festgelegt wurden, zu ändern.

Vorsicht
Diese Änderungen bleiben so lange erhalten, wie die Benutzersitzung aktiv ist. Sie gehen verloren, wenn die Sitzung beendet wird.

### TIMEOUT-Wert mit API USR2076N abfragen/setzen

Sie können die API `USR2076N` verwenden, um dynamisch (innerhalb einer Sitzung) den Wert des Schlüsselwort-Subparameters `TIMEOUT` des Profilparameters `RPC` oder des Parameter-Makros `NTRPC`, die im Natural-Parametermodul für die aktuelle Sitzung festgelegt wurden, abzufragen (Funktion: `G`=Get) oder zu ändern (Funktion: `S`=Set).

`TIMEOUT=value` gibt die Anzahl der Sekunden an, die der Client auf eine RPC-Server-Antwort warten soll. Wenn diese Zeit überschritten wird, wird der Remote Procedure-Aufruf mit einer entsprechenden Fehlermeldung abgebrochen.

Vorsicht
Diese Änderung bleibt so lange erhalten, wie die Benutzersitzung aktiv ist. Sie geht verloren, wenn die Sitzung beendet wird.

Weitere Informationen siehe Beschreibung im Text-Objekt `USR2076T` in der Library `SYSEXT`.

## Server-Kommandos ausführen

Aktive Server, die im Dienste-Verzeichnis (Service Directory) definiert wurden (siehe RPC-Server-Adressen festlegen), können mit der `SYSRPC` Utility-Funktion zur Ausführung von Serverkommandos (Server Command Execution) gesteuert werden. Siehe Server-Kommandos ausführen in der SYSRPC Utility-Dokumentation.

## Kommando an einen RPC-Server senden

Mit der Anwendungsprogrammierschnittstelle (API) `USR9204N` können Sie ein Kommando an einen Server auf einem EntireX Broker-Knoten senden.

Diese Schnittstelle ruft zunächst eine Liste der bei einem bestimmten EntireX Broker registrierten RPC-Server-Replikate ab. Die Liste enthält für jeden Server das Startdatum/die Startzeit, den Hostnamen, den Anwendungsnamen und die IP-Adresse (falls verfügbar). Sie gibt auch die Folgenummer an, die jedem Server bei der Registrierung zugewiesen wurde.

Die Schnittstelle sendet dann eine Sendekommando-Anforderung mit der Folgenummer an den EntireX Broker. Das Kommando übermittelt ein Subprogramm oder ein RPC-Kommando mit der Folgenummer für einen RPC-Server (oder für alle Folgenummern eines RPC-Dienstes).

Um USR9204N zu verwenden:

1. Kopieren Sie das Subprogramm `USR9204N` aus der Library `SYSEXT` in die Library `SYSTEM` oder in die Steplib-Library oder in eine beliebige Anwendung in der Natural-RPC-Server-Umgebung und verfahren Sie wie im Textobjekt `USR9204T` in der Library `SYSEXT` beschrieben.

2. Unterstützte Kommandos:

   -     P,subprogram,parameter-values

     Das angegebene Subprogramm wird direkt in der aktuellen Library des RPC-Servers ausgeführt. Eine Kopie des Objektmoduls des Subprogramms muss auf der Client-Seite vorhanden sein, um dessen Parameterdefinitionen abrufen zu können. Bei den Parameterwerten (parameter-values) müssen alle Werte durch ein Komma voneinander getrennt werden.

   -     C,RPC-command

     Das RPC-Kommando wird direkt in der aktuellen Library des RPC-Servers ausgeführt. Folgende RPC-Kommandos werden unterstützt: `PING`, `TERMINATE`, `TRACE0`, `TRACE1` - `TRACE9`, `TRACE1E` - `TRACE9E` und `TRACEINFO`.

   Anmerkung:
   Das Kommando wird zurückgewiesen, wenn die von der aktuellen Natural-Sitzung verwendete CIS-Version nicht hoch genug ist, um das angeforderte EntireX-Kommando zu unterstützen. Erforderlich ist EntireX Broker 11.0 mit CIS-Version 13 oder höher.

## Anmeldung bei einer Server Library

Die Server Library, in der das `CALLNAT` ausgeführt wird, hängt von der RPC Logon Option auf der Client-Seite und einer Reihe von Parametern auf der Server-Seite ab.

Die folgende Tabelle zeigt, welches die relevanten Parameter sind und wie sie die Library-Einstellung beeinflussen:

| Client | Server
1 | 2 | 3 | 4 | 5 | 6 | 7
*library-id | RPC `LOGON` Flag für Server- Eintrag gesetzt? | `LOGONRQ` set? | Server gestartet mit `STACK=` | NSC oder natives Natural? | NSC: RPC Logon- Option im Library- Profil | Server *library-id
1 | Lib1 | nein | nein | logon lib1 | Kein Einfluss | N/-- | Lib1
2 | Lib1 | nein | nein | logon lib2 | Kein Einfluss | N/-- | Lib2
3 | Lib1 | nein | ja | (Client `LOGON` flag `= NO`) und ( `LOGONRQ=YES`) ist nicht möglich.
4 | Lib1 | ja | Kein Einfluss | Kein Einfluss | NSC | `AUTO` | Lib1
5 | Lib1 | ja | Kein Einfluss | Kein Einfluss | NSC | N | Lib1
6 | Lib1 | ja | Kein Einfluss | Kein Einfluss | Natives Natural | -- | Lib1

Erläuterung der Tabellenspalten:

1. Die Library-Kennung (library-id) der Client-Anwendung, von der das `CALLNAT` `CALLNAT` initiiert wird.

2. Der Wert des RPC `LOGON`-Flags. Kann für einen ganzen Knoten oder einen Server gesetzt werden.

   Das Flag kann gesetzt werden

   - mit der SYSRPC Utility-Funktion Service Directory Maintenance

   - oder mit dem Schlüsselwort-Subparameter `DFS` des Profilparameters `RPC` oder des Parameter-Makros `NTRPC`

   - oder mit der Anwendungsprogrammierschnittstelle `USR2007N`.

3. Der Schlüsselwort-Subparameter `LOGONRQ` des Profilparameters `RPC` oder des Parameter-Makros `NTRPC` kann beim Start des Servers gesetzt werden.

4. Die Library-Kennung (library-id), auf die der Server beim Start positioniert wird.

5. Läuft der Server unter Natural Security (NSC) (siehe Natural RPC mit Natural Security verwenden) oder nicht?

6. Die Einstellung der Logon-Option in den NSC Library Profile Items (Session options > Natural RPC Restrictions) der NSC-Serveranwendung. Wenn die NSC-Logon-Option auf `A` (`AUTO`) gesetzt ist, werden nur Library-Kennung und Benutzerkennung übernommen. Steht sie auf `N` (Standard), werden die Parameter Library, Benutzerkennung und Passwort ausgewertet.

7. Die Library auf dem Server, in der das `CALLNAT`-Programm schließlich ausgeführt wird.

## Logon-Option benutzen

Die Logon-Option legt fest, in welcher Library das Remote-Subprogramm ausgeführt werden soll. Siehe auch Anmeldung bei einer Server Library.

Anmerkung
Wenn Sie die Logon-Option nicht benutzen, wird das `CALLNAT` bei der Library ausgeführt, bei der der Server gerade angemeldet ist. Diese Serveranmeldung wird mit dem Natural-Profilparameter `STACK``=(LOGON library)` definiert. Der Server sucht in der Library nach den auszuführenden CALLNAT-Statements (und allen zugehörigen Steplibs, die für die Library definiert sind).

Einer Client-Anwendung kann die Ausführung eines Subprogramms in einer anderen Library ermöglicht werden, indem die Logon-Option für dieses Subprogramm gesetzt wird. Dies veranlasst den Client, den Namen seiner aktuellen Library zusammen mit der Logon-Option an den Server zu übergeben. Der Server meldet sich daraufhin bei dieser Library an, sucht in ihr nach dem gewünschten Subprogramm und führt es aus, wenn es gefunden wird. Danach meldet er sich bei der vorherigen Library ab.

### Bei einer anderen Library anmelden

Wenn sich der Server bei einer anderen Library als der aktuellen Library des Client anmelden soll, muss der Client die Anwendungsprogrammierschnittstelle `USR4008N` aufrufen, bevor das Remote-`CALLNAT` ausgeführt wird. Mit `USR4008N` gibt der Client einen alternativen Namen einer Library an, bei der sich der Server anmelden soll. Der Name dieser Library wird für alle nachfolgenden Aufrufe von Remote-Subprogrammen verwendet, für die die Logon-Option gilt. Wird für den Library-Namen ein Leerzeichen angegeben, dann wird wieder der Name der aktuellen Client Library verwendet.

Um `USR4008N` zu verwenden:

1. Kopieren Sie das Subprogramm `USR4008N` aus der Library `SYSEXT` in die Library `SYSTEM` oder in die Steplib Library oder in eine beliebige Anwendung in der Serverumgebung.

2. Geben Sie mit dem `DEFINE DATA`-Statement die folgenden Parameter an:

   Parameter | I/O | Format | Beschreibung
   --- | --- | --- | ---
   `P-FUNC` | I | A01 | Funktionscode. Mögliche Werte:
   `P` (Put) | Angabe einer neuen Library für die Remote-`CALLNAT`-Ausführung.
   `G` (Get) | Abrufen der zuvor angegebenen Library für die Remote-`CALLNAT`-Ausführung.
   `P-LIB` | I | A8 | Library auf dem Server für die Remote-`CALLNAT`-Ausführung.

3. Geben Sie im aufrufenden Programm auf der Client-Seite das folgende Statement an:

       CALLNAT 'USR4008N' P-FUNC P-LIB

   Anmerkung:
   Das aufrufende Programm muss ausgeführt werden, bevor der Natural RPC-Client einen Remote-`CALLNAT` aufruft.

### Erforderliche Einstellungen auf der Client-Seite

Um die Logon-Option zu setzen, können Sie entweder die von `SYSRPC`-Funktion Service Directory Maintenance verwenden (siehe den entsprechenden Abschnitt in der SYSRPC Utility-Dokumentation) oder - bei Verwendung eines Standard-Servers - den Schlüsselwort-Subparameter `DFS` des Profilparameters `RPC` oder des Parameter-Makros `NTRPC` oder die Anwendungsprogrammierschnittstelle `USR2007N`.

### Erforderliche Einstellungen auf der Serverseite

Auf der Serverseite ist keine Einstellung erforderlich.

## Komprimierung verwenden

Die Komprimierungstypen können sein: `0`, `1` oder `2`. Interface-Objekte, die mit `COMPR``=1` oder `2` generiert werden, können zur Reduzierung der Datenübertragungsrate beitragen.

Komprimierungstyp | Beschreibung
--- | ---
`COMPR=0` | Alle `CALLNAT`-Parameterwerte werden an den Server gesendet und von diesem zurückgegeben, d.h. es wird keine Kompression durchgeführt.
`COMPR=1` | Parameter vom Typ `M` werden an den Server gesendet und von diesem zurückgegeben, während Parameter vom Typ `O` nur in den Sendepuffer übertragen werden. Parameter vom Typ `A` werden nur in den Antwortpuffer aufgenommen. Der Antwortpuffer enthält nicht die Formatbeschreibung. Dies ist die Standardeinstellung.
`COMPR=2` | Wie bei `COMP=1`, nur dass die Antwortnachricht des Servers noch die Formatbeschreibung der `CALLNAT`-Parameter enthält. Dies kann nützlich sein, wenn Sie bestimmte Optionen für die Datenkonvertierung durch den EntireX Broker verwenden möchten (weitere Informationen finden Sie in der Beschreibung der Translation Services in der EntireX Broker-Dokumentation).

## Secure Socket Layer verwenden

Der Natural RPC unterstützt Secure Socket Layer (SSL) für die TCP/IP-Kommunikation mit dem EntireX Broker.

Damit der EntireX Broker erkennt, dass die TCP/IP-Kommunikation SSL verwenden soll, müssen Sie eine der folgenden Methoden verwenden:

- Fügen Sie die Zeichenfolge `:SSL` an den Knotennamen an. Wenn dem Knotennamen bereits die Zeichenfolge `:TCP` vorangestellt wurde, muss `:TCP` durch `:SSL` ersetzt werden.

- Stellen Sie dem Knotennamen die Zeichenfolge `//SSL` voran:

Beispiel:

`SRVNODE='157.189.160.95:1971:SSL'`

Bevor Sie über SSL auf einen EntireX Broker zugreifen, müssen Sie zunächst die Anwendungsprogrammierschnittstelle `USR2035N` aufrufen, um die erforderliche SSL-Parameterzeichenfolge zu setzen.

Um `USR2035N` zu verwenden:

1. Kopieren Sie das Subprogramm `USR2035N` aus der Library `SYSEXT` in die Library `SYSTEM` oder in eine Steplib Library oder in eine beliebige Anwendung in der Serverumgebung.

2. Geben Sie mit dem `DEFINE DATA`-Statement die folgenden Parameter an:

   Parameter | I/O | Format | Beschreibung
   --- | --- | --- | ---
   `FUNCTION` | I | A01 | Funktionscode. Mögliche Werte:
   `P` (Put) | Geben Sie einen neuen SSL-Parameter-String an. Der SSL-Parameter-String wird intern gespeichert und jedes Mal an EntireX übergeben, wenn ein EntireX Broker, der SSL-Kommunikation verwendet, zum ersten Mal angesprochen wird. Sie können verschiedene SSL-Parameter-Strings für mehrere EntireX Broker-Verbindungen verwenden, indem Sie die Anwendungsprogrammierschnittstelle `USR2035N` jedes Mal aufrufen, bevor Sie das erste Mal auf den EntireX Broker zugreifen. Beispiel:
       FUNCTION := 'P'
       SSLPARMS := 'TRUST_STORE=FILE://DDN:CACERT&VERIFY_SERVER=N'
       CALLNAT 'USR2035N' USING FUNCTION SSLPARMS
   Um SSL-Parameter im Falle eines Natural RPC Servers zu setzen, legen Sie den Namen des aufrufenden Programms beim Start des Servers auf den Natural-Stack. Beispiel:
       STACK=(LOGON server-library;set-SSL-parms)
   Dabei ist set-SSL-parms ein Natural-Programm, das die Anwendungsprogrammierschnittstelle `USR2035N` aufruft, um den SSL-Parameter-String zu setzen.
   `G` (Get) | Abrufen der zuvor angegebenen SSL-Parameterzeichenfolge. Der zuvor gesetzte SSL-Parameterstring wird an den Aufrufer zurückgegeben. Weitere Informationen über den SSL-Parameter-String finden Sie in der EntireX-Dokumentation.
   `SSLPARMS` | I | A128 | SSL-Parameter-String, wie vom EntireX-Broker benötigt.

3. Geben Sie im aufrufenden Programm auf der Client-Seite das folgende Statement an:

       CALLNAT 'USR2035N' FUNCTION SSLPARMS

## Den Status einer RPC-Sitzung überwachen

Folgende Themen werden behandelt:

- Programm RPCERR verwenden

- Subprogramm RPCINFO verwenden

- Server-Trace-Funktion benutzen

- Trace-Datei definieren

### Programm RPCERR verwenden

Sie können das Programm `RPCERR` über die Kommandozeile ausführen oder es mit einem `FETCH`-Statement aus einem Natural-Programm heraus aufrufen. `RPCERR` zeigt die folgenden Informationen an:

- Die letzte Natural-Fehlernummer und -meldung, wenn sie mit RPC zusammenhängt.

- Die letzte EntireX-Broker-Meldung im Zusammenhang mit diesem Fehler.

- The last EntireX RPC server error message if the Natural error error number is related to the EntireX RPC server error

  Die letzte EntireX RPC-Server-Fehlermeldung, wenn die Natural-Fehlernummer mit dem EntireX RPC-Server-Fehler zusammenhängt.

Zusätzlich können der Knoten- und Servername des letzten EntireX Broker-Aufrufs abgerufen werden.

#### Beispiel für eine RPC-Fehleranzeige: RPCERROR

    Natural error number: NAT6972
    Natural error text  :
    Directory error on Client, reason 3.

    RPC error information:
    No additional information available.

    Server Node:                                       Library: SYSTEM
    Server Name:                                       Program: NATCLT3
                                                       Line No: 1010

### Subprogramm RPCINFO verwenden

Sie können das Subprogramm `RPCINFO` in Ihrem Anwendungsprogramm verwenden, um Informationen über den Zustand der aktuellen RPC-Sitzung abzurufen. Dies ermöglicht Ihnen auch eine angemessenere Fehlerbehandlung, indem Sie auf eine bestimmte Fehlerklasse reagieren.

Das Subprogramm `RPCINFO` ist in der Library `SYSTEM` enthalten und kann von jeder Benutzeranwendung aufgerufen werden.

Ein Beispielprogramm `TESTINFO` ist in der Library `SYSRPC` zusammen mit dem Parameterdatenbereich `RPCINFOL` für den Aufruf von `RPCINFO` enthalten.

#### Beispiel:

    DEFINE DATA LOCAL USING RPCINFOL
      LOCAL
      1 PARM   (A1)
      1 TEXT   (A80)
      1 REDEFINE TEXT
        2 CLASS  (A4)
        2 REASON (A4)
    END-DEFINE
    ...
    OPEN CONVERSATION USING SUBPROGRAM 'APPLSUB1'
      CALLNAT 'APPLSUB1' PARM
    CLOSE CONVERSATION *CONVID
    ...
    ON ERROR
       CALLNAT 'RPCINFO' SERVER-PARMS CLIENT-PARMS
       ASSIGN TEXT=C-ERROR-TEXT
       DISPLAY CLASS REASON
    END-ERROR
    ...
    END

#### Parameter von RPC Info

`RPCINFO` hat die folgenden Parameter, die im Parameterdatenbereich `RPCINFOL` bereitgestellt werden:

Parameter | Format | Beschreibung
--- | --- | ---
`SERVER-PARMS` |  | Enthält Informationen über die Natural-Sitzung, wenn Sie als Server fungiert. Die `SERVER-PARMS` gelten nur, wenn Sie `RPCINFO` remote auf einem RPC-Server ausführen.
`S-BIKE` | A1 | Verwendetes Transportprotokoll. Möglicher Wert:
`B` | EntireX Broker
`S-NODE` | A32 | Der Knotenname des Servers.
`S-NAME` | A32 | Der Name des Servers.
`S-ERROR-TEXT` | A80 | Enthält den von der Transportschicht zurückgegebenen Nachrichtentext.
`S-CON-ID` | I4 | Aktuelle Kennung der Konversation. Beachten Sie, dass dies die physische Kennung von EntireX Broker ist, nicht die logische Natural-Kennung. Dieser Parameter enthält immer einen Wert, da EntireX Broker Kennungen sowohl für konversationelle als auch für nicht-konversationelle Anrufe generiert. Wenn die physische Konversationskennung entweder nicht numerisch oder größer als I4 ist, wird ein `-1` zurückgegeben.
`S-CON-OPEN` | L | Gibt an, ob eine offene Konversation besteht. Dieser Parameter enthält den Wert `TRUE`, wenn eine Konversation offen ist, andernfalls enthält er `FALSE`.
`CLIENT-PARMS` |  | Enthält Informationen über die Natural-Sitzung, wenn diese als Client fungiert.
`C-BIKE` | A1 | Verwendetes Transportprotokoll. Möglicher Wert:
`B` | EntireX Broker
`C-NODE` | A32 | Der Knotenname des zuvor angesprochenen Servers.
`C-NAME` | A32 | Der Name des zuvor angesprochenen Servers.
`C-ERROR-TEXT` | A80 | A80 Enthält den von der Transportschicht zurückgegebenen Nachrichtentext.
`C-CON-ID` | I4 | Konversationskennung des letzten Serveraufrufs. Beachten Sie, dass dies die physische Kennung von EntireX Broker ist, nicht die logische Natural-Kennung. Wenn keine Konversation offen ist, ist der Wert dieses Parameters kleiner oder gleich `0`. Wenn die physische Konversationskennung entweder nicht numerisch oder größer als I4 ist, wird ein `-1` zurückgegeben.
`C-CON-OPEN` | L | Gibt an, ob eine offene Konversation besteht. Dieser Parameter enthält den Wert `TRUE`, wenn eine Konversation offen ist, andernfalls enthält er `FALSE`.
`C-ENTIREX-RPC-ERROR-MESSAGE` | A | Enthält den von einem EntireX-RPC-Server zurückgegebenen Nachrichtentext.

### Server-Trace-Funktion benutzen

Natural RPC enthält eine Trace-Funktion, mit der Sie Serveraktivitäten überwachen und mögliche Fehlersituationen aufspüren können.

#### Server-Trace-Funktion aktivieren/deaktivieren

Um die Server-Trace-Funktion zu aktivieren/deaktivieren:

- Starten Sie den Server mit der Option

      TRACE=n

  Der ganzzahlige Wert `n` steht für den gewünschten Trace-Level, d.h. für die Detailtiefe, mit der Ihr Server protokolliert werden soll.

  Die folgenden Werte sind möglich:

  Wert | Trace Level
  --- | ---
  `0` | Es wird kein Trace durchgeführt (Standardeinstellung).
  `1` | Alle Client-Anforderungen und die entsprechenden Server-Rückmeldungen werden aufgezeichnet und dokumentiert.
  `2` | Alle Client-Anforderungen und die entsprechenden Server-Rückmeldungen werden aufgezeichnet und dokumentiert. Zusätzlich werden alle RPC-Daten in die Trace-Datei geschrieben.

  Oder:
  Setzen Sie den Trace Level dynamisch in der Funktion Server Command Execution der SYSRPC-Utility. Sie können dazu das Zeilenkommando `Tn` bzw. `T*` benutzen. Siehe Zeilenkommandos: Server Command Execution.

  Die RPC-Trace-Funktion schreibt die Trace-Daten in den Natural Report Nummer 10.

  Im Falle eines Konvertierungsfehlers, der mit der Natural-Fehlernummer NAT6974 und den Ursachencodes 2 und 3 gemeldet wird, wird die Position der fehlerhaften Daten im Puffer angegeben.

#### Unterstützung von TS=ON für RPC Server Trace

Die folgenden Informationen gelten nur für Großrechner-Umgebungen:

Alle Meldungen im Natural RPC Server Trace werden in Großbuchstaben umgewandelt, wenn `TS=ON` in der Natural RPC Server-Sitzung angegeben ist. Die Trace der Daten vom/zum Client wird durch `TS=ON` nicht beeinflusst und bleibt unverändert.

### Trace-Datei definieren

Die Definition der Trace-Datei hängt von der Umgebung ab:

- Trace-Dateien für Großrechner-Umgebungen - Allgemeine Informationen
- Trace-Datei im z/OS-Batch-Modus
- Trace-Datei unter CICS
- Trace-Dateien für UNIX-Umgebungen
- Trace-Dateien für Windows

#### Trace-Dateien für Großrechner-Umgebungen - Allgemeine Informationen

Definieren Sie auf dem Großrechner die für Ihre Umgebung geeignete Trace-Datei, siehe auch `NTPRINT`-Makro (in der Parameter-Referenz-Dokumentation).

#### Trace-Datei im z/OS-Batch-Modus

#### a) Bei Ausführung eines Servers als einzelne Task

Weisen Sie im Server-Startjob dem zusätzlichen Natural-Report `CMPRT10` einen z/OS-Dataset zu.

#### Beispiel:

    //NATRPC   JOB  CLASS=K,MSGCLASS=X
    //NATSTEP  EXEC PGM=NATOS
    //STEPLIB  DD   DISP=SHR,DSN=SAG.NAT.LOAD
    //         DD   DISP=SHR,DSN=SAG.EXX.LOAD
    //CMPRMIN  DD   *
    IM=D,MADIO=0,MT=0,OBJIN=R,AUTO=OFF,MAXCL=0,ID=',',INTENS=1,
    PRINT=((10),AM=STD)
    /*
    //SYSUDUMP DD   SYSOUT=X
    //CMPRT10  DD   SYSOUT=X
    //CMPRINT  DD   SYSOUT=X
    /*

#### b) Bei Ausführung eines Servers mit Replikaten

1. Setzen Sie den Schlüsselwort-Subparameter `NTASKS` des Profilparameters `RPC` oder des Parameter-Makros `NTRPC` auf einen Wert größer als `1`.

2. Weisen Sie `CMPRMIN` einem Dataset mit `DISP=SHR` oder einen Stern (`*`) zu.

3. Da jede Task auf ein separates `CMPRINT`-Dataset schreibt, definieren Sie die folgenden DD-Kartennamen:

   `CMPRINT` | für die Haupt-Task
   `CMPRINT1` bis `CMPRINT9` | für die ersten neun Subtasks
   `CMPRIN10` bis `CMPRINnn` | für die nächsten zweistelligen Nummern der Subtasks, `nn=NTASKS-1`.

4. Wenn der Schlüsselwort-Subparameter `TRACE` des Profilparameters `RPC` oder des Parameter-Makros `NTRPC` gesetzt ist, schreibt die Trace-Funktion auf Drucker 10.

   Sie müssen die folgenden DD-Kartennamen definieren:

   `CMPRT10` | für die Haupt-Task
   `CMPRT101` bis `CMPRT1nn` | für alle Subtasks, `nn=NTASKS-1`

#### Beispiel:

    //NATRPC   JOB  CLASS=K,MSGCLASS=X
    //NATSTEP  EXEC PGM=NATOS,REGION=8M
    //steplib  DD   DISP=SHR,DSN=SAG.NAT.LOAD
    //         DD   DISP=SHR,DSN=SAG.EXX.LOAD
    //CMPRMIN  DD   *
    IM=D,MADIO=0,MT=0,OBJIN=R,AUTO=OFF,MAXCL=0,ID=',',INTENS=1,
    PRINT=((10),AM=STD)
    /*
    //SYSUDUMP DD   SYSOUT=X
    //CMPRT10  DD   SYSOUT=X
    //CMPRT101 DD   SYSOUT=X
    //CMPRT102 DD   SYSOUT=X
    //CMPRT103 DD   SYSOUT=X
    //CMPRINT  DD   SYSOUT=X
    //CMPRINT1 DD   SYSOUT=X
    //CMPRINT2 DD   SYSOUT=X
    //CMPRINT3 DD   SYSOUT=X
    /*

#### Trace-Datei unter CICS

Weisen Sie unter CICS die Druckdatei 10 einer extra-partitionierten CICS-Warteschlange für transiente Daten zu.

#### Beispiele:

Dynamische Natural-Profildefinition:

    PRINT=((10),AM=CICS,DEST=RPCT,TYPE=TD)

CICS-Definition:

    RPCTRAC DFHDCT TYPE=SDSCI,                       X
                   BLKSIZE=136,                      X
                   BUFNO=1,                          X
                   DSCNAME=RPCTRACE,                 X
                   RECFORM=VARUNB,                   X
                   RECSIZE=132,                      X
                   TYPEFLE=OUTPUT
            SPACE
    RPCT    DFHDCT TYPE=EXTRA,                       X
                   DSCNAME=RPCTRACE,                 X
                   DESTID=RPCT,                      X
                   OPEN=INITIAL

CICS Startup JCL:

    RPCTRACE DD    SYSOUT=*

#### Trace-Dateien für UNIX-Umgebungen

Es wird empfohlen, für jeden Server einen anderen Dateinamen (d. h. eine andere `NATPARM`-Parameterdatei) zu verwenden, damit Sie jeden Server einzeln protokollieren können. Die Trace-Datei wird in der `NATPARM`-Parameterdatei des Natural-Servers definiert:

1. Report-Zuweisungen
   Weisen Sie Ihrem Report Nummer 10 das logische Gerät (Device) LPT10 zu.

2. Device-Parameter- Zuweisungen
   Anstatt eine physische Druckerspezifikation für LPT10 zu wählen, geben Sie einen Dateinamen an, der den Namen Ihrer Trace-Datei darstellt.

#### Beispiel für UNIX:

    /bin/sh -c cat>>/filename

wobei `filename` den Namen der Trace-Datei darstellt.

#### Trace-Dateien für Windows

Es wird empfohlen, für jeden Server einen anderen Dateinamen (d.h. eine andere `NATPARM`-Parameterdatei) zu verwenden, damit Sie sie einzeln protokollieren können. Die Trace-Datei wird in der `NATPARM`-Parameterdatei des Natural-Servers definiert (siehe Device/Report Assignments in Configuration Utility in der Natural for Windows-Dokumentation):

1. #### Reports

   Weisen Sie Ihrer Reportnummer 10 das logische Gerät (Device) LPT10 zu.

2. #### Devices

   Anstatt eine physische Druckerspezifikation für LPT10 zu wählen, geben Sie einen Dateinamen an, der dem Namen Ihrer Trace-Datei entspricht. Standardmäßig werden alte Trace-Dateien gelöscht, wenn eine neue Datei mit demselben Namen angelegt wird.

   Wenn Sie das neue Protokoll an das bestehende anhängen wollen, geben Sie an:

   >>filename

## Laufzeiteinstellungen eines Servers abrufen

Die Natural-Anwendungsprogrammierschnittstelle (API) `USR4010N` ermöglicht es Ihnen, die Laufzeit-Einstellungen eines Servers abzurufen:

- die Systemdatei-Zuweisungen für `FUSER`, `FNAT` und `FSEC`,

- die Steplib-Kette.

Um `USR4010N` zu verwenden:

1. Server-Umgebung:

   Kopieren Sie das Subprogramm `USR4010N` aus der Library `SYSEXT` in die Library `SYSTEM` oder in die Steplib Library oder in eine beliebige Anwendung in der Serverumgebung.

2. Client-Umgebung:

   Geben Sie in einem `DEFINE DATA`-Statement die folgenden Parameter als Redefinition von `USR4010-PARM` (A300) an:

   Parameter | Format | Beschreibung
   --- | --- | ---
   `FUSER-DBID` | N5 | Datenbankkennung der Systemdatei `FUSER`.
   `FUSER-FNR` | N5 | Dateinummer der Systemdatei `FUSER`.
   `FNAT-DBID` | N5 | Datenbankkennung der Systemdatei `FNAT`.
   `FNAT-FNR` | N5 | Dateinummer der Systemdatei `FNAT`.
   `FSEC-DBID` | N5 | Datenbankkennung der Systemdatei `FSEC`.
   `FSEC-FNR` | N5 | Dateinummer der Systemdatei `FSEC`.
   `STEP-NAME` | A8/15 | Name der Steplib.
   `STEP-DBID` | N5/15 | Datenbankkennung der Steplib.
   `STEP-FNR` | N5/15 | Dateinummer der Steplib.

3. Geben Sie im aufrufenden Programm auf der Client-Seite das folgende Statement an:

       CALLNAT 'USR4010N' USR4010-PARM

   Siehe auch Syntax-Beschreibung des `CALLNAT`-Statement.

4. Wenn der Schlüsselwort-Subparameter `AUTORPC` des Profilparameters `RPC` oder des Parameter-Makros `NTRPC` auf `OFF` gesetzt ist, kopieren Sie die Schnittstelle `USR4010X` unter dem Namen `USR4010N` in die Client-Umgebung.

   Wenn der Schlüsselwort-Subparameter `AUTORPC` auf `ON` gesetzt ist, darf die API in der Client-Umgebung nicht verfügbar sein, um zu verhindern, dass die Schnittstelle lokal aufgerufen wird.

Beim Aufruf von USR4010N werden die Werte der oben angegebenen Parameter in der Feldgruppe USR4010-PARM ausgegeben.

## Parameter für EntireX setzen/abfragen

Mit der Anwendungsprogrammierschnittstelle (API) `USR4009N` können Sie den/die EntireX-Parameter, die aktuell vom Natural RPC unterstützt werden, setzen oder abrufen:

- Komprimierungsstufe (Compression Level)

- Verschlüsselungsstufe (Encryption Level)

Um `USR4009N` zu verwenden:

1. Kopieren Sie das Subprogramm `USR4009N` aus der Library `SYSEXT` in die Library `SYSTEM` oder in die Steplib Library oder in eine beliebige Anwendung in der Serverumgebung.

2. Geben Sie mit einem `DEFINE DATA`-Statement die folgenden Parameter an:

   Parameter | Format | I/O | Beschreibung
   --- | --- | --- | ---
   `FUNCTION` | A01 | I | Funktion. Mögliche Werte:
   `G` (Get) | Die bereits eingestellten Werte für die EntireX-Parameter werden zurückgegeben. Wenn in der Natural-Sitzung noch kein `PUT` aufgerufen wurde, sind alle Werte Null oder leer.
   `P` (Put) | Die für die EntireX-Parameter angegebenen Werte werden gespeichert und bei allen nachfolgenden Aufrufen von EntireX verwendet.
   `ENVIRONMENT` | A01 | I | Umgebung. Mögliche Werte:
   `S` | Server
   `C` | Client
   `B` | Beide
   `COMPRESSLEVEL` | A01 | I/O | Komprimierungsstufe.
   `ENCRYPTION-LEVEL` | I01 | I/O | Verschlüsselungsstufe.
   `ACIVERS` | B02 | O | Verwendete API-Version.
   `RC` | B01 | O | Rückgabecode, sofern nicht gleich Null. Enthält die API-Version, die zum Setzen des angeforderten Parameters erforderlich ist:
   `0` | Funktion erfolgreich.
   `6` | Komprimierungsstufe erfordert API-Version 6.
   `7` | Komprimierungsstufe erfordert API-Version 7.

3. Die Schnittstelle kann auf zwei Arten aufgerufen werden:

   1. Aus einem Programm heraus:

          CALLNAT 'USR4009N' FUNCTION ENVIRONMENT
                             COMPRESSLEVEL
                             ENCRYPTION-LEVEL
                             ACIVERS RC

   2. Von der Kommando-Eingabeaufforderung aus oder durch Verwendung des Statements `STACK` mit Werten für die oben genannten Parameter.

      Beispiele:

          USR4009P P,C,ENCRYPTION-LEVEL=1,COMPRESSLEVEL=6
          USR4009P P,C,,6

Im Kommando-Modus können Sie die Notation `keyword=value` verwenden, um nur eine Teilmenge der EntireX-Parameter zu setzen. Die Werte für Parameter, die nicht referenziert werden, bleiben unverändert.

Anmerkungen:

1. Die Anforderung wird abgelehnt und es werden keine Werte gespeichert, wenn die von der aktuellen Natural-Sitzung verwendete API-Version nicht hoch genug ist, um den angeforderten EntireX-Parameter zu unterstützen. In diesem Fall enthält der Parameter `RC` die erforderliche API-Version.
2. Die EntireX-Parameter werden nur vom Natural RPC beachtet.

## Message ID und Correlation ID von EntireX verwalten

Mit der Anwendungsprogrammierschnittstelle (API) `USR8225N` können Sie die EntireX-Parameter `MESSAGE_ID` und `CORRELATION_ID` in einer Natural RPC Client- oder Server-Umgebung verwalten.

Um `USR8225N` zu verwenden:

1. Kopieren Sie das Subprogramm `USR8225N` aus der Library `SYSEXT` in die Library `SYSTEM` oder in die Steplib Library oder in eine beliebige Anwendung in der Serverumgebung.

2. Geben Sie mit einem `DEFINE DATA`-Statement die folgenden Parameter an:

   Parameter | Format | I/O | Beschreibung
   --- | --- | --- | ---
   `FUNCTION` | A08 | I | Funktionscode: `GENERATE` `RETRIEVE`
   `ENVIRONMENT` | A06 | I | Umgebungseinstellung: `CLIENT` `SERVER`
   `MESSAGE_ID` | A64 | O | Nachrichtenkennung.
   `CORRELATION_ID` | A64 | O | Korrelationskennung.
   RC | N04 | O | Rückgabewert: `0` - Keine Fehler `1` - Ungültiger Funktionscode `2` - Ungültige Umgebung `3` - Von Natural RPC nicht unterstützt

## Behandlung von Fehlern

- Behandlung von Remote-Fehlern

- Vermeidung der Fehlermeldung NAT3009 vom Serverprogramm

- User Exit NATRPC01

### Behandlung von Remote-Fehlern

Jeder Natural-Fehler auf der Server-Seite wird wie folgt an den Client zurückgegeben:

- Der Natural RPC überträgt die entsprechende Fehlernummer in die Systemvariable `*ERROR-NR`.

- Natural reagiert so, als ob der Fehler lokal aufgetreten wäre.

Anmerkung
Wenn der Schlüsselwort-Subparameter `AUTORPC` des Profilparameters `RPC` oder des Parameter-Makros `NTRPC` auf `ON` gesetzt ist und ein Subprogramm in der lokalen Umgebung nicht gefunden werden kann, interpretiert Natural dies als einen Remote Procedure-Aufruf. Es versucht dann, dieses Subprogramm im Diensteverzeichnis (Service Directory) zu finden. Wenn es dort nicht gefunden wird, wird ein NAT6972-Fehler ausgegeben. Infolgedessen wird kein NAT0082-Fehler ausgegeben, wenn ein Subprogramm nicht gefunden werden kann.

Siehe auch Programm RPCERR verwenden.

### Vermeidung der Fehlermeldung NAT3009 vom Serverprogramm

Wenn ein Server-Anwendungsprogramm über einen längeren Zeitraum keinen Datenbankaufruf tätigt, kann der nächste Datenbankaufruf eine Fehlermeldung NAT3009 zurückgeben.

Um dieses Problem zu vermeiden, gibt es den optionalen User-Exit `NATRPC39`. Dieser Exit wird in den folgenden Fällen aufgerufen:

1. Nach einem Ping-Kommando.

2. Bei Kommunikation über den EntireX Broker: jedes Mal, wenn die `SERVER-NONACT`-Zeit überschritten wird.

Um den User Exit `NATRPC39` zu aktivieren:

1. Kopieren Sie den Beispiel-Exit `NATRPC39` aus der Library `SYSRPC` in die Library `SYSTEM` in der Systemdatei `FUSER`.

   Die Steplib-Verkettung der Library, bei der der Server gerade angemeldet ist, wird nicht ausgewertet.

2. Passen Sie die Datenbankkennung, die dem Feld `ACB-RSP` zugeordnet ist, an Ihre Bedürfnisse an.

3. Fügen Sie Ihrem `NATRPC39` zusätzliche `CALL 'CMADA'`-Statements hinzu, die auf weitere Datenbankkennungen verweisen, wenn mehr als eine Adabas-Datenbank beteiligt ist.

### User Exit NATRPC01

Der User-Exit `NATRPC01` wird aufgerufen, wenn ein Natural-Fehler aufgetreten ist, und zwar nachdem der Fehler von der Natural RPC-Laufzeit behandelt wurde und unmittelbar bevor die Rückmeldung an den Client zurückgesendet wird. Das heißt, der Exit wird an der gleichen logischen Stelle wie eine Fehlertransaktion aufgerufen, nämlich am Ende der Natural-Fehlerbehandlung, nachdem alle `ON ERROR`-Statement-Blöcke abgearbeitet worden sind.

Im Gegensatz zu einer Fehlertransaktion wird dieser Exit mit einem `CALLNAT`-Statement aufgerufen und muss daher ein Subprogramm sein, das zu seinem Aufrufer zurückmelden muss.

Die Schnittstelle zu diesem Exit ist ähnlich wie die Schnittstelle einer Fehlertransaktion. Darüber hinaus kann der Exit bis zu 10 Zeilen an Informationen zurückgeben, die von der Natural RPC-Laufzeit protokolliert werden. Nur Zeilen, die mit einem Nicht-Leerzeichen beginnen, werden aufgezeichnet.

Ein Beispiel-User Exit NATRPC01 befindet sich in der Library `SYSRPC`.

#### Wichtige Hinweise:

1. `NATRPC01` muss sich in der Library `SYSTEM` in der Systemdatei `FUSER` befinden.

2. Der Statement-Block `DEFINE DATA PARAMETER` darf nicht geändert werden.

## Benutzer-Exits vor und nach der Ausführung von Diensten

Um Administratoren mehr Kontrolle über die Ausführung von Diensten (Remote `CALLNAT`s) zu geben, werden auf der Natural RPC Server-Seite zwei optionale User Exits aufgerufen.

User Exit | Zweck
--- | ---
`NATRPC02` | Der optionale Before-Service-Exit `NATRPC02` wird unmittelbar vor der Ausführung des Dienstes aufgerufen. Zu diesem Zeitpunkt hat die Anforderung bereits alle Sicherheitsprüfungen durchlaufen und die Daten sind "unmarshalled".
`NATRPC03` | Der optionale After-Service-Exit `NATRPC03` wird unmittelbar nach der erfolgreichen Rückkehr von dem Dienst aufgerufen. Zu diesem Zeitpunkt sind die Daten noch nicht "marshalled". Der Exit wird nicht aufgerufen, wenn ein unbehandelter Fehler aufgetreten ist

Diese Exits sind unabhängig voneinander und können separat verwendet werden.

Für beide Exits gelten die folgenden Regeln:

- Der Exit muss sich in der Library `SYSTEM` in der Systemdatei `FUSER` befinden.

  Wird der Exit beim Starten des Natural RPC Servers gefunden, wird eine Meldung in den Natural RPC Server Trace geschrieben, um die Aktivierung des Exits anzuzeigen. Der Exit wird anschließend ohne Vorbedingungen aufgerufen. Wird der Exit während der Lebensdauer der Server-Sitzung entfernt, tritt ein permanenter NAT0082-Fehler auf.

  Wird der Exit beim Starten des Natural RPC Servers nicht gefunden, wird er während der Lebensdauer der Serversitzung nie aufgerufen. Der Exit kann nicht dynamisch aktiviert werden.

- Der Exit muss vom Anwender als Subprogramm implementiert werden. Der Exit wird mit einer einzigen dynamischen Variable als Parameter aufgerufen. Der Inhalt der dynamischen Variablen ist der acht Zeichen lange Name des Remote-Subprogramms.

  Die Verwendung der dynamischen Variable ermöglicht es, künftige Erweiterungen der übergebenen Informationen zu implementieren, ohne dass es zu Problemen mit bestehenden, vom Anwender geschriebenen Exits kommt.

- Der Exit wird auch innerhalb einer Konversation aufgerufen.

- Der Natural RPC Server fängt unbehandelte Fehler im Exit nicht ab. Tritt ein unbehandelter Fehler im Exit auf, wird der Fehler an den Client weitergegeben.

Die Exits können für Auditing- oder Tracing-Zwecke verwendet werden. `NATRPC02` kann auch für zusätzliche Sicherheitsüberprüfungen verwendet werden.

#### Beispiel für `NATRPC02`:

    DEFINE DATA PARAMETER
    1 SUBPROGRAM (A8) BY VALUE
    END-DEFINE
    IF *USER <> 'DBA' AND SUBPROGRAM = 'PRIVATE'
      *ERROR-NR := 999
    END-IF
    END

### On this page

- RPC-Server-Adressen festlegen
- Interface-Objekte und automatische RPC-Ausführung
- RPC-Profilparametern während einer Natural-Sitzung abfragen/ändern
- Server-Kommandos ausführen
- Kommando an einen RPC-Server senden
- Anmeldung bei einer Server Library
- Logon-Option benutzen
- Komprimierung verwenden
- Secure Socket Layer verwenden
- Den Status einer RPC-Sitzung überwachen
- Laufzeiteinstellungen eines Servers abrufen
- Parameter für EntireX setzen/abfragen
- Message ID und Correlation ID von EntireX verwalten
- Behandlung von Fehlern
- Benutzer-Exits vor und nach der Ausführung von Diensten