Mit dem Aufruf FGET (free message GET) wird eine Asynchron-Nachricht oder -Teilnachricht aus der dem Service zugeordneten Message Queue in den Nachrichtenbereich eingelesen.
Der FGET-Aufruf darf nur im ersten Teilprogrammlauf und Verarbeitungsschritt eines Asynchron-Vorgangs gegeben werden. Jede Nachricht kann nur einmal gelesen werden. Dabei ist jede Teilnachricht mit einem eigenen FGET zu lesen. Nur nach einem RSET-Aufruf kann eine (Teil-)Nachricht noch einmal gelesen werden.
Im Folgenden wird das Format des FGET-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 | KCLA | KCMF/kcfn | |
Asynchron-Nachricht lesen | "FGET" | Länge | Formatkennzeichen / Leerzeichen / Name der abstrakten Syntax/ Editprofile (nur BS2000-Systeme) |
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 |
"FGET" | |
Länge in Byte | |
Formatkennzeichen / Leerzeichen / Name der abstrakten Syntax/ Name des Editprofils (nur BS2000-Systeme) | |
KDCS-Aufruf | |
KDCS-Parameterbereich | Nachrichtenbereich |
C/C++-Makroaufruf | |
Parameter | |
KDCS_FGET | (nb,kcla,kcfn) |
Rückgaben von openUTM | |
|---|---|
Inhalt | |
Daten | |
Feldname im KB-Rückgabebereich | |
tatsächliche Länge | |
Returncode | |
interner Returncode | |
Formatkennzeichen/Leerzeichen | |
Redelivery-Zähler | |
Im KDCS-Parameterbereich machen Sie für den FGET-Aufruf folgende Angaben:
KCOP
Im Feld KCOP tragen Sie den Operationscode FGET ein.
KCLA
Im Feld KCLA geben Sie die Länge an, in der die Nachricht gelesen werden soll. Sie darf höchstens so groß sein wie der Nachrichtenbereich, in den die Nachricht gelesen werden soll. Länge Null bedeutet: kein Nachrichtenempfang. Eine eventuell vorhandene Nachricht geht verloren.
KCMF/kcfn
Im Feld KCMF/kcfn geben Sie das Format der zu lesenden Nachricht an:
bei Zeilenmodus: Leerzeichen
oder auf BS2000-Systemen: Name des Editprofils (wird beim INIT im Feld KCRMF/kcrfn zurückgegeben). Dieser Name beginnt mit einem Leerzeichen.
im Formatmodus auf BS2000-Systemen: Formatkennzeichen des erwarteten (Teil) Formats. Dieses wurde beim INIT- bzw. beim vorangegangenen FGET-Aufruf im Feld KCRMF/kcrfn zurückgegeben.
bei einer Nachricht von einem Teilprogramm derselben Anwendung oder von einem LU6.1-Partner: irrelevant.
bei Nachricht von einem OSI TP-Partner:
Name der abstrakten Syntax der Nachricht.
Dieser Name wurde im Feld KCRMF/kcrfn bei dem vorausgegangen INIT-Aufruf zurückgegeben. Leerzeichen stehen dabei für die abstrakte Syntax von UDT codiert nach BER (Basic Encoding Rules); nur in diesem Fall wird die Nachricht von openUTM an das Teilprogramm bereits decodiert übergeben.
Wird hier ein Wert ungleich Leerzeichen angegeben, dann übergibt openUTM die Nachricht an das Teilprogramm in encodierter Form, d.h. in der zu dieser abstrakten Syntax passenden Transfer Syntax; das Teilprogramm muss die Umsetzung in die lokale Darstellung selbst übernehmen. Dies kann z.B. mit Hilfe eines ASN.1-Compilers geschehen.
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 (Teil-)Nachricht in der tatsächlichen, höchstens aber in der angeforderten Länge.
KCRLM
im Feld KCRLM die tatsächliche Länge der (Teil-)Nachricht, ggf. in Abweichung von der angeforderten Länge in KCLA des Parameterbereichs.
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“).
KCRMF/kcrfn
im Feld KCRMF/kcrfn:
nach dem Lesen im Zeilenmodus: Leerzeichen
oder auf BS2000-Systemen: Name des Editprofils der letzten Ausgabenachricht.
nach dem Lesen von einem Partner-Vorgang:
Name des Formatkennzeichens bzw. der abstrakten Syntax der nächsten (Teil-)Nachricht.
Nur auf BS2000-Systemen:
nach dem Lesen eines ganzen Formats: Kennzeichen des zuletzt eingelesenen Formats. Es ist immer gleich dem Kennzeichen des letzten Ausgabeformats.
nach dem Lesen eines Teilformats: Kennzeichen des nächsten Teilformats mit Eingabedaten.
nach dem Lesen des letzten Teilformats: Kennzeichen des zuletzt eingelesenen Teilformats. In diesem Fall ist KCRMF = KCMF (bzw.: kcrfn=kcfn).
KCRRC
im Feld KCRRC den Redelivery-Zähler der gelesenen Nachricht. Dieser enthält die Anzahl der erneuten Zustellungen der FGET-Nachricht nach abnormalem Beenden der Asynchron-Vorgänge in der ersten Transaktion.
Absenderangaben usw. stehen im KB-Kopf (von openUTM beim INIT eingetragen).
KDCS-Returncodes im Feld KCRCCC beim FGET-Aufruf
Im Programm sind auswertbar:
000 | Die Operation wurde durchgeführt. |
01Z | Längenkonflikt: KCLA < KCRLM, die Nachricht wurde abgeschnitten. |
03Z | Bei Teilformaten: Eingabenachricht von einem OSI TP-Partner: |
05Z | Bei Einzelformaten war am Bildschirm ein anderes Format ausgegeben als in KCMF/kcfn eingetragen. Nur auf BS2000-Systemen: |
10Z | Die Nachricht bzw. alle Teilnachrichten wurden bereits vollständig gelesen. |
Weitere Returncodes sind dem DUMP zu entnehmen:
71Z | Die Funktion wurde in einem Folge-Teilprogramm oder nach einem PGWT-Aufruf eines Asynchron-Vorgangs oder in einem Dialog-Vorgang aufgerufen bzw. im Teilprogrammlauf wurde noch kein INIT aufgerufen. |
73Z | Die Längenangabe in KCLA ist negativ oder ungültig. |
77Z | Der Nachrichtenbereich fehlt oder ist in der angegebenen Länge nicht zugreifbar. |
Eigenschaften des FGET-Aufrufs
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 FGET nicht mehr gelesen werden.
Bei der Beschreibung des MGET-Aufrufs finden Sie ein Beispiel, das das Verhalten von openUTM bei Längenkonflikten erläutert.
Ein Teilprogramm kann auch Asynchron-Nachrichten der Länge 0 empfangen, wenn z.B.
eine Funktionstaste eingegeben wurde, ohne eine Nachricht zuzuordnen,
ein Transaktionscode ohne weitere Daten gesendet wurde,
ein Programm der gleichen Anwendung einen Hintergrund-Auftrag mit einer Nachricht der Länge 0 gegeben hat.
TAC-Eingabe von einem Terminal oder einer Transportsystem-Anwendung:
Wird ein Asynchron-TAC im Zeilenmodus eingegeben und in KCMF/kcfn ein Formatkennzeichen eingetragen, so wird nicht - wie beim MGET - der Returncode KCRCCC = 05Z gesetzt, sondern KCRCCC = 000 (falls der Aufruf sonst fehlerfrei ist).
Bei Eingaben aus Teilformaten muss jedes Teilformat mit einem eigenen FGET gelesen werden.
Wird zusammen mit dem Asynchron-TAC eine Nachricht eingegeben, so wird der TAC von der Nachricht abgetrennt: Der TAC wird nicht in den Nachrichtenbereich eingelesen, sondern steht nach dem INIT im KB-Kopf zur Verfügung.
openUTM nimmt keine Umsetzung von Kleinbuchstaben in Großbuchstaben vor.
Auf BS2000-Systemen lässt sich eine Umsetzung jedoch über Editprofile erreichen.
Die Anzahl der erneuten Zustellungen wird im Feld KCRRC zurückgegeben. Eine Nachricht wird immer dann erneut zugestellt, wenn ein Asynchron-Vorgang in der ersten Transaktion abnormal beendet wurde. Voraussetzung ist, dass die Anwendung entsprechend generiert wurde und die generierte maximale Anzahl der erneuten Zustellungen noch nicht erreicht ist. Näheres siehe openUTM-Handbuch „Anwendungen generieren“, Operand REDELIVERY in der MAX-Anweisung.
Sicherung fehlerhafter Nachrichten in der Dead Letter Queue:
Asynchron-Nachrichten zu Transaktionscodes können im Fehlerfall als letzte Rückfallstufe in der globalen Dead Letter Queue gesichert werden. Dazu muss der TAC mit DEAD-LETTER-Q=YES generiert werden. Dann wird die FGET-Nachricht bei abnormaler Beendigung des Asynchron-Vorgangs ohne erfolgreichen Abschluss einer Transaktion in die Dead Letter Queue gestellt, wenn sie nicht erneut zugestellt werden kann (siehe Redelivery) und kein negativer Quittungsauftrag definiert wurde. Sobald ein Asynchron-Vorgang einen Sicherungspunkt erreicht hat, ist sowohl Redelivery als auch Sicherung der FGET-Nachricht in der Dead Letter Queue ausgeschlossen, da die Nachricht dann als erfolgreich verarbeitet gilt.
Beim Sichern einer Nachricht in der Dead Letter Queue wird die Anzahl der erneuten Zustellungen dieser Nachricht (Redelivery) ggf. auf Null zurückgesetzt.