[MiNT] shel_write questions

[Martin_Elsaesser@ll.maus.de (Martin Elsässer)]

Hallo Arnaud,

AB>#define SWM_THRCREATE           20      /**< create a new thread, see
AB>mt_shel_write() */

In my MagiC docu this is named SHW_THR_CREATE.

AB>is there any "official" constant name ?

In the MagiC docu I found these names:

	#define SHW_THR_CREATE	20		/* doex */
	#define SHW_THR_EXIT	21
	#define SHW_THR_KILL	22


AB>What about mode 21 (thread terminate) and 22 (thread terminated by
AB>parent)

In the (german) MagiC docu I found this here for mode 21:

----------------------------------- schnipp
-----------------------------------
Wie beende ich einen Thread ?
=============================

Normalerweise wird der Thread mit dem Ende der Prozedur <proc>, d.h. mit
dem CPU- Befehl "rts", automatisch beendet. Dies ist die sicherste und
beste Methode.

Alternativ kann sich ein Thread selbst beenden mit:

shel_write(SHW_THR_EXIT, 0, 0, errcode, NULL);

Rückgabewert (wenn OK, kehrt die Funktion nicht zurück):

	0 Fehler

Ein Fehler kann auftreten, wenn

	-	der Aufrufer kein Thread ist, sondern etwas anderes
	-	der Thread inzwischen Pexec() gemacht hat

Wenn der Thread Pexec() gemacht hat, muß erst der laufende Prozeß per
Pterm() beendet werden, bevor sich der Thread beenden kann.
----------------------------------- schnapp
-----------------------------------

And this here for mode 22:

----------------------------------- schnipp
-----------------------------------
Im Notfall kann ein Thread auch vom Hauptprogramm aus beendet werden.
Normalerweise ist dies nicht notwendig, weil beim Beenden des Hauptprogramms
automatisch alle zugehörigen Threads mit beendet werden.
Das Hauptprogramm beendet den Thread mit:

shel_write(SHW_THR_KILL, 0, ap_id, NULL, NULL);

Rückgabewert:

	0 Fehler
	1 OK

Ein Fehler kann auftreten, wenn

	-	die ap_id ungültig ist
	-	der Thread sich bereits beendet hat
	-	unter der ap_id kein Thread läuft, sondern etwas anderes
	-	der Thread nicht dem Aufrufer gehört

Auch wenn der Rückgabewert 1 ist, ist zu beachten, daß für den Fall,
daß der Thread inzwischen per Pexec() ein anderes Programm gestartet
hat, nur dieses Programm per Pterm(EBREAK) beendet wird. Der Thread ist
erst dann beendet, wenn der Aufrufer THR_EXIT empfangen hat.

Achtung:	Man beachte, daß Speicher, den der Thread alloziert, dem
		Prozeß gehört, d.h. bei Beendigung des Threads nicht
		automatisch freigegeben wird. Gleiches gilt für offene Dateien,
		die erst bei Programmbeendigung geschlossen werden.
----------------------------------- schnapp
-----------------------------------

The Thread is terminated, if the called procedure returns. But the Thread
can terminated itself with SHW_THR_EXIT. If the main program wants to
terminate a thread, the mode SHW_THR_KILL is used.

AB>I'm looking for documentation on the THREADINFO structure: /**
AB>description of a thread, see mt_shel_write() with #SWM_THRCREATE mode

>From the magiC docu:

----------------------------------- schnipp
-----------------------------------
Ist <user_stack> = NULL, legt das System selbst den Stack an. Terminiert
der Thread, gibt das System den Stack in jedem Fall frei. <stacksize> ist in
jedem Fall anzugeben, damit das System den Stackpointer des Threads auf das
Ende des Stacks setzen kann. Der Systemstapel (supervisor stack) wird vom
System selbst festgelegt, die Größe kann nicht beeinflußt werden.
----------------------------------- schnapp
-----------------------------------

For <user_stack> =NULL the System creates the Stack. When the thread
terminates, the systems frees the stack in all cases! The stacksize must be
valid. The system sets the stackpointer to the end of the stack.

AB>what shall we set in user_stack : the address of the top or the bottom
AB>of  the memory allocated for the stack ? Is NULL a value allowed ?

The address is the beginning of the stack. With the correct value of the
stacksize the system sets the stackpointer correctly.

AB>What are mode and res1 fields for ?

They are reserved for future purposes. From the MagiC docu:

----------------------------------- schnipp
-----------------------------------
<mode> und <res1> sind für mögliche Erweiterungen reserviert. In Solaris 2.x
kann man damit z.B. einen Thread bis zum endgültigen Start anhalten.
----------------------------------- schnapp
-----------------------------------

AB>In gemlib, there is a SHELTAIL structure: what's for ?

This is the structure for the desktop for the mode SHW_CHAIN and
SHW_SINGLE. in the MagiC docu there is a document about the "single mode"
of MagiC when starting applications:

----------------------------------- schnipp
-----------------------------------
Wie starte ich nun ein Programm im "single mode":

a)   Sicherstellen, daß ich Applikation #0 bin (d.h. ap_id == 0).
b)   Pfade und Laufwerk für das neue Programm setzen.
c)   shel_write(TRUE, isgr, SHW_SINGLE, cmd, path);
d)   alle wichtigen Einstellungen in temporäre Datei bzw. Shell- Puffer
e)   appl_exit()/v_clsvwk()/Pterm0

Wie starte ich nun ein Programm im "chain mode":

a)   ggf. Pfade und Laufwerk für das neue Programm setzen und einen
     Aufruf
          shel_write(TRUE, dummy, SHW_SINGLE, dummy2, dummy3);
     machen, um die Pfade für das neue Programm zu setzen.
     (inkompatibel zu TOS)
b)   shel_write(TRUE, isgr, SHW_CHAIN, cmd, path);
c)   alle wichtigen Einstellungen in temporäre Datei bzw. Shell- Puffer
d)   appl_exit()/v_clsvwk()/Pterm0

Nach Beendigung des Programms wird automatisch wieder die Shell geladen.
Beim Aufruf der Shell bekommt man in der Kommandozeile (->shel_read) die
"magische" Sequenz (magx.h):

/* tail for default shell */

typedef struct
     {
     int  dummy;                   /* ein Nullwort               */
     long magic;                   /* 'SHEL', wenn ist Shell     */
     int  isfirst;                 /* erster Aufruf der Shell    */
     long lasterr;                 /* letzter Fehler             */
     int  wasgr;                   /* Programm war Grafikapp.    */
     } SHELTAIL;

Wenn <isfirst> gesetzt ist, ist der Status etwa aus DESKTOP.INF zu lesen,
ist <isfirst> nicht gesetzt, nimmt man die temporäre Datei bzw. den
Shell- Puffer.
<lasterr> ist der Rückgabewert des vorher gelaufenen Programms. Wenn dies
ein
GEM-Programm war, ist der Fehler bereits per Alertbox angezeigt worden.
Bekannlich ist das Langwort negativ, wenn der Fehler beim Pexec selbst
auftrat, ein Programm-Rückgabewert hat immer Hiword 0.
----------------------------------- schnapp
-----------------------------------

First of all only ap_id=0, the desktop, may start applications in single
mode. The desktop starts the application with the following method:

How to start a application in "single mode":

a)   Check that desktop is applikation #0 (i.e. ap_id == 0).
b)   Set the paths and drives for the new program
c)   shel_write(TRUE, isgr, SHW_SINGLE, cmd, path);
d)   Save all options in temporary files or the shell buffer
e)   appl_exit()/v_clsvwk()/Pterm0

How to start a application in "chain mode":

a)   set path and drive for the new program and call
          shel_write(TRUE, dummy, SHW_SINGLE, dummy2, dummy3);
     to set the paths for the new program
     (incompatibel zu TOS!)
b)   shel_write(TRUE, isgr, SHW_CHAIN, cmd, path);
c)   save all options in temporary file or the shel buffer
d)   appl_exit()/v_clsvwk()/Pterm0

When the started program terminates, the desktop is started again. In the
commandloine (shel_read!) the desktop gets a SHELTAIL-Structure. <isfirst>
is set, it is the first start of the desktop (read options from
DESKTOP.INF). If it's cleared, the temporary options should be used.
<lasterr> contains the return value of the started program. If a GEM
applications was started, errors were already shown in alertboxes.

AB>the following constant seems to be a message value to terminate the
AB>AES (that mean that any AES application may terminate the AES???)

Yes! The docu of N.AES discribes this!

Gruß

     Martin    [PGP-Key available]
---
Für Mails >16 kByte: martin@melsaesser.de