QCRE Temporäre Queue erzeugen

Mit dem Aufruf QCRE (queue create) wird dynamisch eine Temporäre Queue erzeugt.

Voraussetzung für einen erfolgreichen QCRE-Aufruf ist, dass bei der Generierung genügend viele Tabellenplätze für QUEUE-Objekte mit der QUEUE-Anweisung reserviert wurden.

Im QCRE-Aufruf können Sie einen Namen für die zu erzeugende Queue vergeben oder festlegen, dass openUTM automatisch einen Namen vergibt, der dann im Rückgabefeld KCRQN (Queue-Name) eingetragen wird.
openUTM erzeugt aufeinanderfolgende Queue-Namen aus abdruckbaren Ziffern. Werden die Queue-Namen von openUTM vergeben, so werden Queue-Namen erst nach 100 Millionen QCRE-Aufrufen erneut verwendet. Damit ist sichergestellt, dass langlaufende Vorgänge für die Kommunikation nicht unbeabsichtigt eine Temporäre Queue verwenden, deren Name nach zwischenzeitlichem Löschen neu vergeben wurde.

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

Versorgen des KDCS-Parameterbereichs (1. Parameter)

Die folgende Tabelle zeigt die notwendigen Angaben im KDCS-Parameterbereich.

Funktion des Aufrufs	Einträge im KDCS-Parameterbereich
	KCOP	KCOM	KCRN	KCLA	KCMF/kcfn	KCQMODE
Queue ohne Namensangabe erzeugen	"QCRE"	"NN"	Leerzeichen	Queue-Level	Leerzeichen	"S" / "W" / binär null
Queue mit Namensangabe erzeugen	"QCRE"	"WN"	Queue-Name	Queue-Level	Leerzeichen	"S" / "W" / binär null

Versorgen der Parameter
Feldname im KDCS-Parameterbereich	Inhalt
KCOP	"QCRE"
KCOM	"NN"/ "WN"
KCRN	Leerzeichen / Name der Queue
KCLA	Queue Level der Queue
KCMF / kcfn	Leerzeichen
KCQMODE	"S" / "W" / binär null

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

C/C++-Makroaufruf
Makronamen	Parameter
KDCS_QCRENN	(kcla,qmode)
KDCS_QCREWN	(kcla,kcrn,qmode)

Rückgaben von openUTM
Feldname im KB-Rückgabebereich	Inhalt
KCRQN	von openUTM vergebener Name
KCRCCC	Returncode

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

KCOP

Im Feld KCOP tragen Sie den Operationscode QCRE ein.

KCOM

Im Feld KCOM:

• NN (no name),
  wenn openUTM den Namen der Queue automatisch erzeugen soll

• WN (with name),
  wenn Sie den Namen selbst vergeben

KCRN

Im Feld KCRN tragen Sie den Namen der Queue ein (KCOM=WN) bzw. Leerzeichen (KCOM=NN). Ein von Ihnen vergebener Name darf nicht mit einer Ziffer beginnen und muss den Konventionen für generierbare Namen genügen. D.h. er darf nur aus den Zeichen A...Z, a...z, 0...9, $, #, @ bestehen und muss ggf. mit Leerzeichen aufgefüllt werden.

KCLA

Im Feld KCLA geben Sie das Queue-Level an, das heißt, Sie geben an, wieviele Nachrichten in dieser Queue maximal gespeichert werden können.
Wenn Sie Null angeben, verwendet openUTM den Wert bzw. Standardwert des Parameters QLEV aus der QUEUE-Anweisung der Generierung.

KCMF / kcfn

Das Feld KCMF/kcfn muss mit Leerzeichen versorgt werden.

KCQMODE

Im Feld KCQMODE:

• S (Standard),
  wenn beim Erreichen des Queue-Levels weitere Nachrichten abgewiesen werden sollen

• W (wrap),
  wenn beim Erreichen des Queue-Levels eine neue Nachricht die älteste vorhandene Nachricht überschreibt

• binär null:
  openUTM verwendet den Wert bzw. Standardwert des Parameters QMODE aus der QUEUE-Anweisung der Generierung.

Beim KDCS-Aufruf geben Sie an:

1. Parameter

Die Adresse des KDCS-Parameterbereichs.

Makronamen

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

openUTM gibt zurück:

KCRQN

im Feld KCRQN den automatisch erzeugten Namen (bei KCOM=NN).

KCRCCC

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

KDCS-Returncodes im Feld KCRCCC beim QCRE-Aufruf

Im Programm sind auswertbar:

000	Die Operation wurde durchgeführt.
16Z	KCOM=WN: Der Queue-Name existiert bereits KCOM=NN: openUTM hat keinen freien Namen gefunden. In diesem Fall können Sie versuchen, mit einem weiteren Aufruf QCRE NN einen freien Queue-Namen zu finden. Hinweis zur Namensvergabe: openUTM vergibt Namen, die nur aus Ziffern bestehen und merkt sich jeweils den letzten vergebenen Namen. Bei QCRE mit KCOM=NN durchsucht openUTM die nächsten 100 aufeinander folgenden, aus Ziffern bestehenden Namen nach einem freien Eintrag. Sind diese Namen alle belegt, dann bricht openUTM die Suche mit 16Z ab. Beim nächsten Aufruf QCRE NN werden dann die nächsten 100 Namen durchsucht.
40Z	Die Operation kann nicht ausgeführt werden, weil: kein freier Tabellenplatz (mehr) für Temporäre Queues vorhanden ist (Maßnahme: Wert für NUMBER in der QUEUE-Anweisung vergrößern und neu generieren oder nicht mehr benötigte Temporäre Queues mit QREL löschen). im Prozess-spezifischen Puffer für Wiederanlaufdaten kein Platz mehr ist (Maßnahme: Wert von MAX RECBUF=(..., length) vergrößern und neu generieren).
42Z	Der Wert in KCOM ist ungültig.
43Z	Der Wert in KCLA (Queue Level) ist negativ bzw. ungültig.
44Z	Der Queue-Name beginnt mit einer Ziffer (KCOM=WN) bzw. KCRN enthält keine Leerzeichen (KCOM=NN).
45Z	KCMF/kcfn wurde nicht mit Leerzeichen versorgt.
46Z	Der Wert in KCQMODE ist ungültig.
49Z	Nicht verwendete Felder haben einen Wert ungleich binär null.

Ein weiterer Returncode ist dem DUMP zu entnehmen:

71Z	Im Teilprogrammlauf wurde noch kein INIT aufgerufen.

Eigenschaften des QCRE-Aufrufs

• Zum Erzeugen einer Temporären Queue ist keine Administrationsberechtigung erforderlich.

• Werden die Queue-Namen von openUTM vergeben, so werden diese erst nach 100 Millionen QCRE-Aufrufen erneut verwendet.

• Wurde eine Temporäre Queue mit QCRE neu erzeugt, dann können schon in der selben Transaktion Nachrichten in diese Queue geschrieben werden. Diese Nachrichten lassen sich jedoch erst nach dem erfolgreichen Abschluss der Transaktion lesen und administrieren.

• Bei UTM-S bleiben Temporäre Queues und ihre Nachrichten über den Anwendungslauf hinaus erhalten, bis sie explizit mit einem QREL-Aufruf gelöscht werden. Bei UTM-F werden Temporäre Queues automatisch mit dem Ende des Anwendungslaufs gelöscht. Alle noch in der Queue gespeicherten Nachrichten gehen verloren.