HomeAESResourcefunktionenErweiterte Grafikfunktionen

8.18 Shellfunktionen

Diese Bibliothek enthält Funktionen um Informationen aus der Programmumgebung zu lesen bzw. in diese zu schreiben; außerdem kann hierüber der Start anderer GEM-Programme übernommen werden. Insgesamt stehen die folgenden Routinen zur Verfügung:

shel_envrn Environment-Variable abfragen
shel_find Datei suchen
shel_get Aus dem Environment-Puffer lesen
shel_help Ausgabe von Hilfetexten
shel_put In den Environment-Puffer schreiben
shel_rdef Abfragen des Default-Programms
shel_read Kommandozeilenparameter lesen
shel_wdef Setzen des Default-Programms
shel_write Applikation starten

Hinweis: Eine besondere Beachtung hat dabei shel_write verdient, welches ab AES-Version 4.0 (bzw. MagiC 3) viele weitere nützliche Dinge wie ein Herunterfahren des Systems (Shut-Down), Auflösungswechsel, AES-Broadcasting usw. zur Verfügung stellt.

Querverweis: AES   Style-Guidelines

8.18.1 shel_envrn

Name: »Shell environment« - ermittelt den Wert von Environmentvariablen.
AES-Nummer: 125
Deklaration: int16_t shel_envrn ( int8_t **sh_epvalue, int8_t *sh_eparm );
Beschreibung: Die Funktion ermittelt den Wert einer beliebigen Environmentvariablen des AES. Es gilt:
Parameter Bedeutung
   
sh_epvalue Name der Environment-Variablen
sh_eparm enthält nach dem Aufruf den Wert der entsprechenen Variablen


Hinweis: Um das AES-Environment zu ändern sollte man sich in den exec_os-Vektor einklinken, über den auch das GEM gestartet wird. In der aufgerufenen Routine liegt (analog zu einem Programm) der Basepage-Zeiger auf dem Stack. In diese Basepage kann dann einfach ein Zeiger auf das neue Environment eingetragen werden. Aber Achtung: In AES-Versionen kleiner als 1.4 werden nur die ersten 50 Bytes übernommen.

Noch ein Tip: Wenn der für 'PATH=' zurückgelieferte Zeiger auf ein Nullbyte verweist, sollte man ihn um den Wert 1 erhöhen, um an das richtige Ergebnis zu gelangen.
Ergebnis: Die Funktion liefert als Ergebnis immer 1.
Verfügbar: All AES versions.
Gruppe: Shell-Kommunikation
Querverweis: Binding

8.18.1.1 Bindings für shel_envrn

C: int16_t shel_envrn ( int8_t **sh_epvalue, int8_t *sh_eparm );
Umsetzung:
int16_t shel_envrn (int8_t **sh_epvalue, int8_t *sh_eparm)
{
   addr_in[0] = sh_epvalue;
   addr_in[1] = sh_eparm;

   return ( crys_if(125) );
}
GEM-Arrays:

Adresse Feldelement Belegung
control control[0] 125 # Opcode der Funktion
control+2 control[1] 0 # Einträge in int_in
control+4 control[2] 1 # Einträge in int_out
control+6 control[3] 2 # Einträge in addr_in
control+8 control[4] 0 # Einträge in addr_out
addr_in addr_in[0] sh_epvalue
addr_in addr_in[1] sh_eparm
int_out int_out[0] Return-Wert

8.18.2 shel_find

Name: »Shell find« - sucht Dateien.
AES-Nummer: 124
Deklaration: int16_t shel_find ( int8_t *sh_fpbuff );
Beschreibung: Die Funktion sucht eine Datei in bestimmten Verzeichnissen. Der Parameter sh_fpbuff enthält den Namen der gesuchten Datei. Nach dem Aufruf der Funktion wird hier der Zugriffspfad auf die Datei abgelegt.

Hinweis: Die Datei wird in den folgenden Verzeichnissen gesucht:
  • im aktuellen Verzeichnis
  • im Wurzelverzeichnis
  • in allen Verzeichnissen, die in der Variable PATH des AES-Environments angegeben sind
  • in dem Pfad, in welchem sich das Programm z.Zt. befindet (ab TOS-Version 1.04)


Die Funktion wird auch von rsrc_load benutzt, um die Resource-Datei zu lokalisieren.
Ergebnis: Ein Rückgabewert von Null signalisiert, daß die angegebene Datei nicht gefunden wurde.
Verfügbar: All AES versions.
Gruppe: Shell-Kommunikation
Querverweis: Binding   shel_envrn

8.18.2.1 Bindings für shel_find

C: int16_t shel_find ( int8_t *sh_fpbuff );
Umsetzung:
int16_t shel_find (int8_t *sh_fpbuff)
{
   addr_in[0] = sh_fpbuff;
   return ( crys_if(124) );
}
GEM-Arrays:

Adresse Feldelement Belegung
control control[0] 124 # Opcode der Funktion
control+2 control[1] 0 # Einträge in int_in
control+4 control[2] 1 # Einträge in int_out
control+6 control[3] 1 # Einträge in addr_in
control+8 control[4] 0 # Einträge in addr_out
addr_in addr_in[0] sh_fpbuff
int_out int_out[0] Return-Wert

8.18.3 shel_get

Name: »Shell get« - liest den GEM-Environment-Puffer.
AES-Nummer: 122
Deklaration: int16_t shel_get ( int8_t *sh_gaddr, uint16_t sh_glen );
Beschreibung: Die Funktion dient zum Lesen von Zeichen aus dem internen Environment-Speicher des AES. Es gilt:
Parameter Bedeutung
   
sh_gaddr Adresse des Zielspeichers
sh_glen Anzahl der zu lesenden Bytes oder Wert -1, um die Länge des Speichers zu ermitteln.


Hinweis: Das Desktop nutzt diesen Speicher zur Aufbewahrung der DESKTOP.INF bzw. NEWDESK.INF Datei. Das Format dieser Dateien ist allerdings nicht offiziell dokumentiert. Eine aktuelle Beschreibung findet sich jedoch in newdesk.hyp.

Unter MagiC werden beim Start des AES alle Daten in den Puffer kopiert, die nach der Zeile #_CTR in MAGX.INF liegen. Die zulässige Länge des Puffers liegt seit MagiC 3 zwischen 4192 und 65534 Bytes. Das Vorhandensein der zusätzlichen Features kann per appl_getinfo (Opcode 6) abgefragt werden.
Ergebnis: Ein Rückgabewert von Null signalisiert einen Fehler.
Verfügbar: All AES versions.
Gruppe: Shell-Kommunikation
Querverweis: Binding   shel_put

8.18.3.1 Bindings für shel_get

C: int16_t shel_get ( int8_t *sh_gaddr, uint16_t sh_glen );
Umsetzung:
int16_t shel_get (int8_t *sh_gaddr, uint16_t sh_glen)
{
   int_in[0]  = sh_glen;
   addr_in[0] = sh_gaddr;

   return ( crys_if(122) );
}
GEM-Arrays:

Adresse Feldelement Belegung
control control[0] 122 # Opcode der Funktion
control+2 control[1] 1 # Einträge in int_in
control+4 control[2] 1 # Einträge in int_out
control+6 control[3] 1 # Einträge in addr_in
control+8 control[4] 0 # Einträge in addr_out
int_in int_in[0] sh_glen
addr_in addr_in[0] sh_gaddr
int_out int_out[0] Return-Wert

8.18.4 shel_help

Name: Ausgabe von Hilfetexten.
AES-Nummer: 128
Deklaration: int16_t shel_help ( int16_t sh_hmode, int8_t *sh_hfile, int8_t *sh_hkey);
Beschreibung: Die Funktion dient zur Ausgabe von Hilfetexten (Online-Hilfe) über einen Help-Server.
Parameter Bedeutung
sh_hmode Hierfür ist im Moment immer SHP_HELP(=0) zu übergeben.
sh_hfile Name der Hilfedatei.

Wird sie inklusive einer Extension übergeben, so wird anhand dieser Extension der entsprechende Server in der Liste der Helpserver aufgesucht.

Hat die übergebene Datei keine Extension, so wird automatisch die des ersten in der CNF-Datei definierten Helpservers angehängt.
sh_hkey Schlüsselwort, zu welchem ein Hilfetext ausgegeben werden soll, oder NULL.


Bei einem Aufruf von shel_help mit einer Datei, welche eine Extension hat, prüft N.AES, ob ein Helpserver für diese Extension (mittels 'helpserver') definiert wurde. Wird ein passender Server gefunden, so wird geprüft, ob dieser bereits aktiv ist (als Accessory oder auch als nebenläufig gestartete Anwendung). Ist dies der Fall, so wird dem Server die Mitteilung VA_START mit den bei sh_hfile und sh_hkey angegebenen Argumenten als Kommandozeile zugesendet.

Ist der Server nicht aktiv, so wird er automatisch gestartet, wenn bei seiner Definition mit Hilfe von 'helpserver' ein Pfad für ihn angegeben wurde. Als Kommandozeile wird ihm dabei die bei sh_hfile und sh_hkey angegebenen Argumente übergeben.
Ergebnis: Ein Rückgabewert von Null signalisiert einen Fehler.
Verfügbar: Das Vorhandensein dieser Funktion kann per appl_getinfo (Opcode 65) festgestellt werden.

Neben N.AES gibt es eine TSR welches diese Funktion auf anderen Systemen zur Verfügung stellt.
Gruppe: Shell-Kommunikation
Querverweis: Binding

8.18.4.1 Bindings für shel_help

C: int16_t shel_help ( int16_t sh_hmode, int8_t *sh_hfile, int8_t *sh_hkey);
Umsetzung:
int16_t shel_help ( int16_t sh_hmode, int8_t *sh_hfile,
                    int8_t *sh_hkey)
{
   int_in[0] = sh_hmode;
   addr_in[0] = sh_hfile;
   addr_in[1] = sh_hkey;

   crys_if(128);

   return = int_out[0];
}
GEM-Arrays:

Adresse Feldelement Belegung
control control[0] 128 # Opcode der Funktion
control+2 control[1] 1 # Einträge in int_in
control+4 control[2] 1 # Einträge in int_out
control+6 control[3] 2 # Einträge in addr_in
control+8 control[4] 0 # Einträge in addr_out
int_in int_in[0] sh_hmode
addr_in addr_in[0] sh_hfile
addr_1n+4 addr_in[1] sh_hkey
int_out int_out[0] Return-Wert

8.18.5 shel_put

Name: »Shell put« - schreibt in den GEM-Environment-Puffer.
AES-Nummer: 123
Deklaration: int16_t shel_put ( int8_t *sh_paddr, uint16_t sh_plen );
Beschreibung: Die Funktion schreibt in den Environment-Speicher des AES. Es gilt:

Parameter Bedeutung
sh_paddr Adresse des Quellpuffers
sh_plen Anzahl der zu schreibenden Zeichen


Hinweis: Das Desktop nutzt diesen Speicher zur Aufbewahrung der DESKTOP.INF bzw. NEWDESK.INF Datei. Das Format dieser Dateien ist allerdings nicht offiziell dokumentiert. Eine aktuelle Beschreibung findet sich jedoch in newdesk.hyp.

Die zulässige Länge des Puffers liegt seit MagiC 3 zwischen 4192 und 65534 Bytes, während sie in ganz alten TOS-Versionen noch bei 1024 Bytes lag.

Prior to AES version 4.0 this function would only copy as many bytes as would fit into the current buffer. As of version 4.0, the AES will dynamically allocate more memory as needed (up to 32767 bytes) for the shell buffer.
Ergebnis: Ein Rückgabewert von Null signalisiert einen Fehler.
Verfügbar: All AES versions.
Gruppe: Shell-Kommunikation
Querverweis: Binding   shel_get   shel_envrn   shel_find

8.18.5.1 Bindings für shel_put

C: int16_t shel_put ( int8_t *sh_paddr, uint16_t sh_plen );
Umsetzung:
int16_t shel_put (int8_t *sh_paddr, uint16_t sh_plen)
{
   int_in[0]  = sh_plen;
   addr_in[0] = sh_paddr;

   return ( crys_if(123) );
}
GEM-Arrays:

Adresse Feldelement Belegung
control control[0] 123 # Opcode der Funktion
control+2 control[1] 1 # Einträge in int_in
control+4 control[2] 1 # Einträge in int_out
control+6 control[3] 1 # Einträge in addr_in
control+8 control[4] 0 # Einträge in addr_out
int_in int_in[0] sh_plen
addr_in addr_in[0] sh_paddr
int_out int_out[0] Return-Wert

8.18.6 shel_rdef

Name: »Shell read default« - Default Programm abfragen
AES-Nummer: 126
Deklaration: int16_t shel_rdef ( int8_t *lpcmd, int8_t *lpdir );
Beschreibung: Die Funktion erlaubt es, das Programm zu erfragen, welches nach Beendigung des aktuellen gestartet wird (i.d.R. der Desktop).
Parameter Bedeutung
lpcmd Zeiger auf einen ausreichend dimensionierten String für den Namen der Applikation.
lpdir Zeiger auf einen ausreichend dimensionierten String für den Pfad der Applikation.
Ergebnis: Der Rückgabewert ist z.Zt. nicht bekannt.
Verfügbar: Unter PC-GEM steht die Funktion ab Version 2.0 zur Verfügung. Ansonsten in KAOS 1.4.2 und MagiC. Das Vorhandensein dieser Funktion kann per appl_getinfo (Opcode 5) festgestellt werden.
Gruppe: Shell-Kommunikation
Querverweis: Binding   shel_wdef   MagiC

8.18.6.1 Bindings für shel_rdef

C: int16_t shel_rdef ( int8_t *lpcmd, int8_t *lpdir );
Umsetzung:
int16_t shel_rdef (int8_t *lpcmd, int8_t *lpdir)
{
   addr_in[0] = lpcmd;
   addr_in[1] = lpdir;

   return ( crys_if(126) );
}
GEM-Arrays:

Adresse Feldelement Belegung
control control[0] 126 # Opcode der Funktion
control+2 control[1] 0 # Einträge in int_in
control+4 control[2] 1 # Einträge in int_out
control+6 control[3] 2 # Einträge in addr_in
control+8 control[4] 0 # Einträge in addr_out
addr_in addr_in[0] lpcmd
addr_in+4 addr_in[1] lpdir
int_out int_out[0] Return-Wert

8.18.7 shel_read

Name: »Shell read« - liest die Kommandozeilen-Parameter der Applikation.
AES-Nummer: 120
Deklaration: int16_t shel_read ( int8_t *sh_rpcmd, int8_t *sh_rptail );
Beschreibung: Die Funktion ermittelt den Namen und die Kommandozeile, mit der eine Applikation gestartet wurde. Es gilt:
Parameter Bedeutung
   
sh_rpcmd vollständiger Pfadname mit Programmname
sh_rptail Kommandozeile (gemäß Pexec, also nullterminiert und mit Längenangaben im ersten Byte)


Hinweis: Die Funktion arbeitet nur dann korrekt, wenn die Applikation per shel_write gestartet worden ist. Daher sollte man im Zweifelsfall auf die Werte der Basepage zurückgreifen.
Ergebnis: Ein Fehler ist nur dann aufgetreten, wenn als Ergebnis 0 zurückgegeben wird.
Verfügbar: All AES versions.
Gruppe: Shell-Kommunikation
Querverweis: Binding   shel_write   Pexec

8.18.7.1 Bindings für shel_read

C: int16_t shel_read ( int8_t *sh_rpcmd, int8_t *sh_rptail );
Umsetzung:
int16_t shel_read (int8_t *sh_rpcmd, int8_t *sh_rptail)
{
   addr_in[0] = sh_rpcmd;
   addr_in[1] = sh_rptail;

   return ( crys_if(120) );
}
GEM-Arrays:

Adresse Feldelement Belegung
control control[0] 120 # Opcode der Funktion
control+2 control[1] 0 # Einträge in int_in
control+4 control[2] 1 # Einträge in int_out
control+6 control[3] 2 # Einträge in addr_in
control+8 control[4] 0 # Einträge in addr_out
addr_in addr_in[0] sh_rpcmd
addr_in+4 addr_in[1] sh_rptail
int_out int_out[0] Return-Wert

8.18.8 shel_wdef

Name: »Shell write default« - Default Programm setzen
AES-Nummer: 127
Deklaration: int16_t shel_wdef( int8_t *lpcmd, int8_t *lpdir );
Beschreibung: Die Funktion erlaubt es, die Applikation festzulegen, welche als Default-Programm anzusehen ist (normalerweise der Desktop).

Hinweis zu MagiC: Sind die Parameter lpcmd und lpdir Leerstrings, so wird MAGXDESK wieder installiert. Ein alternatives Desktop macht zum Programmstart einfach ein shel_write, und beendet sich dann per Pterm0 es bekommt von MagiC eine Kommandozeile (SHELTAIL), die per shel_read ermittelt werden kann. Gibt die Shell einen negativen Fehlercode zurück, so wird MAGXDESK aktiviert.

Hinweis zu N.AES: Sind die Parameter lpcmd und/oder lpdir Leerstrings oder NULL, wird die in N_AES.CNF angegebene 'shell' Applikation gestartet.
Ergebnis: Der Rückgabewert ist z.Zt. nicht bekannt.
Verfügbar: Unter PC-GEM steht die Funktion ab Version 2.0 zur Verfügung. Ansonsten in KAOS 1.4.2 und MagiC. Das Vorhandensein dieser Funktion kann per appl_getinfo (Opcode 5) festgestellt werden.
Gruppe: Shell-Kommunikation
Querverweis: Binding   shel_rdef   MagiC

8.18.8.1 Bindings für shel_wdef

C: int16_t shel_wdef( int8_t *lpcmd, int8_t *lpdir );
Umsetzung:
int16_t shel_wdef(int8_t *lpcmd, int8_t *lpdir)
{
   addr_in[0] = lpcmd;
   addr_in[1] = lpdir;

   return ( crys_if(127) );
}
GEM-Arrays:

Adresse Feldelement Belegung
control control[0] 127 # Opcode der Funktion
control+2 control[1] 0 # Einträge in int_in
control+4 control[2] 1 # Einträge in int_out
control+6 control[3] 2 # Einträge in addr_in
control+8 control[4] 0 # Einträge in addr_out
addr_in addr_in[0] lpcmd
addr_in+4 addr_in[1] lpdir
int_out int_out[0] Return-Wert

8.18.9 shel_write

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_wisgr sh_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: Binding   Shutdown Mechanismus   Threads in MagiC

8.18.9.1 Bindings für shel_write

C: int16_t shel_write ( int16_t sh_wdoex, int16_t sh_wisgr, int16_t sh_wiscr, int8_t *sh_wpcmd, int8_t *sh_wptail );
Umsetzung:
int16_t shel_write (int16_t sh_wdoex, int16_t sh_wisgr,
                    int16_t sh_wiscr, int8_t *sh_wpcmd,
                    int8_t *sh_wptail)
{
   int_in[0]  = sh_wdoex;
   int_in[1]  = sh_wisgr;
   int_in[2]  = sh_wiscr;
   addr_in[0] = sh_wpcmd;
   addr_in[1] = sh_wptail;

   return ( crys_if(121) );
}
GEM-Arrays:

Adresse Feldelement Belegung
control control[0] 121 # Opcode der Funktion
control+2 control[1] 3 # Einträge in int_in
control+4 control[2] 1 # Einträge in int_out
control+6 control[3] 2 # Einträge in addr_in
control+8 control[4] 0 # Einträge in addr_out
int_in int_in[0] sh_wdoex
int_in+2 int_in[1] sh_wisgr
int_in+4 int_in[2] sh_wiscr
addr_in addr_in[0] sh_wpcmd
addr_in+4 addr_in[1] sh_wptail
int_out int_out[0] Return-Wert

HomeAESResourcefunktionenErweiterte Grafikfunktionen