Mit dem Aufruf FPUT (free message PUT) können Sie Nachrichten oder Nachrichtenteile für Message Queues erzeugen, die von openUTM jeweils in Empfänger-spezifische Queues eingetragen werden:
Ausgabeaufträge an LTERM-Partner
Hintergrund-Aufträge an lokale Asynchron-Vorgänge
Hintergrund-Aufträge an ferne Asynchron-Vorgänge, die zuvor mit APRO AM-Aufrufen adressiert wurden
Asynchron-Nachrichten an lokale oder entfernte TAC-Queues
Nur auf BS2000-Systemen: Druckoptionen für RSO-Drucker übergeben (= RSO-Parameterliste)
Die mit FPUT erzeugten Teilnachrichten werden von openUTM gesammelt und beim nächsten PEND-Aufruf abgeschlossen. Die Teilnachrichten werden bei Transaktionsende als eine Nachricht in die entsprechende Message Queue eingetragen. Ausnahme: Bei formatierten Teilnachrichten an Terminals bildet jede Teilnachricht eine eigenständige Nachricht.
Im Falle von TAC-Queues muss der Empfänger die Nachricht in einer eigenen Transaktion aus der Queue lesen.
Nachrichten bleiben solange in einer Message Queue erhalten bis sie:
erfolgreich gesendet (LTERM-Partner) oder
erfolgreich verarbeitet (Asynchron-Vorgang) oder
erfolgreich gelesen wurden (TAC-Queue).
Im Folgenden wird das Format des FPUT-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 verschiedenen Möglichkeiten und die Angaben im KDCS-Parameterbereich.
Funktion des Aufrufs | Einträge im KDCS-Parameterbereich | |||||
|---|---|---|---|---|---|---|
KCOP | KCOM | KCLM | KCRN | KCMF/kcfn | KCDF | |
Ausgabeauftrag im Formatmodus | "FPUT" | "NT"/"NE" | Länge | LTERM-Name | Formatkennzeichen | Bildschirmfunktion |
Unix-, Linux-, Windows-Systeme: | "FPUT" | "NT"/"NE" | Länge | LTERM-Name | Leerzeichen | —— |
BS2000-Systeme: | "FPUT" | "NT"/"NE" | Länge | LTERM-Name | Leerzeichen/Editprofil | Bildschirmfunktion / binär null |
Nachricht an Asynchron-Programm oder an | "FPUT" | "NT"/"NE" | Länge | TAC / Name einer TAC-Queue | —— | —— |
Ausgabe-Auftrag an Transportsystem-Anwendung | "FPUT" | "NT"/"NE" | Länge | LTERM-Name der Anwendung | Leerzeichen | binär null |
Hintergrund-Auftrag über LU6.1 | "FPUT" | "NT"/"NE" | Länge | Vorgangs-Id | —— | —— |
Hintergrund-Auftrag über OSI TP | "FPUT" | "NT"/"NE" | Länge | Vorgangs-Id | Name der abstrakten Syntax / Leerzeichen | —— |
BS2000-Systeme: | "FPUT" | "RP" | Länge | LTERM-Name | Leerzeichen | binär null |
NT: Teilnachricht zum Auftrag
NE: letzte Teilnachricht oder Gesamtnachricht zum Auftrag
RP: RSO Parameterliste (BS2000-Systeme)
Versorgen des 2. Parameters
Hier stellen Sie die Adresse des Nachrichtenbereichs bereit, aus dem openUTM die Nachricht oder die RSO-Parameterliste lesen soll.
Versorgen der Parameter | |
Feldname im KDCS-Parameterbereich | Inhalt |
"FPUT" | |
"NT"/"NE"/"RP" | |
Länge in Byte | |
LTERM-Name/TAC/TAC-Queue/Vorgangs-Id | |
Formatkennzeichen / Leerzeichen / Name der abstrakten Syntax / Editprofile (nur auf BS2000-Systemen) | |
Bildschirmfunktion / binär null | |
Daten | |
KDCS-Aufruf | |
KDCS-Parameterbereich | Nachrichtenbereich |
C/C++-Makroaufrufe | |
Parameter | |
KDCS_FPUTNT / KDCS_FPUTNE | (nb,kclm,kcrn,kcfn,kcdf) |
KDCS_FPUTRP | (nb,kclm,kcrn) |
In den KDCS-Parameterbereich tragen Sie für den FPUT-Aufruf ein:
KCOP
im Feld KCOP den Operationscode FPUT.
KCOM
im Feld KCOM entweder NT für Teilnachricht oder NE für Gesamtnachricht bzw. letzte Teilnachricht oder RP für eine RSO-Parameterliste.
KCLM
im Feld KCLM die Länge der Nachricht im Nachrichtenbereich, die gesendet werden soll (Länge Null darf auch angegeben werden).
Nur auf BS2000-Systemen: Bei KCOM = RP ist dies die Länge der Datenstruktur für die RSO-Parameterliste.
KCRN
im Feld KCRN abhängig vom Empfänger der Nachricht:
den Namen eines LTERM-Partners, wenn dieser FPUT-Aufruf einen Ausgabeauftrag erzeugt oder eine RSO-Parameterliste übergibt,
den Transaktionscode eines Asynchron-Programms, wenn dieser FPUT-Aufruf einen Hintergrund-Auftrag erzeugt (ohne verteilte Verarbeitung),
die Vorgangs-Id eines Auftragnehmer-Vorgangs, wenn dieser Hintergrund-Auftrag an einen Auftragnehmer-Vorgang gerichtet ist,
den Namen der TAC-Queue, wenn die Nachricht an eine TAC-Queue gesendet werden soll,
die Vorgangs-Id der fernen TAC-Queue, wenn diese Nachricht an eine ferne TAC-Queue gesendet werden soll.
KCMF / kcfn
im Feld KCMF/kcfn (bei Nachrichten an einen Asynchron-Vorgang bzw. eine TAC-Queue derselben Anwendung oder an einen LU6.1-Partner irrelevant):
Leerzeichen im Zeilenmodus oder bei einem Auftrag an eine andere Anwendung ohne verteilte Verarbeitung oder beim Übergeben einer RSO-Parameterliste.
bei Nachrichten an OSI TP-Partner:
Name der abstrakten Syntax der Nachricht. Leerzeichen stehen dabei für die abstrakte Syntax von UDT; in diesem Fall wird als Transfer Syntax BER verwendet, und die Encodierung der Nachricht übernimmt openUTM.Wird hier ein Wert ungleich Leerzeichen angegeben, dann muss die Nachricht an openUTM in encodierter Form, d.h. in der zu dieser abstrakten Syntax passenden Transfer Syntax, übergeben werden.
Nur auf BS2000-Systemen:
ein Formatkennzeichen (im Formatmodus)
Bei Nachrichten an RSO-Drucker:
Wenn ein Format speziell für RSO-Drucker erstellt wurde, muss das Formatierungssystem FHS den Druckertyp nicht kennen, da FHS eine logische Nachricht erzeugt, die von RSO in die physikalische Nachricht umgewandelt wird.
Andernfalls muss FHS den Druckertyp, wie er bei RSO generiert ist, unterstützen, da es sonst zum Formatierungsfehler kommt.Editprofil (bei Zeilenmodus oder einem RSO-Drucker)Ist die Nachricht an einen RSO-Drucker gerichtet, so wird nur der Parameter CCSNAME eines Editprofils ausgewertet. Der Zeichensatzname wird an RSO übergeben. Alle weiteren Parameter des Editprofils werden ignoriert, da es sich um VTSU-B Editoptionen handelt, die Nachricht aber von RSO aufbereitet wird.
KCDF
Im Feld KCDF (bei Hintergrund-Aufträgen und TAC-Queues irrelevant):
die Bildschirmfunktion, wenn der FPUT-Aufruf an einen LTERM-Partner gerichtet ist. Bei Aufträgen an andere Anwendungen ohne verteilte Verarbeitung oder bei Übergabe von RSO-Parameterlisten muss hier binär null angegeben werden.
Auf BS2000-Systemen musss binär null auch dann angegeben werden, wenn in KCMF/kcfn ein Editprofil oder ein #Format eingetragen ist.
Nachrichtenbereich
Im Nachrichtenbereich tragen Sie die Nachricht ein, die Sie ausgeben oder die RSO-Parameterliste, die Sie übergeben wollen.
Beim KDCS-Aufruf geben Sie an:
1. Parameter
als 1. Parameter: Die Adresse des KDCS-Parameterbereichs.
2. Parameter
als 2. Parameter: die Adresse des Nachrichtenbereichs, aus dem openUTM die Nachricht oder RSO-Parameterliste lesen soll. Die Adresse des Nachrichtenbereichs geben Sie auch an, wenn Sie in KCLM 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:
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 FPUT-Aufruf
Im Programm sind auswertbar:
000 | Die Funktion wurde ausgeführt. |
04Z | Der Name in KCRN wechselt, ohne dass vorher FPUT NE gegeben wurde. |
40Z | openUTM kann die Funktion nicht durchführen (System- bzw. Generierungsfehler, Deadlock, langandauernde Sperren), siehe KCRCDC. |
41Z | In KCRN wurde der LTERM-Partner adressiert, der den laufenden Vorgang begonnen hat, oder FPUT wurde im ersten Teil des Anmelde-Vorgangs abgesetzt oder es wurde ein FPUT-Aufruf im Anmelde-Vorgang nach einem SIGN ON und vor dem PEND PS Aufruf abgesetzt. |
42Z | Der Eintrag in KCOM ist ungültig. |
43Z | Die Längenangabe in KCLM ist negativ bzw. ungültig. |
44Z | Der Wert in KCRN ist kein TAC eines Asynchron-Programms bzw. einer TAC-Queue, oder der TAC ist gesperrt bzw. verboten und ebenfalls kein Name eines LTERM-Partners bzw. der Name eines UPIC- oder HTTP-Clients, und keine gültige Vorgangs-Id (bei verteilter Verarbeitung), siehe KCRCDC. Nur auf BS2000-Systemen: |
45Z | Der Eintrag in KCMF/kcfn ist unzulässig. Mögliche Ursachen:
Nur auf BS2000-Systemen:
|
47Z | Der Nachrichtenbereich fehlt oder ist in der angegebenen Länge nicht zugreifbar. |
Ein weiterer Returncode ist dem DUMP zu entnehmen:
71Z | In diesem Programm wurde kein INIT gegeben. |
Eigenschaften des FPUT-/DPUT-Aufrufs
FPUT- und DPUT-Aufrufe, die Teilprogramme an ein Alias-LTERM richten, werden wie folgt bearbeitet:
In einer LTERM-Gruppe ohne LTERM-Bündel werden FPUT-/DPUT-Aufrufe von openUTM über das PTERM gesendet, das dem Primary-LTERM zugeordnet ist.
In einer LTERM-Gruppe, deren Primary-LTERM das Master-LTERM eines LTERM-Bündels ist, weist openUTM beim Transaktionsende alle Asynchron-Nachrichten, die in dieser Transaktion an Alias-LTERMs der Gruppe gerichtet wurden, genau einem der Slave-LTERMs zu. Dieses Vorgehen garantiert, dass beim Empfänger die Reihenfolge der Nachrichten erhalten bleibt, die in einer Transaktion für eine LTERM-Gruppe erzeugt wurden.
FPUT- und DPUT-Aufrufe, die Teilprogramme an das Master-LTERM richten, werden beim Transaktionsende einem der Slave-LTERMs zugewiesen.
FPUT- und DPUT-Aufrufe können Teilprogramme auch direkt an das Primary-LTERM richten.
Der Nachrichtenbereich wird beim Ausführen des Aufrufs durch openUTM nicht verändert.
In einem Teilprogramm können mehrere Aufträge erzeugt werden; die zugehörigen Nachrichten können aus mehreren Teilen bestehen.
Bei Ausgabe von +Formaten, *Formaten oder Nachrichten im Zeilenmodus können Sie auch Bildschirmausgabefunktionen verwenden, siehe Abschnitt „Bildschirmausgabefunktionen im Formatmodus (BS2000-Systeme)".
Nur auf BS2000-Systemen:
Wenn Sie #Formate verwenden, müssen Sie KCDF mit binär null versorgen, sonst reagiert openUTM mit 40Z.
Auch bei der Verwendung von Editprofilen reagiert openUTM mit 40Z, falls KCDF nicht mit binär null versorgt ist.
Bei einem PEND ER/FR, PEND RS oder RSET werden die mit FPUT erzeugten Aufträge verworfen.
In einem Dialog-Programm darf kein Ausgabeauftrag an den Client, mit dem das Programm gerade arbeitet, erzeugt werden (KCRN
!=KCLOGTER).Bei FPUT-Aufrufen an eine andere UTM-Anwendung, die als Transportsystem-Anwendung generiert ist, muss der TAC jeweils am Anfang des Nachrichtenbereichs stehen.
Die Nachricht wird gegebenenfalls formatiert, bevor sie ausgegeben wird.
Nachrichten werden aufbewahrt bis:
das angesprochene Teilprogramm oder die Druckerausgabe beendet ist oder, bei Aufträgen an ferne Asynchron-Vorgänge, die Übertragung erfolgreich abgeschlossen ist oder
die Nachricht mit KDCOUT am Terminal gelesen und eine neue Eingabe gemacht wurde (außer KDCLAST-Kommando) oder
die Nachricht aus einer TAC-Queue mit einem DGET-Aufruf gelesen und die den DGET beinhaltende Transaktion erfolgreich abgeschlossen wurde.
Aufträge mit Nachrichten der Länge 0
Erzeugt man eine Nachricht der Länge 0 (so genannte "leere Nachrichten"), so wird
ein Hintergrund-Auftrag ausgeführt, d.h. der Asynchron-Vorgang wird gestartet, ohne dass er eine Nachricht erhält,
bei einem Ausgabeauftrag im Formatmodus ein leeres Format ausgegeben,
bei einer Nachricht für eine TAC-Queue eine leere Nachricht erzeugt, die mit einem DGET-Aufruf gelesen werden kann,
ein Ausgabeauftrag an eine Transportsystem-Anwendung zwar angenommen, aber von openUTM zu einem späteren Zeitpunkt verworfen.
Hintergrund-Aufträge an ein Asynchron-Programm der gleichen Anwendung: Jeder Hintergrund-Auftrag bewirkt, dass ein eigener Asynchron-Vorgang gestartet wird. Werden in einem Teilprogrammlauf mehrere vollständige Nachrichten an den gleichen TAC gesendet, wird für jede Nachricht ein eigener Asynchron-Vorgang gestartet
Werden in einem Teilprogrammlauf mehrere vollständige Nachrichten an die gleiche TAC-Queue gesendet, muss jede Nachricht mit einem eigenen DGET FT-Aufruf gelesen werden.
Wechselwirkungen zwischen FPUT- und DPUT-Aufrufen gibt es nicht, d.h. an ein bestimmtes Ziel können unabhängig voneinander DPUT-Aufrufe mit KCMOD = "'BLANK'" und FPUT-Aufrufe gesendet werden.
Ausgabeaufträge, die für ein Terminal bestimmt sind, werden in die Message Queue eingehängt, und können vom Benutzer mit dem Kommando KDCOUT gelesen werden. Pro KDCOUT-Kommando wird genau eine Nachricht gelesen. Jede Nachricht kann nur einmal gelesen werden. Bei wiederholter Eingabe des KDCOUT-Kommandos wird die nächste Nachricht aus der Queue gelesen.
Dass für ein Terminal Asynchron-Nachrichten vorliegen, wird dem Terminalbenutzer bei Transaktionsende durch eine Meldung in der Systemzeile mitgeteilt.
Auf BS2000-Systemen kann diese Ankündigung unterdrückt werden, wenn bei der Konfiguration für den betreffenden LTERM-Partner ANNOAMSG=N angegeben wurde (Standardwert: ANNOAMSG=Y). Asynchron-Nachrichten werden dann sofort am Bildschirm angezeigt. Dadurch kann die Dialog-Führung gestört werden. Der Terminalbenutzer kann sich jedoch mit dem KDCDISP-Kommando den letzten Bildschirm wieder anzeigen lassen.
Druckoptionen für RSO-Drucker (BS2000-Systeme)
Wenn Sie Druckoptionen für Aufträge an RSO-Drucker verwenden, dann übergeben Sie zuerst mit FPUT RP die Liste mit den Druckoptionen, siehe Handbuch „RSO“. Danach geben Sie mit FPUT NT/NE den eigentlichen Druckauftrag.
Behandeln von Teilnachrichten
Teilnachrichten im Zeilenmodus werden zusammengefasst und als eine Nachricht an den LTERM-Partner ausgegeben. Die mit FPUT erzeugten Teilnachrichten werden von openUTM gesammelt und beim nächsten PEND-Aufruf abgeschlossen, falls der Teilprogrammlauf sie noch nicht mit FPUT NE abgeschlossen hat. Die Teilnachrichten werden bei Transaktionsende als eine Nachricht an den LTERM-Partner oder an die andere Anwendung gesendet.
Bei formatierten Teilnachrichten an Terminals erzeugt jede Teilnachricht eine eigenständige Nachricht. Der Formatname in KCMF/kcfn darf dabei wechseln. An einem Terminal muss jedes Format (jeder Teilnachricht) mit einem KDCOUT-Kommando abgeholt werden. Jeder FPUT NT-Aufruf erzeugt eine eigene Nachricht. Deshalb ist es nicht möglich, mit FPUT NT-Aufrufen einen Bildschirm aus mehreren Teilformaten aufzubauen. Die Formate treffen in der Reihenfolge ein, in der sie erzeugt wurden.
Bei Teilnachrichten an Drucker ist ein Wechsel zwischen formatierten Teilnachrichten und nicht-formatierten Teilnachrichten (im Zeilen-Modus) möglich. Bei Teilnachrichten an Terminals führt dieser Wechsel zum Abschluss der alten und zum Beginn einer neuen Nachricht.
Bei FPUT NT-Aufrufen an lokale oder auch ferne Asynchron-Vorgänge bzw. lokale oder ferne TAC-Queues muss jede Teilnachricht mit einem eigenen FGET NT gelesen werden.
Beim PEND wird die zuletzt mit FPUT aufgebaute Teilnachricht grundsätzlich als letzte Teilnachricht angenommen, auch wenn sie mit NT ausgegeben wurde.
Die maximale Anzahl der FPUT NE-Aufrufe in einer Transaktion wird vom Generierungsparameter RECBUF der KDCDEF-Anweisung MAX begrenzt. Pro FPUT NE werden 30 Bytes in diesem Puffer belegt. Ist der Puffer voll, so wird der FPUT NE mit KCRCDC=K704 abgewiesen.
Wechselt der Name in KCRN (d.h. der Empfänger der Nachricht) bei einer Folge von Teilnachrichten, ohne dass vorher ein FPUT NE gegeben wurde, wird eine Warnung (04Z) erzeugt und eine neue Nachricht begonnen. Die vorherige Nachricht (Teilnachrichtenfolge) wird abgeschlossen; d.h. wechselt mit einem folgenden FPUT der Name in KCRN noch einmal zurück zum ersten Empfänger, wird die erste Nachricht nicht fortgesetzt. Es wird eine neue Nachricht begonnen. Die Nachricht wird beim nächsten Sicherungspunkt an den Empfänger weitergeleitet. Ein paralleler Nachrichtenaufbau wie beim DPUT ist also nicht möglich.
Nur auf BS2000-Systemen: Wechselt das Editprofil innerhalb einer Folge von Teilnachrichten, die an ein Terminal gerichtet sind, dann reagiert openUTM mit 45Z.
Einfluss von Generierungsparametern auf den FPUT-Aufruf
Die folgenden Hinweise beziehen sich auf die Generierung der UTM-Anwendung. Näheres zu den einzelnen Generierungsparametern finden Sie im openUTM-Handbuch „Anwendungen generieren“.
Bei Nachrichten an Terminals und Transportsystem-Anwendungen darf die Gesamtnachricht höchstens so groß sein wie der im Operanden NB der Steueranweisung MAX generierte Wert. Bei Nachrichten an andere Partner ist die Länge einer Teilnachricht auf 32767 beschränkt und die Länge der Gesamtnachricht unbegrenzt.
Beim Aktualisieren der KDCFILE mit dem UTM-Tool KDCUPD kann in der TRANSFER-Anweisung differenziert festgelegt werden, welche Nachrichten in die neue KDCFILE übernommen werden sollen (siehe auch openUTM-Handbuch „Anwendungen generieren“).
Nur auf BS2000-Systemen: Der Operand ANNOAMSG der KDCDEF-Steueranweisung LTERM legt für jeden LTERM-Partner fest, ob Asynchron-Nachrichten an dieses Terminal sofort ausgegeben oder mit einer Meldung angekündigt werden. Die Meldung erscheint in der Systemzeile.
FPUT-Aufrufe bei verteilter Verarbeitung
Im Auftraggeber-Vorgang ist der KDCS-Parameterbereich vor dem FPUT-Aufruf genauso zu versorgen wie bei Hintergrund-Aufträgen an ein Asynchron-Programm der eigenen Anwendung. Lediglich als Rufname im Feld KCRN ist die Vorgangs-Id anzugeben, die vorher beim APRO AM-Aufruf für den Auftragnehmer-Vorgang vergeben wurde.
Nach Abschluss des Aufrufs FPUT NE (letzter Nachrichtenteil oder Gesamtnachricht) oder nach dem KDCS-Returncode 40Z wird die Vorgangs-Id im Auftraggeber-Vorgang freigegeben. Die gleiche Identifikation kann dann für eine neue Auftraggeber/Auftragnehmer-Beziehung dieses Vorgangs verwendet werden.
Falls die Wartezeit für die Belegung einer Session bzw. Association bei der Generierung auf 0 gesetzt wurde und falls beim FPUT-Aufruf keine Verbindung zur Partner-Anwendung besteht, dann setzt openUTM nach dem FPUT-Aufruf die Returncodes 40Z in KCRCCC und KD13 in KCRCDC.