Anmerkungen zu MagiC 3 (SHUTDOWN-Mechanismus)
---------------------------------------------

Andreas Kromke
12.11.95

Achtung:	nderungen am Mechnismus seit 28.6.95
		Vulture-Untersttzung seit 11.11.95


1. Allgemeines
--------------

Bei einem Multitaskingsystem ist es eigentlich nicht mehr zulssig, den
Rechner nach Gebrauch einfach abzuschalten. Auch ein Rcksetzen (per
Reset-Taster) ist "tabu". Vielmehr mu sichergestellt werden, da alle
Programme korrekt beendet und alle Dateien korrekt geschlossen sind, bevor
dem System der Strom abgedreht wird. Ansonsten kann es zu Datenverlusten
kommen.

Aus diesem Grund haben andere Systeme wie UNIX oder der Macintosh einen
sogenannten Shutdown-Mechanismus. Ein solcher wurde auch von Atari bei
MultiTOS eingefhrt und ist jetzt auch ab MagiC 3 eingebaut.

Aktiviert wird der Shutdown mit dem Meneintrag "Optionen/Ausschalten" 
(Magxdesk 3) bzw. "Datei/Ausschalten" (Magxdesk 2.5). Weiterhin kann der 
Shutdown aktiviert werden durch die Tastenkombination Ctrl-Alt-Del oder 
durch einen Auflsungswechsel. Letzterer ist Magxdesk 3 durch 
Optionen/Auflsung bzw. in MAGXDESK 2.5 ber den Dialog 
Optionen/Einstellungen wechseln durchzufhren. Whrend des Shutdown knnen 
keine Programme gestartet werden.

Alle laufenden Programme erhalten eine Nachricht ("AP_TERM"), da sie sich
beenden sollten. Sind nach einer gewissen Zeit (ber Schlsselwort 
"timout" in der Konfigurationsdatei SHUTDOWN.INF einstellbar, Angabe in
Millisekunden) immer noch Programme im Speicher, gibt SHUTDOWN eine
Fehlermeldung aus. Ein Timeout von 0 bedeutet, da SHUTDOWN.PRG beliebig
lang wartet, d.h. ein Programm, das AP_TERM versteht, aber in einer
Endlosschleife steckt, fhrt zum Systemstillstand. In der Datei
SHUTDOWN.INF knnen Sie weiterhin Programmnamen (ohne ".prg" oder ".app")
angeben, die unkritisch sind und nicht zu einer Fehlermeldung durch SHUTDOWN
fhren sollen.

Nachdem alle im Speicher befindlichen Programme terminiert sind bzw. ignoriert
werden drfen, fhrt SHUTDOWN.PRG alle Programme (*.prg) im Verzeichnis
\gemsys\magic\stop aus. Anschlieend werden alle GEMDOS-Gertedateien (-1,-2,-3)
auf u:\dev\null um (d.h. auf -4) umgelenkt und smtliche Devices in u:\dev\
gelscht. Gertetreiber knnen sich dabei aus den Systemvektoren zurckziehen.

ltere Versionen von MagicMac werden am besten dadurch beendet, da 
zunchst im "Atari" der Shutdown durchgefhrt wird. Wenn eine 
Atari-Dialogbox das System zum Abschalten freigibt, schalten Sie Ihren Mac 
nicht aus, sondern beenden MagicMac mit [Command]-Q; direkt ber der 
Atari-Alertbox erscheint dann eine hnliche (sehr einfach und schlicht 
aufgebaute und daher lange nicht so hbsche) des MacOS. Jetzt knnen Sie 
MagicMac gefahrlos durch Bettigen des entsprechenden Buttons der 
Mac-Dialogbox beenden.
Neuere Versionen von MagicMac werden automatisch beendet, d.h. 
SHUTDOWN.PRG fhrt direkt zurck in den Macintosh Finder.

Beachtung: Wenn Sie das System ber Ctrl-Alt-Del beenden wollen, mssen Sie
           darauf achten, da der Bildschirm nicht gesperrt ist, d.h. da
           z.B. nicht gerade ein Programm eine Dialogbox oder Alertbox auf
           dem Bildschirm bearbeitet. Weiterhin mu die Shell (i.a. MAGXDESK)
           geladen sein, d.h. es darf kein Programm im "single mode" oder im
           Modus "Shell nicht resident" (z.B. per Alt-Doppelklick) geladen
           sein.
           Ist der Bildschirm gesperrt, wird nur der Writeback-Daemon
           beendet, d.h. der Cache zurckgeschrieben. Erst nach Freigeben des
           Bildschirms (d.h. nach Schlieen der Dialogbox oder Alertbox) kann
           der Shutdown durchgefhrt werden. Sollte das System derart
           abgestrzt sein, da kein Shutdown mehr mglich ist, bettigen Sie
           Ctrl-Alt-Del ein zweites Mal; jetzt wird der Warmstart
           durchgefhrt, ohne da Programme beendet werden.
           Ist der "single mode" aktiv oder die Shell nicht geladen, wird
           ebenfalls nur der Writeback-Daemon beendet und der Cache
           zurckgeschrieben. Fr den vollstndigen Shutdown mu erst
           das laufende Programm beendet werden, so da die Shell wieder
           aktiv ist. Der Shutdown MUSS dann ber den Menpunkt
           Optionen/ausschalten bzw. Datei/ausschalten durchgefhrt werden.

2. Von der Applikationsseite
----------------------------

An jedes Programm wird beim Shutdown oder Auflsungswechsel die folgende
Nachricht verschickt:

msg[0]         AP_TERM (50)
msg[1]         ap_id der Applikation, die den Shutdown ausgelst hat
msg[5]         AP_TERM    (50)     bei Shutdown
               AP_RESCHNG (57)     beim Auflsungswechsel

Anmerkung: Wurde Ctrl-Alt-Del bettigt, bekommen zunchst nur der
           Writeback-Daemon und die Applikation 0 eine AP_TERM-Nachricht.
           Als Absender ist dabei -1 eingetragen. Die Applikation 0 (i.a.
           die Shell MAGXDESK) beendet sich dann und startet das
           Shutdown-Programm.

Die Art und Weise, wie MagiC beim Shutdown Applikationen behandelt, hngt
davon ab, ob sie das AES informiert haben, da sie die Nachricht AP_TERM
verstehen. Mit shel_write und doex = SHW_INFRECGN (9) informiert eine
Applikation per Parameter <isgr>, welche Nachrichten sie versteht. Ein
gesetztes Bit 0 von <isgr> bedeutet dabei, da AP_TERM verstanden wird.

Whrend MultiTOS AP_TERM nur an solche Applikationen verschickt, die explizit
AP_TERM verstehen, verschickt MagiC die Nachricht an smtliche Applikationen.
Der Shutdown wird vom AES als "erfolgreich" angesehen, wenn alle 
Applikationen, die explizit AP_TERM verstehen, sich beendet haben. Ein 
Sonderfall liegt vor, wenn diese Applikationen terminiert sind, aber 
weitere Programme im System verbleiben, hier liefert das AES eine 
spezielle Nachricht (s.u.). Der Shutdown wird vom AES nur dann 
abgebrochen, wenn eine Applikation das AES informiert, da sie sich nicht 
beenden kann. Eine Applikation, die AP_TERM empfangen hat, hat also 
prinzipiell nur zwei erlaubte Mglichkeiten:

a) Die Applikation terminiert sofort
b) Die Applikation macht folgenden Aufruf:

     int msg[8];
     msg[0] = AP_TFAIL /*51*/;
     msg[1] = err;
     shel_write(SHW_AESSEND /*10*/, 0, 0, (char *) msg, NULL);

   und informiert damit das AES, da der Vorgang mit Fehlercode <err>
   unterbrochen wurde. Die Applikation, die den Shutdown verursacht hat,
   bekommt die ap_id und den Fehlercode der unterbrechenden Applikation
   mitgeteilt.

Reagiert die Applikation anders, d.h. ignoriert die AP_TERM-Nachricht, hngt
das Verhalten des Systems davon ab, ob dem System mitgeteilt wurde, da die
Applikation AP_TERM versteht:

a) Versteht die Applikation explizit AP_TERM, geht das System davon aus, da
   die Applikation z.Zt. keine Nachrichten empfangen kann. D.h. der
   Shutdown-Mechanismus wird nicht unterbrochen, sondern dauert solange, bis
   der Aufrufer (d.h. i.a. das Programm SHUTDOWN) den Shutdown abbricht.
   SHUTDOWN verwendet dazu einen Timeout, der in SHUTDOWN.INF per Default auf
   10s gesetzt ist, d.h. wenn 10s nach Beginn des Shutdown noch Programme aktiv
   sind, die AP_TERM verstehen, bricht SHUTDOWN den Shutdown-Proze ab. Man
   kann auch den Timeout auf 0 setzen, dann bricht SHUTDOWN nicht ab. "Klemmt"
   aber eine Applikation, mu man entweder diese oder aber SHUTDOWN selbst
   ber den Programm-Manager (Ctrl-Alt-Esc) terminieren.

b) Versteht die Applikation nicht explizit AP_TERM, meldet das System dem
   Initiator des Shutdown (d.h. i.a. SHUTDOWN.PRG) den erfolglosen (!) Abschlu
   des Shutdown-Vorgangs; d.h. der Shutdown-Modus wird vom System automatisch
   deaktiviert. Da SHUTDOWN.PRG sehr nachsichtig mit alten Programmen ist,
   testet es, ob noch Applikationen aktiv sind, und gibt ggf.
   eine Meldung aus. Dabei kann man in SHUTDOWN.INF Programme angeben, die
   nicht zu einer Fehlermeldung fhren sollen, d.h. die nicht beendet zu
   werden brauchen.

3. Von der Initiatorseite
-------------------------

Der Shutdown-Proze und der Auflsungswechsel werden in MagiC 3 von dem
Programm SHUTDOWN bernommen. Prinzipiell besteht keine Notwendigkeit, ein
eigenes Programm zu entwickeln, d.h. den Shutdown selbst durchzufhren.
SHUTDOWN.PRG wird mit folgenden Parametern aufgerufen:

     SHUTDOWN.PRG <dev> <txt>

bzw. ab MagiC 4:

     SHUTDOWN.PRG <dev> <txt> <xdv>

Dabei ist <dev> = -1, wenn ein Shutdown ohne Auflsungswechsel durchgefhrt
werden soll, ansonsten die Gertenummer des VDI-Bildschirmtreibers. <txt> ist
die Texthhe fr das AES, diese sollte i.a. Null sein (d.h. Default-Hhe).
Wenn eine Falcon-Auflsung eingestellt werden soll, kann zustzlich das
Falcon- Moduswort <xdv> angegeben werden.

Ein Shutdown wird mit folgendem Systemaufruf durchgefhrt:

     ret = shel_write(SHW_SHUTDOWN /*4*/, TRUE, 0, NULL, NULL));

Ein Rckgabewert von 0 bedeutet, da ein Shutdown nicht mglich ist, weil
z.B. bereits ein Shutdown luft. Auerdem darf der Shutdown nicht ausgefhrt
werden, wenn der Aufrufer den Bildschirm per wind_update(BEG_UDPATE) bzw.
wind_update(BEG_MCTRL) gesperrt hat (da die anderen Programme dann nicht
terminieren knnen). Dies wird jedoch aus Kompatibilitt zu MultiTOS nicht
vom System berprft (ab Version vom 17.5.).
Bei Erfolg ist ret = 1.

Ein Auflsungswechsel wird mit folgendem Systemaufruf durchgefhrt:

     ret = shel_write(SHW_RESCHNG /*5*/, dev, 0, NULL, NULL));

Dabei ist <dev> der VDI-Gertetreiber. Alternativ kann man mit

     ret = shel_write(SHW_RESCHNG /*5*/, xdv, 1, NULL, NULL));

in <xdv> einen Falcon-Auflsungsmodus angeben.
Diese Aufrufe sind alle MultiTOS-konform. Zustzlich existiert in MagiC 3 noch
folgender Aufruf:

     ret = shel_write(SHW_RESCHNG /*5*/, dev, 100+txt, NULL, NULL));

Hiermit kann man die Texthhe fr das AES festlegen. Eine Falcon-Auflsung
kann man bei diesem Modus nicht bergeben, <dev> ist also die Gertenummer
des VDI-Bildschirmtreibers.

Dieser Aufruf wurde in MagiC 4 ersetzt (!) durch:

     ret = shel_write(SHW_RESCHNG /*5*/, dev, (txt<<8), NULL, NULL));
bzw.
     ret = shel_write(SHW_RESCHNG /*5*/, xdv, (txt<<8)+(dev<<1)+1, NULL, NULL));

Dabei kann man im Hibyte des dritten Parameters die Texthhe fr das AES
festlegen, sowohl bei der Falcon-Auflsung als auch bei normalen VDI-
Gertenummern. Zustzlich kann man in den Bits 1..4 desselben Parameters
auch fr den Falcon ein VDI-Device festlegen, wobei 0 dem Device 5
entspricht (Falcon-Standard).

Die Gertenummer hngt vom verwendeten System und vom VDI (bzw. NVDI oder
Nova-VDI usw.) ab. Bei einem "nackten" ST, TT oder Falcon ohne Grafikkarte gilt
folgende Zuordung:

     1    Default-Auflsung
     2    ST niedrig     (320*200*16)
     3    ST mittel      (640*200*4)
     4    ST hoch        (640*400*2)
     5	Falcon-Modi mit zustzl. Moduscode
     6    TT mittel      (640*480*16)
     8    TT hoch        (1280*960*2)
     9    TT niedrig     (320*480*256)

Bei Einsatz einer Grafikkarte oder auf einem Mac stehen die Gertenummern in
der Datei ASSIGN.SYS im Wurzelverzeichnis des Bootlaufwerks.

Nach dem erfolgreichen shel_write-Aufruf befindet sich das System im
Shutdown-Modus, es knnen keine Programme mehr gestartet werden. Nach einem
erfolgreichen Abschlu des Shutdown oder Auflsungswechsels erhlt der
Initiator folgende Nachricht:

     msg[0] = SHUT_COMPLETED  (60)
     msg[3] = 1 - Shutdown erfolgreich

bzw. beim Auflsungswechsel

     msg[0] = RESCH_COMPLETED  (61)
     msg[3] = 1 - Auflsungswechsel erfolgreich

"Erfolgreich" heit fr das System, da alle Programme, die explizit AP_TERM
verstehen, sich beendet haben, und da keine weiteren Programme aktiv 
sind (nur noch ggf. ACCs). Soll der Shutdown trotzdem abgebrochen werden,
kann mit

     ret = shel_write(SHW_SHUTDOWN /*4*/, FALSE, 0, NULL, NULL));

der Shutdown-Modus bzw. Auflsungswechsel abgebrochen werden. Andernfalls
wird der Auflsungswechsel endgltig durchgefhrt, wenn sich der Initiator
beendet hat. Der Shutdown dagegen wird abgebrochen, wenn der Initiator
terminiert.

Hat ein Programm per AP_TFAIL (s.o.) den Shutdown verweigert, erhlt der
Initiator folgende Nachricht.

     msg[0] = SHUT_COMPLETED  (60)
     msg[3] = 0 - Shutdown abgebrochen
     msg[4] = ap_id der Applikation, die verweigert hat, oder -1
     msg[5] = Fehlercode dieser Applikation (s.o.)

bzw. beim Auflsungswechsel

     msg[0] = RESCH_COMPLETED  (61)
     msg[3] = 0 - Auflsungswechsel abgebrochen
     msg[4] = ap_id der Applikation, die verweigert hat, oder -1
     msg[5] = Fehlercode dieser Applikation (s.o.)

Das System hat in diesem Fall den Shutdown bzw. Auflsungswechsel schon
beendet, d.h. der Initiator kann nichts mehr tun. Ist msg[4] == -1, sind 
alle Programme, die explizit AP_TERM verstehen, beendet; es befinden sich 
aber noch weitere Programme (ACCs zhlen hier nicht) im System.

Weil es (z.B. grundstzlich bei XCONTROL) vorkommen kann, da der
Shutdown-Proze niemals vom System als abgeschlossen oder abgebrochen
gemeldet wird (d.h. die Nachricht RESCH_COMPLETED oder SHUT_COMPLETED wird
niemals verschickt), sollte der Initiator beim Warten auf die Nachricht einen
Timeout vorsehen. Tritt dieser Fall ein, mu der Shutdown explizit
abgebrochen werden (s.o.).

Per appl_search() kann der Initiator testen, ob noch Programme aktiv sind,
die nicht explizit AP_TERM verstehen. Auf diese Weise arbeitet SHUTDOWN.PRG.
