REVNT - Ereignis empfangen

Allgemeines

Anwendungsgebiet:	Intertaskkommunikation; siehe "Intertaskkommunikation (ITC)"; Kommunikation; siehe "Kommunikation (Programm, Anwender, System)"
Makrotyp:	O-Typ; siehe "O-Typ-Makroaufrufe"

Makrobeschreibung

Mit dem Makro REVNT kann ein Anwender, der an der Intertaskkommunikation (ITC) teilnimmt, eine Nachricht anfordern und auf ihr Eintreffen warten.

Funktionsweise

Jeder ITC-Teilnehmer kann mit dem Makro REVNT eine Nachricht anfordern. Er kann dabei festlegen, ob er eine Nachricht von einem beliebigen Teilnehmer annimmt oder ob sie von einem bestimmten Absender stammen muss. Wartet der Teilnehmer auf eine beliebige Nachricht, so kann diese auch von einem Absender kommen, der sich später der ITC angeschlossen hat.
Ist zum Zeitpunkt des REVNT-Aufrufs noch keine Nachricht (oder noch keine des gewünschten Absenders) in der Empfangswarteschlange des aufrufenden Teilnehmers, wird die Task unterbrochen. Die unterbrochene Task wird fortgesetzt, wenn die Nachricht eintrifft oder wenn die Wartezeit verstrichen ist, deren Dauer im REVNT-Aufruf festgelegt wurde.

Aus der Empfangswarteschlange überträgt das System die Nachricht in das Empfangsfeld des Programms. Sind mehrere Nachrichten in der Warteschlange, dann überträgt es die erste Nachricht bzw. die erste Nachricht des gewünschten Absenders. Im REVNT-Aufruf kann der Anwender angeben, ob die Nachricht nach der Übertragung aus der Warteschlange gelöscht werden soll. Lässt er sie nicht löschen, dann kann er sie mit einem weiteren REVNT-Aufruf noch einmal übertragen lassen.

Eine Nachricht kann 8 Byte bis 64 KB lang sein (einschließlich 4 Byte Satzlängenfeld). Wenn der Benutzer den Umfang der auszutauschenden Nachrichten beim Programmieren kennt, kann er die Länge der Empfangsfelder danach einrichten. Im Empfangsfeld trägt das System die tatsächliche Länge zusammen mit der Nachricht ein. Kann das Empfangsfeld die Nachricht nicht vollständig aufnehmen, dann überträgt das System nur die ersten 4 Byte der Nachricht, aber im Satzlängenfeld trägt es die vollständige Länge ein.

Der Returncode X'0C' kennzeichnet diesen Fall. Ist die Nachrichtenlänge beim Programmieren unbekannt, dann sollte der Benutzer den Makro REVNT mit REL=NO aufrufen. Er erhält die aktuelle Länge, kann das Empfangsfeld diesem Wert anpassen und mit einem

zweiten REVNT-Aufruf die volle Nachricht übertragen lassen. Diesmal kann er mit
REL=YES die Nachricht löschen lassen, oder er ruft den Makro RELBF auf, der die erste Nachricht in der Warteschlange löscht.

ITC-gekoppelte Ereignissteuerung:
Der Wartezustand, in den die Task nach dem REVNT-Aufruf versetzt wird, kann durch die Kopplung mit der Ereignissteuerung vermieden werden, wenn die Nachricht von einem beliebigen Absender erwartet wird. Außerdem kann das Warten auf eine ITC-Nachricht zusammengelegt werden mit dem Warten auf ein anderes Ereignis (siehe Abschnitt„Ereignisgesteuerte Verarbeitung (Eventing)“).

Die ITC wird dadurch an eine Ereignissteuerung gekoppelt, dass man im REVNT-Aufruf als weiteren Operanden die Adresse der Ereignis-Kurzkennung angibt. Diese Adresse muss vorher in einem ENAEI-Aufruf festgelegt worden sein. Die Task wird nach dem REVNT-Auf-ruf nicht unterbrochen. Der Aufrufer erhält einen eingeschränkten Returncode, der angibt, ob der REVNT-Aufruf akzeptiert ist. Angaben über das Eintreffen der Nachricht erhält er durch den Postcode, sobald der SOLSIG-Aufruf abgeschlossen ist. Mit dem SOLSIG-Auf-ruf kann jetzt der Anwender zu einem beliebigen Zeitpunkt nach dem REVNT (bei Contin-gency-Angabe auch vorher) ein Ereignis-Signal anfordern. Ist noch keine Nachricht eingetroffen, so tritt die Wartezeit des SOLSIG-Aufrufs in Kraft. Die Task wird unterbrochen, falls kein Contingency-Prozess angegeben war. Die Wartezeit des SOLSIG wird durch jedes Ereignis beendet, das bei der angegebenen Ereignissteuerung eintritt. Der Post Code gibt an, welcher Klasse das Ereignis angehört.

Hinweise

• Mit dem Aufruf REVNT...,WTIME=0 kann die Empfangswarteschlange ohne Unterbrechung geprüft werden.

• Die Begrenzung der Wartezeit (Operand WTIME) soll verhindern, dass sich Teilnehmer gegenseitig blockieren (wenn jeder auf eine Nachricht des anderen wartet).

Bei gekoppeltem REVNT zu beachten:

• Die Ereignisklasse im Post Code muss geprüft werden, um festzustellen, ob ein ITC-Ereignis oder ein anderes Ereignis vorliegt.

• Solange ein gekoppelter REVNT-Aufruf nicht abgeschlossen ist, darf kein weiterer RE-VNT-Aufruf - ob gekoppelt oder ungekoppelt - gegeben werden; (wird mit Returncode X'18' abgewiesen).

• Solange ein gekoppelter REVNT-Aufruf nicht abgeschlossen ist, darf die Ereigniskennung nicht gelöscht werden (DISEI-Aufruf). Der REVNT-Aufruf kann sonst nicht abgeschlossen werden, und es können Nachrichten verloren gehen (siehe auch den Hinweis im Abschnitt „Intertaskkommunikation (ITC)“).

Makroaufrufformat und Operandenbeschreibung Format 1:

REVNT

empfangsfeld,länge

[,WTIME=sekunden]

,REL=YES / NO

[,NAME=sendername]

[,EIID=adresse]

empfangsfeld
symbolische Adresse des Feldes, in das die Nachricht aus der Empfangswarteschlange übertragen werden soll. Das Feld muss an einer Wortgrenze beginnen. Nach der Übertragung hat es folgenden Inhalt:

Byte	Inhalt
0 - 7	ITC-Name des Teilnehmers, der die Nachricht gesendet hat.
8 - 11	Satzlängenfeld (SLF) Byte 8-9: Länge der vollständigen Nachricht + 4 (für SLF) Byte 10-11: reserviert
12 - n	Nachricht (mindestens 4 Byte, falls das Feld zu klein war, um die vollständige Nachricht aufzunehmen)

Das Empfangsfeld muss mindestens 16 Byte lang sein, die Angabe im Satzlängenfeld muss mindestens den Wert 8 haben.

länge
Dezimalzahl, die die Länge des Empfangsfeldes einschließlich der 8 Byte für den Absender angibt. Der Wert für „länge“ kann zwischen 16 und 65543 liegen. Die Nachricht darf einschließlich Satzlängenfeld von 8 bis 65535 lang sein.

WTIME=sekunden
gibt an, wie lange die Task auf die Nachricht warten soll, wenn sie beim Aufruf von REVNT noch nicht vorliegt. Hier sind Zeitangaben von 0 bis 21599 Sekunden zugelassen.
Wird WTIME nicht angegeben, dann wartet die Task standardmäßig 600 Sekunden.

REL=

bestimmt den Verbleib der Nachricht in der Empfangswarteschlange.

YES
Die Nachricht wird nach der Übertragung aus der Empfangswarteschlange gelöscht, auch wenn sie nicht vollständig im Empfangsfeld Platz gefunden hat.

NO
Die Nachricht bleibt in der Empfangswarteschlange.

NAME=sendername
ITC-Name eines ITC-Teilnehmers: gibt an, dass eine Nachricht nur übertragen werden soll, wenn der angegebene Teilnehmer der Absender ist.

EIID=adresse
Dieser Operand muss nur angegeben werden, wenn die ITC mit der Ereignissteuerung gekoppelt werden soll (siehe „Koppelung von ITC und Ereignissteuerung“ (Intertaskkommunikation (ITC))).adresse = symbolische Adresse eines Feldes, das die Kurzkennung der Ereigniskennung enthält. Das Feld ist 4 Byte lang. Durch den Aufruf des Makros ENAEI hat das System die Kurzkennung in diesem Feld eingetragen.

Format 2:

REVNT

(1)

(1)
Register R1 enthält die Adresse eines Operandenfeldes mit folgendem Inhalt:

Byte	Inhalt
0 - 3	Adresse des Empfangsfeldes
4 - 7	Länge des Empfangsfeldes (sedezimal)
8	X'00' : keine Kopplung mit Ereignissteuerung X'01' : die REVNT-Anforderung wird an eine Ereigniskennung gekoppelt
9 - 11	C'YES' für REL=YES X'00' C'NO' für REL=NO
12 - 15	Dauer der Wartezeit in Sekunden
16 - 23	ITC-Name des Senders, ggf. mit Leerzeichen zur Länge 8 aufgefüllt, oder nur Leerzeichen, wenn kein Sender angegeben werden soll.
24 - 27	Adresse der Ereignis-Kurzkennung. Nur anzugeben, wenn die Kennung in Byte 8 gesetzt ist.

Rückinformation und Fehleranzeigen

R15:

+---------------+
|   |   |   |   |
| | | | | | |a|a|
+---------------+

Über die Ausführung des Makros REVNT wird im rechtsbündigen Byte des Registers R15 ein Returncode übergeben.

REVNT ohne Kopplung an Ereignissteuerung:

X'aa'	Erklärung
X'00'	Die Nachricht wurde vollständig übertragen.
X'04'	Fehler in der Operandenangabe (z.B. Speicher ist nicht Klasse 6 oder nicht zugewiesen). Es wurde keine Nachricht übertragen.
X'08'	Der Aufrufer ist kein ITC-Teilnehmer. Keine Nachricht wurde übertragen.
X'0C'	Das Empfangsfeld ist zu klein für die vollständige Nachricht. Nur der Kopf und die ersten 4 Byte wurden übertragen.
X'10'	Auch während der Wartezeit ist keine Nachricht eingetroffen.
X'18'	Ein früher aufgerufener REVNT mit Kopplung ist noch nicht abgeschlossen. Der jetzige Aufruf wird abgewiesen.

REVNT mit Kopplung an Ereignissteuerung:

X'aa'	Erklärung
X'00'	Der REVNT-Aufruf ist akzeptiert.
Bei den folgenden Returncodes führt der REVNT-Aufruf nicht zu einem ITC-Ereignis:
X'04'	Fehler in Operandenangabe (z.B. Speicher ist nicht Klasse 6 oder nicht zugewiesen). Der REVNT-Aufruf wird abgewiesen.
X'08'	Der Aufrufer ist kein ITC-Teilnehmer. Der REVNT-Aufruf wird abgewiesen.
X'18'	Ein früher aufgerufener REVNT mit Kopplung ist noch nicht abgeschlossen. Der jetzige Aufruf wird abgewiesen.

Bedeutung des Post Codes (nur bei Kopplung an Ereignissteuerung):

Der Post Code ist 4 Byte lang und wird nach dem SOLSIG-Aufruf unter einer dort angegebenen Adresse eingetragen. Das linksbündige Byte gibt die Ereignisklasse an (siehe AAbschnitt „Ereignisgesteuerte Verarbeitung (Eventing)“). Das rechtsbündige Byte enthält den Returncode, der jeweils für die Ereignisklasse gilt. Ein ITC-Ereignis hat die Ereignisklasse X'08':

ITC-Post Code	Erläuterung
X'08000000'	Ein gekoppelter REVNT-Aufruf ist mit dem Empfang einer Nachricht abgeschlossen worden.
X'08000004'	Operandenfehler: Der Speicherplatz für das Empfangsfeld ist nicht mehr zugewiesen (asynchroner Fall der Ereignissteuerung).
X'0800000C'	Das Empfangsfeld ist zu klein für die vollständige Nachricht. Nur der Kopf und die ersten 4 Byte wurden übertragen.
X'08000010'	Die Wartezeit ist abgelaufen, ohne dass eine Nachricht eingetroffen ist.