Description of "single mode" of Mag!X
=====================================

Position: Mag!X 1.12
Andreas Kromke, 4.3.93
English translation: Peter West, April 99

Mag!X distinguishes between three differently paired types of applications:

a)   The application #0
b)   Accessories
c)   Other applications (ap_id > 0)

The following call serves for launching programs under Mag!X:

*
* int shel_write(int doex, int isgr, int isover, char *cmd, char *tail)
*

Warning: MultiTOS works in a way that is completely incompatible to 
         previous TOS versions. The new calls are controled via <doex>
         (0 here is program launch with automatic isgr-identifier and
         1 with manual isgr-identifier, etc.) while "isover", which is 
         called "iscr" here, controls the ARGV passing.

Thre are 5 different possibilities to launch applications from within 
others ("magx.h"). Here are the parameter values for <isover>:

* #define SHW_IMMED      0                        /* PC-GEM 2.x  */
* #define SHW_CHAIN      1                        /* TOS         */
* #define SHW_DOS        2                        /* PC-GEM 2.x  */
* #define SHW_PARALLEL   100                      /* MAGIX       */
* #define SHW_SINGLE     101                      /* MAGIX       */

Of these, modes 0 and 2 are not supported by Mag!X. <doex> must always 
be 1, otherwise only previous shel_write() calls will be revoked (as in 
TOS 1.04).

1.   SHW_PARALLEL
     A new application will be created. It inherits all standard paths 
     and files from the current application. The new application runs in 
     parallel to the previous one. One will only get an error code if a 
     memory shortage occured during set-up. There is no message at the 
     termination of the new application (no "death-of-child").
2.   SHW_CHAIN
     This is the procedure under TOS. The program makes the call, and 
     after terminating itself the AES launches the new program. SHW_CHAIN 
     does not work with desk accessories, as these must never be permitted 
     to terminate.
     The new program inherits the standard paths and files that the 
     previous program had at the time of its launch. In general these are 
     in turn the ones that the program had that earlier launched the 
     "ancestor" of the application with SHW_PARALLEL. In the case of 
     application #0 therefore the new program gets the standard paths of 
     the  AES.
     If DESKTOP.APP (shell of GEM 2.2) is installed as a shell, then 
     Mag!X will insert the current path and drive before the filename.
3.   SHW_SINGLE
     Works like SHW_CHAIN, with the exception that before calling the 
     program all applications apart from application #0 and #1 (SCRENMGR)
     are frozen. The programs are unfrozen once more after the program 
     terminates as long as it did not make a new shel_write() call with 
     SHW_SINGLE on its part.
     One should add that from Mag!X 2.00 onward when calling shel_write 
     in SHW_SINGLE mode the current paths of the caller are passed to the 
     parent and hence to the new program. Warning: The paths of the 
     calling program are destroyed after this, though this is not critical 
     as the call following shel_write is generally a Pterm.

The loops for SHW_CHAIN and SHW_SINGLE look like this:

For application with ap_id > 0:

     while(doex)
          start(isgr, cmd, tail);

For application #0:

     while(world_is_turning)
          {
          start_desktop();
          while(doex)
               {
               if   (single_mode && single_mode_not_yet_activated)
                    activate_single_mode;
               else unfreeze_programs_if_appropriate;
               start(isgr, cmd, tail);
               }
          unfreeze_programs_if_appropriate;
          }


How do I launch a program in "single mode"?:

a)   Ensure that I am application #0 (i.e. ap_id == 0).
b)   Set paths and drive for the new program.
c)   shel_write(TRUE, isgr, SHW_SINGLE, cmd, path);
d)   All important settings to temporary file or shell-buffer.
e)   appl_exit()/v_clsvwk()/Pterm0.

How do I launch a program in "chain mode"?:

a)   If appropriate set paths and drive for the new program and make a 
     call
          shel_write(TRUE, dummy, SHW_SINGLE, dummy2, dummy3);
     in order to set the paths for the new program (incompatible to TOS).
b)   shel_write(TRUE, isgr, SHW_CHAIN, cmd, path);
d)   All important settings to temporary file or shell-buffer.
d)   appl_exit()/v_clsvwk()/Pterm0.

After the program terminates the shell will be reloaded automatically.
When calling the shell one gets in the command line (->shel_read) the 
"magic" sequence (magx.h):

/* tail for default shell */

typedef struct
     {
     int  dummy;                   /* a null-word                */
     long magic;                   /* 'SHEL', if it's a shell    */
     int  isfirst;                 /* first call of the shell    */
     long lasterr;                 /* last error                 */
     int  wasgr;                   /* program was a graphic-app. */
     } SHELTAIL;

If <isfirst> is set then the status is to be read from something like 
DESKTOP.INF, if <isfirst> is not set then one takes the temporary file or 
shell-buffer.
<lasterr> is the return value of the program running previously. If this 
was a GEM program then the error will already have been displayed in an 
alert box. It is well known that the longword is negative if the error 
occurred with Pexec itself; a program return value always has the high 
word 0.

