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
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:
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 |
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: |
|
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:
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 |
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: |
|
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:
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 |
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: |
|
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. 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 |
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: |
|
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:
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 |
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: |
|
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).
| ||||||
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 |
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: |
|
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:
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 |
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: |
|
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 |
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: |
|
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:
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:
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:
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:
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.
Hinweis: Ab MagiC 3 stehen die folgenden Besonderheiten zur Verfügung:
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 |
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: |
|