Aufruf von Natural aus Benutzerprogrammen

#### Search Results

Search

# Aufruf von Natural aus Benutzerprogrammen

Dieses Kapitel beschreibt die verschiedenen Möglichkeiten, wie Natural aus Benutzerprogrammen aufgerufen werden kann.

Folgende Themen werden behandelt:

- Kommandos zum Aktivieren einer Natural-Sitzung

- Frontend-Parameter

- Frontend-Aufruf über LINK

- Frontend-Aufruf über RETURN IMMEDIATE

- Frontend-Aufruf über START

- Frontend-Aufruf über XCTL

- Frontend-Aufruf über Distributed Program Link (DPL)

- Aufruf eines Frontend-Programms als Backend

## Kommandos zum Aktivieren einer Natural-Sitzung

Eine Natural-Sitzung kann von Benutzer-Frontend-Programmen mit einem der folgenden Kommandos aktiviert werden:

- `EXEC CICS XCTL`

- `EXEC CICS LINK`

- `EXEC CICS RETURN IMMEDIATE`

- `EXEC CICS START`

oder die entsprechenden Anforderungen aus der CICS-Makroebene.

Die Kommandos zum Aktivieren einer Natural-Sitzung werden in den folgenden Abschnitten beschrieben:

- Verwendung von EXEC CICS XCTL oder EXEC CICS LINK

- Verwendung von EXEC CICS RETURN IMMEDIATE

- Verwendung von EXEC CICS START

- Verwendung von Distributed Program Link (DPL)

- Beispielprogramme

- Verwendung der externen Subroutine CMTASK

### Verwendung von EXEC CICS XCTL oder EXEC CICS LINK

Bei Verwendung von `EXEC CICS XCTL/LINK` können die von Natural verwendeten Parameter in einer CICS COMMAREA oder in der TWA übergeben werden.

- Natural bestimmt, an welcher Stelle sich die Startparameter befinden, indem es die Länge der COMMAREA prüft, die ihm während der Sitzungsinitialisierung zur Verfügung übergeben wird.

- Wenn die Länge 22 beträgt, versucht Natural, die Parameter in der COMMAREA zu finden, andernfalls wird angenommen, dass sie in der TWA übergeben wurden.

Um ein Frontend-Programm korrekt zu identifizieren, müssen die ersten 4 Bytes der Frontend-Parameterliste die aktuelle Transaktionskennung enthalten.

Die mit dem Frontend-Programm verknüpfte Transaktionskennung muss eine TWA-Größe haben, die gleich oder größer als die Natural-TWA-Größe ist. Siehe auch `ncitransact` in Installing Natural CICS Interface on z/OS in der Natural Installation-Dokumentation.

### Verwendung von EXEC CICS RETURN IMMEDIATE

Bei Verwendung von`EXEC CICS RETURN IMMEDIATE` können die von Natural verwendeten Frontend-Parameter in einer CICS COMMAREA und die von Natural verwendeten dynamischen Parameter mit `INPUTMSG (...)` und `INPUTMSGLEN (...)` des Kommandos `EXEC CICS RETURN IMMEDIATE` übergeben werden.

### Verwendung von EXEC CICS START

Bei Verwendung von `EXEC CICS START` können die von Natural verwendeten Frontend- und dynamischen Parameter mit `FROM (...)` und `LENGTH (...)` des Kommandos `EXEC CICS START` übergeben werden. Die Parameter werden weiter unten beschrieben.

### Verwendung von Distributed Program Link (DPL)

Wenn Sie `EXEC CICS LINK` mit dem Parameter `SYSID` verwenden, der auf eine entfernte Region zeigt, müssen die von Natural verwendeten Frontend- und dynamischen Parameter in einer CICS COMMAREA übergeben werden. Außerdem muss ein `TRANSID`-Parameter angegeben werden, der den Transaktionscode einer Spiegeltransaktion mit einer TWA-Größe angibt, die den Erfordernissen von Natural entspricht.

Es ist zu beachten, dass für Natural-Sitzungen, die über DPL aufgerufen werden, dieselben Einschränkungen wie für asynchrone Natural-Sitzungen gelten, d.h. es sind keine Eingaben möglich (daher werden dieselben dynamischen Parametereinstellungen empfohlen) und der Aufrufer erhält nach Beendigung der Natural-Sitzung lediglich die Kontrolle zurück.

### Beispielprogramme

Eine Reihe von Beispielprogrammen für die verschiedenen Programmiertechniken ist in der Natural CICS Source Library enthalten. Siehe auch Natural CICS-Beispielprogramme

### Verwendung der externen Subroutine CMTASK

Sie können eine Natural-Sitzung aus einem Natural-Programm heraus starten, indem Sie die externe Subroutine `CMTASK` aufrufen. Siehe dazu das Natural-Beispielprogramm `ASYNCICS` in der Library `SYSEXTP`.

## Frontend-Parameter

Die folgende Liste mit Parametern muss übergeben werden, um Natural von einem Benutzer-Frontend-Programm aus aufzurufen:

Pos. | Inhalt
--- | ---
`1 - 4` | Aufrufende Transaktionskennung Dieser Wert muss mit der aktuellen Transaktionskennung übereinstimmen. Über die aufrufende Transaktionskennung erkennt Natural, dass es von einem Benutzer-Frontend-Programm aufgerufen wurde. Beim Aufruf mit `XCTL` wird die Transaktion am Ende der Natural-Sitzung über `RETURN` mit `TRANS ID` neu gestartet, es sei denn, es wird ein Rückkehrprogrammname angegeben (siehe 5. Parameter).
`5 - 8` | Adresse/Offset des dynamischen Parameterstrings Wenn dynamische Parameterüberschreibungen ausgewertet werden sollen, sollte dieser Wert auf die Adresse gesetzt werden, die 12 Bytes vor dem dynamischen Parameterzuweisungsstring liegt. Beim Aufruf mit `START` oder DPL muss das Feld auf den Offset (relativ zum Beginn der Frontend-Parameterliste) der Adresse gesetzt werden, die 12 Bytes vor dem dynamischen Parameterzuweisungsstring liegt.
`9 - 10` | Länge des dynamischen Parameterstring Null bedeutet, dass keine Parameter übergeben werden sollen. `32760` ist die maximal zulässige Länge. Wird der Maximalwert überschritten, wird die Sitzung mit einer entsprechenden Fehlermeldung beendet.
`11 - 14` | Natural-Transaktionskennung Der angegebene Wert ist die Transaktionskennung, die zur Steuerung einer pseudokonversationellen Natural-Sitzung verwendet wird, wenn diese mit `START` oder `XCTL` aufgerufen wird. Diese Transaktion wird jedes Mal aufgerufen, wenn die Natural-Sitzung im pseudokonversationellen Modus neu gestartet wird, d.h. bei jeder Terminal-Ein-/Ausgabe. Wird die Natural-Transaktionskennung nicht angegeben, startet Natural erneut mit der Transaktionskennung, mit der die aktuelle CICS-Task gestartet wurde, und das Frontend-Programm erhält nach jeder pseudokonversationellen Ein-/Ausgabe wieder die Kontrolle zurück.
`15 - 22` | Name des Backend-Programms Dieser 8-Byte-Wert ist der Name des Programms, an das die Kontrolle am Ende der Natural-Sitzung mit einem CICS `XCTL`-Kommando übergeben wird, anstatt die aufrufende Transaktionskennung über `RETURN` mit `TRANSID` neu zu starten. Wenn das erste Byte dieses Feldes numerisch ist, führt Natural einfach `RETURN` aus, ohne ein Backend zu aktivieren. Beachten Sie, dass dieses Feld durch den Natural-Profilparameter `PROGRAM` überschrieben werden kann. Die Konventionen für den Aufruf von Nicht-Natural-Backend-Programmen finden Sie unter Konventionen für den Aufruf von Backend-Programmen in der Natural Operations-Dokumentation.

## Frontend-Aufruf über LINK

Bei der Rückkehr zum Frontend gibt Natural in der TWA an, ob die Sitzung beendet wurde oder nicht: Wenn die Sitzung beendet wurde, enthält die TWA reguläre Backend-Informationen (siehe Konventionen für den Aufruf von Backend-Programmen in der Operations-Dokumentation), andernfalls setzt Natural die `NEXTTRANSID` in die ersten vier Bytes der TWA.

Wenn Natural im pseudokonversationellen Modus läuft (Profilparameter `PSEUDO` auf `ON` gesetzt) und durch `EXEC CICS LINK` (oder die entsprechende Anforderung auf CICS-Makroebene) aufgerufen wurde, wird die ursprüngliche aufrufende Transaktion jedes Mal aufgerufen, wenn Natural auf ein Terminal schreibt und auf eine Eingabe wartet, was bedeutet, dass Natural eine "logische" `CICS RETURN TRANSID (..)` ausgibt, nachdem es seine Neustartinformationen in den CICS-Zwischenspeicher geschrieben hat.

Die aufrufende Transaktion muß diese Situation erkennen (z.B. durch Überprüfung, ob ein `NEXTTRANSID` gesendet wurde oder durch das Vorhandensein von `NCOMxxxx` TS-Sätzen - wobei `NCOM` die Natural CICS-Parametergenerierungsoption und `xxxx` die Terminalkennung ist -) und die Kontrolle an Natural zurückgeben.

Der Vorteil dieser Vorgehensweise ist, dass das Frontend-Programm während der Sitzung beschließen kann, die Kontrolle an eine andere Anwendung (z.B. COBOL) zu übergeben und die Natural-Sitzung später wieder aufzunehmen.

Weitere Einzelheiten finden Sie in der Beschreibung des Parameters `PSEUDO` in der Parameter-Referenz-Dokumentation.

Natural behandelt ein LINK-Frontend-Programm beim Beenden der Sitzung wie ein Backend-Programm, d.h. es gelten die Konventionen für den Aufruf von Backend-Programmen.

### In CICSplex-Umgebungen

Stellen Sie sicher, dass alle beteiligten CICS-AORs auf die `NCOMxxxx` TS-Sätze zugreifen können (z.B. über entsprechende CICS-TST-Definitionen).

Alternativ kann das LINK-Frontend-Programm die NCI-Sitzungsneustart-Informationen bei Task-Ende auch im CICS-Zwischenspeicher abholen und selbst in einer CICS-COMMAREA übergeben. Eine solche COMMAREA muss dann vor dem Aufruf von Natural zur Sitzungswiederaufnahme wieder im CICS-Zwischenspeicher abgelegt werden.

## Frontend-Aufruf über RETURN IMMEDIATE

Frontend-Aufruftechnik funktioniert nur bei Natural-Terminalsitzungen. Natural sucht nach Startparametern, die mit dem COMMAREA übergeben werden. Beachten Sie, dass bei dieser Technik potenzielle dynamische Parameter nicht verkettet an die Frontend-Parameter übergeben werden können, d.h. die Adressfelder der dynamischen Parameter müssen Null sein. Stattdessen können potenzielle dynamische Parameter über Terminaleingabedaten übergeben werden, die Natural durch ein `EXEC CICS RECEIVE`-Kommando erhält.

## Frontend-Aufruf über START

Wenn es sich bei der Natural-Sitzung um eine gestartete Task handelt (d.h. durch ein `EXEC CICS START`- oder `EXEC CICS LINK/XCTL`-Kommando von einem gestarteten Frontend-Benutzerprogramm aufgerufen), sucht Natural zunächst nach mit der COMMAREA gelieferten Startparametern, dann nach Parametern in der TWA und schließlich versucht es, die erforderlichen Parameter durch ein `EXEC CICS RETRIEVE`-Kommando zu erhalten.

## Frontend-Aufruf über XCTL

Wenn die Natural-Sitzung von einem Frontend-Programm mit `XCTL` initiiert wird und kein Rückkehrprogramm angegeben ist (d.h. weder ein fünfter Parameter in den Sitzungsstartparametern noch eine `PROGRAM`-Angabe in den dynamischen Natural-Parametern oder dem `NTPRM`-Makro), startet Natural die Benutzer-Frontend-Transaktion bei Sitzungsende über `RETURN` mit `TRANSID` neu, indem es intern eine Angabe `PROGRAM='RET=xxx'` simuliert, wobei `xxx` der Code der Frontend-Transaktion ist.

Um eine Schleifenbildung zu vermeiden, muss in die Benutzer-Frontend-Routine eine Logik aufgenommen werden, die entscheidet, ob eine neue Sitzung gestartet oder eine alte Sitzung fortgesetzt werden soll.

## Frontend-Aufruf über Distributed Program Link (DPL)

Wenn die Natural-Sitzung über DPL aufgerufen wird, stellt Natural zunächst fest, ob sie direkt in der Server-Region oder indirekt über `EXEC CICS LINK/XCTL` durch ein lokales Frontend-Programm aufgerufen wird. Bei einem direkten Aufruf holt Natural die Startparameter aus der CICS COMMAREA. Beim indirekten Aufruf sucht Natural nach Startparametern, die mit der COMMAREA geliefert werden, und dann nach Parametern in der TWA. Bei der Rückkehr übergibt Natural normale Backend-Daten in der TWA, wenn ein lokales LINK-Frontend-Programm verfügbar ist, andernfalls gibt es die Abbruchmeldung und potenzielle Backend-Daten in der COMMAREA des Remote-Client zurück.

## Aufruf eines Frontend-Programms als Backend

Wenn die Natural-Sitzung von einem Frontend-Programm initiiert wird und dieses Programm auch als Rückkehrprogramm angegeben ist, sollte das Benutzer-Frontend auch die initiierende Transaktionskennung überprüfen.

Dies gilt insbesondere dann, wenn sich das Frontend-Programm nicht im pseudokonversationellen Modus befindet, Natural aber im konversationellen Modus ist.

In diesem Fall wird Natural erneut aufgerufen, anstatt beendet zu werden, aber dieses Mal ohne zu erkennen, dass es von einem Frontend-Programm aufgerufen wird, da der erste Parameter in den Startparametern die Natural-Transaktionskennung ist.

### On this page

- Kommandos zum Aktivieren einer Natural-Sitzung
- Frontend-Parameter
- Frontend-Aufruf über LINK
- Frontend-Aufruf über RETURN IMMEDIATE
- Frontend-Aufruf über START
- Frontend-Aufruf über XCTL
- Frontend-Aufruf über Distributed Program Link (DPL)
- Aufruf eines Frontend-Programms als Backend