DGET Lesen einer Nachricht aus einer Service-gesteuerten Queue

Mit dem Aufruf DGET (data GET) wird eine Nachricht oder Teilnachricht aus einer Service-gesteuerten Queue in den Nachrichtenbereich eingelesen.
Service-gesteuerte Queues sind TAC-Queues, USER-Queues und Temporäre Queues.

DGET bietet mehrere Varianten, um Nachrichten einer Queue zu lesen:

• Sequenzielles Verarbeiten (DGET FT/NT)

• Browsen (DGET BF/BN)

• Gezieltes Verarbeiten (DGET PF/PN)

Beim sequenziellen oder gezielten Verarbeiten wird die Nachricht gelesen und anschließend aus der Queue gelöscht, beim Browsen bleibt sie in der Queue. Für die Dead Letter Queue ist nur Browsen (Lesen ohne Löschen) erlaubt.

Mit jeder Variante können auch mehrere Teilnachrichten gelesen werden. Der erste Teil wird mit DGET FT/BF/PF (First) gelesen. Die weiteren Teile werden innerhalb desselben Teilprogrammlaufs mit der Next-Variante DGET NT/BN/PN gelesen, ohne zwischenzeitlichen PGWT-Aufruf.

Es können so viel Nachrichtenteile gelesen werden, wie Nachrichtenteile mit DPUT QT geschickt wurden. Jede mit DPUT QT gesendete Teilnachricht muss mit einem eigenen DGET gelesen werden. Nicht gelesene Teilnachrichten gehen verloren, wenn

• mit DGET FT eine neue Nachricht gelesen wird,

• PGWT aufgerufen wird,

• der Teilprogrammlauf beendet wird.

Nach dem Rücksetzen der Transaktion werden verarbeitete Nachrichten wieder in die Queue gestellt (Redelivery) und können damit erneut mit DGET gelesen und verarbeitet werden. Die maximale Anzahl der Zustellungen lässt sich per Generierung einstellen (MAX REDELIVERY=). Ist diese Grenze erreicht, wird die verarbeitete Nachricht abhängig vom Parameter DEAD-LETTER-Q der TAC-Anweisung der Generierung zum Transaktionsende entweder gelöscht oder in die Dead Letter Queue gesichert, sofern (bei Message-Komplexen) kein negativer Quittungsauftrag definiert wurde.
Nachrichten aus USER- oder temporären Queues können nicht in die Dead Letter Queue gesichert werden. Sie gehen also nach maximaler Anzahl der Zustellungen verloren.

Im Folgenden wird das Format des DGET-Aufrufs ausführlich dargestellt. Weitere Informationen zum Thema "Nachrichten-Queues" finden Sie im Abschnitt „Message Queuing (Asynchron-Verarbeitung)".

Versorgen des KDCS-Parameterbereichs (1. Parameter)

Die folgenden Tabellen zeigen die verschiedenen Möglichkeiten und die notwendigen Angaben im KDCS-Parameterbereich.

Sequenzielles Verarbeiten
Funktion des Aufrufs	Einträge im KDCS-Parameterbereich
	KCOP	KCOM	KCLA	KCMF/ kcfn	KCRN	KCQTYP	KCWTIME	KCQRC	KCDPID
Neue Nachricht/ erste Teilnachricht der ersten Nachricht verarbeiten	"DGET"	"FT"	Länge	Leerzeichen	Queue-Name	Typ der Queue	Sekunden Wartezeit	0	binär null
Nächste Teilnachricht verarbeiten	"DGET"	"NT"	Länge	Leerzeichen	Queue-Name	Typ der Queue	0	0	binär null

Browsen
Funktion des Aufrufs	Einträge im KDCS-Parameterbereich
	KCOP	KCOM	KCLA	KCGTM	KCRN	KCQTYP	KCWTIME	KCQRC	KCDPID
Erste Teilnachricht der ersten bzw. nächsten Nachricht lesen	"DGET"	"BF"	Länge	Leerzeichen/Erzeugungszeit*	Queue-Name	Typ der Queue	Sekunden Wartezeit	-1/Redelivery-Zähler	Leerzeichen/DPUT-ID
Nächste Teilnachricht lesen	"DGET"	"BN"	Länge	Erzeugungszeit*	Queue-Name	Typ der Queue	0	0	DPUT-ID

Gezieltes Verarbeiten
Funktion des Aufrufs	Einträge im KDCS-Parameterbereich
	KCOP	KCOM	KCLA	KCGTM	KCRN	KCQTYP	KCWTIME	KCQRC	KCDPID
Erste Teilnachricht einer bestimmten Nachricht verarbeit.	"DGET"	"PF"	Länge	Erzeugungszeit*	Queue-Name	Typ der Queue	0	0	DPUT-ID
Nächste Teilnachricht verarbeiten	"DGET"	"PN"	Länge	Erzeugungszeit*	Queue-Name	Typ der Queue	0	0	DPUT-ID

* Wert aus dem KB-Rückgabefeld KCRGTM des vorhergehenden DGET BF

Versorgen des 2. Parameters

Hier müssen Sie die Adresse des Nachrichtenbereichs bereitstellen, in den openUTM die Nachricht lesen soll.

Versorgen der Parameter
Feldname im KDCS-Parameterbereich	Inhalt
KCOP	"DGET"
KCOM	"FT"/"NT"/"BF"/"BN"/"PF"/"PN"
KCLA	Länge in Byte
KCMF/kcfn KCGTM	Leerzeichen Leerzeichen/Erzeugungszeit
KCRN	Name der Queue
KCQTYP	"T"/"U"/"Q"
KCWTIME	Wartezeit in Sekunden/0
KCQRC	0/-1/Redelivery-Zähler
KCDPID	Binär null / Leerzeichen / DPUT-ID

KDCS-Aufruf
1. Parameter	2. Parameter
KDCS-Parameterbereich	Nachrichtenbereich

C/C++-Makroaufruf
Makronamen	Parameter
KDCS_DGETFT/KDCS_DGETNT	(nb,kcla,kcfn,kcrn,kcqtyp,kcwtime,kcfkt1, kcfkt2)
KDCS_DGETBF/KDCS_DGETBN/KDCS_DGETPF/KDCS_DGETPN	(nb,kcla,kcrn,kcqtyp,kcwtime,kcqrc,kcgtm,kcdpid)

Rückgaben von openUTM
Nachrichtenbereich	Inhalt
	Daten
Feldname im KB-Rückgabebereich
KCRLM	tatsächliche Länge
KCRMF/kcrfn (nur DGET FT/NT)	bei OSI TP-Partner: Name der abstrakten Syntax
KCRWVG (nur DGET FT)	Anzahl der Vorgänge, die schon warten
KCRUS (nur DGET FT)	UTM-Benutzerkennung des Nachrichten-Erzeugers
KCRQRC (nur DGET BF)	Queue-spezifischer Redelivery-Zähler
KCRGTM (nur DGET BF)	Erzeugungszeit der gelesenen Nachricht
KCRDPID (nur DGET BF)	DPUT-ID der gelesenen Nachricht
KCRRC (nur DGET FT/BF/BN/PF)	Redelivery-Zähler der gelesenen Nachricht
KCRCCC	Returncode
KCRCDC	interner Returncode

Im KDCS-Parameterbereich machen Sie für den DGET-Aufruf folgende Angaben:

KCOP

Im Feld KCOP tragen Sie den Operationscode DGET ein.

KCOM

Im Feld KCOM

• FT zum Verarbeiten der ersten Teilnachricht der ersten/neuen Nachricht

• NT zum Verarbeiten einer weiteren Teilnachricht der ersten/neuen Nachricht

• BF zum Lesen der ersten Teilnachricht einer Nachricht (Browsen ohne Löschen)

• BN zum Lesen einer weiteren Teilnachricht der Nachricht (Browsen ohne Löschen)

• PF zum Verarbeiten der ersten Teilnachricht einer bestimmten Nachricht

• PN zum Verarbeiten einer weiteren Teilnachricht einer bestimmten Nachricht

KCLA

Im Feld KCLA geben Sie die Länge des Nachrichtenbereichs an, in den die Nachricht gelesen werden soll. openUTM trägt die Länge der tatsächlich gelesenen Teilnachricht im Rückgabefeld KCRLM ein.

Wenn die Nachricht inclusive aller Teilnachrichten nicht gelesen werden soll, können Sie hier bei DGET FT den Wert 0 angeben. Ein nachfolgender DGET NT wird dann mit dem Returncode 10Z abgewiesen.

KCMF/kcfn 
KCGTM

Das Feld KCGTM bzw. KCMF/kcfn muss wie folgt versorgt werden:

• mit Leerzeichen bei KCOM = FT/NT.

• mit Leerzeichen bei KCOM = BF, wenn der erste Teil der ersten Nachricht der Queue gelesen werden soll.

• mit der Erzeugungszeit der Nachricht bei KCOM = BN/PF/PN oder wenn bei KCOM = BF die nächste Nachricht gelesen werden soll. Die Erzeugungszeit wird beim letzten DGET BF im Feld KCRGTM zurückgegeben.

KCRN

Im Feld KCRN geben Sie den Namen der Queue an, aus der die Nachricht gelesen werden soll.

KCQTYP

Im Feld KCQTYP geben Sie den Typ der Queue an:

• T für TAC-Queue

• U für USER-Queue

• Q für Temporäre Queue

KCWTIME

Im Feld KCWTIME geben Sie bei DGET FT/BF an, wieviele Sekunden maximal auf das Eintreffen einer Nachricht gewartet werden soll. Es wird aber höchstens so lange gewartet wie bei der Generierung festgelegt wurde (MAX QTIME=). Die Angabe 0 bedeutet, dass nicht gewartet werden soll. Wird eine Wartezeit angegeben, muss das Folgeteilprogramm beim PEND einer TAC-Klasse zugeordnet sein.

Bei DGET NT/BN/PF/PN müssen Sie 0 angeben.

KCQRC

Im Feld KCQRC bestimmen Sie bei DGET BF das Verhalten nach Verarbeiten und Rücksetzen einer Transaktion. Sie können angeben:

• entweder den Wert, der beim vorhergehenden DGET BF-Aufruf im Feld KCRQRC zurückgegeben wurde. Damit wird sichergestellt, dass immer alle Nachrichten der Queue gelesen werden, eventuell wird eine verarbeitete Nachricht nach dem Rücksetzen noch einmal gelesen.

• oder den Wert -1 bzw. die Konstante KDCS_NO_QRC. Damit werden eventuell nicht alle Nachrichten der Queue gelesen.

Bei DGET FT/NT/BN/PF/PN müssen Sie 0 angeben.

KCDPID

Im Feld KCDPID geben Sie an:

• Binär null bei KCOM = FT/NT

• Leerzeichen, wenn bei KCOM = BF der erste Teil der ersten Nachricht gelesen werden soll.

• Die DPUT-ID bei KCOM = PF/PN oder wenn bei KCOM = BF/BN die nächste Nachricht/Teilnachricht gelesen werden soll. Die DPUT-ID wird beim
  vorhergehenden DGET BF im Feld KCRDPID zurückgegeben.

Beim KDCS-Aufruf geben Sie an:

1. Parameter

die Adresse des KDCS-Parameterbereichs.

2. Parameter

die Adresse des Nachrichtenbereichs, in den openUTM die Nachricht lesen soll. Die Adresse des Nachrichtenbereichs geben Sie auch an, wenn Sie in KCLA die Länge 0 eintragen.

Makronamen

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

openUTM gibt zurück:

Nachrichtenbereich

im angegebenen Nachrichtenbereich die Teilnachricht in der tatsächlichen, höchstens aber in der Länge des Nachrichtenbereichs.

KCRLM

im Feld KCRLM die tatsächliche Länge der gelesenen Teilnachricht, sofern in KCLA ein Wert > 0 angegeben wurde.

bei KCOM = FT/NT:

KCRMF/kcrfn

im Feld KCRMF den Namen der abstrakten Syntax der gelesenen Teilnachricht, wenn die Nachricht von einem OSI TP-Partner stammt. Sonst Leerzeichen.

KCRWVG

im Feld KCRWVG die Anzahl der Vorgänge, die bereits auf Nachrichten aus der angegebenen Queue warten (der aktuelle Vorgang wird dabei nicht mitgezählt). KCRWVG wird nur bei DGET FT versorgt.

KCRUS

im Feld KCRUS die UTM-Benutzerkennung, unter der die DGET-Nachricht erzeugt wurde. KCRUS wird nur bei DGET FT versorgt.

bei KCOM = BF:

KCRQRC

im Feld KCRQRC den Queue-spezifischen Redelivery-Zähler. Dieser Wert wird benötigt, um beim nächsten DGET BF-Aufruf das Feld KCQRC zu versorgen.

KCRGTM

im Feld KCRGTM die Erzeugungszeit der gelesenen Nachricht (binär). Dieser Wert wird benötigt, um beim nächsten DGET BF/BN/PF/PN-Aufruf das Feld KCGTM zu versorgen.

KCRDPID

im Feld KCRDPID die DPUT-ID der gelesenen Nachricht. Dieser Wert wird benötigt, um beim nächsten DGET BF/BN/PF/PN-Aufruf das Feld KCDPID zu versorgen.

bei KCOM = BF/BN/PF:

KCRRC

im Feld KCRRC den Redelivery-Zähler der gelesenen Nachricht. Dieser gibt an, wie oft die Nachricht nach Verarbeiten und Rücksetzen der Transaktion erneut zugestellt wurde. KCRRC kann maximal den Wert 254 erreichen. Ist dieser Wert erreicht und ist die Anzahl der erneuten Zustellungen nicht per Generierung beschränkt, dann wird nach jedem weiteren DGET BF/BN/PF immer der Wert 254 geliefert.

Bei allen Varianten:

KCRCCC

im Feld KCRCCC den KDCS-Returncode (siehe nächste Seite).

KCRCDC

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

KDCS-Returncodes im Feld KCRCCC beim DGET-Aufruf

Im Programm sind auswertbar:

000	Die Operation wurde durchgeführt.
01Z	Längenkonflikt: KCLA < KCRLM, die Nachricht wurde abgeschnitten, weil die Teilnachricht länger ist als der Nachrichtenbereich.
04Z	Beim vorherigen DGET-Aufruf wurden noch nicht alle Nachrichtenteile gelesen; durch den aktuellen Aufruf DGET FT/BF/PF gehen die noch nicht gelesenen Nachrichtenteile verloren.
08Z	Beim Lesen mit Warten (KCWTIME>0): Es liegt zurzeit keine Nachricht vor. In diesem Fall sind keine weiteren DGET-Aufrufe erlaubt und das Teilprogramm muss mit PEND PA/PR beendet werden oder mit PGWT PR einen Wartepunkt setzen. Sobald eine Nachricht eintrifft oder die maximale Wartezeit abläuft oder die Queue gelöscht wird, setzt openUTM den Vorgang mit dem Folgeteilprogramm bzw. hinter dem PGWT PR fort. Ein Folgeteilprogramm muss einer TAC-Klasse zugeordnet sein.
10Z	Bei DGET NT/BN/PN: Alle Teilnachrichten der Nachricht wurden bereits gelesen.
11Z	Beim Lesen ohne Warten (KCWTIME = 0): Es liegt keine Nachricht vor.
40Z	Bei DGET NT/BN/PN: Name oder Typ der angegebenen Queue passen nicht zum vorherigen DGET-Aufruf des aktuellen Teilprogrammlaufs. Dabei sind evtl. Teilnachrichten verloren gegangen. Es wurde keine Nachricht gelesen. Bei DGET FT/PF: Es liegt ein Generierungsfehler vor (der Wert in MAX ...,RECBUF=... ist zu klein).
41Z	Der DGET-Aufruf erfolgt unerlaubterweise im ersten Teil des Anmelde-Vorgangs oder der vorherige DGET-Aufruf ergab bereits den Returncode 08Z, d.h. es muss gewartet werden und es sind keine weiteren DGET-Aufrufe in diesem Teilprogramm erlaubt.
42Z	Mögliche Ursachen: Der Wert in KCOM ist ungültig oder passt nicht zum vorherigen DGET-Aufruf (z.B. DGET PN nach DGET BF) oder der erste Nachrichtenteil wurde nicht in diesem Teilprogrammlauf gelesen oder es wurde inzwischen ein PGWT-Aufruf durchgeführt
43Z	Der Wert in KCLA oder KCWTIME ist negativ bzw. ungültig oder bei DGET NT/BN/PF/PN wurde KCWTIME nicht mit 0 versorgt.
44Z	Der Wert in KCRN ist ungültig, d.h. es gibt keine Queue mit dem angegebenen Namen und Typ oder die Queue wurde gelöscht oder der USER, der den Vorgang gestartet hat, bzw. dessen LTERM hat keine Berechtigung (KSET) zum Lesen der Queue oder der angegebene TAC ist nicht mit TYPE=Q generiert oder es wurde versucht, die Dead Letter Queue (KDCDLETQ) anders als mit Browse (Lesen ohne Löschen, d.h. DGET BF/BN) zu lesen.
45Z	Der Wert in KCMF/KCGTM ist ungültig: Bei DGET FT/NT: KCMF wurde nicht mit Leerzeichen versorgt. Bei DGET BN/PF: Es existiert keine Nachricht mit der angegebenen DPUT-ID und Erzeugungszeit oder diese Nachricht wurde inzwischen gelöscht.
47Z	Der Nachrichtenbereich fehlt oder die angegebene Bereichsadresse ist ungültig.
49Z	Nicht verwendete Felder haben einen Wert ungleich binär null.
53Z	Bei DGET BF/PF: Der Wert in KCDPID ist keine gültige DPUT-ID oder er passt nicht zu den Angaben in KCRN und KCQTYP. Bei DGET BN/PN: Der Wert in KCDPID bzw. KCGTM stimmt nicht mit dem entsprechenden Wert des letzten DGET BF/PF überein.

Weitere Returncodes sind dem DUMP zu entnehmen:

71Z	INIT missing in this program.

Eigenschaften des DGET-Aufrufs

• Nachrichtenlänge

  Die tatsächliche Nachrichtenlänge wird im Feld KCRLM zurückgegeben. Es gilt:

  • Bei KCRLM <= KCLA werden nur KCRLM Zeichen (Bytes) in den Nachrichtenbereich übertragen. Der Inhalt des restlichen Nachrichtenbereichs ist undefiniert.

  • Bei KCRLM > KCLA werden nur KCLA Zeichen in den Nachrichtenbereich übertragen. Der Rest (KCRLM - KCLA) geht verloren. Er kann mit einem nachfolgenden DGET nicht mehr gelesen werden.

  Bei der Beschreibung des MGET-Aufrufs finden Sie ein Beispiel, das das Verhalten von openUTM bei Längenkonflikten erläutert.

• Browsen und Verarbeiten

  • Beim Browsen (DGET BF/BN) können Nachrichten parallel von mehreren Vorgängen gelesen werden.

  • Beim Verarbeiten von Nachrichten (DGET FT/NT/PF/PN) kann jede Teilnachricht nur einmal gelesen werden. Sobald die Transaktion beendet wird, werden alle Teilnachrichten gelöscht.

  • Soll eine Nachricht nach dem Lesen (DGET BF/BN) mit DGET PF verarbeitet werden, dann muss die bei DGET BF zurückgegebene DPUT-ID und Erzeugungszeit beim DGET PF angegeben werden.

• Warten auf Nachrichten

  Innerhalb eines Dialog- oder Asynchron-Vorgangs dürfen solange DGET-Aufrufe für unterschiedliche Queues gegeben werden, bis auf eine Nachricht gewartet werden muss, d.h. liegt beim DGET-Aufruf mit Warten keine Nachricht vor, wird dies im Programm angezeigt durch KCRCCC = 08Z (KCWTIME > 0).

  Abhängig davon, ob auf eine Nachricht gewartet werden soll, sind folgende KDCS-Aufrufe zu programmieren:

  • Soll auf eine Nachricht gewartet werden, dann muss entweder das Teilprogramm mit PEND PA/PR beendet werden, damit außerhalb des Programmkontextes auf das Eintreffen der Nachricht gewartet werden kann, oder es muss mit PGWT PR ein Wartepunkt im Teilprogramm gesetzt werden.

  • Soll nicht auf eine Nachricht gewartet werden, dann muss entweder die Transaktion zurückgesetzt werden (RSET, PEND RS oder PGWT RB) oder der Vorgang muss mit PEND ER/FR beendet werden.

  Ansonsten wird beim PEND-Aufruf der Fehlercode 72Z zurückgegeben.

• Fortsetzen des Programms

  Wird auf eine DGET-Nachricht gewartet, startet openUTM das Folgeteilprogramm oder setzt das Programm hinter dem PGWT PR fort, sobald:

  1. eine neue Nachricht eintrifft oder

  2. die maximale Wartezeit abläuft oder

  3. die Queue gelöscht wird oder

  4. die verarbeitete Nachricht erneut zugestellt wird (Redelivery nach Rücksetzen der Transaktion), vorausgesetzt, es wird mit DGET FT gewartet oder es wurde KCQRC mit dem Wert des KB-Rückgabefeldes KCRQRC vom vorherigen Browse-Aufruf versorgt.

  In den Fällen a) bis c) werden alle an dieser Queue auf Nachrichten wartenden Vorgänge fortgesetzt (nicht nur der erste wartende Vorgang).

  Bei Redelivery (Fall d)) werden nur die Vorgänge fortgesetzt, die erneut zugestellte Nachrichten lesen sollen. Damit wird erreicht, dass eintreffende oder erneut zugestellte Nachrichten von den Vorgängen parallel gelesen werden können.

  Wird das Programm in einem PEND PA/PR-Folgeteilprogramm fortgesetzt, dann muss es einer TAC-Klasse zugeordnet sein, d.h. diese Funktionalität setzt voraus, dass TAC-Klassen generiert wurden. Ist dies nicht der Fall, wird der PEND-Aufruf mit KCRCCC=74Z abgewiesen.

• Erneute Zustellung (Redelivery)

  Wird eine Transaktion zurückgesetzt, dann wird eine verarbeitete Nachricht wieder in die Queue gestellt und kann erneut gelesen werden. Voraussetzung ist, dass die Anwendung entsprechend generiert wurde und die dort festgelegte Anzahl wiederholter Zustellungen noch nicht erreicht ist. Näheres siehe openUTM-Handbuch „Anwendungen generieren“, Operand REDELIVERY in der MAX-Anweisung.

• Im Vorgang KDCMSGTC und im Anmelde-Vorgang KDCSGNTC darf der Aufruf DGET nur ohne Angabe einer Wartezeit verwendet werden.

• Wird die Hauptnachricht eines Auftrags-Komplexes gelesen, für die ein positiver bzw. negativer Quittungsauftrag definiert ist (nur möglich bei TAC-Queues), dann wird

  • der positive Quittungsauftrag gestartet, nachdem die den DGET-Aufruf enthaltende Transaktion erfolgreich abgeschlossen wurde,

  • der negative Quittungsauftrag gestartet, nachdem die den DGET-Aufruf enthaltende Transaktion zurückgesetzt wurde ohne dass die Hauptnachricht erneut zugestellt wurde, d.h. keine Redelivery.

• Wird mit DGET aus einer Queue gelesen, für die ein Zugriffsschutz besteht, so muss die Benutzerkennung, unter der der Vorgang läuft, und der LTERM-Partner die Zugriffsberechtigung (KSET) für die entsprechende Queue besitzen. Ein Benutzer darf aber immer auf seine eigene USER-Queue zugreifen.
  Bei Anwendungen ohne explizit generierte Benutzerkennungen kann für die USER-Queues kein Zugriffsschutz vergeben werden.

• Sicherung fehlerhafter Nachrichten in der Dead Letter Queue

  Nachrichten aus TAC-Queues können im Fehlerfall als letzte Rückfallstufe in der globalen Dead Letter Queue gesichert werden. Dazu muss die Queue mit DEAD-LETTER-Q=YES generiert werden. Dann wird eine verarbeitete Nachricht beim Rücksetzen der Transaktion in die Dead Letter Queue gestellt, wenn sie nicht erneut zugestellt werden kann (siehe Redelivery) und kein negativer Quittungsauftrag definiert wurde.

  Beim Sichern einer Nachricht in der Dead Letter Queue wird die Anzahl der erneuten Zustellungen dieser Nachricht (Redelivery) ggf. auf null zurückgesetzt.