Mit KC_SEND_MESSAGE können Sie eine Nachricht an ein, mehrere oder alle aktiven Terminals einer UTM-Anwendung auf einem BS2000-System senden. Der Text der Nachricht darf bis zu 74 Zeichen lang sein und wird im Datenbereich an UTM übergeben. Als Nachricht sendet UTM dann die Meldung K023 mit der angegebenen Nachricht als Insert. Sie wird standardmäßig in der Systemzeile am Terminal ausgegeben. Das Meldungsziel der Meldung K023 kann jedoch auch geändert werden. Ist für die UTM-Meldung K023 das Meldungsziel PARTNER ausgewählt (siehe openUTM-Handbuch „Meldungen, Test und Diagnose auf BS2000-Systemen“), können Sie die Nachricht auch an eine, mehrere oder alle konnektierten TS-Anwendungen senden. Die Nachricht geht nur an Dialog-Partner (LTERM mit USAGE=D).
Mit KC_SEND_MESSAGE können Sie:
eine Nachricht an alle Terminals senden, die zur Zeit mit der Anwendung verbunden sind. Dies gilt auch für Terminals, die über einen LTERM-Pool mit der Anwendung verbunden sind.
eine Nachricht an alle TS-Anwendungen senden, die mit der UTM-Anwendung verbunden sind, sofern das Meldungsziel PARTNER für K023 generiert ist.
eine Nachricht an einen bestimmten Terminal-Benutzer oder, vorausgesetzt das Meldungsziel PARTNER ist generiert, an eine bestimmte TS-Anwendung senden. In diesem Fall müssen Sie im Identifikationsbereich den Namen des LTERM-Partners angeben, über den das Terminal mit der Anwendung verbunden ist. Voraussetzung für das Zustellen der Nachricht ist, dass das Terminal zum Zeitpunkt des KC_SEND_MESSAGE-Aufrufs mit der Anwendung verbunden ist.
Wollen Sie die Nachricht an einen bestimmten Benutzer senden, dann können Sie den LTERM-Partner, über den der Benutzer bei der Anwendung angemeldet ist, wie folgt ermitteln:
Sie fordern mit KC_GET_OBJECT zunächst Informationen über die Benutzerkennung an, mit der sich der Benutzer bei der Anwendung angemeldet hat (Objekttyp KC_USER).
UTM liefert dann die Eigenschaften der Benutzerkennung in der Datenstruktur kc_user_str zurück. Ist der Benutzer zum Zeitpunkt der Abfrage mit der Anwendung verbunden, dann steht im Feld lterm_curr der Name des LTERM-Partners, über den der Benutzer angemeldet ist. Diesen Namen übergeben Sie beim Senden der Nachricht mit KC_SEND_MESSAGE im Identifikationsbereich.
Ablauf / Transaktionssicherung
Ein Aufruf von KC_SEND_MESSAGE unterliegt nicht der Transaktionssicherung. Er ist nicht durch einen RSET-Aufruf in derselben Transaktion rücksetzbar.
Geben Sie im Identifikationsbereich keinen Empfänger an und setzen Sie im Parameterbereich obj_number=0, dann ermittelt UTM alle derzeit aktiven LTERM-Partner, die mit usage_type='D' eingetragen sind, und sendet ihnen die Nachricht zu. Bei der Rückkehr in das Teilprogramm wurde die Nachricht bereits gesendet.
Geben Sie im Identifikationsbereich den Namen eines LTERM-Partners an und setzen im Parameterbereich obj_number=1, dann bedeutet die erfolgreiche Bearbeitung des KC_SEND_MESSAGE-Aufrufs, dass die Nachricht an diesen LTERM-Partner gesendet wurde. Ist der LTERM-Partner zur Zeit nicht erreichbar, dann liefert UTM einen entsprechenden Returncode zurück.
Versorgung der zu übergebenden Bereiche
Funktion des Aufrufs | Angabe im | |||
Parameterbereich 1 | Identifikationsbereich | Selektionsbereich | Datenbereich | |
Nachricht an alle aktiven LTERM-Partner senden | obj_number: 0
| —— | —— | Nachricht |
Nachricht an einen LTERM-Partner senden | obj_number: 1 | Name des LTERM-Partners | —— | Nachricht |
1 In allen Fällen muss im Parameterbereich der Operationscode KC_SEND_MESSAGE angegeben werden.
Versorgung der Parameter | |
Parameterbereich | |
Feldname | Inhalt |
version | KC_ADMI_VERSION_1 |
retcode | KC_RC_NIL |
version_data | KC_VERSION_DATA_11 |
opcode | KC_SEND_MESSAGE |
1 / 0 | |
Länge Objektname / 0 | |
select_lth | 0 |
Länge | |
Objektname / — | |
Selektionsbereich | |
— | |
Nachricht | |
KDCADMI-Aufruf |
KDCADMI (¶meter_area, &identification_area, NULL, &data_area) oder |
Rückgaben von UTM | |
Parameterbereich | |
Feldname | Inhalt |
Returncodes | |
obj_number
In obj_number geben Sie an, ob die Nachricht an alle derzeit aktiven LTERM-Partner gesendet werden soll, oder nur an einen bestimmten LTERM-Partner.
obj_number=0 bedeutet:
Die Nachricht soll an alle aktiven LTERM-Partner gesendet werden. Als Adresse des Identifikationsbereichs muss der Nullpointer übergeben werden.obj_number=1 bedeutet:
Die Nachricht soll nur an einen LTERM-Partner gesendet werden. Der Name des LTERM-Partners ist im Identifikationsbereich zu übergeben.
id_lth
In id_lth ist die Länge des Identifikationsbereichs anzugeben. D.h.:
bei obj_number=0 müssen Sie id_lth=0 setzen.
bei obj_number=1 müssen Sie in id_lth die Länge des Objektnamens angeben, der im Identifikationsbereich übergeben wird.
data_lth
Länge der Nachricht, die gesendet werden soll. Die Nachricht müssen Sie im Datenbereich übergeben. Es muss sein: 1 <= data_lth <= 74.
Identifikationsbereich
Wie Sie den Identifikationsbereich versorgen müssen, ist abhängig von obj_number.
bei obj_number=0 müssen Sie beim KC_SEND_MESSAGE-Aufruf den Nullpointer übergeben.
bei obj_number=1 müssen Sie im Identifikationsbereich die Union kc_id_area mit dem Namen des LTERM-Partners angeben (Feld kc_name8), an den die Nachricht gesendet werden soll.
Datenbereich
Im Datenbereich ist die Nachricht, die UTM senden soll, als Character-String zu übergeben. Die Nachricht darf nicht länger als 74 Zeichen sein.
retcode
Im Feld retcode liefert UTM den Returncode des Aufrufs zurück. Neben den im Abschnitt „Returncodes" aufgelissteten Returncodes können zusätzlich folgende Returncodes auftreten.
Maincode = KC_MC_REJECTED Der Aufruf wurde von UTM abgewiesen. Subcodes: |
KC_SC_NOT_EXISTENT Der im Identifikationsbereich angegebene Name ist unbekannt, ein LTERM-Partner mit diesem Namen existiert nicht. |
KC_SC_NOT_ALLOWED Für den im Identifikationsbereich angegebenen LTERM-Partner bzw. für den Client, der diesem LTERM-Partner zugeordnet ist, ist die Operation nicht zulässig.
|
KC_SC_DELETED Der angegebene LTERM-Partner existiert nicht mehr, er wurde aus der Konfiguration der Anwendung gelöscht. |