Der Aufruf DADM (delayed free message administration) bietet folgende Funktionen zur Administration von Message Queues:
Übersichtsinformationen über Nachrichten einer Message Queue in den Nachrichtenbereich lesen (Benutzerkennung, Auftrags-Identifikation (Auftrags-Id), Zeitpunkt der Erzeugung, Startzeit und vorhandene Quittungsaufträge, ursprüngliches Ziel ...)
Benutzerinformationen, die mit DPUT NI/QI/+I/-I erzeugt wurden, in den Nachrichtenbereich lesen
die Bearbeitungsreihenfolge von Nachrichten einer Message Queue ändern
einzelne Nachrichten der Message Queue oder auch alle Nachrichten der Message Queue löschen
einzelne oder alle Nachrichten der Dead Letter Queue wieder ihrem jeweiligen ursprünglichen Ziel oder einem neuen Ziel zuordnen
Unix-, Linux- und Windows-Systeme
In einer UTM-Cluster-Anwendung können Sie nur Message Queues der lokalen Knoten-Anwendung administrieren.
Im Folgenden wird das Format des DADM-Aufrufs ausführlich dargestellt. Weiterführende Informationen zur Administration von Message Queues finden Sie im openUTM-Handbuch „Anwendungen administrieren“.
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 | KCLA | KCRN | KCLT | KCQTYP | KCMOD | Zeitpunkt1 | |
Übersichtsinformation lesen | "DADM" | "RQ" | 54 | Auftrags-Id/Leerzeichen | LTERM/(OSI-)LPAP/TAC | binär null | binär null | binär null |
Queue | "Q"/"U" | |||||||
Benutzerinformation lesen | "DADM" | "UI" | Länge | Auftrags-Id | binär null | binär null | binär null | Zeitpunkt (absolut) |
Reihenfolge ändern | "DADM" | "CS" | 0 | Auftrags-Id | binär null | binär null | binär null | Zeitpunkt (absolut) |
Löschen einer einzelnen Nachricht einer Queue | "DADM" | "DL" | 0 | Auftrags-Id | LTERM/(OSI-)LPAP/TAC | binär null | "C"/"N" | Zeitpunkt (absolut) |
Queue | "Q"/"U" | |||||||
Löschen aller Nachrichten einer Queue | "DADM" | "DA" | 0 | Leerzeichen | LTERM/(OSI-)LPAP/TAC | binär null | binär null | binär null |
Queue | "Q"/"U" | |||||||
Einzelne Nachricht verschieben | "DADM" | "MV" | 0 | Auftrags-Id | TAC/(OSI-)LPAP/Leerzeichen | binär null | binär null | Zeitpunkt (absolut) |
Alle Nachrichten verschieben | "DADM" | "MA" | 0 | Leerzeichen | TAC/(OSI-)LPAP/Leerzeichen | binär null | binär null | binär null |
1 Der Zeitpunkt wird in den Feldern KCTAG/kcday, KCSTD/kchour und KCMIN angegeben.
Alle nicht verwendeten Felder des KDCS-Parameterbereichs müssen mit binär null versorgt werden.
Versorgen des 2. Parameters
Hier stellen Sie die Adresse des Nachrichtenbereichs bereit, in den openUTM die Nachricht lesen soll. Für die Strukturierung des Nachrichtenbereichs beim Aufruf DADM RQ steht eine Sprach-spezifische Datenstruktur zur Verfügung, für COBOL das COPY-Element KCDADC und für C/C++ die Include-Datei kcdad.h.
Versorgen der Parameter | |
Feldname im KDCS-Parameterbereich | Inhalt |
"DADM" | |
"RQ"/"UI"/"CS"/"DL"/"DA"/"MV"/"MA" | |
Länge in Byte/0 | |
Auftrags-Id/Leerzeichen | |
LTERM-Name/(OSI-)LPAP-Name/TAC/Queue/binär null/Leerzeichen | |
Typ des Ziels:"Q"/"U"/binär null | |
"C"/"N"/binär null | |
| Zeitangabe (absolut) | |
|
|
|
|
|
|
|
|
KDCS-Aufruf | |
KDCS-Parameterbereich | Nachrichtenbereich |
C/C++-Makroaufrufe | |
Parameter | |
KDCS_DADMRQ | (nb,kcla,kcrn,kclt) |
KDCS_QADMRQ | (nb,kcla,kcrn,kclt,kcqtyp) |
KDCS_DADMUI | (nb,kcla,kcrn,kcday,kchour,kcmin,kcsec) |
KDCS_DADMCS | (nb,kcrn,kcday,kchour,kcmin,kcsec) |
KDCS_DADMDL | (nb,kcrn,kclt,kcmod,kcday,kchour,kcmin,kcsec) |
KDCS_QADMDL | (nb,kcrn,kclt,kcmod,kcday,kchour,kcmin,kcsec,kcqtyp) |
KDCS_DADMDA | (nb,kclt) |
KDCS_QADMDA | (nb,kclt,kcqtyp) |
KDCS_DADMMV | (nb,kcrn,kclt,kcday,kchour,kcmin,kcsec,kcqtyp) |
KDCS_DADMMA | (nb,kclt,kcqtyp) |
Rückgaben von openUTM | |
|---|---|
Inhalt | |
| Daten | |
Feldname im KB-Rückgabebereich | Inhalt |
tatsächliche Länge | |
Returncode | |
interner Returncode | |
Auftrags-Id/Leerzeichen | |
In den KDCS-Parameterbereich tragen Sie für den DADM-Aufruf Folgendes ein:
KCOP
Im Feld KCOP geben Sie den Operationscode DADM an.
KCOM
Im Feld KCOM wählen Sie die Operationsmodifikation:
RQ zum Lesen der Übersichtsinformationen zu einer Message Queue
UI zum Lesen einer durch DPUT NI/QI erzeugten Benutzerinformation eines Hauptauftrags
CS um eine bestimmte Nachricht vorzuziehen
DL zum Löschen einer einzelnen Nachricht
DA zum Löschen aller Nachrichten in der Message Queue
MV zum Verschieben einer einzelnen Nachricht der Dead Letter Queue in die ursprüngliche Message Queue oder an einen beliebigen Asynchron-TAC, eine beliebige TAC-Queue, einen LPAP-Partner oder einen OSI-LPAP-Partner.
MA zum Verschieben aller Nachrichten der Dead Letter Queue. Dabei gibt es zwei Möglichkeiten:
Verschieben in die jeweiligen ursprünglichen Message Queues
Verschieben aller Nachrichten mit ursprünglichem Ziel TAC, LPAP oder OSI-LPAP an ein beliebiges anderes Ziel vom gleichen Typ (Asynchron-TAC/TAC-Queue, LPAP-Partner oder OSI-LPAP-Partner). Nachrichten, deren ursprüngliches Ziel nicht vom Typ des neuen Ziels ist, verbleiben in der Dead Letter Queue.
Um alle Nachrichten zu verschieben, sind also bis zu drei Aufrufe mit neuen Zielen vom Typ TAC, LPAP und OSI-LPAP erforderlich.
KCLA
Im Feld KCLA geben Sie die Länge an, in der die Daten in den Nachrichtenbereich übertragen werden sollen. Bei KCOM = RQ wird 54, bei KCOM = CS/DL/DA/MV/MA wird 0 eingetragen.
KCRN
Im Feld KCRN identifizieren Sie die Nachricht der Queue, die administriert werden soll. Folgende Angaben sind notwendig:
Leerzeichenbei KCOM = DA/MA oder wenn sich der Aufruf bei KCOM = RQ auf die erste Nachricht in der Queue bezieht.
die Auftrags-Idbei KCOM = UI/CS/DL/MV oder wenn sich der Aufruf bei KCOM = RQ auf nachfolgende Nachrichten in der Queue bezieht. Die Auftrags-Id wird immer beim vorigen DADM RQ im Feld KCRMF/kcrfn zurückgegeben.
KCLT
Im Feld KCLT identifizieren Sie die Queue, d.h.
Bei KCOM = RQ/DL/DA geben Sie an:
den LTERM-Namen, wenn die Nachricht an einen LTERM-Partner gerichtet war,
den (OSI-)LPAP-Namen, wenn die Nachricht an einen (OSI-)LPAP-Partner gerichtet war,
den TAC, wenn die Nachricht an ein Asynchron-Programm gerichtet war,
den Namen der Queue, wenn Sie Nachrichten einer USER-Queue, einer TAC-Queue oder einer Temporären Queue administrieren wollen.
Bei KCOM = UI/CS geben Sie binär null an.
Bei KCOM = MV/MA geben Sie an:
den TAC, wenn die einzelne bzw. alle Nachrichten mit ursprünglichem Ziel TAC oder TAC-Queue an ein Asynchron-Programm gerichtet werden sollen,
den Namen einer TAC-Queue, wenn die einzelne bzw. alle Nachrichten mit ursprünglichem Ziel TAC oder TAC-Queue an eine Service-gesteuerte Queue gerichtet werden sollen,
den Namen eines LPAP-Partners (aber kein MASTER-LU61-LPAP), wenn die einzelne bzw. alle Nachrichten mit ursprünglichem Ziel LPAP an einen LPAP-Partner gerichtet werden sollen,
den Namen eines OSI-LPAP-Partners (aber kein MASTER-OSI-LPAP), wenn die einzelne bzw. alle Nachrichten mit ursprünglichem Ziel OSI-LPAP an einen OSI-LPAP-Partner gerichtet werden sollen,
Leerzeichen, wenn die einzelne bzw. alle Nachrichten wieder ihrem jeweiligen ursprünglichen Ziel zugeordnet werden sollen.
Alle Nachrichten, deren ursprüngliches Ziel nicht zum neuen Ziel passt, verbleiben in der Dead-Letter-Queue.
KCQTYP
Im Feld KCQTYP geben Sie den Typ der Queue an:
bei KCOM = RQ/DL/DA geben Sie an:
binär null, wenn die Queue zu einem LTERM, einem (OSI-)LPAP oder einem TAC gehört oder wenn es eine TAC-Queue ist,
Q bei einer mit QCRE erzeugten Temporären Queue,
U bei einer USER-Queue.
bei KCOM = UI/CS/MV/MA geben Sie binär null an.
KCMOD
Im Feld KCMOD geben Sie beim Löschen eines Auftrags-Komplexes an, ob openUTM den negativen Quittungsauftrag aktivieren soll. Folgende Werte sind möglich:
binär null bei KCOM = RQ/UI/CS/DA/MV/MA,
C zum Löschen des kompletten Auftrags bei KCOM = DL; bei Auftrags-Komplexen werden alle Quittungsaufträge ebenfalls gelöscht,
N zum Aktivieren des negativen Quittungsauftrags bei KCOM = DL; die Nachricht selbst wird gelöscht
KCTAG/...
Bei KCOM = UI/CS/DL/MV geben Sie in diesen Feldern den Zeitpunkt an, an dem die Nachricht erzeugt wurde, und zwar im Feld KCTAG/kcday den Tag im Jahr (Industrietag, Wert von 001 bis 366), in KCSTD/kchour die Stunde, in KCMIN die Minute und in KCSEK/ kcsec die Sekunde. Dieser Zeitpunkt kann vorher mit DADM RQ ermittelt werden.
Bei KCOM = RQ/DA/MA wird binär null eingetragen.
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. Diese Adresse müssen Sie auch angeben, wenn Sie in KCLA 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
bei KCOM = RQ/UI im angegebenen Nachrichtenbereich die Nachricht in der tatsächlichen, höchstens aber in der angeforderten Länge.
KCRLM
im Feld KCRLM die tatsächliche Länge der Nachricht, ggf. in Abweichung von der angeforderten Länge in KCLA des Parameterbereichs.
KCRCCC
im Feld KCRCCC den KDCS-Returncode.
KCRCDC
im Feld KCRCDC den internen Returncode von openUTM (siehe openUTM-Handbuch „Meldungen, Test und Diagnose“).
KCRMF/kcrfn
im Feld KCRMF/kcrfn bei KCOM = RQ die Auftrags-Id der nächsten Nachricht in der Queue (siehe KCLT) oder Leerzeichen bei der letzten Nachricht der Queue.
KDCS-Returncodes im Feld KCRCCC beim DADM-Aufruf
Im Programm sind auswertbar:
000 | Die Operation wurde ausgeführt (bei KCOM = RQ/UI) bzw. der Administrationsauftrag wurde angenommen (bei KCOM = CS/DL/DA/(MV/MA). |
01Z | Längenkonflikt: KCLA < KCRLM, die Nachricht wurde abgeschnitten. |
07Z | Es konnten nicht alle Nachrichten der Dead Letter Queue verschoben werden, weil der taskspezifische Pufferbereich für die Wiederanlauf-Information zu klein generiert wurde, siehe openUTM-Handbuch „Anwendungen generieren“ "Wiederanlaufbereich". |
40Z | Das System kann die Operation nicht ausführen (Generierungs- bzw. Systemfehler, ursprüngliches Ziel nicht mehr existent, keine Administrationsberechtigung, Blockade durch anderen Vorgang), siehe KCRCDC. |
42Z | Der Eintrag in KCOM ist ungültig. |
43Z | Die Längenangabe in KCLA ist negativ bzw. ungültig. |
44Z | Die in KCRN angegebene Auftrags-Id ist ungültig. |
46Z | Die Angabe in KCLT ist ungültig. Mögliche Ursachen:
|
47Z | Der Nachrichtenbereich fehlt oder ist in der angegebenen Länge nicht zugreifbar. |
49Z | Der Inhalt nicht verwendeter Felder des KDCS-Parameterbereichs ist ungleich binär null. |
56Z | Der Wert in KCMOD oder die Zeitangabe in KCTAG/kcday, KCSTD/kchour, KCMIN oder KCSEK/kcsec ist ungültig. |
Ein weiterer Returncode ist dem DUMP zu entnehmen:
71Z | In diesem Teilprogramm-Lauf wurde noch kein INIT-Aufruf gegeben. |
Rückgaben im Nachrichtenbereich bei DADM RQ
Für die Rückgabeninformation bei Aufruf DADM RQ steht eine Datenstruktur zur Verfügung, für COBOL das COPY-Element KCDADC und für C/C++ die Include-Datei kcdad.h. Diese Datenstruktur können Sie zur Definition des Nachrichtenbereichs verwenden. Sie hat folgenden Aufbau:
Byte | Feldname | Bedeutung | |
|---|---|---|---|
1 - 8 | KCDAGUS | UTM-Benutzerkennung des Auftraggebers | |
9 - 16 | KCDADPID | Auftrags-Id (von openUTM vergeben) | |
17 - 25 | KCDAGTIM1 | Zeitpunkt des FPUT-/DPUT-Aufrufs in der Form dddhhmmss: | |
17 - 19 | KCDAGDOY | ddd | Tag im Jahr (Wertebereich 001 - 366) |
20 - 21 | KCDAGHR | hh | Stunde (Wertebereich 00 - 23) |
22 - 23 | KCDAGMIN | mm | Minute (Wertebereich 00 - 59) |
24 - 25 | KCDAGSEC | ss | Sekunde (Wertebereich 00 - 59) |
26 - 34 | KCDASTIM1 | bei zeitverzögertem Auftrag die gewünschte Startzeit in der Form dddhhmmss: | |
26 - 28 | KCDASDOY | ddd | Tag im Jahr (Wertebereich 001 - 366) |
29 - 30 | KCDASHR | hh | Stunde (Wertebereich 00 - 23) |
31 - 32 | KCDASMIN | mm | Minute (Wertebereich 00 - 59) |
33 - 34 | KCDASSEC | ss | Sekunde (Wertebereich 00 - 59) |
Bei einem Auftrag ohne Zeitverzögerung werden Leerzeichen zurückgegeben. | |||
35 | KCDAPMSG | Y | Positiver Quittungsauftrag vorhanden |
N | Kein positiver Quittungsauftrag vorhanden | ||
36 | KCDANMSG | Y | Negativer Quittungsauftrag vorhanden |
N | Kein negativer Quittungsauftrag vorhanden | ||
37 - 44 | KCDADEST | Ziel der Nachricht bzw. ursprüngliches Ziel bei Dead Letter Queue | |
45 | KCDATYPE | Typ des Ziels der Nachricht bzw. Typ des ursprünglichen Ziels bei Dead Letter Queue: | |
Q | für temporäre Queue | ||
U | für USER-Queue | ||
T | für TAC-Queue | ||
A | für Asynchron-TAC | ||
L | für LTERM | ||
P | für LPAP | ||
O | für OSI-LPAP | ||
46 - 53 | KCDAFCTM | Erzeugungs- oder Umwandlungszeitpunkt von DPUT in FPUT der Nachricht. Bei Service-gesteuerten Queues können die mit DADM RQ angezeigten Nachrichten den mit DGET BF gelesenen Nachrichten eindeutig zugeordnet werden. KCDADPID bzw. KCDAFCTM müssen mit den Rückgabewerten KCRDPID bzw. KCRGTM des entsprechenden DGET BF Aufrufs übereinstimmen. | |
54 | KCDAGUST | Typ des Auftraggebers: | |
U | für USER | ||
S | für LU6.1-Session | ||
O | für OSI-Association | ||
1 Für C/C++ sind die zusammenfassenden Felder KCDAGTIM und KCDASTIM nicht definiert, wohl aber die spezifischen Felder für Tag/Stunde/Minute/Sekunde.
Eigenschaften des DADM-Aufrufs
Ermitteln der Auftrags-Id
Die Auftrags-Id wird von openUTM intern vergeben. Sie kann im Teilprogramm wie folgt mit DADM RQ-Aufrufen ermittelt werden: Beim ersten DADM RQ-Aufruf (mit KCRN = Leerzeichen) informiert openUTM über die erste Nachricht in der Queue. openUTM schreibt dabei u.a. die Auftrags-Id in den Nachrichtenbereich. Stehen für die Queue weitere Nachrichten in der Message Queue, dann gibt openUTM in KCRMF/kcrfn die Auftrags-Id der jeweils nächsten Nachricht zurück. Bei der letzten Nachricht in der Queue trägt openUTM im Feld KCRMF/kcrfn Leerzeichen ein.
DADM CS/DL/DA/MV/MA-Aufrufe (Reihenfolge ändern, löschen oder verschieben) unterliegen der Transaktionssicherung und werden deshalb erst bei Transaktionsende ausgeführt. Daher garantiert KCRCCC = 000 nach einem solchen Aufruf noch nicht, dass der Aufruf erfolgreich ausgeführt werden kann, denn in der Zwischenzeit könnte die Nachricht in der Queue durch einen anderen DADM-Aufruf gelöscht worden sein. Ob ein DADM CS/DL/DA/MV/MA-Aufruf erfolgreich war, kann man in einer nachfolgenden Transaktion durch einen DADM RQ-Aufruf erfahren.
Durch den Aufruf DADM CS wird die entsprechende Nachricht an die erste Stelle der zugehörigen Warteschlage vorgezogen. Für zeitgesteuerte Nachrichten, deren Startzeitpunkt noch nicht erreicht ist, wird der Aufruf mit 40Z abgewiesen.
Nach einem Löschauftrag mit DADM DL/DA darf innerhalb derselben Transaktion kein weiterer Löschauftrag und auch kein DADM CS-Aufruf gegeben werden; openUTM lehnt dies mit 40Z ab.
Ein Teilprogramm, das einen DADM-Aufruf absetzt, muss unter einer administrationsberechtigten Benutzerkennung ablaufen, sonst quittiert openUTM den DADM-Aufruf mit 40Z. Allerdings gibt es folgende Ausnahme:
Wenn ein Vorgang von einem Druckersteuer-LTERM aus gestartet wurde und wenn nur solche Aufträge administriert werden, die an Drucker dieses Druckersteuer-LTERMs gerichtet sind, dann benötigen weder das Teilprogramm noch der Benutzer die Administrationsberechtigung.Die Dead Letter Queue besteht aus Nachrichten, die nicht verarbeitet werden konnten. Um diese Nachrichten evtl. nach einer Fehlerbehebung noch verarbeiten zu können, müssen sie entweder ihrem ursprünglichen Ziel oder einem neuen Ziel vom gleichen Typ zugeordnet werden.
Mit DADM MV kann eine einzelne Nachricht, mit DADM MA können alle Nachrichten der Dead Letter Queue verschoben werden. Dabei gibt es zwei Möglichkeiten:Verschieben in die jeweilige(n) ursprüngliche(n) Message Queue(s).
Verschieben der Nachricht bzw. aller Nachrichten mit ursprünglichem Ziel TAC (Asynchron-TAC oder TAC-Queue), LPAP oder OSI-LPAP an ein beliebiges anderes Ziel vom gleichen Typ.
Dabei wird ein evtl. definiertes QLEV und der STATUS der Empfänger-Queue ignoriert.
Bei DADM MA verbleiben Nachrichten in folgenden Fällen in der Dead Letter Queue, ohne dass dies über einen Returncode angezeigt wird:
KCLT = Leerzeichen: Alle Nachrichten, deren ursprüngliches Ziel nicht mehr existiert.
KCLT != Leerzeichen: Alle Nachrichten, deren ursprüngliches Ziel nicht zum neuen Ziel passt. Nachrichten, deren ursprüngliches Ziel nicht mehr existiert, passen dabei nur zum neuen Ziel Asynchron-TAC oder TAC-Queue.