Topic : TOS - das Betriebssystem
Author :
Version : tos.hyp (5. März 2013)
Subject : Programmieren/Atari
Nodes : 3001
Index Size : 93602
HCP-Version : 5
Compiled on : Atari
@charset : atarist
@lang :
@default : Titel
@help :
@options : +g -i -s +x +zz -t4
@width : 70
View Ref-File8.18.9 shel_write TOS Name: »Shell write« - startet eine andere Applikation.
AES-Nummer: 121
Deklaration: int16_t shel_write ( int16_t sh_wdoex, int16_t
sh_wisgr, int16_t sh_wiscr, int8_t *sh_wpcmd, int8_t
*sh_wptail );
Beschreibung: Die Funktion ermöglicht das Starten eines anderen
Programms. Ab AES-Version 4.0 wurde diese Funktion
stark erweitert. So lassen sich nun auch Aufgaben wie
ein Herunterfahren des Systems (Shutdown), ein
Auflösungswechsel, AES-Broadcasting und andere Dinge
realisieren.
Der Parameter sh_wdoex bestimmt die auszuführende
Aktion, die restlichen Parameter sind im wesentlichen
von sh_wdoex abhängig. Es gilt:
sh_wdoex Bedeutung
0 Applikation starten Der Wert des Parameters sh_wisgr (Starten im
Grafikmodus, ja oder nein) wird automatisch
vom AES gesetzt, indem die File-Extension mit
den Inhalten der AES-Environmentvariablen
GEMEXT, TOSEXT und ACCEXT verglichen wird.
1 Applikation im GEM/TOS Modus starten Der Parameter sh_wisgr legt dabei den Modus
fest, in dem das Programm gestartet werden
soll. Es gilt:
sh_wisgr = 0: als TOS-Programm starten
sh_wisgr = 1: als GEM-Programm starten
2 reserviert 3 Accessorie starten Ein Programm soll als Accessorie gestartet
werden.
In den Parametern sh_wpcmd und sh_wptail sind dabei der
Name des zu startenden Programms bzw. ein Zeiger auf
die Kommandozeile zu übergeben. Als Default-Verzeichnis
wird dabei das Verzeichnis gewählt, in dem sich das zu
startende Programm befindet (Ausnahme: erweiterter
Modus mit gesetztem Bit-10, s.u.).
Die Funktion liefert die AES-ID des gestarteten
Prozesses zurück. Ein Wert von 0 zeigt in diesem
Zusammenhang einen Fehler an. Über den Parameter
sh_wiscr kann spezifiziert werden, ob Parameter per
ARGV an das gestartete Programm übergeben werden
sollen. Es gilt:
sh_wiscr = 0: ARGV-Verfahren nicht benutzen
sh_wiscr = 1: ARGV-Verfahren benutzen
Unter MagiC kann hingegen angegeben werden, ob ein
Programm im Single-Modus (oder parallel) gestartet
werden soll. Es gilt:
sh_wiscr = 100: Programm parallel ausführen Die neue Applikation erbt alle Standardpfade und
-dateien von der aktuellen Applikation. Ein Fehlercode
wird nur dann zurückgeliefert, falls bereits beim
Einrichten ein Speicherplatzmangel aufgetreten ist;
eine Benachrichtung beim Beenden der neuen Applikation
(Death-of-Child) existiert nicht (*).
sh_wiscr = 101: Programm im Single-Modus ausführen Dieser Modus entspricht sh_wiscr mit dem Wert 1, mit
der Ausnahme, daß vor Aufruf des Programms alle
Applikationen außer denjenigen mit ID-0 und ID-1
(SCRENMGR) eingefroren werden. Die Programme werden
nach Beendigung des Programms wieder aufgetaut, wenn
dieses nicht seinerseits einen neuen shel_write-Aufruf
mit Singlemode Charakter ausgeführt hat. Das genaue
Kochrezept für den Single-Modus lautet: ∙ sicherstellen, daß man die Applikation mit ID-0
ist
∙ Pfade und Laufwerk für das neue Programm setzen
∙ shel_write (TRUE, sh_wisgr, 101, sh_wpcmd,
sh_wptail)
∙ wichtige Einstellungen in Datei/Shell-Puffer
sichern
∙ appl_exit, v_clsvwk, Pterm0 ausführen
Beachtet werden sollte noch, daß ab MagiC 2 im Single-
Modus die aktuellen Pfade des Aufrufers an den Parent
und damit an das neue Programm übergeben werden. Die
Pfade des Aufrufers sind anschließend zerstört, was
aber unkritisch ist, da dieser auf den shel_write i.a.
ein Pterm folgen läßt (*).
Im erweiterten Modus, kann über spezielle Bits des
Parameters sh_wdoex das Starten von Programmen weiter
spezifiziert werden. Das Low-Byte bleibt dabei
unangetastet, und für das High-Byte gilt:
sh_wdoex Bit Bedeutung
8 Wert von Psetlimit 9 Wert von Prenice 10 Default-Verzeichnis
11 Environment-String
12 reserviert
13 reserviert
14 reserviert
15 reserviert
In diesem erweiterten Modus wird der Parameter sh_wpcmd als Zeiger auf eine Menge von 32bit (Long-)Werten
aufgefaßt. Jedem der o.g. Bits ist dabei ein Long-Wert
zugewiesen, der gültig ist, wenn das entsprechende Bit
gesetzt ist. Die Menge der 32bit Werte ist
folgendermaßen belegt:
Element Bedeutung
[0] Zeiger auf den Namen des Programms
[1] Wert von Psetlimit (Bit-8)
[2] Wert von Prenice (Bit-9)
[3] Zeiger auf das Default-Verzeichnis.
Ein Nullzeiger bedeutet in diesem
Zusammenhang, daß als Default-Verzeichnis
dasjenige gewählt wird, indem sich das zu
startende Programm befindet. (Bit-10)
[4] Zeiger auf das Environment der Applikation
(Bit-11)
Hinweis: Die Elemente [1],[2] und [3] werden bis MagiC
3 ignoriert; Element [1] wird jedoch ab MagiC 4
unterstützt. Das Default-Verzeichnis wird unter MagiC
viel einfacher gesetzt, denn das neue Programm erbt
alle Pfade auf allen Laufwerken vom aufrufenden
Programm.
Bei Geneva wird nur Bit 8 beachtet.
In neueren AES-Versionen stehen darüber hinaus die
folgenden Modi zur Verfügung.
sh_wdoex Bedeutung
4 Shutdown-Modus setzen Dieses Kommando versetzt das System in
Abhängigkeit des Parameters sh_wiscr in den
Normal bzw. Shutdown Modus. Es gilt:
sh_wiscr Bedeutung
0 Shutdown Sequenz abbrechen Ein begonnener Shutdown kann nur
von dem Prozess beendet werden,
der diese Sequenz auch gestartet
hat.
1 Partieller Shutdown Mit Ausnahme des Aufrufers werden
alle Applikationen vom AES
daraufhin überprüft, ob sie die
Meldung AP_TERM verstehen. Wenn
dies der Fall ist, schickt das AES
die Meldungen AP_TERM bzw.
AC_CLOSE an die Programme bzw.
Accessories. Der Aufrufer erhält
keine dieser Meldungen.
2 Vollständiger Shutdown Mit Ausnahme des Aufrufers werden
alle Applikationen und Accessories vom AES daraufhin überprüft, ob
sie die Meldung AP_TERM verstehen.
Wenn dies der Fall ist, schickt
das AES die Meldungen AP_TERM bzw.
AC_CLOSE an die Programme bzw.
Accessories. Accessories erhalten
die AP_TERM Nachricht zusätzlich
nach Erhalt der AC_CLOSE Message.
Der Aufrufer erhält keine dieser
Meldungen.
In N.AES gibt es einen erweiterten Aufruf:
shel_write(4, shutart, 0, &ignorant, NULL);
ignorant ist hierbei ein Integer, dessen
Adresse als vierter Parameter des
shel_write-Aufrufs übergeben wird. Im
Fehlerfall ist der Rückgabewert der Funktion
shel_write wie bisher 0, zusätzlich wird
jedoch in ignorant die Applikations-ID (apid)
der Applikation hinterlegt, die AP_TERM nicht
verstanden hat bzw. -1, wenn bereits ein
Shutdown läuft oder -2, wenn ungültige
Parameter übergeben wurden.
5 Auflösungswechsel Die Applikation fordert das AES auf, die
Auflösung zu wechseln. Falls das AES dem
Wechsel zustimmt, versucht es, das System
herunterzufahren (Shutdown). Die aktiven
Applikationen können sich nun entweder
beenden, oder durch eine AP_TFAIL Nachricht
dem AES mitteilen, daß sie hierzu nicht in
der Lage sind. Die Parameter sh_wisgr und
sh_wiscr sind dabei voneinander abhängig. Es
gilt:
sh_wiscr Bedeutung
0 Der Parameter sh_wisgr ist die ID
des physikalischen Gerätes, auf dem
der Open-Workstation Aufruf des VDI ausgeführt wird. Die aktuelle
physikalische Gerätenummer kann wie
üblich per Getrez() + 2 ermittelt
werden; es stehen folgende Werte
zur Verfügung:
2 = ST-Low (320*200)
3 = ST-Medium (640*200)
4 = ST-High (640*400)
6 = TT-Medium (640*480)
8 = TT-High (1280*960)
9 = TT-Low (320*480)
1 Der Parameter sh_wisgr ist das
int16_t für den Video-Modus des
Falcon.
>2 für zukünftige Zwecke reserviert
In N.AES gibt es einen erweiterten Aufruf:
shel_write(5, vmode, falconflag, &ignorant,
NULL);
Da ein Auflösungswechsel intern zunächst
immer einen vollständigen Shutdown startet,
kann es auch hier geschehen, daß nicht alle
Anwendungen AP_TERM verstehen und der
Auflösungswechsel somit frühzeitig
fehlschlägt. Analog zur obigen Modus-4-
Erweiterung wird auch hier die Applikations-
ID eines Verständnislosen in ignorant hinterlegt, eine -1, wenn bereits ein
Shutdown läuft oder -2, wenn fehlerhafte
Parameter (z.B. unerlaubte Auflösungen)
übergeben wurden.
6 unbekannt 7 AES-Broadcasting Die Applikation möchte eine Nachricht an alle
anderen im System vorhandenen Applikationen
schicken. Als Empfänger ausgenommen sind nur
das AES, der Screen-Manager, sowie der
Absender der Nachricht selbst.
Der Parameter sh_wpcmd ist ein Zeiger auf
einen 16 Bytes großen Nachrichtenpuffer, der
die zu sendenden Daten enthält.
8 Manipulation des AES-Environments Dieses Kommando erlaubt die Modifikation des
AES-Environments. Der Parameter sh_wisgr beschreibt die gewünschte Aktion. Es gilt:
sh_wisgr Bedeutung
0 Größe des Environment-Puffers
erfragen. Diese wird als
Funktionsergebnis zurückgeliefert.
1 Einfügen/Entfernen von Strings. Der
Parameter sh_wpcmd ist ein Zeiger
auf den Environment-String. Die
Syntax zum Einfügen bzw. Entfernen
lautet 'NEW=STRING\0' bzw.
'NEW=\0'.
2 Inhalt des Environment-Puffers
kopieren. Der Parameter sh_wpcmd ist ein Zeiger auf den aufnehmenden
Puffer, der eine Größe von sh_wiscr Bytes besitzt. Die Funktion liefert
die Anzahl der Bytes zurück, die
nicht kopiert werden konnten.
9 Unterstützte Nachrichten anzeigen Die Applikation teilt dem AES mit, welche
(neuen) Nachrichten verstanden werden. Dies
geschieht über gesetzte Bits des Parameters
sh_wisgr.
Bit 0: AP_TERM Bit 1: NM_INHIBIT_HIDE (since XaAES 2005-01-16)
Schützt eine Application davor
versteckt zu werden. Nützlich für
Desktop Utillity wie Taskbar oder
StartMe Up.
Alle anderen Bits (2-15) sind z.Zt. nicht
definiert.
10 Nachricht an AES senden Die Applikation will eine Nachricht an das
AES schicken. Der Parameter sh_wpcmd ist ein
Zeiger auf den 16 Bytes großen
Nachrichtenpuffer.
Geneva A program can cause a windowed dialog
to scroll by sending a WM_ARROWED message to Geneva. Example:
int16_t msg[8];
msg[0] = WM_ARROWED;
msg[3] = window_handle;
msg[4] = WA_UPPAGE;
shel_write( SHW_SENDTOAES, 0, 0, (int8_t *)msg, 0L );
20 Neuen Thread erzeugen Mit diesem Opcode kann die Applikation einen
neuen Thread erzeugen. Dabei gilt:
Parameter Bedeutung
sh_wisgr
0 = Starte Programm im VT52
Fenster der Applikation,
falls eines geöffnet ist.
1 = öffne kein neues Fenster
2 = öffne neues VT52-Fenster
sh_wiscr 0
sh_wpcmd Zeiger auf THREADINFO-Struktur
sh_wptail Parameter vom Typ (void *) für die
Thread-Funktion.
Bei einem erfolgreichen Aufruf wird als
Ergebnis die Applikations-ID des neuen
Threads zurückgeliefert (*).
21 Thread beenden Mit diesem Opcode kann sich ein Thread selbst
beenden. Dazu setzt man die Parameter
sh_wisgrsh_wiscr und sh_wptail auf die Werte
0 bzw. NULL; über sh_wpcmd kann ein
zurückzuliefernder Fehlercode angegeben
werden.
Normalerweise ist ein Ausführen dieser
Funktion nicht notwendig, da sich der Thread
automatisch mit dem Ende seiner Prozedur
(d.h. mit dem CPU-Befehl RTS) selbst beendet.
Wichtig: Wenn der Thread einen Pexec-Aufruf
durchgeführt hat, so muss zuerst der laufende
Prozess per Pterm beendet werden, bevor sich
der Thread beenden kann (*).
22 Thread terminieren Mit diesem Opcode kann ein Thread auch vom
Hauptprogramm beendet werden. Dazu übergibt
man im Parameter sh_wiscr die Applikations-ID
des Thread, und setzt die übrigen Parameter
auf den Wert 0 bzw. NULL.
Normalerweise ist diese Funktion nicht
notwendig, da mit dem Beenden des
Hauptprogramms automatisch auch alle
zugehörigen Threads beendet werden. Die
Funktion wurde erfolgreich ausgeführt, wenn
als Ergebnis der Wert 1 zurückgeliefert wird.
Zu beachten ist jedoch, daß für den Fall, daß
der Thread inzwischen ein Pexec ausgeführt
hat, nur dieses Programm per Pterm (EBREAK)
beendet wird; der Thread selbst ist erst dann
beendet, wenn der Aufrufer ein THR_EXIT empfangen hat (*).
224 Run an application (Geneva since Update 004)
Run an application, letting Geneva determine
the type. This is identical to mode 0, except
that the XSHD_FLAGS bit of sw_doex can also
be set (see below).
225 Run an application (Geneva since Update 004)
This is identical to mode 1, except that the
XSHD_FLAGS bit of sw_doex can also be set.
227 Run a desk accessory. (Geneva since Update
004)
This is identical to mode 3, except that the
XSHD_FLAGS bit of sw_doex can also be set.
When XSHD_FLAGS (1<<15) is added to the
sw_doex, this means that the last longword of
the SHWRCMD passed in the sh_wpcmd parameter
contains the Geneva program flags to use when
executing the application.
It is strongly recommended that a program
using XSHD_FLAGS inquire the current flags
for the application and only change the ones
it needs to change, rather than making most
of the flags zero or some other random value.
See the x_appl_flags section, below, for an
example.
Hinweis: Ab MagiC 3 stehen die folgenden Besonderheiten
zur Verfügung:
∙ Wird in sh_wptail eine Zeichenkette übergeben, die
mit dem Wert 255 beginnt und mit '\0'
abgeschlossen ist, wird die tatsächliche Länge der
Kommandozeile vom AES bestimmt und in ganzer Länge
ans DOS weitergereicht. Das DOS konstruiert
hieraus einen ARGV-Parameter im Environment. Ist
die Kommandozeile kürzer als 127 Bytes, wird sie
über Basepage und per shel_read übergeben,
ansonsten besteht sie nur aus dem Byte mit dem
Wert 127.
∙ Wird in sh_wptail eine Zeichenkette übergeben, die
mit dem Wert 254 beginnt, erwartet das AES dahinter die Zeichenkette "ARGV=irgendwas" und
eine durch '\0' getrennte und durch "\0\0"
abgeschlossene Liste von Parametern. Diese wird
vollständig dem DOS übergeben, das daraus einen
ARGV-Parameter konstruiert. Ist die Kommandozeile
kürzer als 127 Bytes, wird sie über Basepage und
per shel_read übergeben, wobei die Nullbytes durch
Leerstellen ersetzt werden, ansonsten besteht sie
nur aus dem Byte mit dem Wert 127.
Das Vorhandensein der zusätzlichen Features kann per
appl_getinfo (Opcode 10) erfragt werden.
Die mit (*) gekennzeichneten Opcodes von shel_write
stehen z.Zt. nur in MagiC zur Verfügung.
Achtung: Startet man ein neuen AES-Prozeß unter
Singel-TOS mit shel_write wird dieser aber erst nach
Beendigung des eigenen Prozesses gestartet.
Ergebnis: Ein Fehler ist nur dann aufgetreten, wenn als Ergebnis
0 zurückgegeben wird.
Verfügbar: In allen AES Versionen.
Gruppe: Shell-Kommunikation Querverweis: BindingShutdown MechanismusThreads in MagiC