TerminalBasic/openspec/changes/archive/2026-09-04-phase-4-ereignisschleife/umfang-und-form.md

Umfang und Form der Ereignis-Elemente (Aufgaben 1.1, 1.2)

Quelle. bas7advr.hlp (BASIC 7 Advisor), Einzelseiten unter https://dos-help.soulsphere.org/bas7advr.hlp/ (abgerufen 2026-09-04); Gegenprobe qb45advr.hlp unter derselben Domain. Zitate wörtlich aus den Einzelseiten, Übersetzung nur in den Kommentarzeilen.

1.1 Einzelseiten

Element	Seite
ON TIMER	x_dot_ontimerrr.html
ON KEY	x_dot_onkeyr.html
ON UEVENT	x_dot_onur.html
ON SIGNAL	x_dot_onsigbar.html
TIMER (Anweisung)	x_dot_timersr.html
KEY(n) (Ereignis)	x_dot_ketvr.html
UEVENT	x_dot_uevvvr.html
SIGNAL	x_dot_signalr.html
EVENT	x_dot_evntonr.html
SetUEvent	x_dot_SETUEVr.html

ON TIMER

ON TIMER(n&) GOSUB {linenumber | linelabel}

„The maximum number of seconds that can be specified for the time interval, n&, is the number of seconds in a 24-hour day (86,400)."

„A linenumber value of 0 disables event trapping and does not specify line 0 as the start of the routine."

Der Zeitwert ist LONG (n&), Bereich 1–86 400 Sekunden. GOSUB 0 schaltet den Trap ab.

TIMER ON/OFF/STOP

„TIMER ON enables timer-event trapping."

„TIMER OFF disables timer-event trapping. … Events occurring while trapping is off are ignored."

„TIMER STOP suspends timer-event trapping. … Events occurring while trapping is off are remembered and processed when the next TIMER ON statement is executed."

Wiedereintritt — wörtlich belegt:

„an automatic TIMER STOP is executed so that recursive traps cannot take place."

„The RETURN from the trapping routine automatically performs a TIMER ON statement unless an explicit TIMER OFF was performed inside the routine."

Das ist genauer als „die Quelle gilt während des Handlers als gestoppt": RETURN schaltet die Quelle auf ON, außer im Handler stand ein ausdrückliches OFF.

KEY(n) — Wertebereich

KEY(n%) ON
KEY(n%) OFF
KEY(n%) STOP

n%	Taste
0	alle Tasten dieser Tabelle
1–10	F1–F10
11	Pfeil hoch
12	Pfeil links
13	Pfeil rechts
14	Pfeil runter
15–25	benutzerdefinierte Tasten
30–31	F11–F12 (101-Tasten-Tastatur)

ON KEY selbst: ON KEY(n%) GOSUB {linenumber | linelabel}. Zur Frage, ob eine getrappte Taste im Eingabestrom bleibt, sagt die Einzelseite nur:

„After a key is trapped, the information on which key was trapped is no longer available."

Die Gegenprobe in qb45advr.hlp (x_dot_onkeyba.html, x_dot_ketv.html) enthält dazu nichts. → Festlegung nötig, siehe 1.2.

Benutzerdefinierte Tasten 15–25

Die Einzelseite zu KEY n, zeichenkette$ (x_dot_setfkr.html) behandelt nur die Makrozuweisung für 1–10 und 30–31; die Erklärungsform für 15–25 steht in keiner der beiden Hilfen, ebenso wenig die Bedeutung der Bits des Tastaturflagbytes. Belegt ist dagegen die Scancode-Tabelle (qb45advr.hlp, x_dot_kbsct.html), aus der die Zuordnung Zeichen → Scancode stammt:

ESC 01 · „! or 1" 02 … „) or 0" 0B · „_ or -" 0C · „+ or =" 0D · TAB 0F · Q 10 … P 19 · ENTER 1C · A 1E … L 26 · Z 2C … M 32 · SPACEBAR 39 · F1 3B … F10 44 · HOME 47 · UP 48 · LEFT 4B · RIGHT 4D · END 4F · DOWN 50 · INS 52 · DEL 53

→ Festlegung nötig für das Flagbyte, siehe 1.2.

UEVENT und SetUEvent

ON UEVENT GOSUB {linenumber | linelabel}

„This event typically originates from a hardware interrupt but can also be triggered by software."

„SetUEvent … sets a flag that BASIC checks before executing the next statement."

Bestätigt die Zustellung an der Anweisungsgrenze.

UEVENT ON
UEVENT OFF
UEVENT STOP

UEVENT STOP „preserves events in memory for processing once UEVENT ON resumes, though executing UEVENT OFF afterward will discard these queued events."

OFF verwirft also auch ein unter STOP gemerktes Ereignis.

SetUEvent ist eine Routine ohne dokumentierte Argumentliste und ohne dokumentierten Rückgabewert:

„It sets the BASIC entry point that causes a user-defined event."

SIGNAL

SIGNAL(n%) ON
SIGNAL(n%) OFF
SIGNAL(n%) STOP

ON SIGNAL(n%) GOSUB {linenumber | linelabel}

„A linenumber value of 0 disables event trapping."

Quelle der Signale — wörtlich:

„OS/2 protected-mode signal"

„Process flags A, B, and C are used for communicating between processes."

aktiviert durch die OS/2-Funktion DOSFLAGPROCESS aus einem anderen Prozess.

Ein Wertebereich für n% ist nicht dokumentiert; die Einzelseite verweist auf „Chapter 9, ‚Event Handling'" des Programmer's Guide, der nicht vorliegt.

EVENT

EVENT ON
EVENT OFF

„EVENT OFF … equivalent to compiling a program from the BC command line without using /V or /W."

„EVENT OFF and EVENT ON can be used to bracket sections of code where events do not need to be detected and trapped, and fast performance is required."

EVENT STOP ist nicht dokumentiert. EVENT ist im Vorbild kein Laufzeit-Hauptschalter mit drei Zuständen, sondern eine Klammer, die die Erzeugung der Ereignisprüfungen im Kompilat ein- und ausschaltet.

Reihenfolge und Trapping in Prozeduren

Zu beidem geben die Einzelseiten nichts her; sie verweisen auf Kapitel 9 des Programmer's Guide. → Festlegung nötig, siehe 1.2.

1.2 Abweichungen der Delta-Spec vom Beleg

Nach der Leitplanke „Referenzverhalten schlägt Eleganz … das gilt auch gegenüber den eigenen Spezifikationen" ist bei jeder Abweichung die Spec anzugleichen.

Nr.	Delta-Spec sagt	Beleg sagt	Folge
A	EVENT hat ON/OFF/STOP und überlagert die Einzelzustände	nur ON/OFF; Klammer um die Erzeugung der Prüfungen	Spec angleichen; EVENT STOP wird namentlich abgewiesen
B	„während des Handlers gilt die Quelle als gestoppt; mit RETURN gilt wieder ihr Zustand"	Eintritt = automatisches STOP; RETURN = automatisches ON, außer im Handler stand ein ausdrückliches OFF	Spec präzisieren
C	OFF verwirft künftige Ereignisse	OFF verwirft auch ein unter STOP gemerktes	Spec ergänzen
D	ON KEY(n) mit Wertebereich	0, 1–25, 30–31 mit fester Tastenzuordnung	Spec unverändert, Bereich jetzt belegt
E	ON TIMER(n)	n& ist LONG, 1–86 400; GOSUB 0 schaltet ab	Spec unverändert, Form jetzt belegt

Ohne Beleg — unsere Festlegungen (gehören nach sprachreferenz.md unter „Abweichungen"):

1. Getrappte Tasten verlassen den Eingabestrom. Von keiner der beiden Hilfen belegt. Wir legen fest: eine Taste mit aktivem Trap erscheint nicht zusätzlich bei INKEY$/INPUT. Begründung: andernfalls sähe ein Programm dieselbe Taste zweimal, und KEY(n) OFF wäre die einzige Art, eine Taste überhaupt normal zu lesen.
2. Reihenfolge gleichzeitig fälliger Ereignisse. Unbelegt. Wir legen fest: KEY (aufsteigend nach n), dann TIMER, dann UEVENT, dann SIGNAL — Tasten zuerst, weil sie an einer Benutzereingabe hängen.
3. Trapping in Prozeduren. Unbelegt. Wir legen fest: die Zustellung erfolgt an jeder Anweisungsgrenze, auch innerhalb von SUB/FUNCTION; das Ziel liegt im Modulrumpf. Das entspricht dem bereits umgesetzten Verhalten des modulweiten ON ERROR.
4. Bits des Tastaturflagbytes in KEY n, CHR$(flag)+CHR$(scan). Unbelegt. Wir legen die Belegung des BIOS-Flagbytes zugrunde: 1 rechte Umschalttaste, 2 linke Umschalttaste, 4 Strg, 8 Alt. Im Terminal sind linke und rechte Umschalttaste nicht unterscheidbar, beide Bits gelten deshalb gleich; NumLock und CapsLock spielen für einen Trap keine Rolle und werden ignoriert.
5. SIGNAL-Quelle. Die belegte Quelle ist OS/2-gebunden (DOSFLAGPROCESS, Prozessflags A/B/C) und existiert auf keiner Zielplattform; ein Wertebereich ist nicht dokumentiert. → Entscheidung des Projektinhabers ausstehend, siehe unten.

Entscheidung zu SIGNAL (Projektinhaber, 2026-09-04)

SIGNAL wird auf Betriebssystemsignale abgebildet, und zwar nur auf die minimale Menge, die auf allen Zielplattformen existiert.

Der C-Standard garantiert überall — Linux, macOS und Windows — SIGABRT, SIGFPE, SIGILL, SIGINT, SIGSEGV, SIGTERM. Von diesen sind nur zwei asynchron, von außen ausgelöst und fortsetzbar; die vier Fault-Signale entstehen aus dem eigenen Programmzustand, und ein RETURN aus ihrem Handler führte in denselben Fehler zurück. Abgebildet werden deshalb:

n%	Signal	Bedeutung
1	SIGINT	Unterbrechungswunsch von außen
2	SIGTERM	Beendigungswunsch von außen

Ein anderer Wert als 1 oder 2 wird namentlich abgewiesen — zur Übersetzungszeit, wenn er konstant ist, sonst mit Laufzeitfehler 5.

Zustellung. Signale erreichen die Laufzeit wie die Zeit über den Host; nur er berührt das Betriebssystem. Ein Signal wird nicht im Signalkontext verarbeitet, sondern setzt eine Marke, die der Host beim nächsten Abholen in ein Ereignis übersetzt.

Verhältnis zum Abbruch. Im Rohmodus liefert das Terminal Strg+C als Taste, nicht als Signal; daran ändert sich nichts. Trifft SIGINT dagegen von außen ein (kill -INT), gilt: mit aktivem Trap läuft der Handler, ohne aktiven Trap bleibt es beim bisherigen Abbruch. Dieselbe Regel wie bei getrappten Tasten.

Abweichungen, die zu dokumentieren sind:

1. Die belegte Quelle des Vorbilds (OS/2-Prozessflags A/B/C über DOSFLAGPROCESS) existiert nicht; n% bedeutet bei uns etwas anderes als im Vorbild. Ein Wertebereich war im Vorbild ohnehin nicht dokumentiert.
2. SIGTERM ist unter Windows von außen nicht zustellbar (es gibt kein kill); SIGNAL(2) bleibt dort wirkungslos. SIGNAL(1) wird dort über den Konsolen-Steuerhandler (CTRL_C_EVENT) bedient.