Besondere Hinweise

Dieses Kapitel behandelt Themen, die für Entwickler relevant sind.

Entwicklung von Natural-Subprogrammen für Natsubsrv

Dieses Dokument behandelt die Unterschiede, die bestehen, wenn ein Natural-Subprogramm vom Natural Subprogram Server (Natsubsrv) statt von einer Terminalsitzung ausgeführt wird.

Es handelt sich hierbei nicht um eine Einführung in die Natural-Programmierung – dazu siehe die Dokumentation des Basisprodukts Natural.

Die Unterschiede sind auf zwei Eigenschaften zurückzuführen:

  • Kein Terminal. Es handelt sich um eine Serversitzung; es gibt weder einen Bildschirm noch eine Tastatur.

  • Kein Zwischenzustand zwischen Aufrufen. Eine Sitzung bedient nacheinander die Anfragen vieler Endbenutzer und wird bei jeder Anfragegrenze zurückgesetzt.

Dieses Dokument behandelt die folgenden Themen:

Ausführungsmodell

  • Das Subprogramm wird über einen CALLNAT aufgerufen und über sein normales Ende oder über ESCAPE ROUTINE verlassen.

  • Der DEFINE DATA PARAMETER-Block ist der einzige Datenkanal zum und aus dem Subprogramm.

  • Jede Anfrage benennt ihre eigene Bibliothek und ihren eigenen Benutzer; beide werden vom Server vor dem CALLNAT festlegt.

  • Die Sitzung wird an der Anfragegrenze zurückgesetzt, sodass jeder Aufruf aus einem definierten Zustand startet und keine Spur hinterlässt.

Mapping von OpenAPI-Namen

In einem Subprogramm können Sie den Namen des API-Parameters definieren, der auf einen Natural-Parameter gemappt werden soll.

Dies geschieht durch Hinzufügen des Präfixes oapi.n:, gefolgt vom gewünschten Eigenschaftsnamen, im Kommentar des Feldes.

Beispiel in Natural:

#PARAM1 (A1)  /*  oapi.n:nameParm IN

Dadurch wird ein API-Parameter namens nameParm erstellt, der auf den Natural-Parameter #PARAM1 gemappt wird.

Nicht zulässige bzw. eingeschränkte Statements

Nicht zulässige Statements

Statement Grund
TERMINATE Beendet die vom Server verwaltete Sitzung. Die Anfrage wird abgebrochen und die Ausgabeparameter werden nicht zurückgeschrieben.
STOP Verlässt den CALLNAT, ohne die Ausgabeparameter zurückzuschreiben. Verwenden Sie ESCAPE ROUTINE.
FETCH Startet ein Programm innerhalb der Anfrage. Der Rest des Subprogramms wird nicht ausgeführt und die Ausgabeparameter werden nicht zurückgeschrieben.
RUN Erfordert Quellcode und einen Compiler in einer Sitzung, die Anfragen bedient.
LOGON Die Bibliotheksumgebung wird vom Server pro Anfrage eingerichtet.
REINPUT Erfordert ein Terminal.
Maps (INPUT USING MAP, WRITE USING MAP), PROCESS PAGE Erfordert ein Terminal.
SET KEY Erfordert ein Terminal. Die PF-Tasteneinstellungen werden pro Anfrage zurückgesetzt.
SET CONTROL Erfordert ein Terminal.
OPEN CONVERSATION, CLOSE CONVERSATION Konversationaler RPC wird nicht unterstützt.
DEFINE DATA CONTEXT Kontextvariablen sind die Daten einer Konversation, und es gibt keine. Der Bereich gehört zu dem einzelnen CALLNAT, der ihn erstellt, und wird mit diesem freigegeben, sodass er nichts von einem Aufruf zum nächsten überträgt. Verwenden Sie den PARAMETER-Block.

Eingeschränkt verwendbare Statements

Statement Was ist möglich?
STACK Daten können auf den Stack gelegt und innerhalb derselben Anfrage wieder ausgelesen werden. Kommandos werden nicht ausgeführt.
INPUT Nur ohne Terminal-E/A, d. h. beim Lesen von Daten vom Stack. Jedes INPUT-Statement, das einen Bildschirm anspricht, schlägt fehl.

Verursachen einer Sperrung nicht zulässig

Ein gesperrtes Subprogramm blockiert die Sitzung, in der es ausgeführt wird, und damit jede Anfrage, die von diesem Subprogramm bedient worden wäre.

  • Warten Sie nicht auf benutzerseitige Interaktionen, externe Ereignisse oder an anderer Stelle vorhandene Sperren.

  • Halten Sie CALLs zu 3GL-Modulen kurz. Der Server kann einen laufenden 3GL-Aufruf nicht unterbrechen, sodass die Sitzung so lange belegt bleibt, wie der Aufruf dauert.

  • Halten Sie Arbeitseinheiten kurz. Datenbanksperren werden bis zu einem END TRANSACTION oder BACKOUT TRANSACTION aufrechterhalten, sodass eine lange Arbeitseinheit andere Anfragen von denselben Datensätzen fernhält.

Das Gleiche gilt für das Subprogramm als Ganzes: Während seiner Laufzeit steht die Sitzung für alle anderen nicht zur Verfügung.

Zustandslosigkeit

Jeder Aufruf muss für sich allein stehen: Er darf keine Daten weitergeben und darf nicht auf Daten zurückgreifen, die von einem früheren Aufruf hinterlassen wurden.

Folgende Elemente werden an jeder Anfragegrenze in einen definierten Zustand zurückversetzt:

  • Globale Datenbereiche, einschließlich des globalen Datenbereichs mit Namen COMMON.

  • Anwendungsunabhängige Variablen (DEFINE DATA INDEPENDENT).

  • Session-Parameter, einschließlich derer, die mit SET GLOBALS und *LANGUAGE geändert wurden.

  • Die Profilparameter zur Angabe von Maximalwerten MADIO, MAXCL, MAXERR und LT.

  • Steplib-Ketten.

  • Retained Sets und Adabas-Kommandokennungen (CIDs/Command IDs).

  • PF-Tasteneinstellungen.

Ein globaler Datenbereich (GDA) ist zu Beginn jeder Anfrage leer, sofern das Subprogramm ihn nicht selbst füllt, und ein durch RETAINED in einer Anfrage zurückbehaltener Set existiert in der nächsten Anfrage nicht mehr.

Auch mit Kontextvariablen (DEFINE DATA CONTEXT) lässt sich dies nicht umgehen. Ohne eine Konversation stellen sie keinen Datenbereich dar, der sich über Aufrufe hinweg erstreckt: Der Kontext existiert nur für den einen CALLNAT und ist nach dessen Rückkehr nicht mehr vorhanden, sodass er weder einen Zustand weitergeben noch von der nächsten Anfrage gelesen werden kann. Weitere Informationen finden Sie unter Nicht zulässige Statements.

*ETID und die darunter gespeicherten ET-Daten gehören zur Sitzung, nicht zum Endbenutzer. Sie werden von allen Anfragen gemeinsam genutzt, die die Sitzung bedient, und dürfen nicht zur Übertragung benutzerspezifischer Zustände verwendet werden.

Transaktionen und Arbeitsdateien (Work Files)

Beenden Sie Ihnen gehörende Arbeitseinheiten, d.h. vervollständigen Sie jede einzelne Arbeitseinheit mit END TRANSACTION oder BACKOUT TRANSACTION, bevor Sie sie zurückgeben. Der Server führt kein Festschreiben (Commit) durch.

Bei Erreichen der Anfragegrenze nimmt der Server normalerweise ein Rollback der Transaktion vor (BACKOUT TRANSACTION) und schließt offene Arbeitsdateien. Unter Linux können Sie beide Verhaltensweisen mit den Parametern backoutTransactionPerRequest und closeWorkFilesPerRequest deaktivieren; andernfalls werden beide Verhaltensweisen immer ausgeführt.

Anmerkungen:

  1. Eine Arbeitseinheit, die nicht innerhalb der Anfrage festgeschrieben (committed) wird, ist verloren.
  2. Datensätze dürfen nicht über Aufrufe hinweg gehalten werden.
  3. Eine Arbeitsdatei muss innerhalb einer Anfrage geöffnet, verwendet und geschlossen werden. CLOSE MODE=USER hält sie nicht über die Anfragegrenze hinweg offen.

Fehlerbehandlung

Fehler, die während der Verarbeitung einer Anfrage auftreten, werden vom Server abgefangen und dem Aufrufer mit Fehlernummer, Zeile, Status und Objektname gemeldet.

Es wird empfohlen, das Statement ON ERROR zu verwenden, um Fehler als Daten zurückzugeben, auf die der Aufrufer reagieren kann – einen Fehlercode und eine Meldung in den Ausgabeparametern – und unbehandelte Fehler für wirklich unerwartete Bedingungen zu reservieren. Führen Sie die Bereinigung auf dem Fehlerpfad genau wie auf dem Erfolgspfad durch.

Systemvariablen

Variable Wert
*SERVER-TYPE CALLNAT
*USER Der Benutzer der aktuellen Anfrage in Großbuchstaben, bis zu 8 Zeichen.
*NET-USER Der Benutzer der aktuellen Anfrage, wie bei *USER. Unter z/OS enthält diese Variable stattdessen den Benutzer der vom Server gestarteten Sitzung – denselben Wert wie *INIT-USER — und identifiziert daher nicht den anfragenden Benutzer.
*LIBRARY-ID Der Name der von der aktuellen Anfrage angegebene Bibliothek.
*INIT-USER, *INIT-ID, *ETID Die vom Server gestartete Sitzung, nicht der anfragende Benutzer. Unter z/OS enthält *INIT-ID eine Sitzungsnummer, die der Server bei jeder neuen Sitzung erhöht.
*DEVICE Ein Batch-Gerät.

Checkliste