Allgemeines
Anwendungsgebiet: | Ereignissteuerung; siehe "Ereignisgesteuerte Verarbeitung (Eventing)" |
Makrotyp: | S-Typ, MF-Format 1: Standardform/L-/E-Form; siehe "S-Typ-Makroaufrufe" |
Bei Makrokettung müssen alle Makros der Kette dieselbe Schnittstelle benutzen. Bei Verwendung der 24-Bit-Schnittstelle wird für den Post Code nur ein 4 Byte langes Feld generiert. Bei Verwendung der 31-Bit-Schnittstelle kann der Post Code 4 oder 8 Byte lang sein.
Makrobeschreibung
Der Makroaufruf dient dazu, das Eintreten eines Ereignisses der Ereigniskennung anzuzeigen. Die Ereigniskennung muss zuvor der Task des Aufrufers zugeordnet worden sein (ENAEI-Makroaufruf).
Das den POSSIG-Aufruf gebende Programm wird immer fortgesetzt. Es kann auch einen Contingency-Prozess spezifizieren, der aktiviert wird, sobald der POSSIG-Aufruf („Sende Signal“) einen SOLSIG-Aufruf („Anfordern eines Signals“) befriedigt hat oder sobald eine vorgegebene Zeitperiode verstrichen ist. Dieser Contingency-Prozess übergibt eine Information, ob das Signal innerhalb einer Zeitperiode benutzt oder nicht benutzt wurde.
Der Contingency-Prozess muss zuvor definiert worden sein (ENACO-Makroaufruf).
Makroaufrufformat und Operandenbeschreibung
POSSIG |
{ {EINAME=name / EINAMAD={adr / (r)}[,EINAMLN=länge]} SCOPE={LOCAL / GROUP / USER_GROUP / GLOBAL} / EIID={adr / (r)} } [, {SPOSTAD={adr / (r)} / SPOSTR=r}],SPOSTL=1/ 2 [,LIFETIM=sec / (r)] ,CONTINU=NO / YES / SOLSIG [,COID=adr / (r)] [,COMAD=adr / (r)] [,PARMOD=24 / 31] [,MF=L / (E,..)] |
EINAME=name
gibt den Namen der Ereigniskennung an, an die ein Ereignis gemeldet werden soll. Die Ereigniskennung muss zuvor mit dem Aufruf ENAEI definiert worden sein. Der Name der Ereigniskennung ist nur zusammen mit dem Geltungsbereich (SCOPE) eindeutig.
EINAMAD=
bezeichnet den Namen der Ereigniskennung. Diese Angabe ist nur zusammen mit dem Geltungsbereich (Operand SCOPE) eindeutig.
adr
symbolische Adresse des Feldes, das den Namen enthält.
(r)
r = Register, das die Adresse enthält.
EINAMLN=
gibt die Länge des Namens der Ereigniskennung in Byte an. Fehlt dieser Operand, so wird das Längenattribut des EINAMAD-Operandenwertes angenommen, wenn EINAMAD=adr angegeben ist; ist EINAMAD=(r) angegeben, so wird die maximale Länge (54 Byte) angenommen.
länge
Länge des Namens der Ereigniskennung.
SCOPE=
beschreibt den Geltungsbereich (Teilnehmerkreis) für die Ereigniskennung.
LOCAL
Die Ereigniskennung wird nur von der Task des Aufrufers benutzt.
GROUP
Teilnehmer sind alle Tasks unter der Benutzerkennung des Aufrufers.
USER_GROUP
Teilnehmer können alle Tasks sein, deren Benutzerkennungen der gleichen Benutzergruppe angehören wie die Benutzerkennung des einrichtenden Teilnehmers. Der Operandenwert setzt die Existenz von Benutzergruppen voraus und kann daher nur angegeben werden, wenn die Funktionseinheit SRPM des Software-Produkts SECOS im System vorhanden ist. Vor einem Makroaufruf mit SCOPE=USER_GROUP muss deshalb mit dem Makro GETUGR (siehe Handbuch „SECOS“ [14]) geprüft werden, ob SRPM zur Verfügung steht; abhängig vom Ergebnis (Returncode) ist im Programm zu reagieren.
GLOBAL
Teilnehmer sind alle Tasks im System.
EIID=
bezeichnet die Kurzkennung der Ereigniskennung. Die Kurzkennung wird dem Benutzer durch den ENAEI-Makroaufruf zur Verfügung gestellt. Die Verwendung der Kurzkennung an Stelle des Namens zur Identifizierung der Ereigniskennung beschleunigt die Verarbeitung und ist eindeutig.
adr
symbolische Adresse eines 4 Byte langen Feldes, das die Kurzkennung enthält.
(r)
r = Register, das die Adresse des Feldes enthält.
MF=
Zur allgemeinen Beschreibung des Operanden MF, der dazugehörenden Operandenwerte und der evtl. nachfolgenden Operanden (z.B. für einen Präfix) siehe Abschnitt „S-Typ-Makroaufrufe“. Die gültigen MF-Werte sind zu Beginn der Makrobeschreibung bei „Makrotyp“ angegeben und aus dem Aufrufformat ersichtlich.
PARMOD=
steuert die Makroauflösung. Es wird entweder die 24-Bit- oder die 31-Bit-Schnittstelle generiert.
Wird PARMOD nicht spezifiziert, so erfolgt die Makroauflösung entsprechend der Angabe für den Makro GPARMOD oder der Voreinstellung für den Assembler (= 24-Bit-Schnittstelle).
24
Die 24-Bit-Schnittstelle wird generiert. Datenlisten und Befehle benutzen 24-Bit-Adressen (Adressraum <= 16 MB).
31
Die 31-Bit-Schnittstelle wird generiert. Datenlisten und Befehle benutzen 31-Bit-Adressen (Adressraum <= 2 GB).
SPOSTAD=
bezeichnet das Feld mit der Post-Code-Information, die dem korrespondierenden Programm (das den SOLSIG-Makro aufruft) übergeben werden soll (siehe Abschnitt„Ereignisgesteuerte Verarbeitung (Eventing)“). Der Post Code ist 4 bzw. 8 Byte lang.
Der Post Code wird auch dem Contingency-Prozess, falls vorhanden, übergeben (Operand COID). Der Post Code X'00000000' wird nicht übertragen.
Der Operand SPOSTR führt dieselbe Funktion bei schnellerer Verarbeitung aus.
adr
symbolische Adresse des Feldes, das die Post Code-Information enthält. Länge = 4 oder 8 Byte.
(r)
r = Register mit dem Adresswert adr.
SPOSTR=
bezeichnet ein Register mit der Post-Code-Information, die dem korrespondierenden Programm (das den SOLSIG-Makro aufruft) übergeben werden soll. Bei 2 Worten (8 Byte) Post Code muss das dem angegebenen Register folgende Register (der Zahl nach) das
2. Wort des Post Codes enthalten. Post Code X'00000000' wird nicht übertragen.
(r)
r = Register mit dem Post Code. Register R0 und R1 dürfen nicht benutzt werden.
SPOSTL=
bezeichnet die Länge des Post Codes in Worten. Bei Verwendung der 24-Bit-Schnittstelle (PARMOD=24) kann nur SPOSTL=1 angegeben werden.
1
Der Post Code ist 1 Wort (4 Byte) lang.
2
Der Post Code ist 2 Worte lang.
LIFETIM=
Zeit, während der das gesendete Signal durch eine korrespondierende SOLSIG-Anforderung benutzt werden soll.
Falls ein Contingency-Prozess existert, teilt ihm der Ereignis-Informationscode mit, ob das Signal innerhalb der gesetzten Zeitperiode benutzt oder nicht benutzt wurde.
sec
Zeitangabe in Sekunden. 1 <= sec <= 43200
Die Genauigkeit für die Bearbeitung liegt bei +10 Sekunden.
Voreinstellung: 600 sec.
(r)
r = Register, das die Angabe in Sekunden enthält.
CONTINU=
ermöglicht eine Verkettung des POSSIG-Makros mit weiteren POSSIG-Makros oder einem SOLSIG-Makro. Alle Makros der Kette müssen dasselbe Schnittstellenformat benutzen.
NO
Kein weiterer POSSIG- oder SOLSIG-Makro folgt unmittelbar auf den POSSIG-Makro.
YES
Ein weiterer POSSIG-Makro folgt unmittelbar nach dem POSSIG-Makro.
SOLSIG
Ein SOLSIG-Makro folgt unmittelbar auf den POSSIG-Makro.
Operanden für die Angabe eines Contingency-Prozesses
COID=
bezeichnet die Kurzkennung des Contingency-Prozesses. Die Kurzkennung wird dem Anwender bei Aufruf des Makros ENACO übergeben.
adr
symbolische Adresse des Feldes mit der Kurzkennung.
(r)
r = Register mit dem Adresswert adr.
COMAD=
bezeichnet eine Contingency-Mitteilung. Diese Contingency-Mitteilung wird dem Contingency-Prozess übergeben (Register R1). Eine hier gegebene Contingency-Mitteilung ersetzt eine eventuell bei der Definition der Contingency gegebene Mitteilung (siehe Abschnitt „Contingency-Prozesse“).
adr
symbolische Adresse eines Wortes, das eine Contingency-Mitteilung enthält.
(r)
r = Register, das die Adresse enthält.
Hinweise zum Makroaufruf
Die POSSIG-Warteschlange einer Ereigniskennung kann nicht beliebig viele Anforderungen aufnehmen. Um das System zu schützen, ist die Anzahl der POSSIG-Anforderungen in der Warteschlange einer Ereigniskennung auf einen maschinenabhängigen Maximalwert begrenzt.
Wenn ein Programm(paket) einen Contingency-Prozess definiert hat, der in SPL geschrieben ist, muss bei allen ENACO-, SOLSIG- und POSSIG-Aufrufen das Register R12 die Adresse des SPL-Program Managers enthalten.
Rückinformation und Fehleranzeigen
Während der Makrobearbeitung enthält Register R1 die Adresse der Operandenliste.
R15:
+---------------+ | | | | | |b|b| | | | |a|a| +---------------+
Über die Ausführung des Makros POSSIG wird ein gegliederter Returncode (aa=primärer RC, bb=sekundärer RC) im Register R15 übergeben.
X'bb' | X'aa' | Erläuterung |
X'00' | X'00' | Funktion ausgeführt: Das Signal wurde erfolgreich abgeschickt. |
X'0C' | X'04' | Keine Aktion: Die vom System erstellte Ereigniskennung ist der Task des Aufrufers |
X'10' | X'04' | Keine Aktion: Es wurden ungültige Operanden angegeben. |
X'14' | X'04' | Keine Aktion: Ungültiger Name bzw. ungültige Kurzkennung; die spezifizierte |
X'18' | X'04' | Keine Aktion: Maximal erlaubte Anzahl (400) an Contingency-Prozessen pro |
X'24' | X'04' | Keine Aktion: Ungültige Kurzkennung des Contingency-Prozesses. Es existiert |
X'28' | X'04' | Keine Aktion: Die maximale Anzahl der Anforderungen in der POSSIG-Queue |
Bei Makroverkettung (Operand CONTINU) gilt:
aa = X'00'
Alle Makroaufrufe der Kette waren erfolgreich.
aa = X'04'
Ein Makro der Kette war nicht erfolgreich (alle Makros der Kette, die vor diesem Makro liegen, waren erfolgreich.) Die Kette wird an dieser Stelle abgebrochen. Die Fehlerursache zeigt der entsprechende Sekundärindikator an.
Die vorgeschriebene Belegung des Post Codes ist auf "Ereignisgesteuerte Verarbeitung (Eventing)" angegeben.
Die Bedeutung der Werte des Ereignis-Informationscodes (für Contingency-Prozesse) ist in Tabelle 8 (Contingency-Prozesse) beschrieben.
Beispiel
POSSIG START
PRINT NOGEN
POSSIG AMODE ANY
GPARMOD 31
1 *,MACRO: GPARMOD, VERSION: VER121
BALR 5,0
USING *,5
ENAEI EINAME=EVENT,SCOPE=GROUP,EIIDRET=KKEV -------------------(1)
POSSIG EIID=KKEV ----------------------------------------------(2)
ST 15,RCFIELD1
ENACO CONAME=CONT,COADAD=COANFAD,COIDRET=KKCO -----------------(3)
POSSIG EIID=KKEV,COID=KKCO,LIFETIM=60--------------------------(4)
ST 15,RCFIELD2
LOOP CLI SWITCH,'0'
BE LOOP
ST 2,ACKNO -------------------------------------------------(5)
DISCO COID=KKCO
ST 15,RCFIELD3
DISEI EIID=KKEV
ST 15,RCFIELD4
DTH1 TERM
COANF BALR 6,0
USING *,6
CONTXT STACKR=(2),OWNR=(2),FUNCT=WRITE ------------------------(6)
MVI SWITCH,'1'
RETCO
KKEV DS F
KKCO DS F
COANFAD DC A(COANF)
SWITCH DC C'0'
*
ACKNO DS F
RCFIELD1 DS F
RCFIELD2 DS F
RCFIELD3 DS F
RCFIELD4 DS F
END
Ablaufprotokoll
/start-assembh % BLS0500 PROGRAM 'ASSEMBH', VERSION '<ver>' OF '<date>' LOADED % ASS6010 <ver> OF BS2000 ASSEMBH READY //compile source=*library-element(macexmp.lib,possig), - // compiler-action=module-generation(module-format=llm), - // module-library=macexmp.lib, - // listing=parameters(output=*library-element(macexmp.lib,possig)), - // test-support=*aid % ASS6011 ASSEMBLY TIME: 509 MSEC % ASS6018 0 FLAGS, 0 PRIVILEGED FLAGS, 0 MNOTES % ASS6019 HIGHEST ERROR-WEIGHT: NO ERRORS % ASS6006 LISTING GENERATOR TIME: 84 MSEC //end % ASS6012 END OF ASSEMBH /load-executable-program library=macexmp.lib,element-or-symbol=possig, - / test-options=*aid % BLS0523 ELEMENT 'POSSIG', VERSION '@' FROM LIBRARY ':2OSG:$QM212.MACEXMP.LIB' IN PROCESS % BLS0524 LLM 'POSSIG', VERSION ' ' OF '<date> <time>' LOADED /%in dth1;%r STOPPED AT LABEL: DTH1 , SRC_REF: 158, SOURCE: POSSIG , PROC: POSSIG /%d %@(rcfield1) -> %x *** TID: 005000D8 *** TSN: 2QSE ********************************************* CURRENT PC: 000000A6 CSECT: POSSIG ************************************** V'000000FC' = POSSIG + #'000000FC' -------------------------------------(7) 000000FC (000000FC) 00000000 .... /%d %@(rcfield2) -> %x V'00000100' = POSSIG + #'00000100' -------------------------------------(8) 00000100 (00000100) 00000000 .... /%d %@(quitt) -> %x V'000000F8' = POSSIG + #'000000F8' -------------------------------------(9) 000000F8 (000000F8) 00000004 .... /%d %@(rcfield3) -> %x, %@(rcfield4) -> %x ------------------------------(10) V'00000104' = POSSIG + #'00000104' 00000104 (00000104) 04000000 .... V'00000108' = POSSIG + #'00000108' 00000108 (00000108) 04000000 .... /%r
(1) | Die Ereigniskennung EVENT wird definiert. Adresse der Kurzkennung: KKEV |
(2) | Mit POSSIG wird an die Ereignissteuerung ein Signal gegeben. Ein Contingency-Prozess als Quittung ist nicht angegeben. Da kein weiterer Teilnehmer das Signal mit SOLSIG anfordert, bleibt das Signal in der POSSIG-Warteschlange der Ereignissteuerung, bis die Wartezeit abgelaufen ist (Standardwert: 600 Sekunden). |
(3) | Der Contingency-Prozess COANF wird mit der Kurzkennungsadresse KKCO definiert (siehe ENACO-Makro). |
(4) | Ein zweites Signal wird an die Ereignissteuerung gegeben. Der Contingency-Prozess (Kurzkennungsadresse KKCO) soll nach 60 Sekunden gestartet werden, falls nicht schon früher ein SOLSIG-Aufruf seinen Start ausgelöst hat. Anschließend läuft das Programm in einer Warteschleife. |
(5) | Der Basisprozess speichert Register R2 (Ereignis-Informationscode) unter ACKNO ab und schließt die Contingency-Definition (DISCO) und die Ereignissteuerung (DI-SEI). |
(6) | Der Contingency-Prozess COANF ist gestartet. Der Ereignis-Informationscode in Register R2 gibt an, dass kein SOLSIG-Aufruf eingetroffen war. Mit dem Makro CONTXT wird er vom Register R2 des Contingency-Prozesses ins Register R2 des Basisprozesses übertragen (siehe CONTXT-Makro). Anschließend wird die Schleifenvariable geändert, um die Warteschleife zu öffnen, und der Contingency-Prozess wird mit dem Makro RETCO beendet. |
(7) | Rücksprungschalter nach dem ersten POSSIG-Aufruf (vgl.(2)): Das Signal wurde erfolgreich abgeschickt. |
(8) | Rücksprungschalter nach dem zweiten POSSIG-Aufruf (vgl.(4)): Das Signal wurde erfolgreich abgeschickt. |
(9) | Ereignis-Informationscode des Contingency-Prozesses: Das erwartete Ereignis trat innerhalb der Zeitperiode nicht ein. Weder Contingency-Mitteilung noch Post Code ist vorhanden. |
(10) | Rücksprungschalter nach dem DISCO- und nach dem DISEI-Aufruf:Die Contingency-Definition bzw. die Ereigniskennung wurde gelöscht. |
Weitere Beispiele enthält der Abschnitt „Ereignisgesteuerte Verarbeitung (Eventing)“ und der Abschnitt „Contingency-Prozesse“.