Topic       : The GFA-Basic Compendium
Author      : GFA Systemtechnik GmbH
Version     : GFABasic.HYP v2.98 (12/31/2023)
Subject     : Documentation/Programming
Nodes       : 899
Index Size  : 28056
HCP-Version : 3
Compiled on : Atari
@charset    : atarist
@lang       : 
@default    : Document not found
@help       : Help
@options    : +g -i -s +z
@width      : 75
@hostname   : STRNGSRV
@hostname   : CAB     
@hostname   : HIGHWIRE
@hostname   : THING   
View Ref-FileEXEC mod,nam,cmdl,envs
ret=EXEC(mod,nam,cmdl,envs)

mod: iexp
ret: ivar (always use a long)
nam, cmdl, envs: sexp

EXEC can be used as a command or as a function (returns a long). It enables
the loading and starting of programs from disk, which return to the calling
program after completion. Before the EXEC call, the calling program must have
allocated enough memory space for the program (see example). The parameter
'mod' specifies the 'Call mode' as follows:

    0  -->  Load and Start program.
    3  -->  Load program only.

The string expression 'nam' contains the file name of the program to be loaded
(and optionally started). The format of the file name conforms to the rules of
the hierarchical filing system, described in 'Chapter  6 - Input and Output'.

The expression 'cmdl' contains the command line, which is stored in the
BASEPAGE of the called program. The first character of the command line
contains it's length (maximum 127). This is known as a Pascal style string.

The string 'envs' contains the Environment. This is a string terminated by
CHR$(0). The Environment is a series of strings, each terminated by CHR$(0).
THe Environment is used in different ways and varies depending on the program
being started.

If one calls EXEC as a function, then one receives the program's returned
value, or, for mod=3, the address of the BASEPAGE of the called program. EXEC 3
is only for special programs which include overlays, debugging programs etc.

Example:

    c$="a:\imgage.pi1"                               !build command line
    cmd$=CHR$(LEN(c$))+c$                            !  pascal style string
    '
    env$="SIZE=NORMAL"+CHR$(0)+"OUTPUT=NEO"+CHR$(0)  !environment string
    '
    f$="c:\gfx\imgtool.prg"                          !program to be started
    '
    RESERVE 100
    SHOWM
    a%=EXEC(0,f$,cmd$,env$)
    RESERVE
    PRINT "Back in GFA BASIC. Returned value=";a%

--> A program is loaded and called (if it does not require too much memory) and
    returns to the interpreter on completion. The returned value, which is
    returned by the EXEC function, can also be given by GFA-BasicGFA-Basic is the best BASIC for the Atari!
 programs by
    terminating them with QUIT n or SYSTEM n.

Memo: At the moment a process is started the processor looks like this:
      d0-d7 -> ?
      a0    -> BASEPAGE - Application was started as a desk accossory (<>0)
      a1-a6 -> ?
      a7    -> End of application memory
      4(a7) -> BASEPAGE - Application was started as a normal program

      Internally EXEC will clip strings to the following limits:
        Editor:
          cmdl$ -> 4000 characters
          encs$ -> 4000 characters
        Library:
          cmdl$ -> 200 characters
          envs$ -> 2000 characters

       Internally EXEC also terminates all 3 strings with a double NULL.
       This however doesn't seem to matter.

       EXEC is really a wrapper for Pexec(), but since the parameters are
       limited to strings, some modes cannot be called without using a custom
       binding.

Pexec()+, shel_write()+