PGWT Wartepunkt im Programm setzen ohne Teilprogrammende

Mit dem Aufruf PGWT (program wait) wird das Teilprogramm auf einen internen Wartepunkt gesetzt, ohne es zu beenden. Dabei haben Sie die Möglichkeit,

• den Verarbeitungsschritt zu beenden ohne die Transaktion zu beenden

• weder den Verarbeitungsschritt noch die Transaktion zu beenden, um auf eine Nachricht an einer Service-gesteuerten Message Queue zu warten (kein vorheriger MPUT erlaubt!)

• die Transaktion zu beenden. Falls zuvor eine MPUT-Nachricht gesendet wird, wird der Verarbeitungsschritt beendet, ansonsten wird er fortgesetzt.

• die Transaktion zurückzusetzen und den Verarbeitungsschritt fortzusetzen

Das Teilprogramm wird immer vom selben Prozess fortgesetzt (Prozess-Id bleibt erhalten). Der PGWT-Aufruf ist vergleichbar mit einem PEND-Aufruf mit anschließendem impliziten INIT-Aufruf. Geben Sie beim Aufruf im KDCS-Parameterbereich den Parameter KCLI mit einem Wert größer als 0 an, dann liefert openUTM Information über Anwendung, System, Kommunikationspartner. Der PGWT-Aufruf ist dann vergleichbar mit einem PEND-Aufruf mit anschließendem impliziten INIT PU-Aufruf.

Die folgende Tabelle zeigt die Bedeutung des PGWT-Aufrufs und die damit verknüpften Aktionen:

Variante	Bedeutung	Aktionen von openUTM
PGWT KP	Ende des Verarbeitungsschritts, ohne Teilprogramm- oder Transaktionsende, ggf. Informationen anfordern (KCLI > 0)	MPUT-Nachricht senden Programm fortsetzen sobald die Antwort vorliegt bei KCLI > 0: angeforderte Informationen im Nachrichtenbereich bereitstellen
PGWT PR	Warten ohne Beenden von Verarbeitungsschritt, Teilprogramm oder Transaktion, ggf. Informationen anfordern (KCLI > 0)	Programm fortsetzen sobald eine Nachricht an der Queue vorliegt bei KCLI > 0: angeforderte Informationen im Nachrichtenbereich bereitstellen
PGWT CM	Transaktion beenden ohne Beenden des Teilprogramms, ggf. Informationen anfordern (KCLI > 0)	Wenn MPUT gegeben wurde: MPUT-Nachricht senden und Programm fortsetzen, sobald die Antwort vorliegt. Ohne MPUT: Verarbeitung ohne Warten fortsetzen, Ausnahme bei OSI TP siehe "PGWT-Aufruf in einem verteilten OSI TP-Vorgang mit Commit". bei KCLI > 0: angeforderte Informationen im Nachrichtenbereich bereitstellen
PGWT RB	Transaktion zurücksetzen, ggf. Informationen anfordern (KCLI > 0)	Rücksetzen einer Transaktion Verarbeitung fortsetzen, Ausnahme bei OSI TP siehe " PGWT-Aufruf in einem verteilten OSI TP-Vorgang mit Commit ". bei KCLI > 0: angeforderte Informationen im Nachrichtenbereich bereitstellen

Bei allen PGWT-Aufrufen bleibt der lokale Prozess während der Wartezeit bzw. der Kommunikation belegt. Bei den Aufrufen PGWT KP/PR bleiben darüber hinaus Betriebsmittel gesperrt. Verwenden Sie PGWT-Aufrufe daher sparsam und wohlüberlegt.

Versorgung des KDCS-Parameterbereichs (1. Parameter)

Funktion des Aufrufs	Einträge im KDCS-Parameterbereich
	KCOP	KCOM	KCLI
Beenden des Verarbeitungsschritts ohne Teilprogramm- oder Transaktionsende	"PGWT"	"KP"	0 / Länge des Nachrichtenbereichs
Warten ohne Beenden von Verarbeitungsschritt und Transaktion	"PGWT"	"PR"	0 / Länge des Nachrichtenbereichs
Beenden der Transaktion ohne Teilprogrammende	"PGWT"	"CM"	0 / Länge des Nachrichtenbereichs
Rücksetzen der Transaktion und Fortsetzen des Verarbeitungsschritts	"PGWT"	"RB"	0 / Länge des Nachrichtenbereichs

Versorgung des 2. Parameters (nur notwendig bei KCLI > 0)

Hier geben Sie die Adresse des Nachrichtenbereichs an, in den openUTM die angeforderte Information schreiben soll. Für die Strukturierung des Nachrichtenbereichs können Sie die gleiche Datenstruktur verwenden wie für den INIT PU-Aufruf, also für COBOL das COPY-Element KCINIC, für C/C++ die Include-Datei kcini.h.

Im Header der Datenstruktur geben Sie die Versionsnummer der Struktur an und wählen aus, welche Information openUTM zurückliefern soll.

Der genaue Aufbau der Datenstruktur ist beim INIT PU-Aufruf in Kapitel "INIT Initialisieren eines Teilprogramms" beschrieben.

Versorgen der Parameter
Feldname im KDCS-Parameterbereich	Inhalt
KCOP	"PGWT"
KCOM	"KP"/"PR"/"CM"/"RB"
KCLI	0 / Länge in Byte

Versorgen des Headers des Nachrichtenbereichs (nur notwendig bei bei KCLI > 0)
Feldname im Nachrichtenbereich	Inhalt
KCVER/if_ver	Versionsnummer (7)
KCDATE/dattim_info	Anfordern von Datum und Uhrzeit (Y/N)
KCAPPL/appl_info	Anfordern von Anwendungsinformation (Y/N)
KCLOCALE/locale_info	Anfordern von Locale Information (Y/N)
KCOSITP/ositp_info	Anfordern von OSI TP Informationen (Y/N)
KCENCR/encr_info	Anfordern von Verschlüsselungs-Informationen (Y/N)
KCMISC/misc_info	Anfordern von verschiedenen Informationen (Y/N)
KCHTTP/http_info	Anfordern von HTTP Informationen (Y/N)

KDCS-Aufruf
1. Parameter	2. Parameter
KDCS-Parameterbereich	Nachrichtenbereich (nur notwendig bei KCLI > 0)

C/C++-Makroaufrufe
Makronamen	Parameter
KDCS_PGWTKP	()
KDCS_PGWTKP_PU/KDCS_PGWTPR/KDCS_PGWTCM/KDCS_PGWTRB	(nb,kcli)

Rückgaben von openUTM
Nachrichtenbereich	Inhalt
	Daten (nur bei KCLI > 0)
Feldname im KB-Rückgabebereich
KCRLM	Länge der übertragenen Daten (nur bei KCLI > 0)
KCRCCC	Returncode
KCRCDC	interner Returncode
KCRMF/kcrfn	Formatkennzeichen / Leerzeichen
KCRPI	Vorgangs-Id / Reset-Id / Leerzeichen

Im KDCS-Parameterbereich machen Sie für den PGWT-Aufruf folgende Einträge:

KCOP

im Feld KCOP den Operationsnamen "PGWT".

KCOM

im Feld KCOM die Variante des PGWT-Aufrufs:

• KP: Ende des Verarbeitungsschritts ohne Transaktionsende.

• PR: Warten ohne Beenden von Verarbeitungsschritt und Transaktion

• CM: Ende der Transaktion

• RB: Rücksetzen der Transaktion

KCLI

im Feld KCLI die Länge des Nachrichtenbereichs, in den openUTM die Information übertragen soll. Die Länge müssen Sie als Anzahl Bytes angeben. openUTM überträgt maximal so viel Bytes Information in den Nachrichtenbereich wie in KCLI angegeben wird.

Ist KCLI größer null, dann muss bei dem Aufruf als 2. Parameter die Adresse des Nachrichtenbereichs angegeben werden. Die Information entspricht der des INIT PU- Aufrufs.

Alle nicht verwendeten Felder des Parameterbereichs müssen binär null enthalten.

Versorgen des Headers des Nachrichtenbereichs (nur notwendig bei KCLI > 0):

KCVER/if_ver

Im Feld KCVER/if_ver geben Sie die Versionsnummer der Datenstruktur an, die derzeit aktuelle Version ist 7.

KCDATE/dattim_info

Das Feld KCDATE/dattim_info versorgen Sie mit Y, falls Sie Informationen über Datum und Uhrzeit des Starts der Anwendung und des Teilprogrammlaufs haben wollen, sonst geben Sie N an.

KCAPPL/appl_info

Das Feld vrsorgen Sie mit Y, wenn Sie Informationen über Anwendung, System und Kommunikationspartner anfordern, sonst geben Sie N an.

KCLOCALE/locale_info

Das Feldvversorgen Sie mit Y, wenn Sie Informationen über die Sprachumgebung des LTERM-Partners anfordern, sonst geben Sie N an.

KCOSITP/ositp_info

Das Feld KCOSITP/ositp_info versorgen Sie mit Y, wenn Sie OSI TP-spezifische Informationen benötigen, sonst geben Sie N an.

KCENCR/encr_info

Das Feld vorgen Sie mit Y, wenn Sie Informationen über Verschlüsselungsverfahren benötigen, die zwischen dem Client und der UTM-Anwendung gefahren werden, sonst geben Sie N an. (Der Verschlüsselungsmechanismus kann vereinbart werden. Siehe openUTM-Handbuch „Anwendungen generieren“.)

KCMISC/misc_info

Das Feld KCMISC/misc_info versorgen Sie mit Y, wenn Sie verschiedene Informationen (z.B. Anzahl der Asynchron-Nachrichten in der Queue des Benutzers, Passwortgültigkeit, Zeitpunkt der letzten Anmeldung) benötigen, sonst geben Sie N an.

KCHTTP/http_info  

Das Feld  KCHTTP/http_info  versorgen Sie mit Y, wenn Sie HTTP-spezifische Informationen benötigen, sonst geben Sie N an.

Beim KDCS-Aufruf geben Sie an:

1. Parameter

als 1. Parameter: die Adresse des KDCS-Parameterbereichs.

2. Parameter

als 2. Parameter (nur notwendig bei KCLI ungleich 0):
die Adresse des Nachrichtenbereichs, in den openUTM die Informationen schreiben soll. Für die Rückgaben steht Ihnen die Datenstruktur KCINIC für COBOL und die Include-Datei kcini.h für C/C++zur Verfügung (Beschreibung siehe "INIT Initialisieren eines Teilprogramms").

Makronamen

Wie Sie Makroaufrufe für C/C++ nutzen, ist in Abschnitt „C/C++-Makroschnittstelle" ausführlich beschrieben.

openUTM gibt zurück:

Nachrichtenbereich

nur bei KCLI > 0:
im angegebenen Nachrichtenbereich die Information in der tatsächlichen, höchstens aber in der in KCLI angegebenen Länge. Die vom Aufruf PGWT gelieferten Daten entsprechen den Rückgabeinformationen des Aufrufs INIT PU (Beschreibung siehe "INIT Initialisieren eines Teilprogramms").

KCRLM

nur bei KCLI > 0:
im Feld KCRLM die tatsächliche Länge der von openUTM übergebenen Information, sofern KCRCCC = 000. Bei KDCRCCC = 07Z enthält KCRLM die Länge der insgesamt zur Verfügung stehenden Daten. Bei KCRCCC > 40Z ist KCRLM = 0.

KCRCCC

im Feld KCRCCC den KDCS-Returncode (Länge 3 Byte).
Die möglichen Returncodes und ihre Bedeutung siehe unten.

KCRCDC

im Feld KCRCDC den internen Returncode von openUTM (siehe openUTM-Handbuch „Meldungen, Test und Diagnose“).

  KCRMF/kcrfn

nur bei PGWT CM mit vorherigem MPUT und PGWT KP (ähnlich wie beim INIT-Aufruf):

• bei einer Nachricht von einem Terminal:

  Leerzeichen (im Zeilenmodus) oder den Formatnamen (im Formatmodus) der letzten Bildschirmausgabe, also den Namen der beim MPUT des letzten Dialog-Schritts im Feld KCMF/kcfn angegeben wurde.
  Bestand die letzte Ausgabe aus mehreren Teilformaten, so enthält KCRMF/kcrfn den Namen des ersten Teilformats, in das Daten eingegeben wurden. Wurden in keines der Teilformate Daten eingegeben, so enthält KCRMF/kcrfn den Namen des ersten Teilformats.

  Nur auf BS2000-Systemen: Wurde bei der letzten Bildschirmausgabe ein Editprofil verwendet, so enthält KCRMF/kcrfn dieses Editprofil.

• bei einer Nachricht von einer TS-Anwendung: Leerzeichen

• bei einer Nachricht vom LU6.1-Partner oder UPIC-Client:
  das Formatkennzeichen des ersten Nachrichtenteils, das der LU6.1-Partner oder UPIC-Client beim Senden angegeben hat.

  Besonderheit im LU6.1-Auftraggeber-Vorgang:
  Leerzeichen, wenn für die in KCRPI angegebene Vorgangs-Id eine
  Statusinformation vorliegt

• bei verteilter Verarbeitung über OSI TP:

  Wurde der Teilprogrammlauf auf Grund eines verteilten Dialogs gestartet, so enthält KCRMF/kcrfn im Auftraggeber-Vorgang den Namen der abstrakten Syntax, die der Nachricht vom Auftraggeber zugeordnet wurde; enthält das Feld Leerzeichen, dann ist als abstrakte Syntax die UDT-Syntax ausgewählt.

  Im Auftragnehmer-Vorgang enthält KCRMF/kcrfn den Namen der abstrakten Syntax, die der Nachricht von dem in KCRPI beschriebenen AN-Vorgang zugeordnet wurde; enthält das Feld Leerzeichen, dann ist als abstrakte Syntax die UDT-Syntax ausgewählt, oder von dem Partner liegt eine Fehlernachricht vor.

KCRPI

nur bei PGWT CM mit vorherigem MPUT und PGWT KP (ähnlich wie beim INIT-Aufruf):

• Bei einer Nachricht von einem LTERM-Partner: Leerzeichen.

• Im Auftraggeber-Vorgang bei verteilter Verarbeitung:
  die Vorgangs-Id des Auftragnehmer-Vorgangs, wenn eine Nachricht vom Auftragnehmer vorliegt.

• im Auftragnehmer-Vorgang bei verteilter Verarbeitung:
  Leerzeichen.

KDCS-Returncodes im Feld KCRCCC beim PGWT-Aufruf

Im Programm sind auswertbar:

000	Die Operation wurde erfolgreich ausgeführt. Falls beim Aufruf ein Nachrichtenbereich angegeben war (KCLI > 0), wurde die angeforderte Information in der vollen Länge in den Nachrichtenbereich übertragen.
07Z	Die Funktion wurde ausgeführt, der bereitgestellte Nachrichtenbereich ist zu kurz (Länge in KCLI zu kurz). Es wurde keine oder nur unvollständige Information zurückgegeben.
40Z	Bei PGWT CM: die Funktion wurde nicht ausgeführt. Es ist ein Fehler aufgetreten, der ein Vorsetzen der aktuellen Transaktion nicht erlaubt. Die Transaktion wurde implizit mit PGWT RB zurückgesetzt.
48Z	Nur bei KCLI größer Null: Ungültige Version der Datenstruktur.

Weitere Returncodes sind dem DUMP zu entnehmen:

70Z	Die Operation PGWT konnte nicht ausgeführt werden (System- bzw. Generierungsfehler, Deadlock, Timeout).
71Z	In diesem Programm wurde noch kein INIT gegeben oder der Aufruf wurde von einem MSGTAC-Programm ausgeführt.
72Z	Der Eintrag in KCOM ist ungültig oder es wurde KCOM = CM/RB angegeben und in der aktuellen verteilten Transaktion ist ein Partner beteiligt, mit dem über das LU6.1-Protokoll kommuniziert wird.
77Z	Die beim Aufruf angegebene Adresse des Nachrichtenbereichs ist ungültig.
82Z	Vor einem PGWT KP wurde ein MPUT an einen Teilprogrammlauf gegeben.
83Z	Vor einem PGWT KP hat das Teilprogramm keinen MPUT gegeben oder vor PGWT PR wurde ein MPUT gegeben.
87Z	Der PGWT-Aufruf steht im Widerspruch zum Transaktions- oder Vorgangs-Status.
88Z	Ungültige Schnittstellenversion der Datenstruktur (bei KCLI > 0).
89Z	Beim Aufruf der Funktion waren nicht verwendete Parameter nicht mit binär null versorgt.

Eigenschaften des PGWT-Aufrufs

• Wurden Nachrichten oder Nachrichtenteile, die openUTM nach dem INIT für das Programm bereithielt, im Programm mit MGET nicht gelesen, gehen sie verloren.

• PGWT KP und PR

• • Ein PGWT KP-Aufruf entspricht einem PEND KP mit anschließenden INIT/INIT PU. PGWT KP ist immer dann erlaubt, wenn ein PEND KP-Aufruf erlaubt ist.

  • Ein PGWT PR-Aufruf entspricht einem PEND PA/PR mit anschließenden INIT/INIT PU. PGWT PR ist nur sinnvoll, wenn zuvor ein DGET-Aufruf mit Warten abgesetzt wurde und wenn auf eine Nachricht für die angegebene Queue gewartet werden muss. Nach PGWT PR wartet das Programm, bis eine Nachricht für diese Queue eintrifft.

  • PGWT KP und PR bewirken keinen Sicherungspunkt! Die bei PGWT KP durch MPUT veranlassten Dialog-Nachrichten werden ausgegeben. Die restlichen Ausgabeoperationen LPUT, FPUT, SPUT, PTDA und die Freigabeaktion SREL bleiben bis zum nächsten Sicherungspunkt gespeichert.

  • PGWT KP und PR sperren Betriebsmittel (LSSBs, GSSBs, TLS, ULS, ggf. Bereiche in Datenbanken) über einen Verarbeitungsschritt hinaus. Aufrufe aus anderen Transaktionen (SGET, SPUT, SREL, PTDA oder GTDA), die auf diese

    Betriebsmittel zugreifen wollen, werden mit einem Returncode (40Z und KCRCDC-Code) abgewiesen. Deshalb wird empfohlen, bei Verwendung des PGWT KP/PR die globalen Betriebsmittel erst vor der Nutzung zu belegen und sie anschließend sofort wieder frei zu geben.

  • Wurde vor einem PGWT KP oder PR eine DB-Transaktion begonnen, wird diese Transaktion nicht abgeschlossen! Erst ein PEND RE, SP, FI, FC oder ein PGWT CM führen zum Transaktionsende. RSET, PEND, RS FR, ER oder PGWT RB setzen die Transaktion zurück.

  • Wenn die Transaktion zurückgesetzt wird, geht eine durch einen PGWT KP auszuführende MPUT-Ausgabe verloren. Der Vorgang wird auf den letzten Sicherungspunkt zurückgesetzt. Es wird sofort ein Vorgangswiederanlauf durchgeführt, sofern der Benutzer noch angemeldet ist.
    Wenn der Benutzer abgemeldet wurde, z.B. weil die Verbindung zum Client verloren ging, wird beim Anmelden ein Vorgangswiederanlauf durchgeführt, sofern die Benutzerkennung (in Anwendungen ohne Benutzerkennungen der LTERM-Partner) mit Wiederanlauf-Eigenschaft generiert ist (Generierungs-Operanden RESTART=YES der LTERM bzw. USER-Anweisung, siehe openUTM-Handbuch „Anwendungen generieren“).
    Nach einem Anwendungsende ist in stand-alone UTM-Anwendungen ein Vorgangswiederanlauf nur in UTM-S-Anwendungen möglich.

• PGWT CM und RB

• • PGWT CM mit MPUT-Nachricht ist immer dann erlaubt, wenn auch ein PEND RE erlaubt ist. PGWT CM entspricht dann PEND RE mit anschließendem INIT/INIT PU.

  • PGWT CM ohne MPUT-Nachricht ist immer dann erlaubt, wenn auch ein PEND SP erlaubt ist. PGWT CM entspricht dann PEND SP mit anschließendem INIT/INIT PU.

  • Mit PGWT CM wird ein Sicherungspunkt gesetzt, wobei der Programmkontext erhalten bleibt. PGWT CM verhält sich in Bezug auf Datenbank-Transaktionen wie ein PEND SP oder PEND RE.

  • PGWT CM und PGWT RB sind nicht erlaubt, wenn in der aktuellen Transaktion mit einem Partner über das LU6.1-Protokoll kommuniziert wird.

  • Mit PGWT RB wird die Transaktion zurückgesetzt. Der Programmkontext bleibt Im Gegensatz zu RSET oder PEND RS erhalten. Dazu gehören z.B. KB-
    Programmbereich, SPAB und lokale Datenbereiche.

  • Vor PGWT RB darf keine Rücksetznachricht erzeugt werden.

  • Auf einen mit PGWT CM gesetzten Sicherungspunkt ist kein Vorgangs-Wiederanlauf möglich. Deshalb kann die Folge-Transaktion nur mit PGWT RB zurückgesetzt werden, ohne den abnormal Vorgang zu beenden.

• Wenn der PGWT-Aufruf nicht erfolgreich ausgeführt werden kann, ruft openUTM intern PEND ER auf.

• Fortsetzen der Verarbeitung

• • Nach einem PGWT-KP-Aufruf oder einem PGWT-CM-Aufruf mit MPUT wird in das aufrufende Programm zurückgekehrt, sobald alle Antworten vorliegen.

  • Nach einem PGWT CM ohne MPUT und einem PGWT RB wird die Verarbeitung sofort fortgesetzt, Ausnahme siehe Verteilte Verarbeitung mit OSI TP auf "PGWT Wartepunkt im Programm setzen ohne Teilprogrammende".

  • Nach einem PGWT PR-Aufruf wird die Verarbeitung fortgesetzt, sobald eine Nachricht auf der Queue eingetroffen ist. Um eine solche Nachricht zu lesen, muss ein DGET-Aufruf verwendet werden.

Verwenden Sie den Aufruf sparsam, da hiermit der Prozess belegt bleibt und während der Wartezeit keine anderen Aufgaben bearbeiten kann. Dies gilt besonders, wenn der PGWT-Aufruf auf eine Eingabe von einem Terminal wartet. Dann ist der Prozess solange blockiert, bis eine Eingabe über die Tastatur erfolgt!

PGWT-Aufruf in einem verteilten OSI TP-Vorgang mit Commit

Wurde bei Verteilter Verarbeitung über OSI TP die Commit-Funktionalität ausgewählt, dann führen PGWT CM ohne MPUT und PGWT RB immer zu einem Wartepunkt, d.h.:

• bei PGWT CM ohne MPUT wird die Verarbeitung erst fortgesetzt, nachdem das Transaktionsende von allen Partnern bestätigt oder die Transaktion zurückgesetzt wurde, z.B. wegen eines Fehlers.

• bei PGWT RB wird die Verarbeitung erst fortgesetzt, nachdem das Rücksetzen von allen Partnern bestätigt wurde.

Es wird auch dann ins Teilprogramm zurückgekehrt, wenn

• bei einem PGWT KP Aufruf eine Situation erkannt wurde, die ein Vorsetzen der Transaktion nicht erlaubt.

• bei einem PGWT CM oder RB die aktuelle Transaktion vorgesetzt bzw. zurückgesetzt wurde und eine Situation vorliegt, die ein Vorsetzen der aktuellen Transaktion oder der Folgetransaktion nicht erlaubt.

Diese Situation wird dem Teilprogramm durch das Feld KCTARB im KB-Kopf angezeigt:

KCTARB

zeigt in einem OSI TP-Vorgang an, ob eine Situation eingetreten ist, die ein Rücksetzen der Transaktion erfordert.

Leerzeichen	es ist keine Situation eingetreten, die ein Rücksetzen der Transaktion erfordert.
Y	es ist eine Situation eingetreten, die ein Vorsetzen der Transaktion nicht erlaubt. Es ist noch Kommunikation mit den Partner-Vorgängen erlaubt. Ein Aufruf zum Vorsetzen der Transaktion führt zum abnormalen Vorgangsende.